core.yaml

id: https://w3id.org/nmdc/core
name: NMDC-Core
title: NMDC Schema Core Types
description: Schema for National Microbiome Data Collaborative (NMDC), Core Types

license: https://creativecommons.org/publicdomain/zero/1.0/

imports:
  - basic_slots
  - external_identifiers
  - prov

prefixes:
  KEGG.COMPOUND: "https://bioregistry.io/kegg.compound:"
  SIO: http://semanticscience.org/resource/SIO_
  UniProtKB: "https://bioregistry.io/uniprot:"
  biolink: https://w3id.org/biolink/vocab/
  dcterms: http://purl.org/dc/terms/
  linkml: https://w3id.org/linkml/
  nmdc: https://w3id.org/nmdc/
  qud: http://qudt.org/1.1/schema/qudt#
  rdf: http://www.w3.org/1999/02/22-rdf-syntax-ns#
  schema: http://schema.org/
  wgs84: http://www.w3.org/2003/01/geo/wgs84_pos#
  OBI: http://purl.obolibrary.org/obo/OBI_

default_prefix: nmdc
default_range: string


subsets:
  environment: { }
  investigation: { }
  nucleic acid sequence source: { }
  sequencing: { }

types:

  bytes:
    description: An integer value that corresponds to a size in bytes
    base: int
    uri: xsd:long
    see_also:
      - UO:0000233
  
  decimal degree:
    description: A decimal degree expresses latitude or longitude as decimal fractions.
    uri: xsd:decimal
    base: float
    see_also:
      - https://en.wikipedia.org/wiki/Decimal_degrees

  language code:
    description: A language code conforming to ISO_639-1
    see_also:
      - https://en.wikipedia.org/wiki/ISO_639-1
    base: str
    uri: xsd:language

  unit:
    base: str
    uri: xsd:string
    mappings:
      - qud:Unit
      - UO:0000000

enums:
  DeviceEnum:
    permissible_values:
      Orbital Shaker:
      Thermomixer:
      Vortex:
      Agitation plunger:
      Drying oven:
      CEREX System 96 processor:

