template_example.yml

apiVersion: neotoma v2.0
headers: 2
kind: Development
# ─────────────────────────────────────────────────────────────────────────────
# Universal DataBUS Template
#
# This template covers the union of fields seen across SISAL, 210Pb, NODE-OST,
# EANODE-OST, and Pollen datasets. Each entry maps a CSV column name to its
# target field in the Neotoma database.
#
# Columns marked "required: true" must be present and non-null for a dataset
# to pass validation. Everything else is optional and may be left blank (or
# the row omitted from the CSV entirely).
#
# If there are `id` elements, they can be set to string, however there will
# be a search for their corresponding integer ID in the database. If a match is not found, the dataset
# will fail validation. This allows users to specify values using familiar names
# instead of opaque integer IDs. For example, a user can specify "John Doe" for
# the collector, and the system will look up the corresponding contact ID.
#
# DataBUS does not insert new publications, contacts, or variables. If a value is not found in the database, the
# steward must indicate which new values need to be inserted to the DB or insert them via Tilia.
#
# "rowwise: true"  → the column has one value per sample row.
# "rowwise: false" → the column has a single value shared by all rows.
#
# ── WIDE DATA FORMAT ─────────────────────────────────────────────────────────
# DataBUS expects data in WIDE format: each variable (taxon/proxy) is its own
# column in the CSV file. This is in contrast to narrow/long format where a
# single "Value" column holds all measurements.
#
# Wide format CSV example (210Pb-style):
#
#   Depth | 210Pb_alpha | Dry.Mass | 137Cs  | 210Pb_alpha.Units | ...
#   1.0   | 15.2        | 0.52     | 0.003  | Bq/kg             | ...
#   2.0   | 14.8        | 0.55     | 0.004  | Bq/kg             | ...
#   3.0   | 14.1        | 0.58     | 0.005  | Bq/kg             | ...
#
# Wide format CSV example (SISAL-style):
#
#   depth | d18O   | d13C   | d18O.error | d13C.error | interp_age | ...
#   1.0   | -5.21  | -8.41  | 0.10       | 0.05       | 1250.0     | ...
#   2.5   | -5.18  | -8.35  | 0.11       | 0.06       | 1300.0     | ...
#
# Each wide-format column that holds measurement data MUST have a `taxonname`
# key in its YAML entry (see the "Data values" section below).
# ─────────────────────────────────────────────────────────────────────────────
metadata:
# ── Dataset metadata (constants) ─────────────────────────────────────────────
- column: datasettypeid
  neotoma: ndb.datasettypes.datasettypeid
  required: true
  value: null
  notes: >
    Set to the dataset type name string, e.g. "pollen", "Lead 210",
    "speleothem", "ostracode surface sample", etc.

- column: databasename
  neotoma: ndb.datasetdatabases.databasename
  required: true
  value: null
  notes: Name of the contributing database (e.g. SISAL, African Pollen Database).

# ── Site ─────────────────────────────────────────────────────────────────────
- column: SiteName
  neotoma: ndb.sites.sitename
  required: true
  rowwise: false
  type: string

- column: Latitude
  neotoma: ndb.sites.geog.latitude
  required: true
  rowwise: false
  type: float

- column: Longitude
  neotoma: ndb.sites.geog.longitude
  required: true
  rowwise: false
  type: float

- column: Altitude
  neotoma: ndb.sites.altitude
  required: false
  rowwise: false
  type: float

- column: SiteArea
  neotoma: ndb.sites.area
  required: false
  rowwise: false
  type: float

- column: SiteDescription
  neotoma: ndb.sites.sitedescription
  required: false
  rowwise: false
  type: string

- column: SiteNotes
  neotoma: ndb.sites.notes
  required: false
  rowwise: false
  type: string

# ── Geopolitical Units ────────────────────────────────────────────────────────
- column: Country
  neotoma: ndb.sitegeopolitical.national_unit
  required: false
  rowwise: false
  type: string
  vocab: [fixed]

