Variable & ID Mapping
A statistical test doesn't know which column is your group, which is your subject ID, or which is your batch. Without explicit mapping, Licklider cannot detect paired structure, pseudoreplication, or batch confounding. Variable & ID Mapping makes these relationships explicit —once, at the start of the session —so every downstream guard has the context it needs.
STEP 1 —The Pitfall: Unmapped Structure, Undetected Errors
Most statistical errors that arise from study design are invisible to the analysis software —
not because the software can't detect them, but because it doesn't know where to look.
When a researcher uploads a CSV with columns named value, grp,
mouse_id, plate_no, and day, the software sees five
columns of numbers. Without knowing that grp is the group variable,
mouse_id is the subject identifier, and plate_no is the batch,
critical checks are impossible:
- Paired/unpaired confusion. If
mouse_idis not mapped, Licklider cannot verify whether the comparison is paired (same mice before/after) or unpaired (different mice). The test may run as unpaired when a paired test is appropriate —or vice versa — without any warning. - Pseudoreplication undetected. Without a mapped subject ID, Licklider cannot check whether multiple rows come from the same biological unit. Technical replicates look identical to biological replicates.
- Batch confounding invisible. If
plate_nois not declared as the batch variable, Licklider cannot check whether all control samples are on one plate and all treatment samples on another —a confound that would invalidate the primary comparison. - Repeated measures structure ignored. Without a mapped time point column, longitudinal data is treated as cross-sectional, and the appropriate repeated measures or mixed model is never suggested.
STEP 2 —Journal Requirement
Nature Methods and Cell require that the statistical analysis section of the Methods explicitly describe the data structure: which variables were treated as fixed effects, which as random effects, and how repeated measurements or nested structure was handled. JAMA's statistical guidelines require that "variables included in the analysis and their roles (outcome, exposure, confounder, effect modifier)" be stated.
For clinical research, ICH E9 requires a complete variable specification in the Statistical Analysis Plan: which variable is the primary endpoint, which is the grouping factor, and which are covariates. CONSORT requires the analysis population to be defined in terms of the randomized group variable, subject ID (for paired designs), and any stratification factors.
The practical consequence is that a complete Data Contract —with explicit variable mapping — is a prerequisite for meeting these requirements. Without it, the Methods section must be reconstructed from the analysis code or from memory.
STEP 3 —Licklider's Solution
Input
- An interactive mapping interface, presented after the Observation Unit Declaration, showing all columns in the uploaded dataset with dropdown assignments for each semantic role: Outcome variable, Group variable, Subject ID / Donor ID / Animal ID, Batch ID / Plate ID, Time point, Covariate (optional), Unmapped.
- Multiple subject ID columns can be declared when the nesting is multi-level (e.g., animal ID + litter ID for multi-level pseudoreplication detection).
- The mapping is locked once confirmed. Columns marked as "Unmapped" are still accessible for visualization and covariate adjustment but do not trigger structural guards.
Output
- Locked variable mapping. Every downstream analysis uses the declared mapping: group comparisons use the group variable, paired tests use the subject ID, batch alerts use the batch ID, and time-series guards use the time point column.
- Structure summary panel. A compact display showing the confirmed mapping alongside detected structure (e.g., "3 animals x4 slices / animal; 2 plates").
- Automated guard activation. Mapping a subject ID column activates the Pseudoreplication Detection guard (4.5.1), Biological vs. Technical Replicate guard (4.5.2), and Paired vs. Unpaired Guard (4.4.1). Mapping a batch ID activates Batch/Plate Confounding Detection (4.5.3).
Guard
Guard condition —Group variable not mapped: If no group variable is declared, Licklider cannot perform any group comparison analysis. All comparative tests are blocked until a group variable is assigned. Descriptive analyses and single-variable plots are still available.
Guard condition —Batch confound detected: After mapping the batch ID, Licklider checks for complete confounding between batch and group (e.g., all Control samples on Plate 1, all Treatment samples on Plate 2). If detected, a "batch-group confound" alert is raised and the primary comparison is blocked until the researcher acknowledges the confounding and either resolves it or declares it in the Methods.
STEP 4 —Draft Output (Draft / Needs review)
Example: Data structure declaration in Methods
Data were structured as follows: the primary outcome variable was tumor
volume (mm^3, continuous); the grouping variable was treatment assignment
(2 levels: Control, Treatment); the subject identifier was mouse_id
(n = 15 unique animals); batch was encoded as plate number (3 plates,
with samples balanced across plates and groups). The time point variable
encoded measurement days (days 0, 7, 14, and 21). Variable mapping was
declared and locked prior to analysis in the Licklider Data Contract
(mapping ID: map-5b2e).Example: Paired structure declaration
The study used a paired design; each animal contributed measurements at
both baseline (day 0) and endpoint (day 21). The subject identifier
(mouse_id) was declared as the pairing variable in the Licklider Data
Contract prior to analysis. All group comparisons used paired tests
consistent with this declared structure (Licklider mapping ID: map-2c9a).