Class: ModelTerm

One term of the model: a column of the design matrix, or the equivalent predictor in a family with no design matrix. A categorical term names its levels and the entities carrying them; a continuous term carries the facts that make a slope interpretable. Nothing here is a fact about any one contrast -- what a contrast did with this term is a Cell on that contrast's Effect. A term with no cell on some contrast is a term that contrast was adjusted for rather than tested.

URI: neurostudy:ModelTerm

 classDiagram
    class ModelTerm
    click ModelTerm href "../ModelTerm/"
      ModelTerm : assessment





        ModelTerm --> "0..1" Assessment : assessment
        click Assessment href "../Assessment/"



      ModelTerm : functional_form

      ModelTerm : id

      ModelTerm : interaction_with





        ModelTerm --> "*" ModelTerm : interaction_with
        click ModelTerm href "../ModelTerm/"



      ModelTerm : levels





        ModelTerm --> "*" FactorLevel : levels
        click FactorLevel href "../FactorLevel/"



      ModelTerm : name

      ModelTerm : region





        ModelTerm --> "0..1" Region : region
        click Region href "../Region/"



      ModelTerm : source_definition

      ModelTerm : type





        ModelTerm --> "1" TermType : type
        click TermType href "../TermType/"



      ModelTerm : unit

      ModelTerm : variation_level

Slots

Name	Cardinality and Range	Description	Inheritance
id	1 String	Stable identifier, referenced by an Effect's cells and its `mediation	direct
name	1 String	Term label, unique within the model: a name appearing twice is one term recor...	direct
type	1 TermType	Whether the term is categorical or continuous	direct
levels	* FactorLevel	The levels of a categorical term, and for each the entities carrying it	direct
assessment	0..1 Assessment	The assessment whose measurements supply a continuous term, **including when ...	direct
region	0..1 Region	The region whose signal supplies this term: a seed timecourse, an ROI mean co...	direct
variation_level	0..1 String or  VariationLevel	Whether this term moves within a participant or only across the sample	direct
functional_form	0..1 String or  FunctionalForm	Shape of the term's relationship to the measure	direct
interaction_with	* ModelTerm	The other terms this term is a product of -- what makes this column an intera...	direct
unit	0..1 String	The unit a continuous term is measured in, when the source gives one -- years...	direct
source_definition	0..1 String	The source's own definition of the term, and the origin of a continuous term ...	direct

Unique Keys

name_per_model

Unique key slots: name

Usages

used by	used in	type	used
Mediation	mediator	range	ModelTerm
Cell	term	range	ModelTerm
ModelEstimation	terms	range	ModelTerm
ModelTerm	interaction_with	range	ModelTerm

Identifier and Mapping Information

Schema Source

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

Mappings

Mapping Type	Mapped Value
self	neurostudy:ModelTerm
native	neurostudy:ModelTerm

LinkML Source

Direct

name: ModelTerm
description: 'One term of the model: a column of the design matrix, or the equivalent
  predictor in a family with no design matrix. A categorical term names its levels
  and the entities carrying them; a continuous term carries the facts that make a
  slope interpretable. Nothing here is a fact about any one contrast -- what a contrast
  did with this term is a `Cell` on that contrast''s Effect. A term with no cell on
  some contrast is a term that contrast was adjusted for rather than tested.'