- column: StateProvince
  neotoma: ndb.sitegeopolitical.subnational_unit_lv1
  required: false
  rowwise: false
  type: string
  vocab: [fixed]

- column: County
  neotoma: ndb.sitegeopolitical.subnational_unit_lv2
  required: false
  rowwise: false
  type: string
  vocab: [fixed]

# ── Collection Unit ───────────────────────────────────────────────────────────
- column: Handle
  neotoma: ndb.collectionunits.handle
  required: false
  overwrite: true
  rowwise: false
  type: string
  notes: Short unique identifier for the collection unit (≤10 chars).

- column: CollectionUnitName
  neotoma: ndb.collectionunits.collunitname
  required: false
  rowwise: false
  type: string

- column: CollectionType
  neotoma: ndb.collectionunits.colltypeid
  required: false
  rowwise: false
  type: string

- column: DepositionalEnvironment
  neotoma: ndb.collectionunits.depenvtid
  required: false
  rowwise: false
  type: string

- column: CollectionDate
  neotoma: ndb.collectionunits.colldate
  formatorrange: '%Y-%m-%d'
  required: false
  rowwise: false
  type: date

- column: CollectionDevice
  neotoma: ndb.collectionunits.colldevice
  required: false
  rowwise: false
  type: string

- column: GPSLatitude
  neotoma: ndb.collectionunits.geog.latitude
  required: false
  rowwise: false
  type: float

- column: GPSLongitude
  neotoma: ndb.collectionunits.geog.longitude
  required: false
  rowwise: false
  type: float

- column: GPSAltitude
  neotoma: ndb.collectionunits.gpsaltitude
  required: false
  rowwise: false
  type: float

- column: GPSError
  neotoma: ndb.collectionunits.gpserror
  required: false
  rowwise: false
  type: float

- column: WaterDepth
  neotoma: ndb.collectionunits.waterdepth
  required: false
  rowwise: false
  type: float

- column: Substrate
  neotoma: ndb.collectionunits.substrateid
  required: false
  rowwise: false
  type: string

- column: SlopeAngle
  neotoma: ndb.collectionunits.slopeangle
  required: false
  rowwise: false
  type: float

- column: SlopeAspect
  neotoma: ndb.collectionunits.slopeaspect
  required: false
  rowwise: false
  type: float

- column: Location
  neotoma: ndb.collectionunits.location
  required: false
  rowwise: false
  type: string

- column: CollectionUnitNotes
  neotoma: ndb.collectionunits.notes
  required: false
  rowwise: false
  type: string

# ── Dataset ──────────────────────────────────────────────────────────────────
- column: DatasetName
  neotoma: ndb.datasets.datasetname
  required: false
  rowwise: false
  type: string

- column: DatasetNotes
  neotoma: ndb.datasets.notes
  required: false
  rowwise: false
  type: string

# ── Analysis Units ────────────────────────────────────────────────────────────
- column: Depth
  neotoma: ndb.analysisunits.depth
  required: false
  overwrite: true
  rowwise: true
  type: float

- column: Thickness
  neotoma: ndb.analysisunits.thickness
  required: false
  overwrite: true
  rowwise: true
  type: float

- column: AnalysisUnitName
  neotoma: ndb.analysisunits.analysisunitname
  required: false
  rowwise: true
  type: string

