Skip to content

Class: ModelEstimation

How a model was specified in software and estimated: its terms, the family, the source's wording for it, the estimator, the stage, the software, the pipeline that produced the data it was fitted to, and the spatial element it was fitted over. One record may be referenced by several Analyses, so every field must hold for all of them; an analysis specified or estimated differently takes its own record. The data a model was fitted to is part of its specification.

One record is one estimation stage. Neuroimaging splits a model across stages for tractability, and inputs_from is what puts it back together: a stage's terms are its own plus those of the stages it consumed, so the split costs the record nothing while each stage keeps its own family, estimator, software and basis.

__

The test for whether two analyses share a record is mechanical: list the columns each was fitted with. A different dependent variable, a different covariate set, or a different subset of participants means a different design matrix and therefore a separate record, even when family, estimator and software are identical. Two BPM regressions of the same measure on the same regressor, one over the patients and one over patients and controls pooled, are two records.

Sharing one record across matrices corrupts the derived adjustment set. The adjustment set is the model's terms minus the terms named by its cells. If several matrices share one record, they claim adjustments that their original models never made, and the record cannot expose the error.

URI: neurostudy_ex:ModelEstimation

 classDiagram
    class ModelEstimation
    click ModelEstimation href "../ModelEstimation/"
      ModelEstimation : estimator





        ModelEstimation --> "0..1" ExtractedString : estimator
        click ExtractedString href "../ExtractedString/"



      ModelEstimation : hrf_model





        ModelEstimation --> "0..1" ExtractedString : hrf_model
        click ExtractedString href "../ExtractedString/"



      ModelEstimation : inputs_from





        ModelEstimation --> "*" ModelEstimation : inputs_from
        click ModelEstimation href "../ModelEstimation/"



      ModelEstimation : local_id

      ModelEstimation : model_family





        ModelEstimation --> "1" ExtractedModelFamily : model_family
        click ExtractedModelFamily href "../ExtractedModelFamily/"



      ModelEstimation : model_settings





        ModelEstimation --> "0..1" ExtractedString : model_settings
        click ExtractedString href "../ExtractedString/"



      ModelEstimation : model_type





        ModelEstimation --> "1" ExtractedString : model_type
        click ExtractedString href "../ExtractedString/"



      ModelEstimation : preprocessing





        ModelEstimation --> "*" Preprocessing : preprocessing
        click Preprocessing href "../Preprocessing/"



      ModelEstimation : software





        ModelEstimation --> "0..1" ExtractedString : software
        click ExtractedString href "../ExtractedString/"



      ModelEstimation : spatial_unit





        ModelEstimation --> "0..1" ExtractedSpatialUnit : spatial_unit
        click ExtractedSpatialUnit href "../ExtractedSpatialUnit/"



      ModelEstimation : stable_id

      ModelEstimation : stage





        ModelEstimation --> "1" ExtractedString : stage
        click ExtractedString href "../ExtractedString/"



      ModelEstimation : terms





        ModelEstimation --> "*" ModelTerm : terms
        click ModelTerm href "../ModelTerm/"

Slots

Name Cardinality and Range Description Inheritance
stable_id 0..1
String		 UUID minted by the store the first time this entity appears, never by an extr... direct
local_id 1
String		 Stable identifier used by Analysis foreign-key references direct
model_family 1
ExtractedModelFamily		 Normalized statistical model family, which is the queryable form direct
model_type 1
ExtractedString		 The source's own wording for the model, minimally cleaned, such as mass- univ... direct
hrf_model 0..1
ExtractedString		 The haemodynamic response basis the design matrix was built with: a canonical... direct
model_settings 0..1
ExtractedString		 Essential estimator, variance, autocorrelation, covariance, regularization, a... direct
stage 1
ExtractedString		 Stage of analysis, in the source's terms: run, session, subject and group are... direct
estimator 0..1
ExtractedString		 Estimation method, such as OLS, WLS, maximum likelihood, restricted maximum l... direct
software 0..1
ExtractedString		 Statistical software name, version, and relevant implementation details direct
spatial_unit 0..1
ExtractedSpatialUnit		 The element this model was fitted over direct
preprocessing *
Preprocessing		 The pipelines that produced the data this model was fitted to direct
inputs_from *
ModelEstimation		 The models whose fitted output this model was estimated on: the first-level G... direct
terms *
ModelTerm		 The terms this stage was specified with -- the columns of its design matr... direct

