alterlab-redcap-cdisc

$npx mdskill add AlterLab-IEU/AlterLab-Academic-Skills/alterlab-redcap-cdisc

Designs REDCap data dictionaries and maps studies to CDISC standards.

  • Builds REDCap projects from a requirements spec with validated fields.
  • Uses local rules and bundled linter; no external API required.
  • Lints data dictionaries for common errors and validates branching logic.
  • Outputs offline CSV data dictionaries and CDISC mapping documentation.

SKILL.md

.github/skills/alterlab-redcap-cdiscView on GitHub ↗
---
name: alterlab-redcap-cdisc
description: "Designs validated research data-capture instruments and aligns them to CDISC submission standards. Builds REDCap projects from a requirements spec: instrument and field design, the 18-column data dictionary (Variable/Field Name, Form Name, Field Type, Choices, Branching Logic, Text Validation, Identifier?), field validation (date_ymd, integer, number, email, phone), branching/show-field logic, longitudinal events and survey settings, and lints a data dictionary for common errors. Maps a study to CDISC: CDASH collection fields, SDTM domain mapping (DM, AE, VS, LB, EX, CM, MH across Interventions/Events/Findings classes), and NCI-EVS controlled terminology. Use when the user wants to build a REDCap project, write or lint a data dictionary, set up branching logic or validation, or map a study to CDISC SDTM/CDASH/CDISC CT. For LabArchives ELN bridging use alterlab-labarchive; for Likert/sampling/reliability use alterlab-survey-design. Part of the AlterLab Academic Skills suite."
license: MIT
allowed-tools: Read Write Edit Bash(python:*) Bash WebSearch WebFetch
compatibility: No API key required — designs REDCap data dictionaries as offline CSV and maps to CDISC standards from local rules; the bundled linter is stdlib-only `uv run python`. Pushing a dictionary into a live REDCap instance (the REDCap API) is out of scope and delegated to the instance owner.
metadata:
  skill-author: AlterLab
  version: "1.0.0"
  last_updated: "2026-06-06"
  depends_on: "alterlab-labarchive (ELN bridge), alterlab-survey-design (psychometrics)"
---

# REDCap & CDISC — Research Data Capture and Standards Alignment

Designs **validated electronic data capture (EDC)** instruments in REDCap and
aligns a study's variables to **CDISC** submission standards. It owns two jobs
that overlap with sibling skills only at the edges:

1. **REDCap project & instrument design** — turn a study's requirements into a
   REDCap **data dictionary** (the importable 18-column CSV), with correct field
   types, validation, branching logic, longitudinal events, and survey settings.
2. **CDISC alignment** — map collected variables to **CDASH** (collection) and
   **SDTM** (tabulation) domains, and tie coded values to **CDISC Controlled
   Terminology** (NCI-EVS), so the data is submission- and reuse-ready.

This is design + standards work, not a live-API connector. Producing the CSV and
the mapping is in scope; importing it into a running REDCap server is the
instance owner's job (REDCap's own API/UI).

## Quick Start

```
Build me a REDCap data dictionary for a 3-arm RCT screening + follow-up.
Add branching logic so the pregnancy question only shows when sex = female.
Lint this data_dictionary.csv before I import it.
Map my CRF variables to CDISC SDTM domains and CDASH fields.
Which SDTM domain and controlled-terminology codelist does "adverse event" go in?
```

→ Draft or read the dictionary, run `scripts/lint_data_dictionary.py` to catch
structural errors, then (for CDISC) produce a variable → CDASH → SDTM mapping
table. Always state which facts are design conventions vs. instance-specific.

---

## When to Use This Skill

Use it when the request is about **building the instrument or making it
standards-compliant**:

- "Build / design a REDCap project, form, or data dictionary."
- "Write the importable REDCap CSV for these variables."
- "Set up branching logic / show-field logic / field validation / required fields."
- "Configure longitudinal events / arms / repeating instruments / a survey."
- "Lint / validate / debug my data dictionary before import."
- "Map my study to CDISC — which SDTM domain / CDASH field / codelist?"
- "Make my CRF submission-ready (SDTM/CDASH/CDISC CT)."

### Does NOT Trigger — route to the right sibling

