CellxGene Ontology Guide is a filtered and curated collection of ontological metadata from different public sources. The primary goal is to serve the ontology needs of the CellxGene project and its associated tools. An API for querying the data is also provided.
This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to [email protected].
If you believe you have found a security issue, please responsibly disclose by contacting us at [email protected].
Release-please is used to manage the release process for this repository. To make changes to how releases are managed, update .release-please.yml. [This GHA workflow](.github/workflows/release. yml) performs the release.
For instruction on how to release the different components of this repository, see the following:
The ontology-assets directory contains static ontology assets that are used by CellxGene project. The jsonschema for these assets are stored in asset-schemas.
This is a description of the files within the ontology-assets directory:
- ontology_info.json contains the ontology versions used by the current and deprecated cellxgene-schema
- The
*.json.gzfiles are filtered version of ontology sources found in ontology_info.json. They are generated using the GHA workflow generate_all_ontology.yml and the all_ontology_generator.py script. - The
*_list.jsonfiles are manually curated and are used to filter the ontologies. - The
*_descendants.jsonare descendant mapping files. They are generated on a weekly bases using the GHA workflow generate_descendant_mappings.yml and the generate_descendant_mappings.py script.
Older version of cellxgene-schema will be fully deprecated after 6 months of the release of a new version.
TODO: document the process for deprecating ontologies
The latest tag is use to idenitfy the latest version of the descendant mappings for downsteam consumers to use. To retrieve the latest version of the descendant mappings, use the following urls:
- tissue -
https://github.com/chanzuckerberg/cellxgene-ontology-guide/blob/latest/ontology-assets/tissue_descendants.json - cell type -
https://github.com/chanzuckerberg/cellxgene-ontology-guide/blob/latest/ontology-assets/cell_type_descendants.json
Each release will be tagged and versioned within a GitHub Release using the SemVer Versioning schema. The format of the version will be MAJOR.MINOR.PATCH, where MAJOR and MINOR indicate the compatibility of the change. A new version will be released for the following reasons(not an exhaustive list):
- A Patch version will be created whenever the source ontology files are updated.
- A Minor version will be created whenever new fields or files are added to the precomputed ontology files.
- A Major version will be created when fields or files are removed from the precomputed ontology files.
- A version update will be created if a fix is required related to how the files are computed. This would likely be a Major or Minor update.
To release a new version of the ontology assets, merge a pull request to main. Release-please will automatically create a PR with the a version bump if needed. Merging the release-please PR will create a new release in github with a tagged version. Releasing the ontology assets will also result in a release of the python API. Closing the PR will skip the release of these changes and they will be included in the next release.
The GHA workflow tag-latest-ontology-assets.yml will automatically update the latest tag when the appropriate.
- Update the ontology_info.json file with the new schema version
- Leave the older versions in the file for backward compatibility. They will be deprecated and removed automatically after 6 months. That process is handled in deprecate_previous_cellxgene_schema_versions.