Usages

used by used in type used
Analysis model_estimation range ModelEstimation
ModelEstimation inputs_from range ModelEstimation
Study model_estimations range ModelEstimation

See Also

Identifier and Mapping Information

Schema Source

  • from schema: https://neurostuff.org/schemas/neuroimaging-study-extraction

Mappings

Mapping Type Mapped Value
self neurostudy_ex:ModelEstimation
native neurostudy_ex:ModelEstimation

LinkML Source

Direct

name: ModelEstimation
description: 'How a model was specified in software and estimated: its terms, the
  family, the source''s wording for it, the estimator, the stage, the software, the
  pipeline that produced the data it was fitted to, and the spatial element it was
  fitted over. One record may be referenced by several Analyses, so every field must
  hold for all of them; an analysis specified or estimated differently takes its own
  record. **The data a model was fitted to is part of its specification**.

  One record is one estimation stage. Neuroimaging splits a model across stages for
  tractability, and `inputs_from` is what puts it back together: a stage''s terms
  are its own plus those of the stages it consumed, so the split costs the record
  nothing while each stage keeps its own family, estimator, software and basis.


  The test for whether two analyses share a record is mechanical: list the columns
  each was fitted with. A different dependent variable, a different covariate set,
  or a different subset of participants means a different design matrix and therefore
  a separate record, even when family, estimator and software are identical. Two BPM
  regressions of the same measure on the same regressor, one over the patients and
  one over patients and controls pooled, are two records.

  Sharing one record across matrices corrupts the derived adjustment set. The adjustment
  set is the model''s terms minus the terms named by its cells. If several matrices
  share one record, they claim adjustments that their original models never made,
  and the record cannot expose the error.'
