hca-metadata-schema 0.2.0__py3-none-any.whl

hca_metadata_schema/__init__.py

@@ -0,0 +1,11 @@
+"""The HCA metadata schema: LinkML YAML definitions and the Pydantic models generated from them.
+
+`CORE_SCHEMA_PATH` is the root schema; it imports every other YAML file shipped here. The models are in
+`hca_metadata_schema.generated.core`, regenerated from the YAML by `make gen-schema`.
+"""
+
+from pathlib import Path
+
+__version__ = "0.2.0"  # x-release-please-version
+
+CORE_SCHEMA_PATH = Path(__file__).parent / "core.yaml"

hca_metadata_schema/bionetwork/adipose.yaml

@@ -0,0 +1,32 @@
+id: https://github.com/clevercanary/hca-validation-tools/schema/bionetwork/adipose
+name: hca-validation-adipose
+title: Adipose BioNetwork Extensions
+description: Adipose network–specific refinements to the HCA dataset schema
+license: MIT
+
+prefixes:
+  linkml: https://w3id.org/linkml/
+  hca: https://github.com/clevercanary/hca-validation-tools/schema/
+
+default_prefix: hca
+default_range: string
+
+imports:
+  - linkml:types
+  - ../dataset
+  - ../slots
+  - ../enums
+
+classes:
+  AdiposeDataset:
+    is_a: Dataset
+    description: Dataset with Adipose BioNetwork–specific metadata requirements.
+    slots:
+      - ambient_count_correction
+      - doublet_detection
+    
+  AdiposeSample:
+    is_a: Sample
+    description: Sample with Adipose BioNetwork–specific metadata requirements.
+    slots:
+      - dissociation_protocol

hca_metadata_schema/bionetwork/gut.yaml

@@ -0,0 +1,35 @@
+id: https://github.com/clevercanary/hca-validation-tools/schema/bionetwork/gut
+name: hca-validation-gut
+title: Gut BioNetwork Extensions
+description: Gut network–specific refinements to the HCA dataset schema
+license: MIT
+
+prefixes:
+  linkml: https://w3id.org/linkml/
+  hca: https://github.com/clevercanary/hca-validation-tools/schema/
+
+default_prefix: hca
+default_range: string
+
+imports:
+  - linkml:types
+  - ../dataset
+  - ../slots
+  - ../enums
+classes:
+  GutDataset:
+    is_a: Dataset
+    description: Dataset with Gut BioNetwork–specific metadata requirements.
+    slots:
+      - ambient_count_correction
+      - doublet_detection
+    
+  GutSample:
+    is_a: Sample
+    description: Sample with Gut BioNetwork–specific metadata requirements.
+    slots:
+      - radial_tissue_term
+      - dissociation_protocol
+    
+
+  

hca_metadata_schema/bionetwork/musculoskeletal.yaml

@@ -0,0 +1,25 @@
+id: https://github.com/clevercanary/hca-validation-tools/schema/bionetwork/musculoskeletal
+name: hca-validation-musculoskeletal
+title: Musculoskeletal BioNetwork Extensions
+description: Musculoskeletal network–specific refinements to the HCA dataset schema
+license: MIT
+
+prefixes:
+  linkml: https://w3id.org/linkml/
+  hca: https://github.com/clevercanary/hca-validation-tools/schema/
+
+default_prefix: hca
+default_range: string
+
+imports:
+  - linkml:types
+  - ../dataset
+  - ../slots
+  - ../enums
+classes:
+  MusculoskeletalDataset:
+    is_a: Dataset
+    description: Dataset with Musculoskeletal BioNetwork–specific metadata requirements.
+    slots:
+      - ambient_count_correction
+      - doublet_detection

hca_metadata_schema/cell.yaml

