We have recently introduced a new feature in cellxgene that enables users to create and edit categorical annotations within the app. We’d love for you to try it out and give us feedback!
To get started, run:
cellxgene launch mydata.h5ad
To preserve data provenance,
cellxgene does not alter the input h5ad file. Rather, newly-created annotations are saved in a specified CSV file:
annotations-directoryis your current working directory (i.e., the directory you were in when you started cellxgene).
########; this helps cellxgene identify your file to avoid overwriting your work.
Cellxgene allows you to load and edit compatible draft annotations across multiple sessions.
Compatible annotations are tabular, with category names as column headers;
anndata.obs.index as the index; and categorical values (i.e., fewer unique values per column than specified in
--max-category-items, default 1000).
There are two options for updating draft annotations.
Cellxgene will automatically find and reload your draft annotations in editable mode.
This assumes that:
1 - The h5ad filename is the same
2 - You launch cellxgene from the
annotations-directory (i.e., the directory that contains your CSV)
3 - You use the same browser and have not cleared your cookies (we use a small cookie to keep track of which user created the file to avoid accidental overwrites; see FAQ)
This mode is only appropriate for single-user, local cellxgene instances.
If you’d like to specify the complete file path for your annotations, you can do so by running:
cellxgene launch mydata.h5ad --annotations-file path/to/myfile.csv
Any changes you make will be reflected in the original CSV. If the file does not exist, it will be created.
Please note that this file will be overwritten, making this mode inappropriate for hosted / multi-user settings (see below).
Once you’re finished with your annotations, you should finalize and preserve your work by merging your
csv into your main
You can do so like this:
import pandas as pd import scanpy as sc new_annotations = pd.read_csv('myannotations.csv', comment='#', dtype='category', index_col=0) anndata = sc.read('mydata.h5ad') anndata.obs = anndata.obs.join(new_annotations)
As described in the hosted section, we do not officially support hosted or multi-user use of cellxgene. However, we recognize that the app is often adapted for this purpose, and have tried to provide a “safe path” for multi-user setups that avoids overwriting data.
Specifying a single file name for multiple contributors will result in data overwriting. To avoid this, you can instead specify an output directory and allow cellxgene to assign filenames.
To specify an output directory, run:
cellxgene launch mydata.h5ad --annotations-dir path/to/annotations-directory/
For each user, annotations will be saved as follows:
########; this helps cellxgene identify their specific file to avoid overwriting others’ work.
cellxgene autosaves any changes made to your annotations every 3 seconds.
Not to worry! We save the last 10 versions of your annotations in
Continuous metadata is important! However, these values (e.g., pseudotime) are the result of statistical analyses that are beyond cellxgene’s visualization- and exploration-focused scope. We do, of course, provide visualization of continuous metadata values computed elsewhere and stored in
This is most likely because the h5ad file you are working with is not the original file used to generate the annotations! We recommend merging new annotations in on a regular basis for this reason.
We place a small cookie (file) in your browser that identifies where your draft annotations are saved. This file never leaves your machine, and is never sent to the cellxgene team or anyone else.
Wonderful! This is a relatively new feature; we would love to hear your feedback :)