# ── Chronology ────────────────────────────────────────────────────────────────
# The `chronologyname` key groups related fields into a single age model.
#
# Every field that belongs to the same chronology must share the same
# `chronologyname` value. This key is how DataBUS knows which agemodel,
# agebounds, contact, and sampleage columns belong together.
#
# A dataset can define MULTIPLE chronologies by using different
# `chronologyname` values (e.g., one for a 210Pb model and another for a
# calibrated radiocarbon model). See the SISAL template for an example with
# "interp_author" and "lin_interp_SISAL", and the 210Pb template for "X210Pb".
#
# Example (from the 210Pb template):
#
#   column: X210.LeadModel
#   neotoma: ndb.chronologies.agemodel
#   chronologyname: X210Pb        ← names this chronology "X210Pb"
#
#   column: X210Pb.Date
#   neotoma: ndb.chronologies.age
#   chronologyname: X210Pb        ← ties the age column to the same model
#
#   column: X210Pb.Date
#   neotoma: ndb.sampleages.age
#   chronologyname: X210Pb        ← sampleages also linked by chronologyname
#
- column: ChronologyName
  neotoma: ndb.chronologies.chronologyname
  required: false
  rowwise: false
  type: string
  chronologyname: DefaultChronology

- column: AgeModel
  neotoma: ndb.chronologies.agemodel
  required: false
  rowwise: false
  type: string
  chronologyname: DefaultChronology

- column: AgeType
  neotoma: ndb.chronologies.agetypeid
  required: false
  rowwise: false
  type: string
  chronologyname: DefaultChronology

- column: AgeBoundOlder
  neotoma: ndb.chronologies.ageboundolder
  required: false
  rowwise: false
  type: float
  chronologyname: DefaultChronology

- column: AgeBoundYounger
  neotoma: ndb.chronologies.ageboundyounger
  required: false
  rowwise: false
  type: float
  chronologyname: DefaultChronology

- column: DatePrepared
  neotoma: ndb.chronologies.dateprepared
  required: false
  rowwise: false
  type: string
  chronologyname: DefaultChronology

- column: ChronologyNotes
  neotoma: ndb.chronologies.notes
  required: false
  rowwise: false
  type: string
  chronologyname: DefaultChronology

- column: ChronPreparer
  neotoma: ndb.chronologies.contactname
  required: false
  rowwise: false
  type: string
  chronologyname: DefaultChronology

# ── Chron Controls ────────────────────────────────────────────────────────────
- column: Depth
  neotoma: ndb.chroncontrols.depth
  required: false
  rowwise: true
  type: float

- column: Thickness
  neotoma: ndb.chroncontrols.thickness
  required: false
  rowwise: true
  type: float

- column: ChronControlAge
  neotoma: ndb.chroncontrols.age
  required: false
  rowwise: true
  type: float

- column: ChronControlAgeYounger
  neotoma: ndb.chroncontrols.agelimityounger
  required: false
  rowwise: true
  type: float

- column: ChronControlAgeOlder
  neotoma: ndb.chroncontrols.agelimitolder
  required: false
  rowwise: true
  type: float

- column: ChronControlType
  neotoma: ndb.chroncontrols.chroncontroltypeid
  required: false
  rowwise: true
  type: string

- column: AgeType
  neotoma: ndb.chroncontrols.agetypeid
  required: false
  rowwise: true
  type: string

# ── Geochronology ─────────────────────────────────────────────────────────────
- column: GeochronAge
  neotoma: ndb.geochronology.age
  required: false
  rowwise: true
  type: float

- column: GeochronType
  neotoma: ndb.geochronology.geochrontypeid
  required: false
  rowwise: true
  type: string

- column: GeochronAgeType
  neotoma: ndb.geochronology.agetypeid
  required: false
  rowwise: true
  type: string

- column: GeochronErrorOlder
  neotoma: ndb.geochronology.errorolder
  required: false
  rowwise: true
  type: float

- column: GeochronErrorYounger
  neotoma: ndb.geochronology.erroryounger
  required: false
  rowwise: true
  type: float

- column: LabNumber
  neotoma: ndb.geochronology.labnumber
  required: false
  rowwise: true
  type: string

- column: MaterialDated
  neotoma: ndb.geochronology.materialdated
  required: false
  rowwise: true
  type: string

# ── Sample Ages ────────────────────────────────────────────────────────────────
- column: SampleAge
  neotoma: ndb.sampleages.age
  required: false
  rowwise: true
  type: float
  chronologyname: DefaultChronology

