HEAL Data Dictionary Preparation Guidance

Overview

Data Dictionary Preparation Focus Areas

Variable Clarity and Reusability

Each variable should be clearly defined, self-contained, and understandable without prior study knowledge. Well-documented variables improve interpretability, support reuse, and reduce ambiguity for both humans and machines.

Best Practices and Examples

• Each row represents exactly one variable.
• Variable names are meaningful and clear, not internal shorthand.
• Each variable is described, so someone unfamiliar with the study can understand what it represents.
• Permissible values are included for categorical variables when known.
• Variable units are included where applicable.
• Relevant contextual information, such as baseline versus longitudinal collection, is included when readily available.
• Each measure is represented once, without duplicate variables under different names.
• Information about each variable, including the variable title, variable name, and variable description, is fully documented within each row, without relying on implicit assumptions or information defined elsewhere.
  • Examples of variable information:
    • Variable title (human-readable): ‘Participant ID’
    • Variable name (machine-readable): ‘participant_id’
    • Variable description: ‘Unique identifier for participant'

Consistency Across Variables

Variables that represent similar concepts should follow consistent naming, structure, and encoding patterns. Consistency improves interpretability, supports cross-variable comparisons, and enables more efficient data harmonization across studies and instruments.

Best Practices and Examples

• Use consistent encoding patterns for similar variables within the same instrument or form, and clearly define how values are represented.
  • For example, ‘Yes/No’ vs ‘1/0’ vs ‘Y/N’
• Original encodings are preserved when similar outcomes are measured across instruments, and differences in permissible values are clearly documented.
  • When the same outcome is measured using different instruments, categorical encodings may differ (for example, one instrument may use ‘Y/N’ while another uses ‘1/0’). These differences are acceptable when clearly documented at the variable level.
• Naming conventions are consistent, and relationships between variables are clear, while allowing for differences across instruments, when appropriate.
  • Variable names for the same outcome may differ across instruments (for example, ‘SleepDuration’ vs ‘SleepTime’) and are acceptable when clearly documented.
• When multiple variables capture related concepts, use consistent naming patterns to make relationships clear, even across different forms.
  • For example, sleep-related variables might share a common prefix such as 'SleepDuration', ‘SleepLatency,’ and ‘SleepQuality,’ to indicate related aspects of the same concept.

Structure for Machine and AI Processing

Data dictionaries should be structured in a simple, consistent, and machine-readable format to support automated processing, validation, and reuse. Clean structure reduces parsing errors, enables tools (like the HEAL VLMD tool) to interpret data reliably, and ensures compatibility across systems and workflows.

Best Practices and Examples

• Use a simple, machine-readable tabular format (e.g., CSV, TSV, JSON, or REDCap export) with a single, clean header row. The VLMD tool only accepts these file types.
• Avoid structural and visual elements that interfere with parsing (e.g., merged cells, hidden columns, multiple header rows, color-coding, decorative fonts, emojis, or special characters). Use plain, unformatted tables and standard characters to support automated and AI-driven processing.
• Ensure required HEAL VLMD fields (e.g., name, description) are present and aligned with the expected schema.
  • Examples of valid and invalid VLMD are available for reference.
  • Because HEAL studies vary in design and data types, some VLMD schema fields may not map directly to every column. In these cases, align column headers and metadata as closely as possible with the expected schema to support automated processing.

Data Integrity and Source Fidelity

Data dictionaries should accurately reflect the original source data and preserve each variable’s full meaning. Maintaining source system fidelity reduces errors introduced through manual handling, ensures completeness, and supports reliable interpretation and reuse.

Best Practices and Examples

• Generate data dictionaries directly from the source system when possible (e.g., REDCap export), rather than manually recreating or editing.
• Ensure each variable row contains all information needed to interpret its encoding (e.g., meaning, permissible values, units) without requiring external references.
• Verify that variable descriptions are complete and not unintentionally truncated due to formatting, software limitations, or export issues.

Data Dictionary Sharing Readiness

A data dictionary that reflects the guidance outlined in this reference guide is generally ready for submission. Not all elements will apply to every study or data type.

Next steps:

• Submit VLMD as a data dictionary through the HEAL Platform's VLMD submission form or by emailing the HEAL Stewards at HEALStewards@renci.org.
• If you have questions, the HEAL Stewards can provide additional guidance.

Additional resources:

• VLMD Overview
• Examples of valid submissions
• Webinar on “Empowering Data Reuse: A Guide to Creating Data Dictionaries and Variable-Level Metadata (VLMD)”
• HEAL Data Packaging Guidance