classes:

  NamedThing:
    description: "a databased entity or concept/class"
    abstract: true
    slots:
      - id
      - name
      - description
      - alternative_identifiers

  #  DataGeneratingInstrument:
  #    slots:
  #      - model
  #      - name # range: DeviceEnum ? # see also "used" and "instrument_name"
  #      - vendor
  #    aliases:
  #      - device
  #    description: An identified thing that is capable of generating scientific data
  #    comments:
  #      - Likely a capital investment. One would want to say "I used this serial number"
  #    todos:
  #      - add examples, like a Thermo Electron Orbitrap
  #    is_a: NamedThing
  #    slot_usage:
  #      id:
  #        required: true
  #        structured_pattern:
  #          syntax: "{id_nmdc_prefix}:inst-{id_shoulder}-{id_blade}{id_version}{id_locus}"
  #          interpolated: true
  #    exact_mappings:
  #      - OBI:0000485

  MaterialEntity:
    abstract: true
    aliases:
      - Material
      - Physical entity
    is_a: NamedThing
    title: Material Entity

  ProcessedSample:
    is_a: MaterialEntity
    title: Processed Sample
    slots:
      - biomaterial_purity
      - dna_absorb1
      - dna_concentration
      - external_database_identifiers
    #      - nucleic_acid_concentration
    slot_usage:
      id:
        required: true
        structured_pattern:
          syntax: "{id_nmdc_prefix}:procsm-{id_shoulder}-{id_blade}{id_version}{id_locus}"
          interpolated: true

  AnalyticalSample:
    is_a: MaterialEntity
    title: Analytical Sample
    slot_usage:
      id:
        required: true
        structured_pattern:
          syntax: "{id_nmdc_prefix}:ansm-{id_shoulder}-{id_blade}{id_version}{id_locus}"
          interpolated: true

  Site:
    abstract: true
    is_a: MaterialEntity
    title: Site
    comments:
      - BCO sample collection site ?
    slot_usage:
      id:
        required: true
        structured_pattern:
          syntax: "{id_nmdc_prefix}:site-{id_shoulder}-{id_blade}{id_version}{id_locus}"
          interpolated: true

  PlannedProcess:
    abstract: true
    class_uri: OBI:0000011
    is_a: NamedThing
    title: Planned Process
    slots:
      - designated_class
      - end_date
      - has_input
      - has_output
      - processing_institution
      - protocol_link
      - start_date
      - instrument_name # or "used" ?
      - qc_status
      - qc_comment
      - has_failure_categorization

    slot_usage:
      designated_class:
        comments:
          - required on all instances in a polymorphic Database slot like planned_process_set
     

  OntologyClass:
    is_a: NamedThing
    notes:
      - The identifiers for terms from external ontologies can't have their ids constrained to the nmdc namespace
    slot_usage:
      id:
        pattern: '^[a-zA-Z0-9][a-zA-Z0-9_\.]+:[a-zA-Z0-9_][a-zA-Z0-9_\-\/\.,]*$'

  EnvironmentalMaterialTerm:
    is_a: OntologyClass

  AttributeValue:
    description: >-
      The value for any value of a attribute for a sample. This object can hold both the un-normalized atomic
      value and the structured value
    slots:
      - has_raw_value
    slot_usage:
      type:
        description: An optional string that specified the type of object.

  QuantityValue:
    is_a: AttributeValue
    description: A simple quantity, e.g. 2cm
    slots:
      - has_maximum_numeric_value
      - has_minimum_numeric_value
      - has_numeric_value
      - has_raw_value
      - has_unit
    slot_usage:
      has_raw_value:
        description: Unnormalized atomic string representation, should in syntax {number} {unit}
      has_unit:
        description: The unit of the quantity
      has_numeric_value:
        description: The number part of the quantity
        range: double
    mappings:
      - schema:QuantityValue

  ImageValue:
    is_a: AttributeValue
    description: An attribute value representing an image.
    slots:
      - url
      - description
      - display_order
  
  PersonValue:
    is_a: AttributeValue
    description: An attribute value representing a person
    slots:
      - email
      - name
      - orcid
      - profile_image_url
      - websites
    todos:
      - add additional fields e.g for institution
      - deprecate "has_raw_value" in favor of "name"
    slot_usage:
      orcid:
        annotations:
          display_hint: Open Researcher and Contributor ID for this person. See https://orcid.org
      email:
        annotations:
          display_hint: Email address for this person.
      has_raw_value:
        description: The full name of the Investigator in format FIRST LAST.
        notes:
          - May eventually be deprecated in favor of "name".
      name:
        description: >-
          The full name of the Investigator.
          It should follow the format FIRST [MIDDLE NAME| MIDDLE INITIAL] LAST, where MIDDLE NAME| MIDDLE INITIAL is optional.
        annotations:
          display_hint: First name, middle initial, and last name of this person.
  
  MagBin:
    slots:
      - bin_name
      - bin_quality
      - completeness
      - contamination
      - gene_count
      - gtdbtk_class
      - gtdbtk_domain
      - gtdbtk_family
      - gtdbtk_genus
      - gtdbtk_order
      - gtdbtk_phylum
      - gtdbtk_species
      - members_id
      - num_16s
      - num_23s
      - num_5s
      - num_t_rna
      - number_of_contig
      - total_bases
      - type

  MetaboliteQuantification:
    description: This is used to link a metabolomics analysis workflow to a specific metabolite
    slots:
      - alternative_identifiers
      - highest_similarity_score
      - metabolite_quantified

  PeptideQuantification:
    description: This is used to link a metaproteomics analysis workflow to a specific peptide sequence and related information
    slots:
      - all_proteins
      - best_protein
      - min_q_value
      - peptide_sequence
      - peptide_spectral_count
      - peptide_sum_masic_abundance
  
  ProteinQuantification:
    description: This is used to link a metaproteomics analysis workflow to a specific protein
    slots:
      - all_proteins
      - best_protein
      - peptide_sequence_count
      - protein_spectral_count
      - protein_sum_masic_abundance
    slot_usage:
      best_protein:
        description: the specific protein identifier most correctly grouped to its associated peptide sequences
      all_proteins:
        description: the grouped list of protein identifiers associated with the peptide sequences that were grouped to a best protein

  ChemicalEntity:
    aliases:
      - metabolite
      - chemical substance
      - chemical compound
      - chemical
    is_a: OntologyClass
    description: >-
      An atom or molecule that can be represented with a chemical formula. Include lipids, glycans, natural products, drugs.
      There may be different terms for distinct acid-base forms, protonation states
    comments:
      - As with the parent OntologyClass, we will not assign an nmdc id pattern or typecode to this class.
    slots:
      - chemical_formula
      - inchi
      - inchi_key
      - smiles

    see_also:
      - https://bioconductor.org/packages/devel/data/annotation/vignettes/metaboliteIDmapping/inst/doc/metaboliteIDmapping.html
    id_prefixes:
      - cas
      - CHEBI
      - CHEMBL.COMPOUND
      - DRUGBANK
      - HMDB
      - KEGG.COMPOUND
      - MESH
      - PUBCHEM.COMPOUND
    exact_mappings:
      - biolink:ChemicalSubstance

  GeneProduct:
    is_a: NamedThing
    description: A molecule encoded by a gene that has an evolved function
    notes:
      - we may include a more general gene product class in future to allow for ncRNA annotation
    id_prefixes:
      - PR
      - UniProtKB
      - gtpo
    exact_mappings:
      - biolink:GeneProduct

  TextValue:
    is_a: AttributeValue
    description: A basic string value
    slots:
      - language

  UrlValue:
    is_a: AttributeValue
    description: A value that is a string that conforms to URL syntax

  TimestampValue:
    is_a: AttributeValue
    description: A value that is a timestamp. The range should be ISO-8601
    notes:
      - "removed the following slots: year, month, day"

  IntegerValue:
    is_a: AttributeValue
    description: A value that is an integer
    slots:
      - has_numeric_value

  BooleanValue:
    is_a: AttributeValue
    description: A value that is a boolean
    slots:
      - has_boolean_value

  ControlledTermValue:
    is_a: AttributeValue
    description: A controlled term or class from an ontology
    slots:
      - term
    todos:
      - add fields for ontology, branch

  ControlledIdentifiedTermValue:
    description: A controlled term or class from an ontology, requiring the presence of term with an id
    notes:
      - To be used for slots like env_broad_scale
    is_a: ControlledTermValue
    slot_usage:
      term:
        required: true

  GeolocationValue:
    is_a: AttributeValue
    description: A normalized value for a location on the earth's surface
    slots:
      - latitude
      - longitude
    notes:
      - "what did 'to_str: {latitude} {longitude}' mean?"
    slot_usage:
      has_raw_value:
        description: The raw value for a geolocation should follow {latitude} {longitude}
      latitude:
        required: true
      longitude:
        required: true
    mappings:
      - schema:GeoCoordinates