from_schema: https://neurostuff.org/schemas/neuroimaging-study-storage
rank: 1000
attributes:
  id:
    name: id
    description: Stable identifier, referenced by an Effect's `cells` and its `mediation.mediator`,
      and by `interaction_with`.
    in_subset:
    - mvp
    - deterministic
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-storage/analysis
    identifier: true
    domain_of:
    - Arm
    - Timepoint
    - Group
    - Task
    - Condition
    - Assessment
    - Region
    - Acquisition
    - Device
    - Analysis
    - Measure
    - Preprocessing
    - ModelEstimation
    - ModelTerm
    - InferenceSettings
    - StatisticalMap
    - Table
    - CoordinateSet
    - Study
    range: string
    required: true
  name:
    name: name
    description: 'Term label, unique within the model: a name appearing twice is one
      term recorded twice. For a categorical term this is the factor''s identity.

      Often a label the source never writes. A paper reporting 1-back, 2-back and
      3-back conditions states the levels and states that they vary together, but
      frequently names no axis; `load` is then a name supplied for a grouping the
      source does make. That is permitted, within two limits: the levels must be source-stated,
      and the name must not assert a comparison or a construct the paper does not.'
    in_subset:
    - mvp
    - model_extracted
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-storage/analysis
    domain_of:
    - Arm
    - Timepoint
    - Group
    - Task
    - Condition
    - Assessment
    - Region
    - Analysis
    - ModelTerm
    - ExternalDataset
    - PerformanceMetric
    range: string
    required: true
  type:
    name: type
    description: 'Whether the term is categorical or continuous. Categorical when
      the column distinguishes named cells of the design -- occasions, cohorts, conditions,
      arms, regions -- whether or not the paper names the axis; `levels` is then required.
      Continuous when the column carries a measured value and the model fits a slope.

      Small as it is, this field settles four others: whether `levels` exists, whether
      a `Cell` here takes a `level`, whether the term can be crossed, and which branch
      of the derived kind fires. A term recorded continuous is one no contrast can
      be built across.

      **A term whose name states a comparison -- `pre > post`, `A versus B` -- is
      almost always a categorical factor written down from its contrast''s side.**
      The design matrix distinguished two occasions, cohorts or conditions; the paper
      labelled the difference and left the axis unnamed. Record the factor with a
      level per side and let the cells carry the direction (`representing-models.md`
      §5.6). Collapsed into one continuous column, nothing says what was compared
      and the effect reads as a slope.

      The exception is a column genuinely holding one number per participant -- a
      difference score, a percent change entered as a covariate. That is continuous,
      and `source_definition` records the subtraction it came from.'
    in_subset:
    - mvp
    - model_extracted
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-storage/analysis
    domain_of:
    - Measure
    - ModelTerm
    range: TermType
    required: true
  levels:
    name: levels
    description: 'The levels of a categorical term, and for each the entities carrying
      it. This is the whole of what a factor is: its level vocabulary, and which cohort,
      condition, occasion, or arm occupies each cell. Record a level the source names
      even when no reported contrast uses it -- a three-level factor contrasted at
      two levels is still a three-level factor. Empty for a continuous term.'
    in_subset:
    - mvp
    - model_extracted
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-storage/analysis
    rank: 1000
    domain_of:
    - ModelTerm
    range: FactorLevel
    multivalued: true
    inlined_as_list: true
  assessment:
    name: assessment
    description: 'The assessment whose measurements supply a continuous term, **including
      when the column is derived from them rather than being one of them**: a change
      score, a percent change, a composite of subscales, a residualized score. The
      instrument is still where the values came from, and one administration or several
      makes no difference to that -- `region` says the same by example, an ROI mean
      and a PPI regressor both naming their region.

      One instrument, one record, however many columns it supplies: two subscale scores
      of one questionnaire each name it, and which subscale a column carries is the
      term''s `name`.

      Unset only when the values come from somewhere the study does not record as
      an Assessment -- age, dose, a motion parameter, cardiac phase, scanner drift
      -- in which case `source_definition` names the origin. A term with neither is
      a column whose origin the record does not state.'
    in_subset:
    - mvp
    - model_extracted
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-storage/analysis
    rank: 1000
    domain_of:
    - ModelTerm
    range: Assessment
    inlined: false
  region:
    name: region
    description: 'The region whose signal supplies this term: a seed timecourse, an
      ROI mean covariate, a PPI physiological regressor. The counterpart of `assessment`
      for a column drawn from a place in the brain rather than an instrument.

      Singular, so it does not serve a factor that *compares* regions: that is one
      term with several levels, and the regions hang off `FactorLevel.regions`.'
    in_subset:
    - mvp
    - model_extracted
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-storage/analysis
    rank: 1000
    domain_of:
    - ModelTerm
    range: Region
    inlined: false
  variation_level:
    name: variation_level
    description: 'Whether this term moves within a participant or only across the
      sample. Populate it for **any** term: a repeated-measures factor is within-subject
      and a diagnosis factor is between-subject in exactly the sense a trial-wise
      modulator and an age covariate are.

      For a continuous term it is what separates a parametric modulation from a cross-subject
      regression, and the derived kind of any effect testing it reads this on that
      basis. For a categorical factor it feeds no derivation, so setting it changes
      no other value; it is the factor''s scope, and two studies that crossed a factor
      within participants and between them did not estimate the same thing.

      A categorical factor''s levels usually settle it, and the two should agree:
      levels naming `groups` are between-subject, since a participant belongs to one
      cohort; levels naming `timepoints` are within-subject, since an occasion is
      when the same people were measured again; levels naming `conditions` are within-subject
      in the ordinary repeated-measures case; levels naming `arms` follow `StudyDesign.assignment_structure`,
      crossover being within and parallel between.

      A level the vocabulary cannot name is written here as free text; the derived
      kind then cannot choose between a modulation and a regression, so it is undetermined
      for that record rather than wrong.'
    in_subset:
    - mvp
    - model_extracted
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-storage/analysis
    rank: 1000
    domain_of:
    - ModelTerm
    any_of:
    - range: VariationLevel
    - range: string
  functional_form:
    name: functional_form
    description: 'Shape of the term''s relationship to the measure. A squared term
      with a negative coefficient is an inverted-U relationship, not a negative association,
      so non-linear and transformed terms must not be recorded as linear. A model
      fitting both a linear and a quadratic form of the same measurement has two terms,
      not one.

      Not where a product is recorded: a non-empty `interaction_with` is what makes
      a column a product.'
    in_subset:
    - mvp
    - model_extracted
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-storage/analysis
    rank: 1000
    domain_of:
    - ModelTerm
    any_of:
    - range: FunctionalForm
    - range: string
  interaction_with:
    name: interaction_with
    description: 'The other terms this term is a product of -- what makes this column
      an interaction column. Populate it when the source names an interaction term
      in one model; leave it empty when the source describes a regression on a contrast.

      The terms it may name are those of this model and of the stages it reaches through
      `inputs_from`, which is how a group stage crosses a cohort factor with a first-level
      condition: the product column is declared where it was fitted and names the
      lower stage''s column directly.

      A crossing of two factors is normally read off the cells, since a factor compared
      against itself carries a positive cell and a negative one. A continuous term
      has no levels and so cannot be crossed that way, which makes this slot the only
      record of a moderation such as `age x group`; the derived kind reads it before
      `variation_level`.

      A product of terms that are all categorical and all crossed is legal but decides
      nothing, the crossed cells already saying what it says, and is flagged for review.

      A product column declares no `levels` of its own; a signed cell on one with
      a continuous component may name a level of the factor, saying whose slope the
      sign describes. Such a column is not a covariate of a contrast whose cells name
      all of its components.'
    in_subset:
    - mvp
    - model_extracted
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-storage/analysis
    rank: 1000
    domain_of:
    - ModelTerm
    range: ModelTerm
    multivalued: true
    inlined: false
  unit:
    name: unit
    description: The unit a continuous term is measured in, when the source gives
      one -- years for age, mg for a dose. It is what makes a reported slope interpretable.
    in_subset:
    - mvp
    - model_extracted
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-storage/analysis
    domain_of:
    - Measure
    - ModelTerm
    range: string
  source_definition:
    name: source_definition
    description: 'The source''s own definition of the term, and the origin of a continuous
      term that no Assessment supplies, such as age, dose, a motion parameter, cardiac
      phase, or scanner drift.

      **Required for a derived column, whatever its `assessment` says.** A change
      score names its instrument in `assessment` and its derivation here, in the source''s
      own words and including the occasions it spans -- "percent reduction in BDI,
      (post-pre)/pre, from baseline to post-treatment". Nothing else can carry those
      occasions: `FactorLevel.timepoints` names the occasions a factor *compares*,
      and a derived column has no levels to hang them on, so where a study has several
      post-intervention occasions this is the only thing separating a change to the
      endpoint from a change to a later follow-up.

      Not the shape of the fitted relationship, which is `functional_form`: a percent
      change entered linearly is a linear term computed from a difference, so recording
      the construction as the form would lose whether the fit was linear or quadratic.
      A transform *of the measure* the vocabulary cannot name still goes in functional_form.'
    in_subset:
    - mvp
    - model_extracted
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-storage/analysis
    rank: 1000
    domain_of:
    - ModelTerm
    range: string
