linkml-redcap 0.1.0__py3-none-any.whl

linkml_redcap/__init__.py

@@ -0,0 +1,22 @@
+"""linkml-redcap: LinkML schemas for REDCap structures.
+
+Two submodules are available:
+
+* :mod:`linkml_redcap.data_dictionary` — the meta-schema describing a valid
+  REDCap *data dictionary* (the 18-column CSV).
+* :mod:`linkml_redcap.record` — the reusable envelope for REDCap *record data*,
+  in both its flat-export and structured/nested shapes, plus structural
+  grouping helpers for flat ⇄ structured conversion.
+"""
+
+from linkml_redcap import data_dictionary, record
+from linkml_redcap._version import __version__
+from linkml_redcap.data_dictionary import schema_path, schema_view
+
+__all__ = [
+    "data_dictionary",
+    "record",
+    "schema_path",
+    "schema_view",
+    "__version__",
+]

linkml_redcap/_resources.py

@@ -0,0 +1,29 @@
+"""Resolve bundled schema files to stable filesystem paths.
+
+``importlib.resources.as_file`` only guarantees a real path *within* its context
+manager: for a zip-imported package it extracts the resource to a temporary file
+that is removed as soon as the context exits. Returning such a path from a public
+``schema_path()`` would hand callers (and ``SchemaView``) a path that may already
+be gone.
+
+We therefore enter the ``as_file`` context under a single process-lifetime
+``ExitStack`` that is closed at interpreter shutdown, so the path stays valid for
+the whole session. For a normally installed (unzipped) wheel this is a no-op that
+simply returns the real file on disk.
+"""
+
+from __future__ import annotations
+
+import atexit
+from contextlib import ExitStack
+from importlib.resources import as_file, files
+from pathlib import Path
+
+_file_manager = ExitStack()
+atexit.register(_file_manager.close)
+
+
+def resolve_schema(package: str, filename: str) -> Path:
+    """Return a stable filesystem path to ``<package>/schema/<filename>``."""
+    resource = files(package).joinpath("schema").joinpath(filename)
+    return Path(_file_manager.enter_context(as_file(resource)))

linkml_redcap/_version.py

@@ -0,0 +1,8 @@
+"""Resolved package version (falls back when running from a source tree)."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("linkml-redcap")
+except PackageNotFoundError:  # not installed (e.g. running from a checkout)
+    __version__ = "0.1.0"

linkml_redcap/data_dictionary/__init__.py

@@ -0,0 +1,25 @@
+"""LinkML meta-schema for REDCap data dictionaries."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from linkml_redcap._resources import resolve_schema
+
+if TYPE_CHECKING:
+    from linkml_runtime.utils.schemaview import SchemaView
+
+SCHEMA_FILENAME = "redcap_data_dictionary.yaml"
+
+
+def schema_path() -> Path:
+    """Return the filesystem path to the bundled meta-schema YAML."""
+    return resolve_schema(__name__, SCHEMA_FILENAME)
+
+
+def schema_view() -> SchemaView:
+    """Return a SchemaView instance ready for introspection."""
+    from linkml_runtime.utils.schemaview import SchemaView
+
+    return SchemaView(str(schema_path()))

linkml_redcap/data_dictionary/schema/README.md

@@ -0,0 +1,3 @@
+# Schema Directory
+
+This folder contains the LinkML schema yaml files.

linkml_redcap/data_dictionary/schema/redcap_data_dictionary.yaml

