Match up neurons between the hemibrain and FAFB

Source: R/flywire_matching.R, R/hemibrain_matching.R

Match up neurons between the hemibrain, FAFB and light level data and save the result using a Google Sheet on the hemibrain Google Team Drive operated by the flyconnectome group at the University of Cambridge. Your aim is to match the light blue neuron to the best red neuron! You must have access to the Team Drive in order to use this function. This function makes use of the Google Filestream application or rclone, which should be installed on your machine. Further, note that neurons are read from the FAFB CATMAID project when repository=="CATMAID", and you must have login details for this project recorded in your .Renviron for these functions to work. You are given neurons assigned to your initials on the matching google sheet (the User column) though you can look at other's assigned matches using superUser=TRUE. Your selection is further narrowed by omitting neurons whose matches have already been made, when using the default overwrite="TRUE". However, you can change this to overwrite matches, and to review made matches.

LR_matching(
  ids = NULL,
  threshold = 0,
  mirror.nblast = NULL,
  selected_file = options()$hemibrainr_matching_gsheet,
  batch_size = 50,
  db = flywire_neurons(),
  query = flywire_neurons(mirror = TRUE),
  overwrite = c("FALSE", "bad", "TRUE", "review"),
  column = NULL,
  entry = NULL,
  User = NULL,
  superUser = FALSE,
  flywire.good = FALSE,
  verbose = FALSE
)

hemibrain_matching(
  ids = NULL,
  hemibrain.nblast = NULL,
  threshold = 0,
  selected_file = options()$hemibrainr_matching_gsheet,
  batch_size = 50,
  db = NULL,
  repository = c("flywire", "CATMAID", "lm"),
  query = hemibrain_neurons(brain = "FAFB14"),
  overwrite = c("FALSE", "bad", "TRUE", "review"),
  column = NULL,
  entry = NULL,
  User = NULL,
  superUser = FALSE,
  verbose = FALSE
)

lm_matching(
  ids = NULL,
  hemibrain.nblast = NULL,
  selected_file = options()$hemibrainr_matching_gsheet,
  batch_size = 50,
  db = hemibrain_neurons(),
  query = NULL,
  overwrite = c("FALSE", "bad", "TRUE", "review"),
  column = NULL,
  entry = NULL,
  User = NULL,
  superUser = FALSE
)

fafb_matching(
  ids = NULL,
  repository = c("flywire", "CATMAID"),
  hemibrain.nblast = NULL,
  threshold = 0,
  selected_file = options()$hemibrainr_matching_gsheet,
  batch_size = 20,
  db = hemibrain_neurons(brain = "FAFB14"),
  query = NULL,
  overwrite = c("FALSE", "bad", "TRUE", "review"),
  column = NULL,
  entry = NULL,
  User = NULL,
  superUser = FALSE,
  flywire.good = FALSE
)

Arguments

ids

body IDs for hemibrain neurons present in the Google Sheet, for which the user will attempt to make a match if one has not been made already. Else, LM neuron IDs in the tab 'lm' when using lm_matching.
threshold

the minimum normalised NBLAST score between query and target neurons, for the potential match to be show. If set to NULL then all hits can be shown.
mirror.nblast

a flywire (rows) - flywire-mirrored (columns) normalised NBLAST matrix. By default this is read from the hemibrain Team Drive.
selected_file

the Google Sheet database to read and write from. For now, defaults to this Google Sheet.
batch_size

the number of FAFB top matches to read from CATMAID in one go.
db

Either a neuronlist or the name of a character vector naming a neuronlist. Defaults to the value of hemibrain_neurons().
query

a neuronlist of neurons for matching. Should correspond to the given NBLAST matrix. Defaults to reading a transformed most.lhns from the Hemibrain Google Team Drive.
overwrite

