S1. Preparing a new taxonomy for TDT annotation

[hkir-dev]

Epic:

Description

User: A scientist with a lot of biological and computational skills and basic knowledge of GitHub. Use Case: I have just completed a version of a taxonomy (AIT99) that I am happy with and I’m ready to share it with colleagues for joint annotation. What I have:

• An h5ad file in AIT format with the cell by gene matrix, cell-level metadata, cluster relationships (including taxonomy ‘levels’), dendrogram (with marker genes for each node)
• Initial cluster annotations (e.g., with data-driven summarizes and optional initial manual annotations), either embedded in the h5ad or in a separate table (e.g., Google sheet or csv) What I need to know:
• File preparation
  • What fields (“columns”) are required for input files to make sure my taxonomy can be annotated with TDT?
  • How do I need to format the input files prior to sharing? Is an AIT h5ad file (+ an annotation table?) sufficient?
  • Where do I need to put the files for joint annotation?
• How can I set up TDT on my computer properly (see Use Case 2 #99 )? Are there any extra steps required for setting up a new taxonomy?
• How do I confirm that AIT99 is created properly and ready for annotation?
• What, specifically, do I share with my colleagues so that they can annotate as well?
  • I’ve heard about GitHub and PURLs and CAS but I don’t know what they are. Do I need to worry about that?

Tasks

• [x] #44
• [ ] #111

[dosumis]

What fields (“columns”) are required for input files to make sure my taxonomy can be annotated with TDT?

• There are no compulsory columns. Users need to submit a configuration file that adds some general metadata and documents what the columns in the input table refer to. We will improve doc (#44). We also plan to support configuration through the UI in future.
  • How do I need to format the input files prior to sharing? Is an AIT h5ad file (+ an annotation table?) sufficient?

If the taxonomy is represented in both an AIT h5ad file AND a table - the two must be in sync - columns names must match OBS names, taxonomy structure will match. However, we test this on initial load and report any problems back to users.

What, specifically, do I share with my colleagues so that they can annotate as well?

Currently the best way to do this is to share the repo. Your colleagues can then check out the repo and set it up TDT as per doc.

I’ve heard about GitHub and PURLs and CAS but I don’t know what they are. Do I need to worry about that?

See #111

GitHub - Generally no, except that all users MUST have a GitHub Account. Users also currently need to be able to check out (clone) a GitHub repo (our doc will recommend using GitHub Desktop to do this as it wraps the command line setup & linking to account etc). In future we hope to be able to wrap this step with our UI.

PURLs - Only in as far as they provide a simple way to generate and share versions as URLs via never change.

CAS - No need to know, although computationally savvy users familiar with Python may want to learn to use CAS-Tools.