@@ -0,0 +1,69 @@
+id: https://github.com/clevercanary/hca-validation-tools/schema/cell
+name: hca-validation-cell
+title: HCA Validation Cell Schema
+description: Schema for validating Human Cell Atlas (HCA) cell metadata
+license: MIT
+
+prefixes:
+  linkml: https://w3id.org/linkml/
+  hca: https://github.com/clevercanary/hca-validation-tools/schema/
+
+default_prefix: hca
+default_range: string
+
+imports:
+  - linkml:types
+
+classes:
+  Cell:
+    description: >-
+      A single cell derived from a sample
+    slots:
+      - author_cell_type
+      - cell_type_ontology_term_id
+
+slots:
+  author_cell_type:
+    title: Author Cell Type
+    description: Encoding of author intuition of cellular annotation in the dataset.
+    examples:
+      - value: Goblet cell; microglia
+    annotations:
+      annDataLocation: obs
+      tier: Tier 1
+    range: string
+    required: false
+    multivalued: false
+    comments:
+      - Encoding of author intuition of cellular annotation in their dataset.
+      - >-
+        Retained alongside the ontology term so the author's original naming is not lost
+        when terms are mapped to CL.
+
+  cell_type_ontology_term_id:
+    title: Cell Type Ontology Term ID
+    description: Cell Ontology (CL) term.
+    examples:
+      - value: CL:0001204
+    annotations:
+      annDataLocation: obs
+      tier: Tier 1
+      cxg: cell_type_ontology_term_id
+    range: string
+    required: false
+    multivalued: false
+    notes:
+      - |
+        This must be a Cell Ontology (CL) term (http://www.ebi.ac.uk/ols4/ontologies/cl).
+
+        If no appropriate high-level term can be found or the cell type is unknown, then it is strongly recommended to use 'unknown'.
+
+        The following terms must not be used: "CL:0000255" for eukaryotic cell; "CL:0000257" for Eumycetozoan cell; "CL:0000548" for animal cell.
+      - >-
+        ZFA, FBbt, and WBbt terms are allowed depending on the organism, and "na" is
+        allowed if tissue_type is "cell line" — per the h5ad validator's curie_constraints.
+    comments:
+      - Encoding of cell type to help alignment with other datasets.
+      - >-
+        Unrecoverable once dropped — populate_labels derives cell_type from this column,
+        not the reverse. Optional here to match the h5ad validator's requirement_level.

hca_metadata_schema/core.yaml

@@ -0,0 +1,23 @@
+id: https://github.com/clevercanary/hca-validation-tools/schema/core
+name: hca-validation-core
+title: HCA Validation Core Schema
+description: Core schema for validating Human Cell Atlas (HCA) data
+license: MIT
+version: 0.2.0  # x-release-please-version
+
+prefixes:
+  linkml: https://w3id.org/linkml/
+  hca: https://github.com/clevercanary/hca-validation-tools/schema/
+
+default_prefix: hca
+default_range: string
+
+imports:
+  - linkml:types
+  - dataset
+  - bionetwork/adipose
+  - bionetwork/gut
+  - bionetwork/musculoskeletal
+  - donor
+  - sample
+  - cell

hca_metadata_schema/dataset.yaml

@@ -0,0 +1,297 @@
+id: https://github.com/clevercanary/hca-validation-tools/schema/dataset
+name: hca-validation-dataset
+title: HCA Validation Dataset Schema
+description: Schema for validating Human Cell Atlas (HCA) dataset metadata
+license: MIT
+
+prefixes:
+  linkml: https://w3id.org/linkml/
+  hca: https://github.com/clevercanary/hca-validation-tools/schema/
+
+default_prefix: hca
+default_range: string
+
+imports:
+  - linkml:types
+  - ./enums
+  - ./slots
+
+classes:
+  Dataset:
+    description: >-
+      A collection of data from a single experiment or study in the Human Cell Atlas
+    slots:
+      - alignment_software
+      - assay_ontology_term_id
+      - assay_ontology_term
+      - batch_condition
+      - comments
+      - consortia
+      - contact_email
+      - default_embedding
+      - description
+      - gene_annotation_version
+      - intron_inclusion
+      - protocol_url
+      - publication_doi
+      - reference_genome
+      - sequenced_fragment
+      - sequencing_platform
+      - study_pi
+      - title
+      - dataset_id
+    slot_usage:
+      dataset_id:
+        range: string
+        identifier: true
+
+slots:
+  alignment_software:
+    title: Alignment Software
+    description: Protocol used for alignment analysis, please specify which version was used e.g. cell ranger 2.0, 2.1.1 etc.
+    range: string
+    required: true
+    examples:
+      - value: "cellranger_8.0.0"
+    comments:
+      - Affects which cells are filtered per dataset, and which reads (introns and exons or only exons) are counted as part of the reported transcriptome. This can convey batch effects.
+    annotations:
+      annDataLocation: obs
+
+  assay_ontology_term_id:
+    title: Assay Ontology Term Id
+    description: Platform used for single cell library construction.
+    range: string
+    required: true
+    examples:
+      - value: "EFO:0009922"
+    notes:
+      - |
+        This must be an EFO term and either:
+        - "EFO:0002772" for assay by molecule or preferably its most accurate child
+        - "EFO:0010183" for single cell library construction or preferably its most accurate child
+        - An assay based on 10X Genomics products should either be "EFO:0008995" for 10x technology or preferably its most accurate child.
+        - An assay based on SMART (Switching Mechanism at the 5' end of the RNA Template) or SMARTer technology SHOULD either be "EFO:0010184" for Smart-like or preferably its most accurate child.
+        Recommended:
+        - 10x 3' v2 "EFO:0009899"
+        - 10x 3' v3 "EFO:0009922"
+        - 10x 5' v1 "EFO:0011025"
+        - 10x 5' v2 "EFO:0009900"
+        - Smart-seq2 "EFO:0008931"
+        - Visium Spatial Gene Expression "EFO:0010961"
+    comments:
+      - Major source of batch effect and dataset filtering criterion
+    annotations:
+      cxg: assay_ontology_term_id
+      annDataLocation: obs
+
+  assay_ontology_term:
+    is_a: deprecated_slot
+    title: Assay Ontology Term
+    description: Deprecated placeholder for assay ontology term.
+
+  batch_condition:
+    title: Batch Condition
+    description: >-
+      Name of the covariate that confers the dominant batch effect in the data as judged by the data contributor. 
+      The name provided here should be the label by which this covariate is stored in the AnnData object.
+    range: string
+    multivalued: true
+    required: false
+    examples:
+      - value: '["patient", "seqBatch"]'
+        description: "Multiple batch conditions as a JSON array"
+    notes:
+      - Values must refer to cell metadata keys in obs. Together, these keys define the batches that a normalisation or integration
+        algorithm should be aware of. For example if "patient" and "seqBatch" are keys of vectors of cell metadata, either
+        ["patient"], ["seqBatch"], or ["patient", "seqBatch"] are valid values.
+    annotations:
+      cxg: batch_condition
+      annDataLocation: uns
+
+  comments:
+    title: Comments
+    description: >
+      Other technical or experimental covariates that could affect the quality or batch of the sample. 
+      Must not contain identifiers. This field is designed to capture potential challenges for data integration not captured elsewhere.
+    range: string
+    required: false
+    annotations:
+      annDataLocation: uns
+
+  contact_email:
+    title: Contact Email
+    description: Contact name and email of the submitting person
+    range: Email
+    required: true
+
+  consortia:
+    is_a: deprecated_slot
+    title: Consortia
+    description: Deprecated placeholder for consortia information.
+
+  default_embedding:
+    title: Default Embedding
+    description: The value must match a key to an embedding in obsm for the embedding to display by default in CELLxGENE Explorer.
+    range: string
+    required: false
+    annotations:
+      cxg: default_embedding
+      annDataLocation: uns
+
+  description:
+    title: Description
+    description: Short description of the dataset
+    range: string
+    required: true
+    annotations:
+      annDataLocation: uns
+
+  gene_annotation_version:
+    title: Gene Annotation Version
+    description: >
+      Ensembl release version accession number. Some common codes include:
+      GRCh38.p12 = GCF_000001405.38
+      GRCh38.p13 = GCF_000001405.39
+      GRCh38.p14 = GCF_000001405.40
+    range: string
+    required: true
+    examples:
+      - value: "GCF_000001405.40"
+    notes:
+      - http://www.ensembl.org/info/website/archives/index.html or NCBI/RefSeq
+    comments:
+      - Possible source of batch effect and confounder for some biological analysis
+    annotations:
+      annDataLocation: obs
+
+  intron_inclusion:
+    title: Intron Inclusion
+    description: Were introns included during read counting in the alignment process?
+    range: YesNoEnum
+    required: false
+    examples:
+      - value: "yes"
+      - value: "no"
+    annotations:
+      annDataLocation: obs
+
+  protocol_url:
+    title: Protocol URL
+    description: >
+      The protocols.io URL (if none exists, please use the BioRxiv URL) for the full experimental protocol; 
+      or if multiple protocols exist please list them e.g. sample preparation protocol / sequencing protocol.
+    range: string
+    required: false
+    examples:
+      - value: "https://www.biorxiv.org/content/early/2017/09/24/193219"
+    comments:
+      - Useful to look up protocol data that can provide insight on batch effects. As protocols can sometimes apply to a subset of the study, we capture this at a sample level. This information may not always be available.
+    annotations:
+      annDataLocation: obs
+
+  publication_doi:
+    title: Publication DOI
+    description: >
+      The publication digital object identifier (doi) for the protocol. If no pre-print nor publication exists, please write 'not applicable'.
+    range: string
+    required: false
+    examples:
+      - value: "10.1016/j.cell.2016.07.054"
+
+  reference_genome:
+    title: Reference Genome
+    description: Reference genome used for alignment.
+    range: ReferenceGenomeEnum
+    required: true
+    examples:
+      - value: "GRCm37"
+      - value: "GRCh37"
+    comments:
+      - Possible source of batch effect and confounder for some biological analysis
+    annotations:
+      annDataLocation: obs
+
+  sequenced_fragment:
+    title: Sequenced Fragment
+    description: Which part of the RNA transcript was targeted for sequencing.
+    range: SequencedFragmentEnum
+    required: true
+    examples:
+      - value: "3 prime tag"
+      - value: "full length"
+    comments:
+      - May be a source of batch effect that has to be tested.
+    annotations:
+      annDataLocation: obs
+
+  sequencing_platform:
+    title: Sequencing Platform
+    description: Platform used for sequencing.
+    range: string
+    required: false
+    examples:
+      - value: "EFO:0008563"
+    notes:
+      - Values should be "subClassOf" ["EFO:0002699"] - https://www.ebi.ac.uk/ols/ontologies/efo/terms?iri=http%3A%2F%2Fwww.ebi.ac.uk%2Fefo%2FEFO_0002699
+    comments:
+      - This captures potential strand hopping which may cause data quality issues.
+    annotations:
+      annDataLocation: obs
+
+  study_pi:
+    title: Study Pi
+    description: Principal Investigator(s) leading the study where the data is/was used.
+    range: string
+    multivalued: true
+    required: true
+    examples:
+      - value: '["Teichmann,Sarah,A."]'
+        description: "Principal Investigator in Last Name,MiddleInitial, FirstName format"
+    annotations:
+      annDataLocation: uns
+
+  title:
+    is_a: deprecated_slot
+    title: Title
+    description: >
+      This text describes and differentiates the dataset from other datasets in the same collection. 
+      It is strongly recommended that each dataset title in a collection is unique and does not depend on other metadata 
+      such as a different assay to disambiguate it from other datasets in the collection.
+    range: string
+    examples:
+      - value: "Cells of the adult human heart collection is 'All — Cells of the adult human heart'"
+    comments:
+      - Useful to look up protocol data that can provide insight on batch effects. As protocols can sometimes apply to a subset of the study, we capture this at a sample level. This information may not always be available.
+    annotations:
+      cxg: title
+      annDataLocation: uns
+
+enums:
+  ReferenceGenomeEnum:
+    permissible_values:
+      GRCh37:
+        description: Human reference genome version 37
+      GRCh38:
+        description: Human reference genome version 38
+      GRCm37:
+        description: Mouse reference genome version 37
+      GRCm38:
+        description: Mouse reference genome version 38
+      GRCm39:
+        description: Mouse reference genome version 39
+      "not applicable":
+        description: No reference genome was used
+
+  SequencedFragmentEnum:
+    permissible_values:
+      "3 prime tag":
+        description: 3' end of the transcript
+      "5 prime tag":
+        description: 5' end of the transcript
+      "full length":
+        description: Entire transcript
+      "not applicable":
+        description: Not applicable to this dataset
+      "probe-based":
+        description: Probe-based sequencing

hca_metadata_schema/donor.yaml

@@ -0,0 +1,91 @@
+id: https://github.com/clevercanary/hca-validation-tools/schema/donor
+name: hca-validation-donor
+title: HCA Validation Donor Schema
+description: Schema for validating Human Cell Atlas (HCA) donor metadata
+license: MIT
+
+prefixes:
+  linkml: https://w3id.org/linkml/
+  hca: https://github.com/clevercanary/hca-validation-tools/schema/
+
+default_prefix: hca
+default_range: string
+
+imports:
+  - linkml:types
+  - ./slots
+
+classes:
+  Donor:
+    description: >-
+      An individual organism from which biological samples have been derived
+    slots:
+      - donor_id
+      - organism_ontology_term_id
+      - sex_ontology_term_id
+      - sex_ontology_term
+      - manner_of_death
+      - dataset_id
+    slot_usage:
+      donor_id:
+        range: string
+        identifier: true
+        # Annotations are duplicated here to get around an apparent bug in inheriting them (https://github.com/linkml/linkml/issues/2805)
+        annotations:
+          annDataLocation: obs
+          tier: Tier 1
+          cxg: donor_id
+
+slots:
+  sex_ontology_term_id:
+    title: Sex Ontology Term ID
+    description: Reported sex of the donor.
+    range: string
+    required: true
+    notes: >
+      This must be a child of PATO:0001894 for phenotypic sex
+      or "unknown" if unavailable.
+    examples:
+      - value: "PATO:0000383"
+        description: female
+      - value: "PATO:0000384"
+        description: male
+    annotations:
+      annDataLocation: obs
+      cxg: sex_ontology_term_id
+  
+  sex_ontology_term:
+    is_a: deprecated_slot
+    title: Sex Ontology Term
+    description: Deprecated placeholder for sex ontology term.
+  
+  manner_of_death:
+    title: Manner of Death
+    description: |
+      Manner of death classification based on the Hardy Scale or "unknown" or "not applicable":
+      * Category 1 = Violent and fast death — deaths due to accident, blunt force trauma or suicide, terminal phase < 10 min.
+      * Category 2 = Fast death of natural causes — sudden unexpected deaths of reasonably healthy people, terminal phase < 1 h.
+      * Category 3 = Intermediate death — terminal phase 1–24 h, patients ill but death unexpected.
+      * Category 4 = Slow death — terminal phase > 1 day (e.g. cancer, chronic pulmonary disease).
+      * Category 0 = Ventilator case — on a ventilator immediately before death.
+      * Unknown = The cause of death is unknown.
+      * Not applicable = Subject is alive.
+      [Leave blank for embryonic/fetal tissue.]
+    range: MannerOfDeath
+    required: true
+    examples:
+      - value: "1"
+    notes: "1; 2; 3; 4; 0; unknown; not applicable"
+    annotations:
+      annDataLocation: obs
+
+  organism_ontology_term_id:
+    title: Organism Ontology Term ID
+    description: The name given to the type of organism, collected in NCBITaxon:0000 format.
+    range: Organism
+    required: true
+    notes: "\"NCBITaxon:9606\" for Homo sapiens or \"NCBITaxon:10090\" for Mus musculus."
+    annotations:
+      annDataLocation: obs
+      cxg: organism_ontology_term_id
+      tier: Tier 1