Manually review split neurons and save your results to a Google Sheet for everyone to use

Source: R/hemibrain_save_split.R

A 3D interactive pipeline for reviewing our hemibrain_precomputed_splitpoints. Each user can manually edit neurons if needs be, add whether or not they have a soma or are cropped, and make additional notes. The purpose of this function if for interested users to work together to curate axon-dendrite splits suggested by the flow_centrality algorithm. Currently, this function is built to review our most promising set of split points (hemibrain_splitpoints_polypre_centrifugal_synapses). As the Google sheet gets updated, new manual splits will be re-saved into this package, as hemibrain_manual_splitpoints and implemented as default for those neurons when using hemibrain_flow_centrality and hemibrain_read_neurons.For this function to work, you may have to add the Google Sheet database to your Google Drive.

hemibrain_task_update(
  bodyids,
  update,
  gs = NULL,
  selected_file = "1YjkVjokXL4p4Q6BR-rGGGKWecXU370D1YMc1mgUYr8E",
  column = c("soma.edit", "cut", "truncated", "manual_edit", "splittable", "checked",
    "user", "time", "note", "priority", "edited.cable", "skeletonization")
)

hemibrain_adjust_saved_split(
  bodyids = NULL,
  phases = c("complete", "I", "II", "III"),
  db = NULL,
  check_thresh = 1,
  batch_size = 10,
  by.type = TRUE,
  assignments = TRUE,
  brain = hemibrainr::hemibrain.surf,
  update_regularly = TRUE,
  motivate = TRUE,
  clean = TRUE,
  prioritise = TRUE,
  selected_file = "1YjkVjokXL4p4Q6BR-rGGGKWecXU370D1YMc1mgUYr8E",
  selected_col = "#fadadd",
  ...
)

Arguments

bodyids

bodyids which specify individual neurons, as used in the relevant neuPrint project
update

a vector of length(bodyids) or 1, which will replace cells in the column specified by column for given bodyids (bodyids). E.g. If I wanted to changed the given bodyids on the task sheet to checked = TRUE, I would use update = TRUE.
gs

A Google sheet object, as read by googlesheets4::read_sheet(selected_file).
selected_file

an optional path to a yaml file that already contains a selection
column

the column in the split-check task's Google Sheet (specified by selected_file) to be updated with the value of the argument update. E.g. If I wanted to changed the given bodyids on the task sheet to checked = TRUE, I would use column = "check".
phases

which Phases of the split check process you want to engage with. Phase I involves choosing which neurons need to be manually split, making notes on them and marking if they are truncated by by the volume or not Phase II involves manually splitting those neurons that have been flagged as as in need to splitting. And Phase III involves reviewing the manual splits that have been made, and re-splitting neurons if needs be. The default, complete, is to go through all three phases with sequential batches of neurons, of batch_size.
db

a neuronlist object to act as a database of neuron skeletons. If you want to provide all hemibrain neurons that could possibly be split, then you can use hemibrain_download_neurons to download all hemibrain neurons as a nat::neuronlistfh file. All neurons can be read using db = hemibrain_read_neurons(savedir=TRUE). This can then be given as the argument to db.
check_thresh

when checking skeleton splits and correcting them, we do not want to look at skeletons that have already been checked by others many times. If a skeleton has already been checked by this many users or more, it will not be given to the user to edit.
batch_size

when reviewing splits for hemibrain neurons, we examine neurons (or putative cell types, see parameter by.type) in batches of this size. We then go through two phases, choosing neurons that are incorrect in some way (wrongly split, cropped) and then editing them manually, before saving them to a Google Sheet. You may not have access to this Google Sheet, in which case you will not be able to contribute manual splits for neurons to this package. Contact us if you would like access.
by.type

logical. If TRUE then putative cell types (as assigned as the type field in neuPrint) of neurons are presented. The number of cell types pulled are of size batch_size.
assignments

logical. If TRUE then the user is invited to examine only neurons that they are flagged for them. These are entries into the 'roots' tab of the Google Sheet, where the user column is the same as the initials the user enters.
brain

which brain to plot while splitting neuron. If NULL no brain is plotted. Otherwise it is recommended to use hemibrain.surf (which is in raw voxel space).
update_regularly

whether or not to read from the Google Sheet database regularly, to avoid duplicating manual splits. Should be set to TRUE unless reading the Google Sheet introduces a prohibitive time delay.
motivate

whether or not to plot 2D motivationals from InspiroBot to keep to entertained while splitting neurons.
clean

whether or not to set synapse-less branches to Label = 0.
prioritise

whether or not to look at higher priority neurons first. Initial, this means olfactory system neurons.
selected_col

the color in which selected neurons (such as those specified in selected_file) should be plotted
...

additional arguments passed to plotting functions, such as plot3d_split and nlscan_split

Value

Updates a Google Sheet which records whether neurons have been checked in one tab ("roots") and records actual manually made splits in a second tab ("manual").

Details

the pipeline works in three phases and you choose to take a batch_size of X neurons/types (defaults to 10) through these stages:

  • Phase I - choose which neurons are okay and which need modifying / are truncated / are unsplittable / have a bad soma, etc.

  • Phase II - manually edit those neurons that need modifying. Top tip: You can ‘cycle’ through branches and update them to a certain cable type one at a time. This works by removing the primary neurite and linker, so it is good to define these first for a neuron, and then cycle through branches as a quick way to assign axon/dendrite.

  • Phase III - Review manually modified neurons.

If you have authentication issues with the Google sheet, look here first. Video tutorial: https://drive.google.com/open?id=1FB7m1QFKApysO74maHAx-yg2CQWkx49C

Examples

# \donttest{
if (FALSE) {
# Assign mPN review to Nik Drummond (ND)
hemibrain_task_update(bodyids = mpn.ids, column = "user", update = "ND")

# Assign members of the FlyConnectome group to work on their favourite neurons:
ton.batches = split(hemibrainr::ton.ids,
  ceiling(seq_along(1:length(hemibrainr::ton.ids))/2700))
hemibrain_task_update(bodyids =
  c(hemibrainr::upn.ids, hemibrainr::mpn.ids, hemibrainr::orn.ids),
  column = "user", update = "ND")
hemibrain_task_update(bodyids = hemibrainr::dan.ids, column = "user", update = "GD")
hemibrain_task_update(bodyids = c(hemibrainr::vppn.ids,hemibrainr::hrn.ids),
  column = "user", update = "RT")
hemibrain_task_update(bodyids = hemibrainr::alln.ids, column = "user", update = "TS")
hemibrain_task_update(bodyids = hemibrainr::mbon.ids, column = "user", update = "MWP")
hemibrain_task_update(bodyids = ton.batches[[1]], column = "user", update = "AJ")
hemibrain_task_update(bodyids = ton.batches[[2]], column = "user", update = "IT")
hemibrain_task_update(bodyids = ton.batches[[3]], column = "user", update = "JH")
}# }
# \donttest{
if (FALSE) {
# Plot splits to check them, correcting any errors, and saving your changes
nat::nopen3d()
hemibrain_adjust_saved_split()

# In order to read neurons more quickly from a local source / Google Drive
db = hemibrain_neurons()
nat::nopen3d()
hemibrain_adjust_saved_split(db=db)

# We can also try to correct somas en masse
nat::nopen3d()
hemibrain_adjust_saved_somas()
}# }