data-raw/naming_refactoring.md

In bbuchsbaum/fmrireg: R package for the anlysis of fmri data

Design Matrix Naming Refactoring Plan

This document outlines the plan to refactor the design matrix column naming scheme within the fmrireg package. The goal is to establish a consistent, deterministic, and unambiguous grammar for column names generated from event models.

1. Naming Grammar Specification

1.1 Building Blocks (Atomic Tokens)

• Factor Level: Var.Level (e.g., cond.A, run.2) - Sanitized variable name, dot, sanitized level name. Used as a component in condition_tag.
• Generative Basis Index: ## (e.g., 01, 02) - Zero-padded index for columns generated by functions like Poly, BSpline. Used as a component in condition_tag.
• Ident Variable Name: var (e.g., RT1, Age) - Raw variable name used directly when passed via Ident(). Used as a component in condition_tag for these specific terms.
• HRF Basis Suffix: _b## (e.g., _b01, _b05) - Underscore, 'b', dynamically zero-padded HRF basis index. Appended at the very end by make_column_names if the HRF has nbasis > 1.

1.2 Condition Tag (condition_tag)

• Purpose: Identifies the specific regressor within a given hrf() term, relative to its term_tag.
• Structure:
  • For simple factors: Var.Level (e.g., cond.a).
  • For generative bases (Poly, BSpline): Just the zero-padded index (01, 02). The basis type and variable info are captured by the term_tag.
  • For Ident() variables (within an Ident()-only term): The raw variable name (RT1).
  • For interactions: Components joined by _ (e.g., cond.a_01 for hrf(cond, Poly(RT,2))).
• Generation: Assembled by conditions.event_term. For continuous/basis components, it relies on columns(event_object) which ultimately (via columns.event and levels(basis_object)) sources these minimal indices from the levels.ParametricBasis methods (e.g. levels.Poly returning 01, 02). For factor components, it uses tokens from level_token().

1.3 Term Tag (term_tag)

