redcap-longitudinal-structure

name

redcap-longitudinal-structure

description

Parse and interpret REDCap longitudinal project structure from the three exported CSVs: Arms, Events, and Event-Instrument Mapping (Instrument Designations). Use this skill whenever a user provides any of these files, asks about a project's longitudinal design, wants to know which forms are collected at which events or timepoints, needs to map out arm/event/form relationships, or is troubleshooting branching logic that references events. Trigger on: "longitudinal", "arms", "events CSV", "event mapping", "define my events", "instrument designations", "which forms are at which events", "event-instrument mapping", "unique event name", or when any uploaded CSV has "Arms", "Events", or "Designat" in the filename. Also trigger when the user asks "what events does this project have?" or "which forms are assigned to which events?" even without uploading a file — the answer will require these CSVs and you should ask for them.

REDCap Longitudinal Structure Skill

This skill teaches you how to parse and interpret the three CSVs that define a REDCap longitudinal project's structure. Use it whenever any of these files are in play.

---

What These Files Are

REDCap longitudinal projects organize data collection across arms and events. Three separate CSVs define this structure:

File	What it defines	Typical filename pattern
Arms	Study arms (groups of events, e.g. treatment vs control)	*_Arms_*.csv, Arms.csv
Events	Timepoints within each arm (e.g. Baseline, Month 3)	*_Events_*.csv, Events.csv
Instrument Designations	Which forms are assigned to which events	*InstrumentDesignations*.csv, *formEventMapping*.csv

These files can be exported from:

• REDCap UI: Project Setup → Define My Events / Designate Instruments for My Events
• REDCap API: ?content=arm, ?content=event, ?content=formEventMapping

A project may have just one arm (still longitudinal if it has multiple events), or many arms.

---

Step 1: Find the Files

Uploaded files land at /sessions/.../mnt/uploads/<filename>. Also check any mounted workspace folder. The user may supply one, two, or all three CSVs — work with whatever is available and note what's missing.

---

Step 2: Run the Parser

Always use the bundled parser rather than reading the CSVs by hand:

python <skill_path>/scripts/parse_longitudinal.py \
  --arms <path_to_arms.csv> \
  --events <path_to_events.csv> \
  --mapping <path_to_designations.csv>

Any of the three flags can be omitted if that file wasn't provided. The script auto-detects column names and handles encoding variations (BOM, UTF-8, latin-1).

For machine-readable output (useful if you need to do further analysis):

python <skill_path>/scripts/parse_longitudinal.py \
  --arms <path> --events <path> --mapping <path> --json

Run the parser and read its full output before responding to the user.

---

Step 3: Understand the Column Schemas

Arms CSV

Column	Notes
arm_num	Integer. The arm number REDCap uses internally.
arm_name / name	Display label for the arm.

A single-arm project may still export an Arms file with one row.

Events CSV

Column	Notes
event_name	Display label (e.g. "Baseline", "Month 3").
arm_num	Which arm this event belongs to.
day_offset	Scheduled day from arm start (0 = first event).
offset_min	Earliest acceptable day (visit window lower bound).
offset_max	Latest acceptable day (visit window upper bound).
unique_event_name	System identifier used in branching logic, e.g. baseline_arm_1.

unique_event_name is what appears in branching logic as [baseline_arm_1][fieldname]. It is auto-generated by REDCap: <slugified_event_name>_arm_<arm_num>.

Instrument Designations CSV

Column	Notes
arm_num	The arm number.
unique_event_name	The event system name.
form	The instrument (form) variable name as it appears in the data dictionary.

One row per form-event assignment. If a form appears at 5 events, there are 5 rows.

---

Step 4: Interpret the Structure

After parsing, build a mental model of the project:

Arms: How many? Are they parallel treatment groups, or sequential phases? Single-arm longitudinal projects are common and still use events to separate timepoints.

Events per arm: List them in day_offset order. Note visit windows if present (when offset_min ≠ 0 or offset_max ≠ day_offset). Events with identical names across arms (e.g. "Baseline" in Arm 1 and Arm 2) are separate events with different unique_event_name values.

Form-event matrix: Which forms appear at which events? Patterns to watch for:

• Forms at every event → universal/repeated collection (e.g. vitals, adverse events)
• Forms only at first event → baseline-only (e.g. demographics, eligibility)
• Forms only at last event → endpoint/closeout
• Forms at select events → scheduled assessments (e.g. labs at months 3 and 6 only)

Branching logic implications: Any branching logic that references data from a different event uses the syntax [unique_event_name][field_name]. This only works if the form containing the target field is actually designated to that event.

---

Step 5: Present the Summary

Structure your response as follows:

1. Project overview — arm count, total event count, total form-event assignments
2. Arms — list each arm with its name and event count
3. Events per arm — ordered by day_offset; include the unique_event_name since users often need it for branching logic; include visit window if non-trivial
4. Form-event matrix — a table showing which forms are at which events (rows = forms, columns = events). Use ✓ for assigned, blank for not assigned. If there are many events, abbreviate column headers.
5. Notable patterns — call out anything that looks unusual or worth flagging:
   • A form assigned to every event (typically expected — just confirm)
   • A form assigned to no events (likely an oversight)
   • Very large visit windows that overlap with adjacent events
   • Events with no forms assigned

Keep it readable. If the project is simple (1 arm, 3–4 events), a brief table is enough. If it's complex (multiple arms, many events, many forms), a fuller narrative helps.

---

What These Files Do NOT Tell You

• Field-level data (that's in the Data Dictionary)
• Survey settings or repeating instrument configuration
• Actual collected data
• User rights or Data Access Groups

If the user asks about field definitions within events, also load the Data Dictionary and use the redcap-data-dictionary skill in conjunction with this one.

---

Common Scenarios

"Which events does this project have?"

Parse the Events CSV. List events in day_offset order per arm with their unique names.

"Which forms are collected at baseline?"

Parse the mapping CSV. Filter rows where unique_event_name contains "baseline". List the form values.

"Is [form_name] assigned to [event_name]?"

Parse the mapping CSV. Look for a row matching both. Answer yes/no and note which arm(s) the assignment applies to.

"I need to write branching logic that references the baseline visit"

Parse the events CSV to find the correct unique_event_name for the baseline event in the relevant arm. The syntax will be [<unique_event_name>][<field_name>].

"Why is my cross-event branching logic not working?"

Check: (1) Is the target form actually designated to the referenced event? (2) Is the unique_event_name in the logic spelled correctly? Use the parser output to verify.