-
Notifications
You must be signed in to change notification settings - Fork 1
banc‐bot user manual
@banc-bot is a slackbot that makes it easy to interact with the BANC's annotations, e.g. labels that describe cell types, proofreading status, etc in the dataset. Interacting with @banc-bot involves simply typing messages to it in a Slack direct message. This manual will tell you everything you need to know about how to chat with the bot to get the information you want or to post new annotations yourself. (@banc-bot doesn't use anything fancy like GPT to help interpret your messages, instead it only recognizes messages that fit the patterns listed below.)
To interact with the BANC's annotations effectively, it will help to first familiarize yourself with the current list of annotations we use, listed here
@banc-bot is currently running in the #banc channel on the FlyWire Forum Slack workspace. To access it:
- Join us in the FlyWire Forum Slack workspace
- Join the #banc channel
- Search for "banc-bot" in the Slack search bar and click on 🏦
banc-bot [APP] - Send it the message "help" and you should get a welcome message. If so, you're good to go.
Example messages you can send to @banc-bot to test out the find feature:
- find neck motor neuron
- findids neck motor neuron
- findnum neck motor neuron
- find neck motor neuron and soma on left
- find neck motor neuron and soma on left and not soma in VNC
As shown in the examples, send the bot a message starting with the word "find" followed by the term you want to search for, or a combination of search terms separated by and, optionally with not to exclude some terms. You can use as many terms as you want separated by ands. If you use findids you'll get a list of segment IDs instead of a neuroglancer link. If you use findnum you'll get only the number of matching cells but not their IDs or a link.
If you want to do an or search, e.g. find all ascending OR descending neurons that have their soma on the left side, currently the best option is to do two searches, one after the other: "find ascending and soma on left" and then "find descending and soma on left". This may be improved in the future.
Example messages you can send to @banc-bot to test out annotation queries:
- 720575941539792220?
- 720575941539792220??
- 110568, 107775, 3100?
- 110568, 107775, 3100??
These 4 messages are all different ways of requesting information about a neuron (it happens to be a neck motor neuron).
- The first two examples use the neuron's segment ID, copied from the right bar of neuroglancer.
- The third and fourth examples use the coordinate of a point inside that neuron, copied from the top left corner of neuroglancer.
- You can use one
?to request a basic list of annotations on the neuron, or you can use two??to request the neuron's annotations with additional details (e.g. when each annotation was posted, who posted it, which CAVE table it comes from).
Annotations should be added to cells only after the cell has been proofread enough to be recognizable – for example, a neuron should probably have a cell body, a dendritic region, and an axonal region. If a cell doesn't look anywhere near proofread yet, consider making some edits to help it look more accurately reconstructed before adding an annotation. Once a neuron is proofread to be in decent shape, you will often want to start by marking a cell as proofread via a message that looks like:
- 110568, 107775, 3100! backbone proofread
where the point coordinate you choose must be a point inside the large-diameter backbone of the neuron, which you're sure won't be cut off as proofreading continues. (For example 110568, 107775, 3100 in the message above – view that location in neuroglancer.) IMPORTANT: Do NOT right click on a neuron's mesh in 3D and then use the point you end up at – this point is often one pixel outside the boundary of the neuron. Check in 2D that your point is right in the center of a thick branch of the neuron you want to annotate!
After this, you can start posting information about the cell via messages like the following ones – you could try running these exact commands as a test, but @banc-bot will just tell you that the cell already has this annotation:
- 720575941539792220! motor neuron
- 110568, 107775, 3100! motor neuron
These examples annotate a cell as a motor neuron. You can use the first type of message where you provide the cell's segment ID if the cell has already been marked as backbone proofread, or already has a point in one of the other "anchor point" tables like neck_connective. However if the cell you're trying to annotated doesn't yet have an "anchor point", the bot won't know where to put your annotation if you just provide a segment ID. Instead, @banc-bot will request that you provide a specific point at which to put the annotation, as shown in the second example message above.
For a complete list of the "standard" annotations we have in the BANC, check out our dedicated page on Annotations (cell types, etc.). As an example, if you found this claw chordotonal sensory neuron and wanted to annotate it, you'd send @banc-bot the following messages (one at a time, waiting for a reply from the bot after each one):
- 158012, 149966, 2921! backbone proofread
- 720575941507004194! claw chordotonal neuron
The second message would actually add 3 annotations to the cell: sensory neuron, chordotonal neuron, and finally claw chordotonal neuron (as determined by the standard annotation hierarchy). After successfully posting these annotations, you can ask the bot 720575941507004194? or 720575941507004194?? to see all the annotations that are now on this cell.
We are constantly expanding our list of standard annotations for the BANC. If you have a suggestion of something to add to what's currently listed on Annotations (cell types, etc.), which @banc-bot would then recognize, definitely post about it in the FlyWire Slack to see what everyone thinks and get your annotation added!
If you want to annotate a neuron's identity (it's "name"), something that isn't in our list of standard annotations, you can do that by sending a message like:
- 720575941460783117! neuron identity: DNx01
- 122244, 92500, 2598! neuron identity: DNx01
By including neuron identity: in front of your annotation, @banc-bot will accept any text you put afterward. (Otherwise, @banc-bot only accepts text that's listed over on Annotations (cell types, etc.).) These neuron identity: annotations are stored in the database slightly differently to keep them separate from the standard annotations, but you can still see these identity annotations like normal if you ask for 720575941460783117? or 720575941460783117?? (but notice that in the response to the ?? message, you'll see that the annotation_class is neuron identity for this annotation).
Neurons may have many names/identities. In fact, it's encouraged! Feel free to add the name that you or your lab uses for a neuron, even if that neuron has already been given one or more names by other members of the community.
Finally, you can upload absolutely anything you want about a neuron using the freeform: keyword:
- 114513, 127120, 1682! freeform: this cell has a really weird shape, I can't even tell if it's a neuron or a glia!
If you find yourself using the same freeform annotation many times, it would be great if you pause and ask on Slack for that annotation to be added as a standard annotation (see Annotations (cell types, etc.)) instead of continuing to use it as a freeform one.
These sorts of messages will delete an annotation on a neuron, if you're the one who made that annotation:
- 720575941622740682- motor neuron
- 110568, 107775, 3100- motor neuron
These look just like the ! commands used to add annotations, but with a - (minus sign) instead.
If you try to delete an annotation that someone else made, the bot won't delete it but instead will tell you who made the annotation so you can contact them and ask them to delete the annotation if you want to.
Warning: This is a fairly new feature that still has some room for improvement! Please feel free to provide feedback if you have suggestions about ways to change/improve it.
The goal of this command is to allow users to get a short list of cells that need attention – "need attention" can be defined in many different ways, so we provide a few different types of todo commands.
- Send the bot the message
todo helpto get a list of all the different available types oftodocommands, each of which allow you to ask for cells from a particular region of the dataset. - For example
todo gngwill give you cells to proofread from the gnathal ganglion (GNG). You will see thatgngis an option because it is listed in thetodo helpcommand. You can try running similar commands replacinggngwith other search names that you see from the help command.
- Jasper recorded a demo of proofreading and annotating using @banc-bot (18 mins for the basics / 44 mins for the basics plus additional proofreading and annotation demonstrations)
- @banc-bot's source code is available in the current GitHub repository, here. If you're interested in setting up your own slackbot to do something similar, instructions are written at the top of the source code that describe how to do it.
- If you have suggestions for improvements or new feature requests, feel free to open a new issue or post about it on the FlyWire Forum to discuss it with other members of the community.