• Purpose: Identifies the entire hrf(...) term, acting as a namespace prefix for its columns.
• Generation:
  • Derived from user-provided id= argument in hrf(), OR
  • Defaults to a name derived from the variable(s)/expression(s) passed to hrf() (e.g., condition, Poly_RT, condition_RT).
  • Sanitized (e.g., . -> _).
  • Made unique across the model via make_unique_tags (e.g., condition, condition#1).
• Special Case (Ident-only): For hrf(Ident(V1, V2, ...)) without an explicit id=, the term_tag is intentionally set to NULL by make_term_tag. This signals that these variables should not be prefixed.

1.4 Final Column Name Structure

1. General Case: term_tag + _ + condition_tag + [_b## HRF suffix]

2. Special Case (Ident-only, no id): (term_tag is NULL) condition_tag + [_b## HRF suffix] (Where condition_tag is the raw variable name, e.g., RT1)

3. This single canonical structure (with the Ident exception) replaces previous compact/qualified styles.

4. Construction happens in make_column_names, called by convolve.event_term.

1.4.1 Examples of Final Column Names

• hrf(condition) -> condition_cond.a, condition_cond.b
• hrf(condition, id="Cond") -> Cond_cond.a, Cond_cond.b
• hrf(condition, basis="spmg3") -> condition_cond.a_b01, condition_cond.a_b02, condition_cond.a_b03, condition_cond.b_b01, ...
• hrf(Ident(RT1, RT2)) -> RT1, RT2
• hrf(Ident(RT1, RT2), id="myID") -> myID_RT1, myID_RT2
• hrf(Ident(RT1, RT2), basis="spmg2") -> RT1_b01, RT1_b02, RT2_b01, RT2_b02
• hrf(Ident(RT1, Age)) + hrf(Ident(RT1, RT2)) -> RT1, Age, RT1.1, RT2 (warning issued by make.names)
• hrf(Poly(RT, 2)) -> Poly_RT_01, Poly_RT_02
• hrf(Poly(RT, 2), id="MyPoly") -> MyPoly_01, MyPoly_02
• hrf(Poly(RT, 2), basis="spmg2") -> Poly_RT_01_b01, Poly_RT_01_b02, Poly_RT_02_b01, Poly_RT_02_b02
• hrf(condition, Poly(RT, 2), id="MyInt") -> MyInt_cond.a_01, MyInt_cond.a_02, MyInt_cond.b_01, MyInt_cond.b_02
• hrf(condition) + hrf(condition) -> Term tags condition and condition#1. Columns: condition_cond.a, condition_cond.b, condition#1_cond.a, condition#1_cond.b.

1.5 Guarantees

• Uniqueness: All final column names in the design matrix are unique and syntactically valid R names.
  • Uniqueness of term_tags (when not NULL) is handled preemptively by make_term_tag using # suffixes.
  • Global uniqueness of the final assembled column names is ensured by build_event_model_design_matrix, which applies make.names(..., unique = TRUE) as a final step. This resolves any remaining clashes (e.g., from multiple Ident() terms proposing the same raw variable name) by appending suffixes like .1, .2.
• Determinism: Same formula, data, and HRF specifications yield reproducible names (up to the suffixes added by make.names for uniqueness).
• Clarity: Aims for readable names, balancing conciseness (e.g., for Ident) with necessary namespacing (via term_tag) for more complex terms or explicit user IDs.

2. Migration Plan Summary

A step-by-step refactoring process targeting specific functions in order:

1. Prep Work: Create R/naming-utils.R with core helper functions.
2. hrf() / hrfspec(): Ensure hrfspec$id is only set if explicitly provided by user.
3. realise_event_terms(): Generate and store term_tag (potentially NULL for Ident-only) via make_term_tag. Attach term_tag attribute to event_term objects.
4. levels.ParametricBasis methods: Ensure levels.Poly, levels.BSpline, etc. (when called on a basis object, typically via columns(event_object) -> columns.event in the naming pipeline) return only zero-padded indices. Ensure levels.Ident returns raw variable names. (Dedicated columns.BasisType S3 methods should also align if used directly elsewhere).
5. conditions.event_term(): Rewrite to assemble condition_tags using tokens from level_token and (indirectly, as described above) levels.ParametricBasis methods, handling interactions.
6. convolve.event_term(): Simplify. Use make_column_names() helper, passing the term_tag attribute (which might be NULL) and base condition names. This is the sole place final proposed names for a term are constructed.
7. Event term construction (event_term()): Internal legacy column naming logic for basis functions within event_term objects (if any existed beyond what design_matrix and convolve.event_term now handle) is removed/superseded. The primary naming construction occurs in later stages.
8. build_event_model_design_matrix(): Apply make.names(..., unique=TRUE) to the combined column names before returning the final matrix.
9. Tests & Docs: Update tests, documentation, and examples to reflect the final naming scheme.

3. expand_basis Flag Handling

• Flag remains in conditions(). Used only to control whether conditions() returns basis-collapsed (cond.a) or basis-expanded (cond.a_b01, cond.a_b02) condition tags.
• convolve.event_term (and thus the final design matrix) always includes the HRF basis suffix (_b##) if nbasis > 1, regardless of this flag's value passed to conditions().

4. naming-utils.R Specification

Defines helper functions. Key decisions: Exports: Only sanitize, zeropad, basis_suffix are exported. Internal Helpers: make_unique_tags, make_term_tag, level_token, continuous_token, make_cond_tag, add_basis, make_column_names marked internal (@keywords internal). Padding: zeropad used for both HRF basis suffix (_b##) and generative basis indices (01, 02). Sanitization: sanitize(allow_dot=FALSE) used for term tags; sanitize(allow_dot=TRUE) generally used elsewhere. Basis Condition Tags: levels.Poly, levels.BSpline (called via columns(event_object_with_basis) in the naming pipeline) return only the zero-padded index (e.g., "01") as the condition_tag component. Info about basis type/variable captured in term_tag. Ident Handling: make_term_tag returns NULL for hrf(Ident(V1,V2,...)) without explicit id=. make_column_names detects this and produces final column names directly from the Ident variable names (V1, V2), plus any HRF basis suffix. * Global Uniqueness: Guaranteed by build_event_model_design_matrix applying make.names(..., unique=TRUE).

bbuchsbaum/fmrireg documentation built on June 10, 2025, 8:18 p.m.