YAML Schema Reference

QPX data views have formal schema definitions in YAML format. These schemas define the structure and types of each field using Arrow-native type names and serve as the canonical, language-independent schema definition for the QPX format.

Expression views use AnnData

The expression views (Absolute Expression, Differential Expression) use AnnData (.h5ad) as their primary format and do not have YAML schemas. See AnnData Concepts for details.

API views have no schemas

API views (e.g., peptide summaries, protein summaries) are computed on demand from the primary data views. They are programmable and do not have formal schemas.

YAML vs Parquet

YAML schemas (.yaml) define the logical data model -- the field names, Arrow types, nullability, and documentation for each view. The actual data is serialized in Apache Parquet format for efficient columnar storage and querying. The YAML schemas are the single source of truth for the QPX data model, while Parquet handles the physical storage layer.

How to use these schemas

• Validation: Use these schemas to validate that a QPX file conforms to the expected structure.
• Code generation: The QPX loader converts YAML schemas to PyArrow schemas at import time.
• Documentation: Each field includes a doc attribute describing its purpose and semantics.
• Shared types: Common struct types (e.g., score, modification, intensity) are defined once in types.yaml and reused across schemas.

Schemas

Data Views

PSMFeatureProtein GroupMass SpectraExtracted-Ion Chromatograms

psm.yaml

name: psm
file_type: psm_file
primary_key: [psm_id]
identity_composite: [peptidoform, charge, run_file_name, scan]
doc: "Peptide Spectrum Matches from identification searches"

fields:
  # Identity
  psm_id:
    type: int64
    required: true
    nullable: false
    doc: "Opaque identity of the psm (int64), supplied by the producer or derived from the identity_composite declared in the footer; the primary key of this view."

  # Core identification (shared with Feature)
  sequence:
    type: string
    required: true
    doc: "Unmodified peptide sequence"
  peptidoform:
    type: string
    required: true
    doc: "ProForma notation"
  modifications:
    type: "list<modification>"
    doc: "Structured modifications"
  # Competing modification interpretations (optional)
  modification_candidates:
    type: "list<modification_candidate>"
    optional: true
    nullable: true
    doc: "Every modification the evidence considers, the ones the peptidoform places (assigned) and the ones they compete with, each with its marginal probability given this identification. Candidates that share an alternative_group are mutually exclusive explanations of one event (acetyl or trimethyl on one Lys; one phosphate on S4 or T5) and their probabilities sum to at most 1; a candidate without a group can co-occur with others (a SILAC label and an acetyl on one Lys). Null when the producer reports no alternatives; modifications keeps what the peptidoform says."
  charge:
    type: int16
    required: true
    doc: "Precursor charge"
  posterior_error_probability:
    type: float64
    doc: "PEP - probability PSM is incorrect (lower is better)"
  is_decoy:
    type: bool
    required: true
    doc: "Decoy match flag; false when the identification did not use a target-decoy database search"
  calculated_mz:
    type: float32
    required: true
    nullable: true
    doc: "Theoretical m/z; null when it cannot be calculated from the reported peptidoform"
  observed_mz:
    type: float32
    required: true
    doc: "Experimental m/z"
  mass_error_ppm:
    type: float32
    doc: "Mass error in ppm: 1e6 * (observed_mz - calculated_mz) / calculated_mz"
  additional_scores:
    type: "list<score>"
    doc: "Search engine scores"
  predicted_rt:
    type: float32
    doc: "Predicted RT (seconds)"
  run_file_name:
    type: string
    required: true
    doc: "Run file containing this PSM"
  cv_params:
    type: "list<cv_param>"
    doc: "CV parameters"
  scan:
    type: "list<int32>"
    required: true
    doc: "Scan ID (array of int components)"
  rt:
    type: float32
    doc: "Retention time (seconds)"
  ion_mobility:
    type: float32
    optional: true
    doc: "Ion mobility"
  missed_cleavages:
    type: int16
    doc: "Number of missed enzymatic cleavages (MS:1003044)"

  # PSM-specific fields
  protein_accessions:
    type: "list<string>"
    doc: "Protein accessions the peptide maps to"

  # Cross-linking (XL-MS)
  cross_links:
    type: "list<cross_link>"
    optional: true
    doc: "Cross-link information for XL-MS experiments"

  # Spectral data (optional - may be stored in mz.parquet instead)
  mz_array:
    type: "list<float32>"
    optional: true
    doc: "Spectrum m/z values"
  intensity_array:
    type: "list<float32>"
    optional: true
    doc: "Spectrum intensity values"
  charge_array:
    type: "list<int32>"
    optional: true
    doc: "Fragment charge values"
  ion_type_array:
    type: "list<string>"
    optional: true
    doc: "Fragment ion type annotations (e.g., b1, y2, a2)"
  ion_mobility_array:
    type: "list<float32>"
    optional: true
    doc: "Fragment ion mobility values"

  # Optional cross-reference
  feature_id:
    type: int64
    optional: true
    nullable: true
    doc: "Optional reference to the feature this PSM maps to (feature.feature_id); null when unlinked."