- column: SampleAgeOlder
  neotoma: ndb.sampleages.ageolder
  required: false
  rowwise: true
  type: float
  chronologyname: DefaultChronology

- column: SampleAgeYounger
  neotoma: ndb.sampleages.ageyounger
  required: false
  rowwise: true
  type: float
  chronologyname: DefaultChronology

- column: SampleAgeModel
  neotoma: ndb.sampleages.agemodel
  required: false
  rowwise: false
  type: string
  chronologyname: DefaultChronology

# ── Data values (WIDE FORMAT) ─────────────────────────────────────────────────
# In wide format, each proxy/variable column in the CSV has its own YAML entry
# that maps it to ndb.data.value and carries a `taxonname` key.
#
# ─── taxonname (CRITICAL for data columns) ───────────────────────────────────
# The `taxonname` key links a CSV column to a specific Neotoma taxon.
# It MUST be present for every column mapped to ndb.data.value and for the
# corresponding units column. Without it, the column is silently ignored.
#
# Rules:
#   - The value must match the taxon name in the Neotoma database exactly.
#   - Both the data column AND its units column must carry the same taxonname.
#   - DataBUS does not create new taxa. If the taxon is not found in Neotoma,
#     validation will fail and the steward must add the taxon via Tilia first.
#
# Example pair (data column + units column, from the 210Pb template):
#
#   column: Unsupported.210Pb              ← CSV column name
#   neotoma: ndb.data.value
#   taxonname: Excess 210Pb               ← Neotoma taxon name (MUST exist in DB)
#   rowwise: true
#   type: float
#   unitcolumn: Unsupported.210Pb.Units   ← name of the matching units column
#
#   column: Unsupported.210Pb.Units       ← units CSV column
#   neotoma: ndb.variables.variableunitsid
#   taxonname: Excess 210Pb               ← MUST match the data column's taxonname
#   rowwise: true
#   type: string
#
# Replace the entries below with your actual variable columns.
# Add one pair (value + units) for every proxy/taxon in your dataset.
# ─────────────────────────────────────────────────────────────────────────────

- column: MyVariable1
  neotoma: ndb.data.value
  taxonname: my variable 1 neotoma name   # REQUIRED – exact Neotoma taxon name
  required: false
  rowwise: true
  type: float
  unitcolumn: MyVariable1.Units           # CSV column that holds the units string

- column: MyVariable1.Units
  neotoma: ndb.variables.variableunitsid
  taxonname: my variable 1 neotoma name   # MUST match the data column above
  required: false
  rowwise: true
  type: string

- column: MyVariable2
  neotoma: ndb.data.value
  taxonname: my variable 2 neotoma name
  required: false
  rowwise: true
  type: float
  unitcolumn: MyVariable2.Units

- column: MyVariable2.Units
  neotoma: ndb.variables.variableunitsid
  taxonname: my variable 2 neotoma name
  required: false
  rowwise: true
  type: string

# ── Contacts ──────────────────────────────────────────────────────────────────
- column: PrincipalInvestigator
  neotoma: ndb.datasetpis.contactname
  required: false
  rowwise: false
  type: string

- column: Collector
  neotoma: ndb.collectors.contactname
  required: false
  rowwise: false
  type: string

- column: DatasetProcessor
  neotoma: ndb.datasetprocessor.contactname
  required: false
  rowwise: false
  type: string

- column: SampleAnalyst
  neotoma: ndb.sampleanalysts.contactname
  required: false
  rowwise: false
  type: string

# ── Publications ──────────────────────────────────────────────────────────────
- column: DOI
  neotoma: ndb.publications.doi
  formatorrange: '^10\.\d{4,9}/[-._;()/:A-Z0-9]+$'
  required: false
  rowwise: false
  type: string

- column: Citation
  neotoma: ndb.publications.citation
  required: false
  rowwise: false
  type: string