HEARTLAND/ redcap

v1.0.0 · Open source · MIT

A REDCap instrument ready to import.

Pre-built data dictionary and XML instrument for the peer-reviewed HEARTLAND Protocol. Five forms, 75 variables, a weighted 0-18 risk score, and 12 monthly follow-ups — so any rural hospital or research institution can start collecting structured heart failure data on day one.

View on GitHub→Read the Protocol→

For clinicians and researchers with institutional REDCap access. All sample data is synthetic — no PHI is ever transmitted or collected by this template.

heartland_data_dictionary.csvready
  • 01enrollment13 fields
  • 02baseline15 fields · risk score
  • 03gdmt_status19 fields
  • 04monthly_followup20 fields · repeating
  • 05outcomes_12mo8 fields
75 fields totalMIT · v1.0.0
75
fields
5
REDCap forms
0–18
weighted risk score
3
risk tiers
12×
monthly follow-ups

What's inside

Five forms, one shared workflow.

Clinical definitions match the published Protocol v3.3 exactly. Calculated fields, branching logic, and a 20-row synthetic sample dataset are all included so your first import validates cleanly.

  • 01

    Enrollment

    Facility information, consent, demographics, geographic context (state, county FIPS, USDA RUCA rurality).

  • 02

    Baseline

    The ten HEARTLAND risk variables and a weighted 0-18 score with automatic tier assignment (low / moderate / high).

  • 03

    GDMT Status

    RAS inhibitor, beta-blocker, MRA, and SGLT2i tracked with target doses, start dates, and the generic $4 bridge option.

  • 04

    Monthly follow-up

    Repeating instrument, months 1-12. Vitals, optional labs, GDMT titrations, red flags, hospitalizations, KCCQ-12.

  • 05

    12-month outcomes

    Mortality, HF hospitalizations, HF ED visits, days alive and out of hospital, and GDMT optimization rate.

Quickstart

Three steps, fifteen minutes.

REDCap 14.x or newer is recommended. A 13.x instance works with minor caveats documented in the import guide.

Full import guideLatest release
  1. 01

    Create an empty REDCap project

    In your institutional REDCap, pick New Project → Research → name it (e.g. “HEARTLAND Validation — Site X”).

  2. 02

    Upload the data dictionary

    Project Setup → Data Dictionary → Upload. Select heartland_data_dictionary.csv from the GitHub release.

  3. 03

    Enable the repeating instrument

    Project Setup → Enable optional modules → Repeatable instruments and events. Mark monthly_followup as repeating.

Regenerate artifacts locallybash
# In the repo root
python3 scripts/csv_to_xml.py \
  --input instruments/heartland_data_dictionary.csv \
  --output instruments/heartland_instrument.xml

python3 scripts/generate_sample_data.py \
  --output examples/sample_data.csv

Clinical foundation

Every field traces back to the peer-reviewed protocol.

The data dictionary mirrors HEARTLAND Protocol v3.3 exactly. The codebook PDF cites the specific module or table for every variable, so reviewers and adjudicators can verify clinical fidelity without leaving the repo.

Suggested validation study

A reference design you can hand to your IRB.

A pre-written, STROBE-aligned observational protocol ships alongside the instrument. Primary endpoint, statistical plan, and inclusion criteria are ready to adapt — no blank page to fight on a Sunday night.

Read the study protocol
150
participants (50 per tier)
12 mo
follow-up window
STROBE
reporting checklist
  • •Primary endpoint: all-cause mortality by HEARTLAND tier.
  • •Secondary: HF hospitalizations, days alive and out of hospital, GDMT optimization.
  • •Exploratory: discrimination vs MAGGIC / GWTG-HF; Track A vs Track B comparison.

If you use this

Please cite the template and the protocol.

Machine-readable citation is in CITATION.cff at the repo root. Zenodo DOI for this release will be wired in once the GitHub → Zenodo integration mints it.

bibtexCITATION.cff ↗
@misc{ferreira_heartland_redcap_2026,
  author       = {Ferreira, Vicky Muller},
  title        = {{HEARTLAND Protocol REDCap
                   Instrument Template, v1.0.0}},
  year         = {2026},
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.<pending>},
  url          = {https://redcap.heartlandprotocol.org}
}