feature.yaml

name: feature
file_type: feature_file
primary_key: [feature_id]
identity_composite: [peptidoform, charge, run_file_name, rt]
doc: "Quantified peptide features with a mandatory opaque feature_id and a footer-declared producer identity composite"

fields:
  # Identity
  feature_id:
    type: int64
    required: true
    nullable: false
    doc: "Opaque identity of the feature (int64), supplied by the producer or derived from the identity_composite declared in the footer; the primary key of this view."

  # Core identification
  sequence:
    type: string
    required: true
    doc: "Unmodified peptide sequence"
  peptidoform:
    type: string
    required: true
    doc: "ProForma notation"
  modifications:
    type: "list<modification>"
    doc: "Structured modifications"
  # Competing modification interpretations (optional)
  modification_candidates:
    type: "list<modification_candidate>"
    optional: true
    nullable: true
    doc: "Every modification the evidence considers, the ones the peptidoform places (assigned) and the ones they compete with, each with its marginal probability given this identification. Candidates that share an alternative_group are mutually exclusive explanations of one event (acetyl or trimethyl on one Lys; one phosphate on S4 or T5) and their probabilities sum to at most 1; a candidate without a group can co-occur with others (a SILAC label and an acetyl on one Lys). Null when the producer reports no alternatives; modifications keeps what the peptidoform says."
  charge:
    type: int16
    required: true
    doc: "Charge state"
  posterior_error_probability:
    type: float64
    doc: "PEP for the peptide match"
  peptide_qvalue:
    type: float64
    nullable: true
    optional: true
    doc: "Peptide-level q-value; null/absent when the search engine does not provide one"
  is_decoy:
    type: bool
    required: true
    doc: "Decoy flag; false when the identification did not use a target-decoy database search"
  calculated_mz:
    type: float32
    required: true
    nullable: true
    doc: "Theoretical m/z; null when it cannot be calculated from the reported peptidoform"
  observed_mz:
    type: float32
    required: true
    nullable: true
    doc: "Experimental m/z; null when the producer reports no measured precursor m/z (e.g. a DIA-NN report without Precursor.Mz)"
  mass_error_ppm:
    type: float32
    doc: "Mass error in ppm: 1e6 * (observed_mz - calculated_mz) / calculated_mz"
  additional_scores:
    type: "list<score>"
    doc: "Search engine scores"
  predicted_rt:
    type: float32
    doc: "Predicted RT (seconds)"
  run_file_name:
    type: string
    required: true
    doc: "Run file name"
  quantification_unit_id:
    type: string
    nullable: true
    optional: true
    doc: "Producer-reported or QPX-mapped quantification unit; used when one quantity can aggregate multiple raw runs"
  cv_params:
    type: "list<cv_param>"
    doc: "CV parameters"
  scan:
    type: "list<int32>"
    required: true
    doc: "Scan ID (array of int components)"
  rt:
    type: float32
    nullable: true
    doc: "Retention time (seconds); may participate in a producer-specific identity composite when it identifies the upstream Feature entity"
  consensus_rt:
    type: float32
    nullable: true
    optional: true
    doc: "Parent ConsensusFeature retention time; populated by the OpenMS consensusXML converter"
  ion_mobility:
    type: float32
    doc: "Ion mobility"
  compensation_voltage:
    type: float32
    nullable: true
    optional: true
    doc: "FAIMS compensation voltage; 0 for a producer's non-FAIMS quantification unit when used in its identity composite"
  missed_cleavages:
    type: int16
    doc: "Number of missed enzymatic cleavages (MS:1003044)"

  # Quantification
  intensities:
    type: "list<intensity>"
    doc: "Primary intensities per label"
  additional_intensities:
    type: "list<additional_intensity>"
    doc: "Tool-provided intensities (normalized, LFQ, iBAQ) read from upstream output"

  # Protein mapping
  pg_accessions:
    type: "list<pg_protein>"
    doc: "Full membership of the peptide's protein group, with optional peptide positions (start, end). Null under the same conditions as anchor_protein."
  anchor_protein:
    type: string
    required: true
    nullable: true
    doc: "Representative protein of the peptide's protein group. Null when no protein mapping was performed, or when the peptide's protein evidence spans more than one inferred protein group (a shared peptide the producer did not assign); the feature's intensities are kept either way."
  unique:
    type: bool
    doc: "True when the peptide resolves to a protein group of exactly one protein, False when that group has several members. A shared peptide the producer assigns to one of its groups (MaxQuant's razor group) carries that group and is False. Null when the group is unresolved, including a shared peptide whose evidence spans more than one inferred group and that the producer did not assign."
  pg_global_qvalue:
    type: float64
    optional: true
    doc: "Global q-value of PG"
  pg_positions:
    type: "list<protein_position>"
    optional: true
    doc: "One-based peptide positions, one entry per protein occurrence: on the members of the resolved protein group, or on every evidence protein when the peptide is shared across groups and pg_accessions is null."

  # Ion mobility window
  ion_mobility_start:
    type: float32
    doc: "Start ion mobility"
  ion_mobility_stop:
    type: float32
    doc: "Stop ion mobility"

  # Gene annotations
  gg_accessions:
    type: "list<string>"
    optional: true
    doc: "Gene group identifiers (gene symbols; Ensembl IDs when available)"
  gg_names:
    type: "list<string>"
    optional: true
    doc: "Gene group names (gene symbols from tool output)"

  # Spectra reference
  id_run_file_name:
    type: string
    doc: "Run file containing best PSM"
  rt_start:
    type: float32
    doc: "RT window start"
  rt_stop:
    type: float32
    doc: "RT window end"

  # Optional cross-references
  psm_ids:
    type: "list<int64>"
    optional: true
    nullable: true
    doc: >-
      Optional producer-supplied hardlink to the psm rows this feature maps to
      (list of psm_id). NOT materialized by qpx's own converters — when absent
      (null), use the computed inverse softlink: Dataset.link_feature_psm(), the
      inverse of the authoritative psm.feature_id foreign key (group by feature_id
      to recover this list, bigbio/qpx#267). See docs/spec/psm.md -> feature_id.
  pg_ids:
    type: "list<int64>"
    optional: true
    nullable: true
    doc: >-
      Optional producer-supplied hardlink to the pg rows this feature maps to
      (list of pg_id). NOT materialized by qpx's own converters — when absent
      (null), use the computed softlink: Dataset.link_feature_pg(), a label-aware
      read-side join of feature and pg on canonical(pg_accessions) +
      run_file_name in pg.grouped_runs + label in feature.intensities
      (bigbio/qpx#269). See docs/spec/pg.md -> Protein group semantics.

pg.yaml

name: pg
file_type: pg_file
primary_key: [pg_id]
identity_composite: [pg_accessions, grouped_runs, label]
doc: "Protein groups with per-quantification-unit quantification (one row per label; label/intensity flattened from the old intensities list)"

fields:
  # Identity
  pg_id:
    type: int64
    required: true
    nullable: false
    doc: "Opaque identity of the pg (int64), supplied by the producer or derived from the identity_composite declared in the footer; the primary key of this view."

  # Protein group identity
  pg_accessions:
    type: "list<string>"
    required: true
    doc: "Protein accessions within this group. Part of the default identity composite: the FULL group membership (not just the leader) keys the pg_id, so two distinct groups that happen to share a leading protein get distinct ids. Hashed order-independently (membership is a set)."
  pg_names:
    type: "list<string>"
    doc: "Protein group names"
  gg_accessions:
    type: "list<string>"
    doc: "Gene group identifiers (gene symbols; Ensembl IDs when available)"
  gg_names:
    type: "list<string>"
    doc: "Gene group names (gene symbols from tool output)"
  gg_qvalue:
    type: float64
    nullable: true
    doc: "Gene group q-value (e.g., DIA-NN GG.Q.Value)"
  anchor_protein:
    type: string
    required: true
    doc: "Anchor/leading protein of the group — a descriptive representative for display only. NOT part of the pg_id identity (which keys on the full pg_accessions membership), and MUST NOT be used for feature->pg joins or per-protein statistics: it is not unique across groups that share a leading protein. Join feature->pg via feature.pg_ids/pg_id or full pg_accessions. See docs/spec/pg.md -> Protein group semantics."

  # Quantification-unit context
  grouped_runs:
    type: "list<string>"
    required: true
    doc: "Raw files grouped into this quantification unit (fractions aggregated together; single-element for unfractionated/DIA)"

  # Quality metrics
  global_qvalue:
    type: float64
    doc: "Global q-value at experiment level"
  pg_qvalue:
    type: float64
    doc: "Protein group q-value at run level"

  # Quantification (flattened: retain known labels for identified groups even
  # without a quantity. Both fields are null only when label context is absent.)
  label:
    type: string
    nullable: true
    doc: "Channel/label of this quantification; retained for identified groups without a quantity, null only when identification-only input has no label context. Part of the default identity composite."
  intensity:
    type: float32
    nullable: true
    doc: "Primary intensity for this label; null when the identified group has no reported quantity. Without identification or quantification evidence for this unit, omit the row instead of adding a zero or null placeholder."
  additional_intensities:
    type: "list<additional_intensity>"
    doc: "Tool-provided intensities (normalized, LFQ, iBAQ) for this row's label, read from upstream output"

  # Flags
  is_decoy:
    type: bool
    required: true
    doc: "Decoy flag"
  contaminant:
    type: bool
    doc: "Contaminant flag"

  # Peptide/feature counts
  peptides:
    type: "list<peptide_per_protein>"
    required: true
    doc: "Peptide counts per protein in the group"
  peptide_counts:
    type: peptide_counts
    doc: "Unique/total peptide sequence counts"
  feature_counts:
    type: feature_counts
    doc: "Unique/total feature counts"

  # Protein properties
  sequence_coverage:
    type: float32
    doc: "Sequence coverage percentage"
  molecular_weight:
    type: float32
    doc: "Molecular weight (kDa)"

  # Scores and metadata
  additional_scores:
    type: "list<score>"
    doc: "Additional scores"
  cv_params:
    type: "list<cv_param>"
    doc: "CV parameters"

mz.yaml

name: mz
file_type: mz_file
primary_key: [id]
doc: "Mass spectrometry spectral data (scan-level)"

fields:
  # Scan identification
  id:
    type: string
    required: true
    doc: "Unique scan/spectrum identifier"
  run_file_name:
    type: string
    optional: true
    doc: "Run file containing this spectrum (links to PSM/feature run_file_name)"
  scan:
    type: "list<int32>"
    optional: true
    doc: "Scan ID from native ID (array of int components; links to PSM/feature scan)"
  ms_level:
    type: int32
    required: true
    doc: "MS level (1=MS1, 2=MS2)"
  centroid:
    type: bool
    required: true
    doc: "Centroided (true) or profile (false)"

  # Timing and mobility
  scan_start_time:
    type: float32
    required: true
    doc: "Scan start time (minutes)"
  inverse_ion_mobility:
    type: float32
    optional: true
    doc: "Inverse ion mobility (TIMS)"
  ion_injection_time:
    type: float32
    optional: true
    doc: "Ion injection time (ms); null when the source does not record it"
  total_ion_current:
    type: float32
    required: true
    doc: "Total ion current"

  # Precursor info (MS2+ only)
  precursors:
    type: "list<precursor>"
    optional: true
    doc: "Precursor ions"

  # Spectral data
  mz:
    type: "list<float32>"
    required: true
    doc: "m/z values"
  intensity:
    type: "list<float32>"
    required: true
    doc: "Intensity values"

  # Metadata
  cv_params:
    type: "list<cv_param>"
    optional: true
    doc: "CV parameters"

xic.yaml

name: xic
file_type: xic_file
primary_key: [xic_id]
doc: "Extracted-ion chromatograms (XIC) for DIA and targeted acquisitions — one row per traced precursor or fragment ion per run"

fields:
  # Identity
  xic_id:
    type: string
    required: true
    doc: "Opaque identifier of one chromatogram trace. Producer-supplied (e.g. <run_file_name>|<precursor_id>|<transition>|<isotope>|<compensation_voltage>) and unique within the file; the primary key of this view."
  run_file_name:
    type: string
    required: true
    doc: "Raw data file containing the trace (without extension); links to run_file_name in the run, feature, psm, and mz views."
  label:
    type: string
    required: true
    doc: "Channel label. Use 'LFQ' for label-free DIA, or the reporter/plex channel name (e.g. 'TMT126') for multiplexed traces. Matches feature.intensities[].label."
  feature_ids:
    type: "list<int64>"
    optional: true
    nullable: true
    doc: "Optional links to the feature.feature_id rows this trace supports. A trace is precursor-level evidence and can support several candidate peak groups, so this is a list rather than one feature id."
  feature_scores:
    type: "list<feature_score>"
    optional: true
    nullable: true
    doc: "Per-feature scores for this trace, for producers whose fragment scores depend on the feature (e.g. area, apex intensity/RT, mass error or shape scores). Use trace-level additional_scores for scores that do not depend on a feature."
  compensation_voltage:
    type: float32
    optional: true
    nullable: true
    doc: "FAIMS compensation voltage of the trace, when the acquisition uses FAIMS; part of the trace identity because one precursor can be traced at several voltages."

  # Precursor identity
  precursor_id:
    type: string
    required: true
    doc: "The producer's precursor identifier (DIA-NN pr: modified sequence plus charge, e.g. 'PEPTM(UniMod:35)IDEK2'). Preserved as reported so a trace can be traced back to the source file."
  peptidoform:
    type: string
    required: true
    doc: "Precursor peptidoform in ProForma notation; links to feature.peptidoform and psm.peptidoform."
  charge:
    type: int16
    required: true
    doc: "Precursor charge state."

  # Traced ion
  transition:
    type: string
    required: true
    doc: "Transition annotation: 'ms1' for the precursor trace, or a fragment label such as 'y7^1' or 'b4^2'. Fragment annotations should follow mzPAF (the PSI peak annotation format) where the producer supports it; ms1 is reserved for the precursor trace."
  transition_type:
    type: string
    required: true
    doc: "Kind of trace: 'ms1' for the precursor (MS1) trace, 'fragment' for a fragment-ion (MS2) trace."
  fragment_type:
    type: string
    optional: true
    nullable: true
    doc: "Fragment-ion series (e.g. 'b', 'y'). Null for an ms1 trace or a fragment the producer did not annotate."
  fragment_number:
    type: int16
    optional: true
    nullable: true
    doc: "Fragment-ion ordinal measured from its terminus (y7 -> 7). Null when the transition carries no fragment annotation."
  fragment_charge:
    type: int16
    optional: true
    nullable: true
    doc: "Charge of the traced fragment ion (y7^1 -> 1). Null when the producer does not report it."
  neutral_loss:
    type: string
    optional: true
    nullable: true
    doc: "Neutral-loss annotation of the traced ion (e.g. '-H2O'). Null when the trace has no neutral loss."
  isotope:
    type: int16
    optional: true
    nullable: true
    doc: "Isotope index of the traced ion: 0 is monoisotopic, 1 is M+1, and so on. Applies to both precursor (ms1) and fragment traces; null when the producer does not report isotope resolution."
  target_mz:
    type: float32
    optional: true
    nullable: true
    doc: "m/z the trace was extracted at: the precursor m/z for an ms1 trace, or the product-ion m/z for a fragment trace. Null when the producer does not report it."
  target_rt:
    type: float32
    optional: true
    nullable: true
    doc: "Expected/target retention time of the trace in seconds, when the producer reports one (e.g. the library or predicted apex)."
  rt_start:
    type: float32
    optional: true
    nullable: true
    doc: "Start of the extraction window in seconds. Null when the producer does not report the window or the whole run was extracted."
  rt_stop:
    type: float32
    optional: true
    nullable: true
    doc: "End of the extraction window in seconds. Null when the producer does not report the window or the whole run was extracted."
  target_ion_mobility:
    type: float32
    optional: true
    nullable: true
    doc: "Target ion-mobility value of the trace (1/K0), when the acquisition is ion-mobility coupled and the producer reports it."
  ion_mobility_start:
    type: float32
    optional: true
    nullable: true
    doc: "Start of the ion-mobility extraction window (1/K0), when applicable."
  ion_mobility_stop:
    type: float32
    optional: true
    nullable: true
    doc: "End of the ion-mobility extraction window (1/K0), when applicable."
  library_intensity:
    type: float32
    optional: true
    nullable: true
    doc: "Library or predicted relative intensity of this fragment, when available; useful as an ML feature or for transition prioritisation."
  used_for_quantification:
    type: bool
    optional: true
    nullable: true
    doc: "True when the producer used this trace for quantification or scoring, false when it was only extracted for inspection. Null when the producer does not mark it."

  # Measurement
  rt:
    type: "list<float32>"
    required: true
    doc: "Raw retention times of the trace in seconds, strictly increasing and in acquisition order. Not aligned or iRT-corrected. MUST have the same length as intensity and, when present, mz."
  intensity:
    type: "list<float32>"
    required: true
    doc: "Raw intensity at each retention time, as exported by the producer; zero-intensity points are kept and QPX does not smooth them. MUST have the same length as rt; element i corresponds to rt[i]."
  mz:
    type: "list<float32>"
    optional: true
    nullable: true
    doc: "Optional observed m/z at each retention time, aligned with rt; enables mass-error traces. Null when the producer does not report a per-point m/z."
  is_decoy:
    type: bool
    optional: true
    nullable: true
    doc: "Decoy flag for the precursor when the producer reports one; null when the trace is not classified."
  additional_scores:
    type: "list<score>"
    optional: true
    doc: "Trace-level scores reported by the producer. Feature-by-trace score tables (several candidate features sharing one trace) are outside this view."

  # Metadata
  cv_params:
    type: "list<cv_param>"
    optional: true
    doc: "Controlled-vocabulary parameters for trace-specific metadata. Settings that are constant for a run (m/z tolerance, extraction-window width, smoothing method) belong in run/provenance metadata, not repeated on every row."

Metadata Views

DatasetSampleRunOntologyProvenance

dataset.yaml

name: dataset
file_type: dataset_file
primary_key: [project_accession]
doc: "Project-level metadata for a QPX dataset (single-row file)"

fields:
  project_accession:
    type: string
    required: true
    doc: "Project accession (e.g., PXD014414)"
  project_title:
    type: string
    doc: "Title of the project"
  project_description:
    type: string
    doc: "Project description"
  pubmed_id:
    type: string
    doc: "PubMed ID"
  software_name:
    type: string
    doc: "Software that generated the data"
  software_version:
    type: string
    doc: "Software version"
  creation_date:
    type: string
    required: true
    doc: "ISO 8601 date when dataset was created"

  # Integrity / packaging
  file_checksums:
    type: "map<string, string>"
    doc: "SHA-256 hex digests keyed by file name (relative to dataset root)"
  file_row_counts:
    type: "map<string, int64>"
    doc: "Row counts keyed by file name"
  file_sizes_bytes:
    type: "map<string, int64>"
    doc: "File sizes in bytes keyed by file name"
  total_structures:
    type: int32
    doc: "Number of Parquet structures in this dataset"
  packaged_at:
    type: string
    doc: "ISO 8601 timestamp when integrity was computed"

sample.yaml

name: sample
file_type: sample_file
primary_key: [sample_accession]
doc: "Biological sample metadata, one row per sample"
extra_columns: true

fields:
  sample_accession:
    type: string
    required: true
    doc: "Unique sample identifier (SDRF source name)"
  organism:
    type: string
    required: true
    doc: "Species (e.g. Homo sapiens)"
  organism_part:
    type: string
    required: true
    doc: "Tissue or organ (e.g. Brain; Frontal cortex)"
  disease:
    type: string
    optional: true
    doc: "Disease state (omitted when absent from SDRF)"
  cell_line:
    type: string
    optional: true
    doc: "Cell line name (omitted when absent from SDRF)"
  cell_type:
    type: string
    optional: true
    doc: "Cell type (omitted when absent from SDRF)"
  sex:
    type: string
    optional: true
    doc: "Biological sex (omitted when absent from SDRF)"
  age:
    type: string
    optional: true
    doc: "Age of specimen (omitted when absent from SDRF)"
  developmental_stage:
    type: string
    optional: true
    doc: "Developmental stage (omitted when absent from SDRF)"
  ancestry:
    type: string
    optional: true
    doc: "Ancestry category (omitted when absent from SDRF)"
  individual:
    type: string
    optional: true
    doc: "Individual/patient identifier (omitted when absent from SDRF)"
  sample_description:
    type: string
    optional: true
    doc: "Free-text sample description (omitted when absent from SDRF)"

run.yaml

name: run
file_type: run_file
primary_key: [run_file_name]
doc: "MS acquisition run metadata, one row per run"

fields:
  run_accession:
    type: string
    required: true
    doc: "Unique run identifier (SDRF assay name)"
  run_file_name:
    type: string
    required: true
    doc: "Raw data file name (without extension)"
  file_name:
    type: string
    optional: true
    doc: "Original file name with extension (e.g. S1_Frontal_1.raw)"

  # Sample-channel mapping (supports multiplexed runs)
  samples:
    type: "list<sample_channel>"
    required: true
    doc: "Sample-channel mappings with replicate info"

  # Run properties
  fraction:
    type: string
    optional: true
    doc: "Fraction identifier"

  # Instrument and method (plain strings; CV mappings in ontology.parquet)
  instrument:
    type: string
    optional: true
    doc: "Mass spectrometer name"
  enzymes:
    type: "list<string>"
    optional: true
    doc: "Proteolytic enzyme names"
  dissociation_method:
    type: string
    optional: true
    doc: "Fragmentation method name (HCD, CID, ETD)"
  acquisition_method:
    type: string
    nullable: true
    optional: true
    doc: "Data acquisition method name (e.g. DDA, DIA); from comment[proteomics data acquisition method]"

  # Additional ontology-backed run terms (acquisition method as CV, labeling, etc.);
  # plain-string values live in the fields above, resolved CV terms in ontology.parquet
  additional_terms:
    type: "list<ontology_term>"
    nullable: true
    optional: true
    doc: "Other ontology-backed run terms (acquisition method, labeling, etc.)"

  # Search configuration
  modification_parameters:
    type: "list<modification_param>"
    optional: true
    doc: "Modifications configured in database search"

ontology.yaml

name: ontology
file_type: ontology_file
primary_key: [field_name, view]
doc: "Field-to-ontology mappings. Makes the dataset self-describing"

fields:
  field_name:
    type: string
    required: true
    doc: "snake_case QPX field or score name"
  ontology_name:
    type: string
    doc: "Proper ontology term name"
  ontology_accession:
    type: string
    doc: "Ontology accession identifier (e.g., MS:1002252)"
  ontology_source:
    type: string
    doc: "Ontology prefix (MS, UBERON, UNIMOD, etc.)"
  ontology_version:
    type: string
    doc: "Version of the ontology used for resolution (e.g., 4.1.235)"
  view:
    type: string
    required: true
    doc: "QPX view this field belongs to (psm, feature, pg, etc.)"
  description:
    type: string
    doc: "Human-readable description"
  source_column_name:
    type: string
    doc: "Original column name in the tool output (e.g., Precursor.Quantity)"
  source_tool:
    type: string
    doc: "Tool name that produced this field (e.g., DIA-NN)"

provenance.yaml

name: provenance
file_type: provenance_file
primary_key: [step_order]
doc: "Processing provenance - one row per pipeline step"

fields:
  step_order:
    type: int32
    required: true
    doc: "Execution order (1, 2, 3, ...)"
  step_category:
    type: string
    required: true
    doc: "Broad category (workflow, database_search, quantification, etc.)"
  step_name:
    type: string
    required: true
    doc: "Specific name (sequence_search, psm_rescoring, etc.)"
  tool_name:
    type: string
    required: true
    doc: "Tool that performed this step"
  tool_version:
    type: string
    doc: "Tool version"
  tool_uri:
    type: string
    doc: "Container URI or tool URL"
  parameters:
    type: "list<parameter>"
    doc: "Key-value pairs of important settings"
  config:
    type: string
    doc: "Full tool configuration as JSON string"
  output_views:
    type: "list<string>"
    doc: "QPX views this step generated (e.g., ['psm', 'feature'])"

Shared Types

types.yaml

# Shared struct types used across QPX schemas.
# These are referenced by name in schema YAML files (e.g., type: list<intensity>).

score:
  fields:
    score_name: {type: string}
    score_value: {type: float64}
    higher_better: {type: bool, nullable: true}

feature_score:
  fields:
    feature_id: {type: int64}
    scores: {type: "list<score>"}

cv_param:
  fields:
    cv_name: {type: string}
    cv_value: {type: string}

modification_position:
  fields:
    position: {type: int32}
    amino_acid: {type: string, nullable: true}
    scores: {type: "list<score>", nullable: true}

modification:
  fields:
    name: {type: string}
    accession: {type: string, nullable: true}
    positions: {type: "list<modification_position>"}

intensity:
  fields:
    label: {type: string}
    intensity: {type: float32}

intensity_pair:
  fields:
    intensity_name: {type: string}
    intensity_value: {type: float32}

additional_intensity:
  fields:
    label: {type: string}
    intensities: {type: "list<intensity_pair>"}

pg_protein:
  fields:
    accession: {type: string}
    start: {type: int32, nullable: true}
    end: {type: int32, nullable: true}
    pre: {type: string, nullable: true}
    post: {type: string, nullable: true}

protein_position:
  fields:
    protein_accession: {type: string}
    start: {type: int32}
    end: {type: int32}

ontology_property:
  fields:
    key: {type: string}
    value: {type: string}

ontology_term:
  fields:
    accession: {type: string}
    name: {type: string, nullable: true}
    properties: {type: "list<ontology_property>", nullable: true}

sample_channel:
  fields:
    sample_accession: {type: string}
    label: {type: string}
    biological_replicate: {type: int32, nullable: true}
    technical_replicate: {type: int32, nullable: true}

modification_param:
  fields:
    accession: {type: string}
    name: {type: string, nullable: true}
    fixed: {type: bool, nullable: true}
    position: {type: string, nullable: true}
    target_amino_acid: {type: string, nullable: true}

modification_candidate:
  fields:
    position: {type: int32}
    amino_acid: {type: string, nullable: true}
    name: {type: string}
    accession: {type: string, nullable: true}
    mass_delta: {type: float64, nullable: true}
    probability: {type: float64, nullable: true}
    assigned: {type: bool}
    alternative_group: {type: int32, nullable: true}
    scores: {type: "list<score>", nullable: true}

sequence_edit:
  fields:
    start: {type: int32}
    end: {type: int32}
    reference: {type: string}
    alternative: {type: string}
    name: {type: string, nullable: true}
    accession: {type: string, nullable: true}

peptide_sequence_edit:
  fields:
    protein_accession: {type: string}
    start: {type: int32}
    end: {type: int32}
    reference: {type: string}
    alternative: {type: string}
    name: {type: string, nullable: true}
    accession: {type: string, nullable: true}

site_alternative:
  fields:
    name: {type: string}
    accession: {type: string, nullable: true}
    mass_delta: {type: float64}
    evidence_fraction: {type: float64}

peptide_per_protein:
  fields:
    protein_name: {type: string}
    peptide_count: {type: int32}

peptide_counts:
  fields:
    unique_sequences: {type: int32}
    total_sequences: {type: int32}

feature_counts:
  fields:
    unique_features: {type: int32}
    total_features: {type: int32}

precursor:
  fields:
    selected_ion_mz: {type: float32}
    selected_ion_charge: {type: int32, nullable: true}
    selected_ion_intensity: {type: float32, nullable: true}
    isolation_window_target: {type: float32, nullable: true}
    isolation_window_lower: {type: float32, nullable: true}
    isolation_window_upper: {type: float32, nullable: true}
    spectrum_ref: {type: string, nullable: true}

parameter:
  fields:
    key: {type: string}
    value: {type: string}

cross_link:
  fields:
    xl_type: {type: string}
    partner_sequence: {type: string, nullable: true}
    partner_peptidoform: {type: string, nullable: true}
    donor_position: {type: int32}
    acceptor_position: {type: int32, nullable: true}
    linker_name: {type: string}
    linker_accession: {type: string, nullable: true}
    linker_mass: {type: float64}

Viewing schemas programmatically

You can load and inspect any schema in Python using the QPX loader:

from qpx.core.models.loader import load_schema

schema = load_schema("feature")
for field in schema._iter_fields():
    print(f"{field.name}: {field.arrow_type} (nullable={field.nullable})")