unique_keys:
  name_per_model:
    unique_key_name: name_per_model
    unique_key_slots:
    - name

Induced

name: ModelTerm
description: 'One term of the model: a column of the design matrix, or the equivalent
  predictor in a family with no design matrix. A categorical term names its levels
  and the entities carrying them; a continuous term carries the facts that make a
  slope interpretable. Nothing here is a fact about any one contrast -- what a contrast
  did with this term is a `Cell` on that contrast''s Effect. A term with no cell on
  some contrast is a term that contrast was adjusted for rather than tested.'
from_schema: https://neurostuff.org/schemas/neuroimaging-study-storage
rank: 1000
attributes:
  id:
    name: id
    description: Stable identifier, referenced by an Effect's `cells` and its `mediation.mediator`,
      and by `interaction_with`.
    in_subset:
    - mvp
    - deterministic
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-storage/analysis
    identifier: true
    owner: ModelTerm
    domain_of:
    - Arm
    - Timepoint
    - Group
    - Task
    - Condition
    - Assessment
    - Region
    - Acquisition
    - Device
    - Analysis
    - Measure
    - Preprocessing
    - ModelEstimation
    - ModelTerm
    - InferenceSettings
    - StatisticalMap
    - Table
    - CoordinateSet
    - Study
    range: string
    required: true
  name:
    name: name
    description: 'Term label, unique within the model: a name appearing twice is one
      term recorded twice. For a categorical term this is the factor''s identity.

      Often a label the source never writes. A paper reporting 1-back, 2-back and
      3-back conditions states the levels and states that they vary together, but
      frequently names no axis; `load` is then a name supplied for a grouping the
      source does make. That is permitted, within two limits: the levels must be source-stated,
      and the name must not assert a comparison or a construct the paper does not.'
    in_subset:
    - mvp
    - model_extracted
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-storage/analysis
    owner: ModelTerm
    domain_of:
    - Arm
    - Timepoint
    - Group
    - Task
    - Condition
    - Assessment
    - Region
    - Analysis
    - ModelTerm
    - ExternalDataset
    - PerformanceMetric
    range: string
    required: true
  type:
    name: type
    description: 'Whether the term is categorical or continuous. Categorical when
      the column distinguishes named cells of the design -- occasions, cohorts, conditions,
      arms, regions -- whether or not the paper names the axis; `levels` is then required.
      Continuous when the column carries a measured value and the model fits a slope.

      Small as it is, this field settles four others: whether `levels` exists, whether
      a `Cell` here takes a `level`, whether the term can be crossed, and which branch
      of the derived kind fires. A term recorded continuous is one no contrast can
      be built across.

      **A term whose name states a comparison -- `pre > post`, `A versus B` -- is
      almost always a categorical factor written down from its contrast''s side.**
      The design matrix distinguished two occasions, cohorts or conditions; the paper
      labelled the difference and left the axis unnamed. Record the factor with a
      level per side and let the cells carry the direction (`representing-models.md`
      §5.6). Collapsed into one continuous column, nothing says what was compared
      and the effect reads as a slope.

      The exception is a column genuinely holding one number per participant -- a
      difference score, a percent change entered as a covariate. That is continuous,
      and `source_definition` records the subtraction it came from.'
    in_subset:
    - mvp
    - model_extracted
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-storage/analysis
    owner: ModelTerm
    domain_of:
    - Measure
    - ModelTerm
    range: TermType
    required: true
  levels:
    name: levels
    description: 'The levels of a categorical term, and for each the entities carrying
      it. This is the whole of what a factor is: its level vocabulary, and which cohort,
      condition, occasion, or arm occupies each cell. Record a level the source names
      even when no reported contrast uses it -- a three-level factor contrasted at
      two levels is still a three-level factor. Empty for a continuous term.'
    in_subset:
    - mvp
    - model_extracted
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-storage/analysis
    rank: 1000
    owner: ModelTerm
    domain_of:
    - ModelTerm
    range: FactorLevel
    multivalued: true
    inlined: true
    inlined_as_list: true
  assessment:
    name: assessment
    description: 'The assessment whose measurements supply a continuous term, **including
      when the column is derived from them rather than being one of them**: a change
      score, a percent change, a composite of subscales, a residualized score. The
      instrument is still where the values came from, and one administration or several
      makes no difference to that -- `region` says the same by example, an ROI mean
      and a PPI regressor both naming their region.

      One instrument, one record, however many columns it supplies: two subscale scores
      of one questionnaire each name it, and which subscale a column carries is the
      term''s `name`.

      Unset only when the values come from somewhere the study does not record as
      an Assessment -- age, dose, a motion parameter, cardiac phase, scanner drift
      -- in which case `source_definition` names the origin. A term with neither is
      a column whose origin the record does not state.'
    in_subset:
    - mvp
    - model_extracted
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-storage/analysis
    rank: 1000
    owner: ModelTerm
    domain_of:
    - ModelTerm
    range: Assessment
    inlined: false
  region:
    name: region
    description: 'The region whose signal supplies this term: a seed timecourse, an
      ROI mean covariate, a PPI physiological regressor. The counterpart of `assessment`
      for a column drawn from a place in the brain rather than an instrument.

      Singular, so it does not serve a factor that *compares* regions: that is one
      term with several levels, and the regions hang off `FactorLevel.regions`.'
    in_subset:
    - mvp
    - model_extracted
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-storage/analysis
    rank: 1000
    owner: ModelTerm
    domain_of:
    - ModelTerm
    range: Region
    inlined: false
  variation_level:
    name: variation_level
    description: 'Whether this term moves within a participant or only across the
      sample. Populate it for **any** term: a repeated-measures factor is within-subject
      and a diagnosis factor is between-subject in exactly the sense a trial-wise
      modulator and an age covariate are.

      For a continuous term it is what separates a parametric modulation from a cross-subject
      regression, and the derived kind of any effect testing it reads this on that
      basis. For a categorical factor it feeds no derivation, so setting it changes
      no other value; it is the factor''s scope, and two studies that crossed a factor
      within participants and between them did not estimate the same thing.

      A categorical factor''s levels usually settle it, and the two should agree:
      levels naming `groups` are between-subject, since a participant belongs to one
      cohort; levels naming `timepoints` are within-subject, since an occasion is
      when the same people were measured again; levels naming `conditions` are within-subject
      in the ordinary repeated-measures case; levels naming `arms` follow `StudyDesign.assignment_structure`,
      crossover being within and parallel between.

      A level the vocabulary cannot name is written here as free text; the derived
      kind then cannot choose between a modulation and a regression, so it is undetermined
      for that record rather than wrong.'
    in_subset:
    - mvp
    - model_extracted
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-storage/analysis
    rank: 1000
    owner: ModelTerm
    domain_of:
    - ModelTerm
    range: string
    any_of:
    - range: VariationLevel
    - range: string
  functional_form:
    name: functional_form
    description: 'Shape of the term''s relationship to the measure. A squared term
      with a negative coefficient is an inverted-U relationship, not a negative association,
      so non-linear and transformed terms must not be recorded as linear. A model
      fitting both a linear and a quadratic form of the same measurement has two terms,
      not one.

      Not where a product is recorded: a non-empty `interaction_with` is what makes
      a column a product.'
    in_subset:
    - mvp
    - model_extracted
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-storage/analysis
    rank: 1000
    owner: ModelTerm
    domain_of:
    - ModelTerm
    range: string
    any_of:
    - range: FunctionalForm
    - range: string
  interaction_with:
    name: interaction_with
    description: 'The other terms this term is a product of -- what makes this column
      an interaction column. Populate it when the source names an interaction term
      in one model; leave it empty when the source describes a regression on a contrast.

      The terms it may name are those of this model and of the stages it reaches through
      `inputs_from`, which is how a group stage crosses a cohort factor with a first-level
      condition: the product column is declared where it was fitted and names the
      lower stage''s column directly.

      A crossing of two factors is normally read off the cells, since a factor compared
      against itself carries a positive cell and a negative one. A continuous term
      has no levels and so cannot be crossed that way, which makes this slot the only
      record of a moderation such as `age x group`; the derived kind reads it before
      `variation_level`.

      A product of terms that are all categorical and all crossed is legal but decides
      nothing, the crossed cells already saying what it says, and is flagged for review.

      A product column declares no `levels` of its own; a signed cell on one with
      a continuous component may name a level of the factor, saying whose slope the
      sign describes. Such a column is not a covariate of a contrast whose cells name
      all of its components.'
    in_subset:
    - mvp
    - model_extracted
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-storage/analysis
    rank: 1000
    owner: ModelTerm
    domain_of:
    - ModelTerm
    range: ModelTerm
    multivalued: true
    inlined: false
  unit:
    name: unit
    description: The unit a continuous term is measured in, when the source gives
      one -- years for age, mg for a dose. It is what makes a reported slope interpretable.
    in_subset:
    - mvp
    - model_extracted
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-storage/analysis
    owner: ModelTerm
    domain_of:
    - Measure
    - ModelTerm
    range: string
  source_definition:
    name: source_definition
    description: 'The source''s own definition of the term, and the origin of a continuous
      term that no Assessment supplies, such as age, dose, a motion parameter, cardiac
      phase, or scanner drift.

      **Required for a derived column, whatever its `assessment` says.** A change
      score names its instrument in `assessment` and its derivation here, in the source''s
      own words and including the occasions it spans -- "percent reduction in BDI,
      (post-pre)/pre, from baseline to post-treatment". Nothing else can carry those
      occasions: `FactorLevel.timepoints` names the occasions a factor *compares*,
      and a derived column has no levels to hang them on, so where a study has several
      post-intervention occasions this is the only thing separating a change to the
      endpoint from a change to a later follow-up.

      Not the shape of the fitted relationship, which is `functional_form`: a percent
      change entered linearly is a linear term computed from a difference, so recording
      the construction as the form would lose whether the fit was linear or quadratic.
      A transform *of the measure* the vocabulary cannot name still goes in functional_form.'
    in_subset:
    - mvp
    - model_extracted
    from_schema: https://neurostuff.org/schemas/neuroimaging-study-storage/analysis
    rank: 1000
    owner: ModelTerm
    domain_of:
    - ModelTerm
    range: string
unique_keys:
  name_per_model:
    unique_key_name: name_per_model
    unique_key_slots:
    - name