slots:
  total_bases:
    domain: MagBin
    range: integer # MAM 2023-12-08
    todos:
      - this slot needs some basic textual annotations and constraints
  members_id:
    domain: MagBin
    range: string
    todos:
      - this slot needs some basic textual annotations and constraints
  bin_name:
    range: string
  number_of_contig:
    range: integer
  completeness:
    range: float
  contamination:
    range: float
  gene_count:
    range: integer
  bin_quality:
    range: string
  num_16s:
    range: integer
  num_5s:
    range: integer
  num_23s:
    range: integer
  num_t_rna:
    range: integer
  gtdbtk_domain:
    range: string
  gtdbtk_phylum:
    range: string
  gtdbtk_class:
    range: string
  gtdbtk_order:
    range: string
  gtdbtk_family:
    range: string
  gtdbtk_genus:
    range: string
  gtdbtk_species:
    range: string

  language:
    range: language code
    description: Should use ISO 639-1 code e.g. "en", "fr"

#  attribute:
#    aliases:
#      - field
#      - property
#      - template field
#      - key
#      - characteristic
#    abstract: true
#    description: >-
#      A attribute of a biosample. Examples: depth, habitat, material.
#      For NMDC, attributes SHOULD be mapped to terms within a MIxS template

  has_raw_value:
    description: The value that was specified for an annotation in raw form, i.e. a string. E.g. "2 cm" or "2-4 cm"
    multivalued: false
    domain: AttributeValue
    range: string

  has_unit:
    description: Links a QuantityValue to a unit
    aliases:
      - scale
    domain: QuantityValue
    range: unit
    mappings:
      - qud:unit
      - schema:unitCode

  has_numeric_value:
    description: Links a quantity value to a number
    multivalued: false
    domain: QuantityValue
    range: float
    mappings:
      - qud:quantityValue
      - schema:value
  
  has_minimum_numeric_value:
    is_a: has_numeric_value
    domain: QuantityValue
    description: The minimum value part, expressed as number, of the quantity value when the value covers a range.

  has_maximum_numeric_value:
    is_a: has_numeric_value
    domain: QuantityValue
    description: The maximum value part, expressed as number, of the quantity value when the value covers a range.
  
  has_boolean_value:
    description: Links a quantity value to a boolean
    range: boolean
    multivalued: false
  
  latitude:
    domain: GeolocationValue
    range: decimal degree
    description: latitude
    slot_uri: wgs84:lat
    examples:
      - value: -33.460524
    mappings:
      - schema:latitude

  longitude:
    domain: GeolocationValue
    range: decimal degree
    description: longitude
    slot_uri: wgs84:long
    examples:
      - value: 150.168149
    mappings:
      - schema:longitude

  term:
    domain: ControlledTermValue
    range: OntologyClass
    description: pointer to an ontology class
    inlined: true
    notes:
      - "removed 'slot_uri: rdf:type'"

  orcid:
    description: The ORCID of a person.
    domain: PersonValue
    range: string

  email:
    description: >-
      An email address for an entity such as a person.
      This should be the primary email address used.
    range: string
    slot_uri: schema:email

  alternate_emails:
    description: One or more other email addresses for an entity.
    range: string

  profile_image_url:
    description: A url that points to an image of a person.
    domain: PersonValue
    range: string
  
  has_input:
    aliases:
      - input
    domain: NamedThing
    range: NamedThing
    multivalued: true
    description: >-
      An input to a process.

  has_output:
    aliases:
      - output
    domain: NamedThing
    range: NamedThing
    multivalued: true
    description: An output biosample to a processing step

  part_of:
    aliases:
      - is part of
    range: NamedThing
    domain: NamedThing
    multivalued: true
    slot_uri: dcterms:isPartOf
    description: Links a resource to another resource that either logically or physically includes it.
  
  execution_resource:
    domain: Activity
    range: string