from_schema: https://neurostuff.org/schemas/neuroimaging-study-extraction
see_also:
- https://cdisc-org.github.io/analysis-results-standard/
- https://bids-standard.github.io/stats-models/spec.html
- https://nidm.nidash.org/specs/nidm-results_120.html
rank: 1000
attributes:
  stable_id:
    name: stable_id
    description: UUID minted by the store the first time this entity appears, never
      by an extractor, and kept across re-runs so a later extraction matches the same
      entity.
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-extraction/analysis
    domain_of:
    - Arm
    - Timepoint
    - Group
    - Task
    - Condition
    - Assessment
    - Region
    - Acquisition
    - Device
    - Analysis
    - Measure
    - Preprocessing
    - ModelEstimation
    - ModelTerm
    - InferenceSettings
    - Table
    - CoordinateSet
    - Study
    range: string
    pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
  local_id:
    name: local_id
    description: Stable identifier used by Analysis foreign-key references.
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-extraction/analysis
    identifier: true
    domain_of:
    - Arm
    - Timepoint
    - Group
    - Task
    - Condition
    - Assessment
    - Region
    - Acquisition
    - Device
    - Analysis
    - Measure
    - Preprocessing
    - ModelEstimation
    - ModelTerm
    - InferenceSettings
    - Table
    - CoordinateSet
    - Study
    range: string
    required: true
  model_family:
    name: model_family
    description: 'Normalized statistical model family, which is the queryable form.
      Required, so a paper that never says still carries the slot, as `extraction_status:
      not_reported`. A method the vocabulary cannot name -- ICA, representational
      similarity, a decoder -- is written here as free text; the Analysis.details
      subclass also identifies the method.'
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-extraction/analysis
    rank: 1000
    domain_of:
    - ModelEstimation
    range: ExtractedModelFamily
    required: true
  model_type:
    name: model_type
    description: The source's own wording for the model, minimally cleaned, such as
      mass- univariate GLM, meta-analysis, multivariate, predictive model, ICA, or
      representational similarity analysis.
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-extraction/analysis
    rank: 1000
    domain_of:
    - ModelEstimation
    range: ExtractedString
    required: true
  hrf_model:
    name: hrf_model
    description: 'The haemodynamic response basis the design matrix was built with:
      a canonical HRF, a canonical plus temporal or dispersion derivatives, an FIR
      or gamma basis, or a named alternative. Unset for a measure that models no timeseries
      -- morphometry, diffusion, static PET.'
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-extraction/analysis
    rank: 1000
    domain_of:
    - ModelEstimation
    range: ExtractedString
  model_settings:
    name: model_settings
    description: Essential estimator, variance, autocorrelation, covariance, regularization,
      and software-specific settings.
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-extraction/analysis
    rank: 1000
    domain_of:
    - ModelEstimation
    range: ExtractedString
  stage:
    name: stage
    description: 'Stage of analysis, in the source''s terms: run, session, subject
      and group are the usual words, and any other the source uses is storable as
      written. Deliberately left open -- no vocabulary fits every design, and nothing
      derives anything from it.

      A label, not an ordering. Only `inputs_from` records which stage fed another:
      two records labelled `group` say nothing about their relationship, and these
      strings never imply a chain.'
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-extraction/analysis
    rank: 1000
    domain_of:
    - ModelEstimation
    range: ExtractedString
    required: true
  estimator:
    name: estimator
    description: Estimation method, such as OLS, WLS, maximum likelihood, restricted
      maximum likelihood, permutation, or Bayesian estimation.
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-extraction/analysis
    rank: 1000
    domain_of:
    - ModelEstimation
    range: ExtractedString
  software:
    name: software
    description: Statistical software name, version, and relevant implementation details.
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-extraction/analysis
    domain_of:
    - Preprocessing
    - ModelEstimation
    range: ExtractedString
  spatial_unit:
    name: spatial_unit
    description: 'The element this model was fitted over. Distinct from the Analysis''s
      `spatial_scope`, which gives the extent rather than the element: a whole-brain
      model can be voxelwise or vertexwise, and a model over an ROI can average the
      region or test its parcels. Record it rather than inferring it from `coordinate_space`.

      A model fitted over a different element is a different model, so a voxelwise
      GLM and an ROI-mean ANOVA of the same design take two records: no contrast of
      one can be read off the other''s fit.'
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-extraction/analysis
    rank: 1000
    domain_of:
    - ModelEstimation
    range: ExtractedSpatialUnit
  preprocessing:
    name: preprocessing
    description: 'The pipelines that produced the data this model was fitted to. Every
      Analysis referencing this record came through them, so a model fitted to differently
      prepared data -- unsmoothed images for a classifier, smoothed ones for a mass-univariate
      fit -- takes its own record rather than sharing one.

      More than one entry when the fit consumed more than one kind of image: a multimodal
      regression of perfusion on grey-matter volume was fitted to the output of both
      pipelines, and naming either alone says the other''s smoothing and normalisation
      did not touch the map.'
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-extraction/analysis
    rank: 1000
    domain_of:
    - ModelEstimation
    range: Preprocessing
    multivalued: true
    inlined: false
  inputs_from:
    name: inputs_from
    description: 'The models whose fitted output this model was estimated on: the
      first-level GLM whose contrast images a group model takes as its data, the subject-level
      fit an ROI ANOVA summarises. The stage graph, recorded only where the source
      states it.

      **A model''s terms are its own plus, transitively, those of the models named
      here.** That combined list is what `terms` would be had the analysis been fitted
      in one step.

      Leave it empty when the source describes one design matrix, and when it describes
      the lower stage too thinly to constitute a model. Empty is not a claim that
      no lower stage existed; it is the absence of a statement about one, exactly
      as an unrecorded term is.

      Must be acyclic, no model may reach itself.'
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-extraction/analysis
    rank: 1000
    domain_of:
    - ModelEstimation
    range: ModelEstimation
    multivalued: true
    inlined: false
  terms:
    name: terms
    description: 'The terms **this stage** was specified with -- the columns of its
      design matrix, in the general sense that covers a GLM''s regressors and the
      predictors of any other family. Stated once here however many contrasts are
      taken from them, and never restated on a stage above: the terms of a lower stage
      are reached through `inputs_from`.

      Record every term the source states, including ones no reported contrast tests,
      and including ones mentioned only in passing: "controlling for age and sex"
      is a statement about the design matrix. This list, together with the lists reached
      through `inputs_from`, is **the adjustment set of every contrast taken from
      this model** -- each contrast''s is that combined list minus the terms its cells
      name -- so a term omitted from every stage reads as one the model did not adjust
      for. Where the list is incomplete, the slot''s extraction_status is what says
      so.

      May be empty, and legitimately is for a stage that fits only an intercept: a
      one-sample group test over first-level contrast images has no column of its
      own. Do not invent an intercept term to fill it.

      Analyses whose design matrices differ take their own records rather than sharing
      one.'
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-extraction/analysis
    rank: 1000
    domain_of:
    - ModelEstimation
    range: ModelTerm
    multivalued: true
    inlined_as_list: true