@@ -0,0 +1,421 @@
+---
+id: https://w3id.org/linkml/redcap-data-dictionary
+name: redcap_data_dictionary
+title: REDCap Data Dictionary LinkML Schema
+description: >-
+  A LinkML meta-schema that formally models the structure of REDCap data
+  dictionaries (CSV format). This schema defines the rules, constraints, and
+  relationships of all 18 REDCap data dictionary columns, enabling
+  programmatic validation, generation, and transformation of REDCap instruments.
+  It is a vendor-neutral model of REDCap itself; RareLink-style ontology
+  conventions (variable-name prefixes, coded choices, structured field
+  annotations, BioPortal/ontology curation) are layered on top in the rarelink
+  repository, not defined here.
+
+license: MIT
+version: 0.1.0
+
+see_also:
+  - https://github.com/linkml/linkml-redcap
+  - https://w3id.org/linkml/redcap-record   # sibling schema: REDCap *record* data
+  - https://github.com/BIH-CEI/rarelink
+  - https://rarelink.readthedocs.io
+  - https://projectredcap.org
+
+prefixes:
+  linkml: https://w3id.org/linkml/
+  redcap_dd: https://w3id.org/linkml/redcap-data-dictionary/
+  schema: http://schema.org/
+
+default_prefix: redcap_dd
+default_range: string
+
+imports:
+  - linkml:types
+
+
+# =============================================================================
+# CLASSES
+# =============================================================================
+classes:
+
+  # ---------------------------------------------------------------------------
+  # Top-Level Container
+  # ---------------------------------------------------------------------------
+  DataDictionary:
+    description: >-
+      A complete REDCap data dictionary representing one or more instruments
+      (forms). This is the top-level container that corresponds to the CSV file
+      uploaded to REDCap. Fields must be grouped contiguously by form_name.
+    tree_root: true
+    comments:
+      - >-
+        The first field in the data dictionary must be the record identifier
+        (typically record_id) and must be of field_type 'text'.
+      - >-
+        All fields belonging to the same form_name must be in contiguous rows;
+        no interleaving of forms is permitted.
+    attributes:
+      fields:
+        description: >-
+          Ordered list of all fields (variables) in the data dictionary.
+          Fields within the same form must be in contiguous rows.
+        range: Field
+        multivalued: true
+        inlined_as_list: true
+        required: true
+
+  # ---------------------------------------------------------------------------
+  # Core REDCap Field (mirrors one row of the CSV)
+  # ---------------------------------------------------------------------------
+  Field:
+    description: >-
+      A single variable (field) in a REDCap data dictionary. This class maps
+      directly to one row of the REDCap data dictionary CSV, with each
+      attribute corresponding to one of the 18 standard columns.
+    attributes:
+
+      variable_field_name:
+        description: >-
+          The unique variable name for this field. Must contain only lowercase
+          letters, numbers, and underscores. Cannot start with a number.
+          Must be unique across the entire project.
+        range: string
+        required: true
+        identifier: true
+        pattern: "^[a-z][a-z0-9_]*$"
+
+      form_name:
+        description: >-
+          The instrument (form) this field belongs to. Must be lowercase
+          with underscores only. All fields for a form must be contiguous.
+        range: string
+        required: true
+        pattern: "^[a-z][a-z0-9_]*$"
+
+      section_header:
+        description: >-
+          Optional section header text displayed above this field to visually
+          group fields within a form. Supports HTML/rich text.
+        range: string
+        required: false
+
+      field_type:
+        description: >-
+          The type of input field. Determines how the field is rendered
+          in the data entry form and what data it can accept.
+        range: FieldType
+        required: true
+
+      field_label:
+        description: >-
+          The display label shown to users during data entry. Supports
+          HTML/rich text formatting. For ontology-based models, this
+          typically includes a section number and human-readable name
+          (e.g., '2.1 Date of birth').
+        range: string
+        required: true
+
+      choices_calculations_slider_labels:
+        description: >-
+          For dropdown, radio, and checkbox fields: pipe-delimited list of
+          'raw_value, label' pairs (e.g., '1, Yes | 2, No | 3, Unknown').
+          For calc fields: the calculation expression.
+          For slider fields: 'left | center | right' anchor labels.
+          For text fields with BioPortal ontology autocomplete:
+          'BIOPORTAL:ONTOLOGY_NAME' (e.g., 'BIOPORTAL:HP').
+        range: string
+        required: false
+
+      field_note:
+        description: >-
+          Supplementary text displayed below the field during data entry.
+          Typically provides instructions, expected formats, or context.
+        range: string
+        required: false
+
+      text_validation_type_or_show_slider_number:
+        description: >-
+          For text fields: the validation type constraining input format.
+          For slider fields: whether to show the numeric value ('number').
+        range: TextValidationType
+        required: false
+
+      text_validation_min:
+        description: >-
+          Minimum allowed value for validated text fields (dates, numbers).
+        range: string
+        required: false
+
+      text_validation_max:
+        description: >-
+          Maximum allowed value for validated text fields (dates, numbers).
+        range: string
+        required: false
+
+      identifier:
+        description: >-
+          Whether this field contains identifying information (PHI).
+          Set to 'y' for identifier fields. Affects data export behaviour.
+        range: IdentifierStatus
+        required: false
+
+      branching_logic:
+        description: >-
+          Conditional display logic. Uses REDCap's branching syntax
+          (e.g., '[field_name] = ''value'''). When specified, the field
+          is only shown if the condition evaluates to true.
+        range: string
+        required: false
+
+      required_field:
+        description: >-
+          Whether the field is required for form completion. Set to 'y'
+          for required fields. Can also contain conditional expressions
+          for conditionally required fields.
+        range: string
+        required: false
+
+      custom_alignment:
+        description: >-
+          Controls the alignment of the field on the form.
+          LV = Left Vertical, LH = Left Horizontal,
+          RV = Right Vertical (default), RH = Right Horizontal.
+        range: CustomAlignment
+        required: false
+
+      question_number:
+        description: >-
+          Custom question number for surveys. Overrides auto-numbering.
+          Any text entered here is displayed as the question number.
+        range: string
+        required: false
+
+      matrix_group_name:
+        description: >-
+          Groups multiple radio/checkbox fields into a matrix display.
+          All fields with the same matrix_group_name must be contiguous
+          and use the same field_type and choices.
+        range: string
+        required: false
+        pattern: "^[a-z0-9_]*$"
+
+      matrix_ranking:
+        description: >-
+          Whether ranking is enabled for this matrix group. When enabled,
+          no two fields in the matrix can have the same selected value.
+        range: MatrixRanking
+        required: false
+
+      field_annotation:
+        description: >-
+          REDCap's field annotation column — free text plus action tags
+          (e.g. @HIDDEN, @READONLY, @CALCTEXT). Any structured convention layered
+          inside it (semantic variable codes, ontology-coded choices, ontology
+          versions, interoperability mappings) is defined downstream by rarelink,
+          not by this base schema.
+        range: string
+        required: false
+
+  # ---------------------------------------------------------------------------
+  # Structured Choice (for programmatic use beyond flat CSV)
+  # ---------------------------------------------------------------------------
+  Choice:
+    description: >-
+      A single permissible value for a dropdown, radio, or checkbox field.
+      In REDCap CSV format, choices are encoded as a pipe-delimited string,
+      but this class provides a structured representation for programmatic
+      generation and validation.
+    attributes:
+      raw_value:
+        description: >-
+          The stored value (code) for this choice. In ontology-based models,
+          this typically encodes the ontology prefix and concept ID
+          (e.g., 'snomedct_248152002'). Must contain only lowercase letters,
+          numbers, and underscores to comply with REDCap naming rules.
+        range: string
+        required: true
+        pattern: "^[a-z0-9_]*$"
+      label:
+        description: >-
+          The human-readable display label for this choice
+          (e.g., 'Female', 'Male', 'Unknown').
+        range: string
+        required: true
+
+  # ---------------------------------------------------------------------------
+  # Instrument (logical grouping derived from form_name)
+  # ---------------------------------------------------------------------------
+  Instrument:
+    description: >-
+      A logical REDCap instrument (form) grouping related fields.
+      This class is not directly represented in the CSV but is derived
+      from the contiguous grouping of fields sharing the same form_name.
+      In RareLink, instruments follow the naming convention
+      'rarelink_N_section_name' and each has a completion status field.
+    attributes:
+      instrument_name:
+        description: >-
+          The form_name shared by all fields in this instrument.
+        range: string
+        required: true
+        identifier: true
+        pattern: "^[a-z][a-z0-9_]*$"
+      instrument_label:
+        description: >-
+          Human-readable label for the instrument. REDCap derives this
+          by capitalising and replacing underscores with spaces.
+        range: string
+        required: false
+      is_repeating:
+        description: >-
+          Whether this instrument supports repeating instances.
+          In RareLink, sections 4-8 (care pathway, disease, genetic
+          findings, phenotypic features, measurements, family history)
+          are repeating instruments.
+        range: boolean
+        required: false
+      fields:
+        description: All fields belonging to this instrument.
+        range: Field
+        multivalued: true
+        inlined_as_list: true
+        required: true
+
+
+# =============================================================================
+# ENUMS
+# =============================================================================
+enums:
+
+  FieldType:
+    description: >-
+      The complete set of REDCap field types that determine how a
+      variable is rendered and what data it accepts.
+    permissible_values:
+      text:
+        description: >-
+          Single-line text input. Can be combined with validation types
+          (date_ymd, integer, number, email, etc.) and BioPortal
+          ontology autocomplete.
+      notes:
+        description: Large multi-line text area for free-text entry.
+      dropdown:
+        description: >-
+          Single-select dropdown menu. Requires choices to be specified
+          in the choices column.
+      radio:
+        description: >-
+          Single-select radio button group. Requires choices to be
+          specified in the choices column.
+      checkbox:
+        description: >-
+          Multi-select checkboxes. Requires choices. Each checkbox
+          creates a separate binary variable in the export.
+      yesno:
+        description: >-
+          Built-in Yes/No radio buttons (stored as 1/0).
+      truefalse:
+        description: >-
+          Built-in True/False radio buttons (stored as 1/0).
+      calc:
+        description: >-
+          Calculated field. The calculation expression is specified
+          in the choices column.
+      file:
+        description: File upload field for attaching documents or images.
+      slider:
+        description: >-
+          Visual analogue scale (0-100). Anchor labels are specified
+          in the choices column as 'left | center | right'.
+      descriptive:
+        description: >-
+          Display-only field for instructional text, images, or HTML
+          content. Does not collect data.
+      sql:
+        description: >-
+          Dynamic dropdown populated by a SQL query against the
+          REDCap database.
+
+  TextValidationType:
+    description: >-
+      Validation rules for text fields constraining the input format.
+    permissible_values:
+      date_ymd:
+        description: Date in YYYY-MM-DD format.
+      date_mdy:
+        description: Date in MM-DD-YYYY format.
+      date_dmy:
+        description: Date in DD-MM-YYYY format.
+      datetime_ymd:
+        description: Datetime in YYYY-MM-DD HH:MM format.
+      datetime_mdy:
+        description: Datetime in MM-DD-YYYY HH:MM format.
+      datetime_dmy:
+        description: Datetime in DD-MM-YYYY HH:MM format.
+      datetime_seconds_ymd:
+        description: Datetime with seconds in YYYY-MM-DD HH:MM:SS format.
+      datetime_seconds_mdy:
+        description: Datetime with seconds in MM-DD-YYYY HH:MM:SS format.
+      datetime_seconds_dmy:
+        description: Datetime with seconds in DD-MM-YYYY HH:MM:SS format.
+      time:
+        description: Time in HH:MM format.
+      time_mm_ss:
+        description: Time in MM:SS format.
+      integer:
+        description: Whole number (no decimals).
+      number:
+        description: Decimal number.
+      number_1dp:
+        description: Number with 1 decimal place.
+      number_2dp:
+        description: Number with 2 decimal places.
+      number_3dp:
+        description: Number with 3 decimal places.
+      number_4dp:
+        description: Number with 4 decimal places.
+      number_comma_decimal:
+        description: Decimal number using a comma as the decimal separator (e.g. de_DE).
+      number_1dp_comma_decimal:
+        description: Number with 1 decimal place, comma decimal separator.
+      number_2dp_comma_decimal:
+        description: Number with 2 decimal places, comma decimal separator.
+      phone:
+        description: Phone number format.
+      email:
+        description: Email address format.
+      zipcode:
+        description: US ZIP code format.
+      alpha_only:
+        description: Letters only (no numbers or special characters).
+
+  CustomAlignment:
+    description: Field alignment options for the data entry form.
+    permissible_values:
+      LV:
+        description: Left Vertical
+      LH:
+        description: Left Horizontal
+      RV:
+        description: Right Vertical (default)
+      RH:
+        description: Right Horizontal
+
+  IdentifierStatus:
+    description: >-
+      Whether a field contains Protected Health Information. The REDCap column is
+      'y' for identifiers and blank otherwise; a blank cell is represented as an
+      absent value (the slot is optional), not as a permissible value.
+    permissible_values:
+      y:
+        description: Field contains identifying information (PHI).
+
+  MatrixRanking:
+    description: >-
+      Whether matrix ranking is enabled. 'y' when enabled and blank otherwise;
+      a blank cell is represented as an absent value (the slot is optional), not
+      as a permissible value.
+    permissible_values:
+      y:
+        description: Ranking is enabled for this matrix group.

linkml_redcap/record/__init__.py

@@ -0,0 +1,39 @@
+"""Reusable LinkML envelope for REDCap record data (flat and structured)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from linkml_redcap._resources import resolve_schema
+from linkml_redcap.record.grouping import (
+    STRUCTURAL_KEYS,
+    group_flat_records,
+    ungroup_records,
+)
+
+if TYPE_CHECKING:
+    from linkml_runtime.utils.schemaview import SchemaView
+
+SCHEMA_FILENAME = "redcap_record.yaml"
+
+__all__ = [
+    "SCHEMA_FILENAME",
+    "STRUCTURAL_KEYS",
+    "schema_path",
+    "schema_view",
+    "group_flat_records",
+    "ungroup_records",
+]
+
+
+def schema_path() -> Path:
+    """Return the filesystem path to the bundled record-envelope schema YAML."""
+    return resolve_schema(__name__, SCHEMA_FILENAME)
+
+
+def schema_view() -> SchemaView:
+    """Return a SchemaView over the record-envelope schema, ready for introspection."""
+    from linkml_runtime.utils.schemaview import SchemaView
+
+    return SchemaView(str(schema_path()))