Whether or not to overwrite matches already made. The neurons you could possibly be looking at are selected through the arguments: ids, column, entry. If ids is NULL you will be given all neurons that have been assigned to your user on the Google sheet. If overwrite is set to "FALSE", you will not overwrite any matches that have already been made from among the selected neurons. If "TRUE" (be careful!) then you overwrite made matches among the selected neurons. If "bad" then you can overwrite made matches that are 'tract-only' or 'none'. If "review" then you will only be shown already-matched neurons, which appear in green. If you make no new selection (hit 't' to exit selection mode) then the made selection will persist. If ids is not NULL, then the selected neurons will be further sub-setted by their unique id. Note that selection also works with superUser, the default is to only take neurons allocated to you. In order to change this, you can user superUser=TRUE.
column

defaults to NULL, no further subsetting. Else, you can select a column from the Google sheet. Only neurons with a certain value (entry) in that column will be chosen for matching.
entry

defaults to NULL, no further subsetting. Else, it is a value in column.
User

the initials of the matching 'Users', i.e. you, which should also be recorded on the master matching google sheet. However, you can enter a new user for the matches you make in R. If set to NULL then all Users are 'selected'.
superUser

if FALSE then you will only be given neurons flagged for your user. If TRUE then you will be given neurons flagged for any user. To select whether or not you want to look at neurons with no match, neurons with a match or either, use the overwrite argument.
flywire.good

logical, whether or not to only take 'well traced' flywire neurons, as annotated by the Drosophila Connectomics Group. This relies on the status column retrieved by flywire_meta.
verbose

logical. If TRUE the pipeline pauses for each neuron that is missing from the NBLAST/data set.
hemibrain.nblast

a FAFB (rows) - hemibrain (columns) normalised NBLAST matrix. By default this is read from the flyconnectome Team Drive.
repository

whether to match up FAFB skeletons from CATMAID (using catmaid::read.neurons.catmaid) or flywire (using flywire_neurons) for matching. Alternatively,light level skeletons ("lm") from Dolan et al. and Frechter et al. 2019 (eLife), stored in the package lhns as most.lhns.

Details

Currently, the Google Sheet is set up with limited number of users, each of whom have been assigned a number of neurons to match up. In order to add yourself as a user, simply open this Google Sheet in your browser and add your initials to neurons of your choosing on the rightmost column 'Users'. Once a match is recorded, the user selects a quality for that match. There can be no match (none), a poor match (poor) an okay match (okay) or an exact match (good). As a rule of thumb, a poor match could be a neuron from a very similar same cell type or a highly untraced neuron that may be the correct cell_type. An okay match should be a neuron that looks to be from the same morphological cell type but there may be some discrepancies in its arbour. A good match is a neuron that corresponds well between FAFB and the hemibrain data.

See also

hemibrain_adjust_saved_split

Examples

# \donttest{
if (FALSE) {

# install package to bridge neurons between FAFB14 and hemibrain space
if (!requireNamespace("remotes")) install.packages("remotes")
remotes::install_github('natverse/nat.jrcbrains')
nat.jrcbrains::download_saalfeldlab_registrations()

# Load precomputed NBLAST from the flyconnectome Team Drive
load(file.path("/Volumes/GoogleDrive/Shared drives/flyconnectome/",
  "fafbpipeline/fib.fafb.crossnblast.twigs5.mean.compress.rda"))
# Sometimes the filenames are changed by drive
# load(file.path("/Volumes/GoogleDrive/Shared drives/flyconnectome",
# "fafbpipeline/fib.fafb.crossnblast.twigs5.mean.compress (1).rda"))

# Match!
hemibrain_matching(hemibrain.nblast = fib.fafb.crossnblast.twigs5.mean.compress)

# And example of matching neurons in a flywire tracing sheet
sheet = flywire_tracing_sheet("SLPal2_dorsal", regex = TRUE)
fafb_matching(ids = unique(sheet$root_id), repository="flywire",
overwrite = "bad", User = "AJ", superUser = TRUE)

# Look at all poorly made matches
fafb_matching(repository="flywire", column = "hemibrain_match_quality",
entry = "poor", overwrite = "TRUE", User = "AJ", superUser = TRUE)
}# }