Induced

name: ModelEstimation
description: 'How a model was specified in software and estimated: its terms, the
  family, the source''s wording for it, the estimator, the stage, the software, the
  pipeline that produced the data it was fitted to, and the spatial element it was
  fitted over. One record may be referenced by several Analyses, so every field must
  hold for all of them; an analysis specified or estimated differently takes its own
  record. **The data a model was fitted to is part of its specification**.

  One record is one estimation stage. Neuroimaging splits a model across stages for
  tractability, and `inputs_from` is what puts it back together: a stage''s terms
  are its own plus those of the stages it consumed, so the split costs the record
  nothing while each stage keeps its own family, estimator, software and basis.


  The test for whether two analyses share a record is mechanical: list the columns
  each was fitted with. A different dependent variable, a different covariate set,
  or a different subset of participants means a different design matrix and therefore
  a separate record, even when family, estimator and software are identical. Two BPM
  regressions of the same measure on the same regressor, one over the patients and
  one over patients and controls pooled, are two records.

  Sharing one record across matrices corrupts the derived adjustment set. The adjustment
  set is the model''s terms minus the terms named by its cells. If several matrices
  share one record, they claim adjustments that their original models never made,
  and the record cannot expose the error.'
from_schema: https://neurostuff.org/schemas/neuroimaging-study-extraction
see_also:
- https://cdisc-org.github.io/analysis-results-standard/
- https://bids-standard.github.io/stats-models/spec.html
- https://nidm.nidash.org/specs/nidm-results_120.html
rank: 1000
attributes:
  stable_id:
    name: stable_id
    description: UUID minted by the store the first time this entity appears, never
      by an extractor, and kept across re-runs so a later extraction matches the same
      entity.
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-extraction/analysis
    owner: ModelEstimation
    domain_of:
    - Arm
    - Timepoint
    - Group
    - Task
    - Condition
    - Assessment
    - Region
    - Acquisition
    - Device
    - Analysis
    - Measure
    - Preprocessing
    - ModelEstimation
    - ModelTerm
    - InferenceSettings
    - Table
    - CoordinateSet
    - Study
    range: string
    pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
  local_id:
    name: local_id
    description: Stable identifier used by Analysis foreign-key references.
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-extraction/analysis
    identifier: true
    owner: ModelEstimation
    domain_of:
    - Arm
    - Timepoint
    - Group
    - Task
    - Condition
    - Assessment
    - Region
    - Acquisition
    - Device
    - Analysis
    - Measure
    - Preprocessing
    - ModelEstimation
    - ModelTerm
    - InferenceSettings
    - Table
    - CoordinateSet
    - Study
    range: string
    required: true
  model_family:
    name: model_family
    description: 'Normalized statistical model family, which is the queryable form.
      Required, so a paper that never says still carries the slot, as `extraction_status:
      not_reported`. A method the vocabulary cannot name -- ICA, representational
      similarity, a decoder -- is written here as free text; the Analysis.details
      subclass also identifies the method.'
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-extraction/analysis
    rank: 1000
    owner: ModelEstimation
    domain_of:
    - ModelEstimation
    range: ExtractedModelFamily
    required: true
  model_type:
    name: model_type
    description: The source's own wording for the model, minimally cleaned, such as
      mass- univariate GLM, meta-analysis, multivariate, predictive model, ICA, or
      representational similarity analysis.
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-extraction/analysis
    rank: 1000
    owner: ModelEstimation
    domain_of:
    - ModelEstimation
    range: ExtractedString
    required: true
  hrf_model:
    name: hrf_model
    description: 'The haemodynamic response basis the design matrix was built with:
      a canonical HRF, a canonical plus temporal or dispersion derivatives, an FIR
      or gamma basis, or a named alternative. Unset for a measure that models no timeseries
      -- morphometry, diffusion, static PET.'
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-extraction/analysis
    rank: 1000
    owner: ModelEstimation
    domain_of:
    - ModelEstimation
    range: ExtractedString
  model_settings:
    name: model_settings
    description: Essential estimator, variance, autocorrelation, covariance, regularization,
      and software-specific settings.
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-extraction/analysis
    rank: 1000
    owner: ModelEstimation
    domain_of:
    - ModelEstimation
    range: ExtractedString
  stage:
    name: stage
    description: 'Stage of analysis, in the source''s terms: run, session, subject
      and group are the usual words, and any other the source uses is storable as
      written. Deliberately left open -- no vocabulary fits every design, and nothing
      derives anything from it.

      A label, not an ordering. Only `inputs_from` records which stage fed another:
      two records labelled `group` say nothing about their relationship, and these
      strings never imply a chain.'
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-extraction/analysis
    rank: 1000
    owner: ModelEstimation
    domain_of:
    - ModelEstimation
    range: ExtractedString
    required: true
  estimator:
    name: estimator
    description: Estimation method, such as OLS, WLS, maximum likelihood, restricted
      maximum likelihood, permutation, or Bayesian estimation.
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-extraction/analysis
    rank: 1000
    owner: ModelEstimation
    domain_of:
    - ModelEstimation
    range: ExtractedString
  software:
    name: software
    description: Statistical software name, version, and relevant implementation details.
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-extraction/analysis
    owner: ModelEstimation
    domain_of:
    - Preprocessing
    - ModelEstimation
    range: ExtractedString
  spatial_unit:
    name: spatial_unit
    description: 'The element this model was fitted over. Distinct from the Analysis''s
      `spatial_scope`, which gives the extent rather than the element: a whole-brain
      model can be voxelwise or vertexwise, and a model over an ROI can average the
      region or test its parcels. Record it rather than inferring it from `coordinate_space`.

      A model fitted over a different element is a different model, so a voxelwise
      GLM and an ROI-mean ANOVA of the same design take two records: no contrast of
      one can be read off the other''s fit.'
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-extraction/analysis
    rank: 1000
    owner: ModelEstimation
    domain_of:
    - ModelEstimation
    range: ExtractedSpatialUnit
  preprocessing:
    name: preprocessing
    description: 'The pipelines that produced the data this model was fitted to. Every
      Analysis referencing this record came through them, so a model fitted to differently
      prepared data -- unsmoothed images for a classifier, smoothed ones for a mass-univariate
      fit -- takes its own record rather than sharing one.

      More than one entry when the fit consumed more than one kind of image: a multimodal
      regression of perfusion on grey-matter volume was fitted to the output of both
      pipelines, and naming either alone says the other''s smoothing and normalisation
      did not touch the map.'
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-extraction/analysis
    rank: 1000
    owner: ModelEstimation
    domain_of:
    - ModelEstimation
    range: Preprocessing
    multivalued: true
    inlined: false
  inputs_from:
    name: inputs_from
    description: 'The models whose fitted output this model was estimated on: the
      first-level GLM whose contrast images a group model takes as its data, the subject-level
      fit an ROI ANOVA summarises. The stage graph, recorded only where the source
      states it.

      **A model''s terms are its own plus, transitively, those of the models named
      here.** That combined list is what `terms` would be had the analysis been fitted
      in one step.

      Leave it empty when the source describes one design matrix, and when it describes
      the lower stage too thinly to constitute a model. Empty is not a claim that
      no lower stage existed; it is the absence of a statement about one, exactly
      as an unrecorded term is.

      Must be acyclic, no model may reach itself.'
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-extraction/analysis
    rank: 1000
    owner: ModelEstimation
    domain_of:
    - ModelEstimation
    range: ModelEstimation
    multivalued: true
    inlined: false
  terms:
    name: terms
    description: 'The terms **this stage** was specified with -- the columns of its
      design matrix, in the general sense that covers a GLM''s regressors and the
      predictors of any other family. Stated once here however many contrasts are
      taken from them, and never restated on a stage above: the terms of a lower stage
      are reached through `inputs_from`.

      Record every term the source states, including ones no reported contrast tests,
      and including ones mentioned only in passing: "controlling for age and sex"
      is a statement about the design matrix. This list, together with the lists reached
      through `inputs_from`, is **the adjustment set of every contrast taken from
      this model** -- each contrast''s is that combined list minus the terms its cells
      name -- so a term omitted from every stage reads as one the model did not adjust
      for. Where the list is incomplete, the slot''s extraction_status is what says
      so.

      May be empty, and legitimately is for a stage that fits only an intercept: a
      one-sample group test over first-level contrast images has no column of its
      own. Do not invent an intercept term to fill it.

      Analyses whose design matrices differ take their own records rather than sharing
      one.'
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-extraction/analysis
    rank: 1000
    owner: ModelEstimation
    domain_of:
    - ModelEstimation
    range: ModelTerm
    multivalued: true
    inlined: true
    inlined_as_list: true