Update the root_id column in a set of google sheets based on flywire_xyz positions

Source: R/flywire_googledrive.R

This function retrieves flywire IDs based on xyz positions in flywire voxel space, from a set of google sheets. It also writes the updated flywire IDs to the same google sheets. This is often helpful because flywire IDs are inherently unstable, they change every time a neuron is modified even slightly. Users can record 'stable' points in a neuron that identify it, e.g. a single xyz position in the cell body fibre, or at the soma, and then use this function to update and get the correct flywire ID whenever they wish.

flywire_ids_update(
  selected_sheets = NULL,
  chosen.columns = c("flywire_xyz", "flywire_svid", "root_id", "skid", "fafb_xyz",
    "cell_type", "side", "ito_lee_hemilineage", "hartenstein_hemilineage", "status"),
  ws = NULL,
  regex = FALSE,
  meta = NULL,
  match = FALSE,
  matching_sheet = options()$hemibrainr_matching_gsheet,
  priority = c("FAFB", "hemibrain"),
  Verbose = TRUE,
  retry = 1
)

Arguments

selected_sheets

character vector. the google sheet(s) to update. Each entry is a unique google sheet ID. You can find these in a sheet's URL. If NULL then defaults to option('hemibrainr_gsheets').
chosen.columns

as well as writing column updates to the specified google sheets, this function returns a data.frame built from all given sheets and their individual tabs, that have been updated. This argument specifies which column you want returned. Filled with NAs if it does not exist.
ws

character vector, tabs (i.e. work sheets) on the google sheet to query/read. This works with regex, so you only need to give the name partially. If set to NULL for flywire_tracing_sheets, the whole google sheet is read and all tabs are combined using plyr::rbind.fill.
regex

logical, use ws with regex.
meta

meta data for flywire neurons, e.g. as retrieved using flywire_meta. Used to efficiently input flywire_xyz column if only a root_id entry has been given. Only works if that id is also in this provided data.frame, meta.
match

logical. If TRUE, hemibrain_matches given.
matching_sheet

the master matching sheet. Cannot be in selected_sheets. This sheet will be processed using hemibrain_matches to produce a data.frame describing hemibrain-FAFB and FAFB-hemibrain_matches.
priority

whether to use FAFB->hemibrain_matches (FAFB) or hemibrain->FAFB matches (hemibrain) in order to ascribe cell_type names to FAFB neurons. In both cases, cell_type names are attached to hemibrain bodyids, and propagated to their FAFB matches.
Verbose

logical, whether or not to supply you with messages.
retry

integer, sometimes fafbseg::flywire_xyz2id fails due to a server timeout. This is the number of times to re-attempt failed calls before accepting defeat.

Value

a data.frame with columns from the given google sheet(s), specified using the argument chosen.columns.

Details

For this function to work, the specified google sheet(s) must have either the column flywire_xyz, which gives the xyz position of points in a format that can be read by nat::xyzmatrix, for example "(135767,79463,5284)" or "(135767;79463;5284)". If this is missing, then the columns: fw.x, fw.y, fw.z must be specified. The xyz positions must be in FlyWire voxel space, which is what you get if you use the copy location tool in the flywire.ai web-interface.

The logic of the update procedure is:, find the flywire_xyz column. If that does not exist, find: fw.x, fw.y, fw.z, and use that to create a flywire_xyz column. We use flywire_xyz if both are given, and there is a mismatch. For each row, a root_id is then found based on these points, using fafbseg::flywire_xyz2id (using the argument rawcoords = TRUE). The google sheet columns root_id,flywire_xyz, fw.x, fw.y, fw.z are then updated if they exist in the original google sheet. If they do not, they are not updated. The function returns a data.frame combining all tabs of all googlesheets specified, but returning only the columns specified by the argument chosen.columns.

See also

flywire_ids, flywire_meta, flywire_neurons

Examples

# \donttest{
if (FALSE) {

# Update flywire_ids in the sheet:
### https://docs.google.com/spreadsheets/d/
### 1rzG1MuZYacM-vbW7100aK8HeA-BY6dWAVXQ7TB6E2cQ
### /edit#gid=0
## And return
fw.gsheet.meta = flywire_ids_update(selected_sheets =
"1rzG1MuZYacM-vbW7100aK8HeA-BY6dWAVXQ7TB6E2cQ")

}# }