#    is_a: attribute
    examples:
      - value: NERSC-Cori

  url:
#    is_a: attribute
    range: string
    notes:
      - See issue 207 - this clashes with the mixs field
  
  display_order:
    #    is_a: attribute
    domain: ImageValue
    range: integer
    description: When rendering information, this attribute to specify the order in which the information should be rendered.

  git_url:
#    is_a: attribute
    range: string
    examples:
      - value: "https://github.com/microbiomedata/mg_annotation/releases/tag/0.1"

  file_size_bytes:
#    is_a: attribute
    domain: DataObject
    range: bytes
    description: Size of the file in bytes
  
  md5_checksum:
#    is_a: attribute
    range: string
    description: MD5 checksum of file (pre-compressed)

  keywords:
    range: string
    multivalued: true
    description: >-
      A list of keywords that used to associate the entity.
      Keywords SHOULD come from controlled vocabularies, including MESH, ENVO.
    mappings:
      - dcterms:subject
  
  objective:
    range: string
    multivalued: false
    description: >-
      The scientific objectives associated with the entity.
      It SHOULD correspond to scientific norms for objectives field in a structured abstract.
    mappings:
      - SIO:000337

  websites:
    range: string
    multivalued: true
    pattern: ^[Hh][Tt][Tt][Pp][Ss]?:\/\/(?!.*[Dd][Oo][Ii]\.[Oo][Rr][Gg]).*$
    description: A list of websites that are associated with the entity.
    comments: 
      - DOIs should not be included as websites. Instead, use the associated_dois slot. 
      - A consortium's homepage website should be included in the homepage_website slot, not in websites.

  homepage_website:
    is_a: websites
    maximum_cardinality: 1
    description: The website address (URL) of an entity's homepage.
    examples:
      - value: https://www.neonscience.org/
        
  highest_similarity_score:
    todos:
      - Yuri to fill in description
    range: float

  metabolite_quantified:
    description: the specific metabolite identifier
    domain: MetaboliteQuantification
    range: ChemicalEntity

  all_proteins:
    description: the list of protein identifiers that are associated with the peptide sequence
    range: GeneProduct
    multivalued: true
  best_protein:
    description: the specific protein identifier most correctly associated with the peptide sequence
    range: GeneProduct
  min_q_value:
    description: smallest Q-Value associated with the peptide sequence as provided by MSGFPlus tool
    range: float
    see_also:
      - OBI:0001442
  peptide_sequence:
    range: string
  peptide_spectral_count:
    description: sum of filter passing MS2 spectra associated with the peptide sequence within a given LC-MS/MS data file
    range: integer
  peptide_sum_masic_abundance:
    description: >-
      combined MS1 extracted ion chromatograms derived from MS2 spectra associated with the peptide sequence from a given LC-MS/MS data file using the MASIC tool
    range: integer

  chemical_formula:
    description: A generic grouping for molecular formulae and empirical formulae
    range: string

  inchi_key:
    range: string
    notes:
      - "key set to false due to rare collisions: Pletnev I, Erin A, McNaught A, Blinov K, Tchekhovskoi D, Heller S (2012) InChIKey collision resistance: an experimental testing. J Cheminform. 4:12"
  inchi:
    range: string
  peptide_sequence_count:
    description: count of peptide sequences grouped to the best_protein
    range: integer
  protein_spectral_count:
    description: sum of filter passing MS2 spectra associated with the best protein within a given LC-MS/MS data file
    range: integer
  protein_sum_masic_abundance:
    description: >-
      combined MS1 extracted ion chromatograms derived from MS2 spectra associated with the best protein from a given LC-MS/MS data file using the MASIC tool
    range: integer
  smiles:
    description: >-
      A string encoding of a molecular graph, no chiral or isotopic information. There are usually a large number of valid SMILES which represent a given structure. For example, CCO, OCC and C(O)C all specify the structure of ethanol.
    multivalued: true
    range: string