crantr is an R package designed to support the analysis of connectome data sets for clonal raider ants (Ooceraea biroi, formerly Cerapachys biroi). The package primarily focuses on proofread auto-segmentation data from the CRANT (Clonal Raider Ant) project.
This project has a community based in the CRANT slack.
The project was foudned as a collaboration between the laboratories of Wei-Chung Allen Lee,
Daniel Kronauer and Hannah Haberkern,
among others.
The project lead is Lindsey Lopes.
For the time being, there is a single ant brain connectome under construction,CRANTb
.
Clonal raider ants (Ooceraea biroi) are a fascinating species of ant known for their unique reproductive biology and social structure:
- They reproduce through parthenogenesis, meaning all individuals are female clones.
- They lack a queen caste, with all individuals capable of laying eggs.
- They alternate between reproductive and brood care phases in synchronized cycles.
- They exhibit collective hunting behavior, raiding other ant colonies for their larvae.
These characteristics make clonal raider ants an excellent model system for studying the neural basis of social behavior and the evolution of eusociality in insects.
At present, the connectome data for one brain is available: CRANTb, which represents the brain of a worker clonal raider ant.
The crantr package serves as a wrapper over the fafbseg package, the wrapper adds:
- Setup of necessary default paths / data redirects.
- Integration with CAVE tables for storing various annotation information.
- Relevant helper functions called from the bancr package.
- CLANT project specific data wrangling and browsing code.
You can install the development version of crantr
from GitHub:
remotes::install_github('flyconnectome/crantr')
To use the crantr package, you need authorisation to access CRANT resources.
Follow these steps to set up your access CAVE token, if you have been given authorisation:
# Set up token - will open your browser to generate a new token
crant_set_token()
# If you already have a token:
# crant_set_token("<my token>")
To ensure everything is set up correctly, run:
# Diagnose issues
dr_crant()
# Confirm functionality (should return FALSE)
crant_islatest("576460752684030043")
Some functions rely on underlying Python code. To install the full set of recommended libraries, including fafbseg-py
, run:
fafbseg::simple_python("full")
fafbseg::simple_python('none', pkgs='numpy~=1.23.5')
fafbseg::simple_python(pkgs="pcg_skel")
If you encounter errors related to cloud-volume, update it with:
fafbseg::simple_python('none', pkgs='cloud-volume~=8.32.1')
Use with_crant()
to wrap additional fafbseg::flywire_*
functions for use with CRANT data.
Alternatively, use choose_crant()
to set all flywire_*
functions from fafbseg
to target CRANT.
Usefully the package contains the main use cases, functions named like crant_*
.
This is likely the main way you want to use this package.
Example:
library(crantr)
choose_crant()
# Your analysis code here, .e.g.
neuron.mesh <- crant_read_neuron_meshes("576460752684030043")
plot3d(neuron.mesh, col = "purple")
To update the package and all dependencies:
remotes::install_github('flyconnectome/crantr')
To update a specific Python library dependency:
fafbseg::simple_python(pkgs='fafbseg')
Project lead Lindsey Lopes in the Kronauer group is interested in the olfactory system of the ant, and so some of the earliest reconstruction was done in the ant antennal lobe.
Let us look at some antennal lobe projection neurons.
If you are a collaborator on the project and have access to our seatable, you can do this:
# load library
library(crantr)
# get meta data, will one dya be available via CAVE tables
ac <- crant_table_query()
# Quickly update all of our IDs
ac <- crant_updateids(ac)
# have a look at it!
View(ac)
# filter to get our IDs
pn.meta <- ac %>%
dplyr::filter(cell_class=="olfactory_projection_neuron")
# get our ids
pn.ids <- unique(pn.meta$root_id)
If not, here are some neuron IDs to get started:
# load library
library(crantr)
# specify IDs to examine, could also be gotten from a CAVE table
pn.ids <- c("576460752684030043", "576460752688452399", "576460752688452655",
"576460752666304186", "576460752683636730", "576460752724736013")
You can do important operations such as update the 'root' IDs for a CRANT reconstruction, as so.
# update these IDs to their most current versions, they change after each proofreading edit
pn.ids <- crant_latestid(pn.ids)
Now we can read mesh data for these reconstructions and plot them together with a surface model of the CRANTb
brain, using rgl
!
# fetch
pn.meshes <- crant_read_neuron_meshes(pn.ids)
# plot brain
crant_view()
plot3d(crantb.surf, col = "lightgrey", alpha = 0.1)
# plot neurons
plot3d(pn.meshes)
We can also make this plot in 2D, in the popular ggplot2
framework.
# ggplot
crant_ggneuron(pn.meshes , volume = crantb.surf)
Sometimes it is also useful for work with skeletons, for example for NBLASTing neurons. We can swiftly fetch the L2 skeletons of a neuron, built from its supervoxel locations using the python library pcg_skel, as so:
# You may need to run this before the belows works, should just need it once:
## fafbseg::simple_python('none', pkgs='numpy~=1.23.5')
## fafbseg::simple_python(pkgs="pcg_skel")
# fetch
pn.skels <- crant_read_l2skel(pn.ids)
# plot brain
nopen3d()
crant_view()
plot3d(crantb.surf, col = "lightgrey", alpha = 0.1)
# plot neurons
plot3d(pn.skels, lwd = 1)
These are the raw ingredients to start morphological analyses in CRANTb
using the natverse!
We hope to come: neuron annotations, synapses, transmitter predictions, dense core vesicle predictions, possibly other organelles, etc ....
Seatable is a powerful way to make collaborative annotations in this connectome dataset and we encourage you to use it rather than keeping your own google sheets or similar to track neurons. It works similarly to google sheets, but has better filter views, data type management, programmatic access, etc.
It should work in the browser and as an app.
See our seatable here. If this link does not work you can request access by contacting Lindsey Lopes.
Each row is a CRANTb
neuron. If you hover your tool-tip over the i icon in each column header, you can see what that column records.
You can access the seatable programmatically using the crantr
, if you have access.
You will first need to obtain your authorised login credentials, you only need to do this once:
crant_table_set_token(user="MY_EMAIL_FOR_SEATABLE.com",
pwd="MY_SEATABLE_PASSWORD",
url="https://cloud.seatable.io/")
And then you may read the data, and make nice plots from it!
# Read BANC meta seatable
ac <- crant_table_query()
You can also update rows automatically. Be careful when doing this. If you want to be sure not to mess something up, you can take a 'snapshot' of the seatable before you edit it in the browser, which will save a historical version.
You can then change column in ac
, keeping their names, as youl ike. Then to update via R:
# Update
crant_table_update_rows(base="CRANTb"",
table = "CRANTb_meta",
df = bc.new,
append_allowed = FALSE,
chunksize = 100)
You can also make a quick, simpler update, replacing one column's entries with a given update
for a set of root IDs.
crant_table_annotate(root_ids = c("576460752667713229",
"576460752662519193",
"576460752730083020",
"576460752673660716",
"576460752662521753"),
update = "lindsey_lopes",
overwrite = FALSE,
append = FALSE,
column = "user_annotator")
To update, you must have the seatable identifier for each column in ac.new
, i.e. an _id
column.
This method is good for bulk uploads/changes.
When using CRANT data, please acknowledge it in accordance with the CRANT community guidelines and in agreement with the CRANT consortium.
If you use this package, please cite:
- The upcoming CRANT paper (TBD)
- The natverse paper: Bates et al. 2020
- This R package:
citation(package = "crantr")
Bates A (2024). crantr: R Client Access to the Brain And Nerve Cord (CRANT) Dataset. R package version 0.1.0, https://github.com/flyconnectome/crantr.
- CRANT data set: Collected at Harvard Medical School in the laboratory of Wei-Chung Allen Lee, by Wangchu Xiang and Lindsey Lopes.
- Segmentation and synapse prediction: Built by Zetta.ai.
- Neuron reconstruction: Hosted and supported by the laboratory of Wei-Chung Allen Lee and the Kronauer Laboratory at the Rockerfeller Institute.
- R package: Initialized using the fancr package developed by Greg Jefferis at the MRC Laboratory of Molecular Biology, Cambridge, UK.
- Development: Alexander S. Bates worked on this R package while in the laboratory of Rachel Wilson at Harvard Medical School.
Bates, Alexander Shakeel, James D. Manton, Sridhar R. Jagannathan, Marta Costa, Philipp Schlegel, Torsten Rohlfing, and Gregory SXE Jefferis. 2020. The Natverse, a Versatile Toolbox for Combining and Analysing Neuroanatomical Data. eLife 9 (April). https://doi.org/10.7554/eLife.53350.