| The request is really about… | Route to |
|------------------------------|----------|
| Bridging an **ELN** to REDCap; reading/writing LabArchives notebook entries or attachments via its REST API | `alterlab-labarchive` |
| **Psychometrics** — Likert scale construction, response-bias mitigation, sampling strategy, pilot testing, reliability/validity (Cronbach's α, factor analysis) | `alterlab-survey-design` |
| Picking or running the **statistical test**, assumptions, power/sample size, APA results | `alterlab-statistical-analysis` |
| **KVKK / Turkish data-protection** plan, anonymization, VERBIS, açık rıza | `alterlab-kvkk-dmp` |
| **IRB / ethics application**, informed consent, GDPR/HIPAA, human-subjects protocol | `alterlab-research-ethics` (or `alterlab-tr-research-ethics` for Turkish etik kurul) |
| **Finding** registered trials by condition/NCT ID on ClinicalTrials.gov | `alterlab-clinicaltrials` |
| **ISO 13485** medical-device QMS documentation | `alterlab-iso13485` |

Routing rule of thumb: **survey-design owns the questions and their measurement
properties; this skill owns the database that captures them and its standards
mapping.** If the user asks for both (e.g. "design a validated depression scale
*and* the REDCap form for it"), do the scale work under `alterlab-survey-design`
and the dictionary/mapping here.

---

## REDCap Data Dictionary (the importable CSV)

REDCap projects are defined by a **data dictionary** — a CSV with **18 columns
in a fixed order**. Authoring or repairing this CSV is the core deliverable.

| # | Column header | Purpose |
|---|---------------|---------|
| 1 | Variable / Field Name | Lowercase machine name (export/analysis). |
| 2 | Form Name | Instrument the field belongs to. |
| 3 | Section Header | Visual section break above the field. |
| 4 | Field Type | One of the values below. |
| 5 | Field Label | Human-readable prompt shown on the form. |
| 6 | Choices, Calculations, OR Slider Labels | `1, Yes \| 0, No` for choice fields; the equation for `calc`. |
| 7 | Field Note | Helper text under the field. |
| 8 | Text Validation Type OR Show Slider Number | Validation for `text`; slider display. |
| 9 | Text Validation Min | Lower bound (integer/number/date). |
| 10 | Text Validation Max | Upper bound. |
| 11 | Identifier? | `y` marks PII/PHI (drives de-identified exports). |
| 12 | Branching Logic (Show field only if...) | Show-field condition. |
| 13 | Required Field? | `y` / blank. |
| 14 | Custom Alignment | Layout. |
| 15 | Question Number (surveys only) | Survey numbering. |
| 16 | Matrix Group Name | Groups matrix fields. |
| 17 | Matrix Ranking? | Matrix ranking flag. |
| 18 | Field Annotation | Action tags / annotations (e.g. `@HIDDEN`). |

**Field Type values:** `text`, `notes`, `dropdown`, `radio`, `checkbox`,
`calc`, `sql`, `descriptive`, `slider`, `yesno`, `truefalse`, `file`.

**Text Validation Type values:** `date_ymd`, `date_mdy`, `datetime_ymd`,
`time`, `integer`, `number`, `email`, `phone`, `zipcode`.

Deeper field-by-field rules, the choice-string grammar, branching-logic
operators, longitudinal/repeating-instrument design, and a worked dictionary are
in **[references/redcap_design.md](references/redcap_design.md)**.

### Lint before import

```bash
uv run python skills/faculty-life/alterlab-redcap-cdisc/scripts/lint_data_dictionary.py \
    path/to/data_dictionary.csv
```

The linter is **stdlib-only** (no network, no REDCap account). It checks the
18-column header, field-name syntax, field-type/validation legality, that choice
fields carry a choices string, that `calc`/branching fields reference variables
that exist, duplicate variable names, and PII fields left unflagged as
`Identifier?`. It exits non-zero and emits a JSON report when issues are found.
It is a **structural** linter — it does not validate against a live REDCap
server, so always tell the user a clean lint still needs a test import.

---

## CDISC Alignment (CDASH → SDTM → Controlled Terminology)

CDISC defines complementary standards across the data lifecycle. Map a study so
its collected data is regulator- and reuse-ready.

| Standard | Role | What you produce |
|----------|------|------------------|
| **CDASH** | *Collection* — standard fields to collect on CRFs; traces into SDTM. | The CRF/REDCap fields named to CDASH conventions. |
| **SDTM** | *Tabulation* — organizes submitted data into domains. | A variable → domain mapping. |
| **Controlled Terminology** | Codelists of valid values (NCI-EVS). | Coded values tied to the right codelist. |

**SDTM observation classes:** Interventions, Events, Findings, and Findings
About. Common domains and their two-letter codes: **DM** Demographics, **AE**
Adverse Events, **VS** Vital Signs, **LB** Laboratory, **EX** Exposure, **CM**
Concomitant Medications, **MH** Medical History.

**Controlled Terminology** is maintained with NCI's Enterprise Vocabulary
Services (NCI-EVS) and **updated quarterly**; do not invent codelist values —
cite the codelist and tell the user to pull the current quarterly release.

Versions are real but move — the skill records the latest it verified
(**SDTM v2.1**, 2024-06-10; **SDTMIG v3.4**, 2021-11-29; **CDASHIG v2.3**,
2023-09-28, referencing CDASH Model v1.3). **Confirm the current version with the
user / cdisc.org before asserting one in a deliverable**, because these are
re-released. The mapping recipe, the CDASH↔SDTM traceability idea, and the
worked AE/VS examples are in
**[references/cdisc_mapping.md](references/cdisc_mapping.md)**.

---

## Workflow

1. **Capture requirements.** Study design (cross-sectional / longitudinal /
   arms), the variables, value sets, PII fields, and whether it is a survey.
   If the *measurement properties* of the questions matter, hand the
   questionnaire design to `alterlab-survey-design` first.
2. **Draft the data dictionary.** Build the 18-column CSV: machine names, field
   types, choices, validation, `Identifier?` for every PII field, branching
   logic, and (longitudinal) the event/arm plan separately.
3. **Lint.** Run `scripts/lint_data_dictionary.py`; fix every error before the
   user imports.
4. **(If submission/standards needed) Map to CDISC.** Produce the variable →
   CDASH → SDTM table, flag value sets needing Controlled Terminology, and name
   the codelists — never fabricate codelist members.
5. **Report honestly.** State which choices are conventions vs. instance config,
   that the lint is structural (a test import is still required), and that CDISC
   versions must be confirmed against the current release.

---

## Self-Check Before Reporting

- Does the dictionary have exactly the **18 columns** in order, and is every
  field type one of the legal values?
- Is **every PII field** marked `Identifier? = y`?
- Do all **branching-logic** and **calc** expressions reference variables that
  actually exist in the dictionary?
- Did the **linter** run and pass — and did you tell the user a clean lint still
  needs a real test import?
- For CDISC: did you **name codelists/versions** rather than invent codelist
  values, and flag that versions must be confirmed against the current release?
- Did you route psychometrics to `alterlab-survey-design` and ELN bridging to
  `alterlab-labarchive` instead of doing them here?

---

## References

- [references/redcap_design.md](references/redcap_design.md) — full 18-column
  field reference, choice-string grammar, branching-logic operators, validation
  types, longitudinal/repeating-instrument design, and a worked dictionary.
- [references/cdisc_mapping.md](references/cdisc_mapping.md) — CDASH→SDTM→CT
  pipeline, SDTM observation classes and domains, controlled-terminology
  sourcing, and worked AE/VS/DM mappings, with verified versions and sources.

Part of the AlterLab Academic Skills suite.

More from AlterLab-IEU/AlterLab-Academic-Skills

SkillDescription
alterlab-abm-mesaBuilds agent-based models of social systems with Mesa 3 — the current AgentSet API (model.agents.shuffle_do('step'), auto-assigned unique_id, mandatory super().__init__(seed=...)), cell spaces (mesa.discrete_space OrthogonalMooreGrid / classic mesa.space grids), the DataCollector, batch_run parameter sweeps, and SolaraViz — for emergence, segregation, diffusion, opinion dynamics, and cooperation models. It uses the Mesa 3.x API (the old mesa.time schedulers like RandomActivation are removed) and treats the model as a generative theory to be validated, not just run. Use when the request mentions an agent-based model, Mesa, simulating interacting agents, or emergent macro behavior from micro rules. For discrete-event (queueing/process) simulation prefer alterlab-simpy; for reinforcement learning prefer alterlab-stable-baselines3. Part of the AlterLab Academic Skills suite.
alterlab-academic-careerPrepares academic career documents and professional-development materials for faculty and researchers. Use when drafting academic CVs, research statements, teaching philosophies, diversity statements, faculty-position cover letters, tenure dossiers, promotion narratives, academic portfolios, or mentorship statements, and when planning conference-networking strategy, building academic web presence, setting up ORCID profiles, or understanding impact metrics. Part of the AlterLab Academic Skills suite.
alterlab-accreditation-aolScaffolds program-level Assurance-of-Learning (AoL) documentation for AACSB (2020 Standard 5) and ABET (Criterion 3 Student Outcomes, Criterion 4 Continuous Improvement) accreditation — program learning outcomes / competency goals, curriculum-to-outcome mapping matrices, direct- and indirect-assessment plans, rubric design, and closing-the-loop continuous-improvement narratives — and validates the structure of an outcome-mapping matrix with scripts/aol_matrix.py. Use when the user needs AACSB or ABET assurance-of-learning material, a program-learning-outcomes set, a curriculum/outcome map or coverage matrix, a direct/indirect assessment plan, a closing-the-loop report, or accreditation self-study text. For single-course design or course rubrics prefer alterlab-teaching-design; for post-award grant reports prefer alterlab-grant-reporting. Part of the AlterLab Academic Skills suite.
alterlab-adaptyvSubmits and tracks protein-testing experiments on the Adaptyv Bio Foundry cloud lab (wet-lab validation), and optimizes protein sequences before submission with computational tools (NetSolP, SoluProt, SolubleMPNN, ESM). Use when designing proteins that need wet-lab validation - binding/affinity screening, expression testing, thermostability, or fluorescence assays - or when submitting experiments to the Foundry API, browsing the target catalog, tracking experiment status, retrieving results, or pre-screening sequences for solubility/expression. Triggers on "Adaptyv", "Foundry API", "cloud lab", "biolayer interferometry / BLI", "wet-lab validation". Part of the AlterLab Academic Skills suite.
alterlab-aeonRuns time series machine learning with the aeon library — classification, regression, clustering, forecasting, anomaly detection, segmentation, and similarity search via scikit-learn compatible APIs. Use when working with temporal data, sequential patterns, or time-indexed observations (univariate or multivariate) that need specialized algorithms beyond standard ML approaches. Part of the AlterLab Academic Skills suite.
alterlab-akademik-tesvikComputes the annual Turkish academic-incentive (akademik teşvik) score for Devlet (state) university öğretim elemanı (academic staff) from a classified activity list, applying the verified Akademik Teşvik Ödeneği Yönetmeliği (2018/11834) Faaliyet Hesaplama Tablosu headline puanları (Proje 20, Araştırma 15, Yayın 30, Patent 30, Atıf 30, Tebliğ 20, Ödül 20) with the k (author-count), p (Q1 1/Q2 0.8/Q3 0.5/Q4 0.25), and r (project-role) coefficients via türü puanı = Σ(faaliyet oranları) × headline (MADDE 8/2), then enforcing the per-type headline ceilings, the 100 cap (MADDE 8/3), and the net-30 payment gate (MADDE 10/3) in a deterministic scripts/tesvik_score.py. Use when the user wants to calculate akademik teşvik puanı, check the en az 30 (net-30) threshold, apply TABLO 4 ceilings, or estimate teşvik eligibility; keeps its coefficients separate from doçentlik scoring. For doçentlik point eligibility prefer alterlab-docentlik-eligibility. Part of the AlterLab Academic Skills suite.
alterlab-alpha-vantageAccesses real-time and historical stock market data, forex rates, cryptocurrency prices, commodities, economic indicators, and 50+ technical indicators via the Alpha Vantage API (requires a free API key from alphavantage.co). Use when fetching stock prices (OHLCV), company fundamentals (income statement, balance sheet, cash flow), earnings, options data, market news/sentiment, insider transactions, GDP, CPI, treasury yields, gold/silver/oil prices, Bitcoin/crypto prices, forex exchange rates, or calculating technical indicators (SMA, EMA, MACD, RSI, Bollinger Bands). Part of the AlterLab Academic Skills suite.
alterlab-alphafoldPredict protein 3D structures with AlphaFold2 via ColabFold — MMseqs2-accelerated MSAs, monomer and AlphaFold2-Multimer complex folding, and confidence-based validation (pLDDT, pTM/ipTM, PAE). Use when folding a protein sequence or complex from FASTA, generating a predicted structure with confidence metrics, ranking models, or checking self-consistency of a design. For co-folding a protein WITH a small-molecule ligand or predicting binding affinity prefer alterlab-boltz; for antibody–antigen or one-FASTA multi-entity complexes prefer alterlab-chai; to LOOK UP an already-computed structure prefer alterlab-alphafold-db; for ESM embeddings or inverse folding prefer alterlab-esm. Part of the AlterLab Academic Skills suite.
alterlab-alphafold-dbAccess the AlphaFold DB of 200M+ AI-PREDICTED protein structures — retrieve models by UniProt accession, download PDB/mmCIF files, and analyze prediction confidence metrics (pLDDT, PAE). Use when a UniProt ID needs a computationally predicted 3D structure or when no experimental structure exists, for homology modeling, protein engineering, or structure-based drug discovery; for EXPERIMENTALLY determined structures (X-ray, cryo-EM, NMR) prefer alterlab-pdb, and for protein sequences, annotations, or accession ID mapping prefer alterlab-uniprot instead. Part of the AlterLab Academic Skills suite.
alterlab-anndataBuild, slice, concatenate, read, and write AnnData annotated data matrices (obs, var, X, layers, obsm, uns) — the scverse data STRUCTURE, not an analysis pipeline. Use when creating or wrangling .h5ad/zarr files, managing cell and gene annotations, concatenating batches, or handling layers/obsm/backed-mode; for the QC, normalization, clustering, UMAP, and differential-expression analysis pipeline prefer alterlab-scanpy instead, and for RNA velocity from spliced/unspliced layers prefer alterlab-scvelo instead. Part of the AlterLab Academic Skills suite.