diff --git a/.github/workflows/get_schema_on_tag.yml b/.github/workflows/get_schema_on_tag.yml index 76cce58..dee8535 100644 --- a/.github/workflows/get_schema_on_tag.yml +++ b/.github/workflows/get_schema_on_tag.yml @@ -18,7 +18,7 @@ jobs: - name: Set up Python uses: actions/setup-python@v6 with: - python-version: '3.12' + python-version: "3.12" - name: Install dependencies run: | diff --git a/.github/workflows/test-critical-high.yml b/.github/workflows/test-critical-high.yml index dbc3743..37a7b49 100644 --- a/.github/workflows/test-critical-high.yml +++ b/.github/workflows/test-critical-high.yml @@ -17,7 +17,7 @@ jobs: - name: Set up Python uses: actions/setup-python@v6 with: - python-version: "3.11" + python-version: "3.12" - name: install run: | diff --git a/.github/workflows/test-medium-low.yml b/.github/workflows/test-medium-low.yml index bc9f5c9..0b43f13 100644 --- a/.github/workflows/test-medium-low.yml +++ b/.github/workflows/test-medium-low.yml @@ -14,7 +14,7 @@ jobs: - name: Set up Python uses: actions/setup-python@v6 with: - python-version: "3.11" + python-version: "3.12" - name: install run: | diff --git a/.gitignore b/.gitignore index b128aba..3f0afbf 100644 --- a/.gitignore +++ b/.gitignore @@ -12,4 +12,7 @@ converage.xml .pytest_cache/ **/.DS_Store -*.egg-info/ \ No newline at end of file +*.egg-info/ + +# Sphinx stuff to ignore +_build/ diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..854f39a --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,44 @@ +# Read the Docs configuration file for Sphinx projects +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + + +# Set the OS, Python version and other tools you might need +build: + os: ubuntu-lts-latest + tools: + python: "3.12" + + # You can also specify other tool versions: + # nodejs: "20" + # rust: "1.70" + # golang: "1.20" + + +# Build documentation in the "docs/" directory with Sphinx +sphinx: + configuration: docs/conf.py + # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs + # builder: "dirhtml" + # Fail on all warnings to avoid broken references + # fail_on_warning: true + +# Optionally build your docs in additional formats such as PDF and ePub +# formats: +# - pdf +# - epub + + +# Optional but recommended, declare the Python requirements required +# to build your documentation + +# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html + +python: + install: + - method: pip + path: . + extra_requirements: + - docs diff --git a/CITATION.cff b/CITATION.cff index 1512687..a0ace03 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -112,5 +112,5 @@ keywords: - crf - data capture license: MIT -version: 1.3.0 -date-released: +version: 1.2.2 +date-released: April 2026 diff --git a/README.md b/README.md index 11ba9c3..b918827 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,7 @@ +[![CodeQL](https://github.com/ISARICResearch/ARC/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/ISARICResearch/ARC/actions/workflows/github-code-scanning/codeql) +[![Run tests marked as medium or low](https://github.com/ISARICResearch/ARC/actions/workflows/test-medium-low.yml/badge.svg)](https://github.com/ISARICResearch/ARC/actions/workflows/test-medium-low.yml) +[![Run tests marked as critical or high](https://github.com/ISARICResearch/ARC/actions/workflows/test-critical-high.yml/badge.svg)](https://github.com/ISARICResearch/ARC/actions/workflows/test-critical-high.yml) +[![Docs](https://app.readthedocs.org/projects/isaric-arc/badge/?version=latest)](https://app.readthedocs.org/projects/isaric-arc/builds/?version__slug=latest) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) # ARC - Analysis and Research Compendium diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css new file mode 100644 index 0000000..b6b14a8 --- /dev/null +++ b/docs/_static/css/custom.css @@ -0,0 +1,3 @@ +.theme-toggle-container { + display: none; +} diff --git a/docs/_static/isaric-logo.png b/docs/_static/isaric-logo.png new file mode 100644 index 0000000..c5e8373 Binary files /dev/null and b/docs/_static/isaric-logo.png differ diff --git a/docs/_static/osi-badge-light.svg b/docs/_static/osi-badge-light.svg new file mode 100644 index 0000000..06969ce --- /dev/null +++ b/docs/_static/osi-badge-light.svg @@ -0,0 +1,142 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..a73b91a --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,251 @@ +# -- IMPORTS -- + +# -- Standard libraries -- +import os +import sys + +sys.path.insert(0, os.path.abspath(".")) +sys.path.insert(0, os.path.dirname(os.path.abspath("."))) + +from datetime import datetime + +# -- 3rd party libraries -- +# -- Internal libraries -- + +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +author = "ISARIC" +copyright = f"ISARIC, {datetime.now().year}" +description = """ARC (Acute and Rapid onset disease Case report form) - standardised clinical data collection.""" +github_url = "https://github.com" +github_repo = f"{github_url}/ISARICResearch/ARC" +github_version = "main" +# pypi_project = '' +project = 'ARC' +release = "1.2.2" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +# Define master TOC +master_doc = "index" + +# Native docs language +language = "en" + +# Minimum required version of Sphinx - not required +# needs_sphinx >= '7.2.5' + +# Set primary domain to null +primary_domain = None + +# Global substitutions - not required for the moment +#rst_epilog = f""" +#.. |author| replace:: **{author}** +#.. |copyright| replace:: **{copyright}** +#.. |docs_url| replace:: '' +#.. |project| replace:: **{project}** +#.. |project_description| replace:: {description} +#.. |release| replace:: **{release}** +#.. |github_release_target| replace:: https://github.com/ISARICResearch/ISARICAnalytics/releases/tag/{release} +#""" + +# Publish author(s) +show_authors = True + +# Sphinx extensions: not all of these are used or required, but they are still +# listed here if requirements change. +extensions = [ + "jupyter_sphinx", + "matplotlib.sphinxext.plot_directive", + "myst_parser", + "nb2plots", + "numpydoc", + "sphinx.ext.autodoc", + #'sphinx.ext.autosectionlabel', + #'sphinx.ext.autosummary', + "sphinxcontrib.email", + "sphinx.ext.coverage", + "sphinx.ext.doctest", + "sphinx.ext.duration", + "sphinx.ext.extlinks", + "sphinx.ext.graphviz", + "sphinx.ext.inheritance_diagram", + "sphinx.ext.intersphinx", + #'sphinx.ext.linkcode', + "sphinx.ext.mathjax", + "sphinx.ext.napoleon", + "sphinx.ext.todo", + "sphinx.ext.viewcode", + "sphinx_copybutton", + "sphinx_design", +] + +# Obfuscate all mailto links in the docs sources, instead using the `email` +# role from `sphinxcontrib-email`. +email_automode = True + + +# Static template paths +templates_path = ["_templates"] + +# The suffix of source filenames. +source_suffix = ".rst" + +# The encoding of source files. +source_encoding = "utf-8" + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [ + "_build", + "Thumbs.db", + ".DS_Store", +] + +# The name of the Pygments (syntax highlighting) style to use. +# pygments_style = "sphinx" + +# A list of prefixes that are ignored when creating the module index. +# (new in Sphinx 0.6) +modindex_common_prefix = ["isaricanalytics."] + +# Not currently required but will be useful later once all public +# library docstrings are complete, with doctest examples +doctest_global_setup = "import isaricanalytics" + +# If this is True, the ``todo`` and ``todolist`` extension directives +# produce output, else they produce nothing. The default is ``False``. +todo_include_todos = True + +# -- Project file data variables --------------------------------------------- + +# HTML global context for templates +html_context = { + "authors": author, + "copyright": copyright, + "default_mode": "dark", + "display_github": True, + "github_url": "https://github.com", + "github_user": "ISARICResearch", + "github_repo": "ARC", + "github_version": "main", + "doc_path": "docs", + "conf_path": "docs/conf.py", + "project": project, + "project_description": description, + "release": release, + "release_target": f"https://github.com/ISARICResearch/ARC/releases/tag/{release}", +} + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +# General (non-theme) HTML output options +# Custom deployment domain required here +# html_baseurl = '' + +# HTML theme options +html_theme = "furo" +html_theme_options = { + # Logos + "light_logo": "isaric-logo.png", + # Customisation to make the site light-only (disable dark mode). + # + # See: https://github.com/pradyunsg/furo/issues/28 + "dark_css_variables": { + # Taken from: https://github.com/pradyunsg/furo/blob/c682d5d3502f3fa713c909eebbf9f3afa0f469d9/src/furo/assets/styles/variables/_colors.scss + "color-problematic": "#b30000", + # Base Colors + "color-foreground-primary": "black", # for main text and headings + "color-foreground-secondary": "#5a5c63", # for secondary text + "color-foreground-muted": "#646776", # for muted text + "color-foreground-border": "#878787", # for content borders + "color-background-primary": "white", # for content + "color-background-secondary": "#f8f9fb", # for navigation + ToC + "color-background-hover": "#efeff4ff", # for navigation-item hover + "color-background-hover--transparent": "#efeff400", + "color-background-border": "#eeebee", # for UI borders + "color-background-item": "#ccc", # for "background" items (eg: copybutton) + # Announcements + "color-announcement-background": "#000000dd", + "color-announcement-text": "#eeebee", + # Brand colors + "color-brand-primary": "#2962ff", + "color-brand-content": "#2a5adf", + # Highlighted text (search) + "color-highlighted-background": "#ddeeff", + # GUI Labels + "color-guilabel-background": "#ddeeff80", + "color-guilabel-border": "#bedaf580", + # API documentation + "color-api-keyword": "var(--color-foreground-secondary)", + "color-highlight-on-target": "#ffffcc", + # Admonitions + "color-admonition-background": "transparent", + # Cards + "color-card-border": "var(--color-background-secondary)", + "color-card-background": "transparent", + "color-card-marginals-background": "var(--color-background-hover)", + # Code blocks + "color-code-foreground": "black", + "color-code-background": "#f8f9fb", + }, + "footer_icons": [ + { + "name": "ARC@GitHub", + "url": "https://github.com/ISARICResearch/ARC", + "html": """ + + + + """, + "class": "", + }, + ], +} + + +# Force pygments style in dark mode back to the light variant +pygments_dark_style = "tango" + +html_logo = '_static/isaric-logo.png' + +# Relative path (from the ``docs`` folder) to the static files folder - so +# ``_static`` should be one level below ``docs``. +html_static_path = ["_static"] + +# Custom CSS file(s) - currently source the Font Awesome CSS classes to support +# Font Awesome icons. for more information see: +# +# https://sphinx-design.readthedocs.io/en/latest/badges_buttons.html#fontawesome-icons +# +html_css_files = [ + "css/custom.css", +] + +# Timestamp format for the last page updated time +html_last_updated_fmt = "%b %d, %Y" + +# Show link to ReST source on HTML pages +html_show_sourcelink = True + +# If true, the reST sources are included in the HTML build as _sources/. +html_copy_source = True + +# Output file base name for HTML help builder - use the project name +htmlhelp_basename = "isaric-arc" diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..b8efdcf --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,36 @@ +.. ARC documentation master file, created by + sphinx-quickstart on Thu Apr 30 13:31:01 2026. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +ARC documentation +================= + +`ARC `_ (Analysis and Research Compendium) is a comprehensive library of questions developed by `ISARIC `_ that can be used to rapidly build standardised Case Report Forms (CRF) for disease outbreaks. It covers a wide range of patient-related information, including demographics, comorbidities, signs and symptoms, medications, outcomes, and more. Each question in ARC has specific guidelines and relevant parameters, such as definitions, answer options, units, minimum and maximum limits, data types, skip logic, and more. + +ARC is designed to serve as a resource for researchers and healthcare professionals involved in the study of outbreaks and emerging public health threats. Here's what you need to know: + +- **Machine-Readable**: ARC is provided in CSV format, making it easy for automated systems to read and process the data. + +- **Open Access**: ARC is made openly available for the research community. While contributions are limited to authorized individuals, the document can be freely accessed and utilized by others. + +- **Version Control**: We continue to improve ARC by adding new questions and implementing structural changes. We maintain a comprehensive history of changes made to ARC using GitHub's version control. This ensures document integrity, traceability of changes, and seamless collaboration among researchers. Previous ARC versions may be accessed via this repository’s `releases `_. Additional questions can be added to future ARC versions by contacting us at: :email:`data@isaric.org`. + +- **Integration with the Clinical Epidemiology Platform**: ARC is integrated into `BRIDGE `_, our software tool for CRF generation. + +ARC is licensed under the open source compliant `MIT license `_. + +.. image:: _static/osi-badge-light.svg + :height: 200px + :width: 200px + +For more information use the content links below to navigate to the page(s) of interest. + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + + sources/arc + sources/arc-variable-naming + sources/arc-field-types + diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..32bb245 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/sources/arc-field-types.rst b/docs/sources/arc-field-types.rst new file mode 100644 index 0000000..b1c232d --- /dev/null +++ b/docs/sources/arc-field-types.rst @@ -0,0 +1,232 @@ +.. _arc-field-types: + +ARC Special Field Types Documentation +===================================== + +This document provides a detailed explanation of the special field types used within the ISARIC ARC (Analysis and Research Compendium) framework to support dynamic, reusable, and semantically structured Case Report Forms (CRFs). These field types extend beyond standard REDCap functionality to enable complex logic, repeated entries, hierarchical lists, and units management. + +-------------- + +.. _overview: + +Overview: REDCap-Compatible Extensions +-------------------------------------- + +Most fields in ARC use standard REDCap field types such as ``text``, ``radio``, ``checkbox``, ``dropdown``, ``calc``, and ``notes``. However, to support enhanced functionality and automation, ARC introduces several **special field types**: + +- ``user_list`` +- ``list`` +- ``multi_list`` +- Blank field (``select units`` in Question) + +These are interpreted and transformed into REDCap-compatible fields when generating a data dictionary. + +-------------- + +.. _user-list: + +1. ``user_list`` +---------------- + +Description +~~~~~~~~~~~ + +A is a structured field type that references a predefined list of options from an external file, where the user has marked some values as *selected* or *preset\_* (i.e., shown as default radio options) and others as optional extensions. A ``user_list`` is a structured field type that references a predefined list of options from an external file, which the user can modify to include the pertinent options for their particular context. This links to specific functionality in `ISARIC BRIDGE `__, where users can select the options they wish to include for a given question. Additionally, each version of ARC includes pre-selected options in the form of presets, which are shown by default, while other options remain available as optional extensions. + +Example +~~~~~~~ + +| Variable: ``inclu_disease`` +| List source: `Lists/inclusion/Diseases.csv `__ + +BRIDGE Transformation +~~~~~~~~~~~~~~~~~~~~~ + +- ``radio`` field with checked values as options: if the number of checked values < 15 +- ``dropdown`` field with checked values as options: if the number of checked values >= 15 +- ``dropdown`` (``otherl2``) to show extended values if user selects “Other” +- ``text`` field (``otherl3``) to specify unlisted values + +Derived Variables +~~~~~~~~~~~~~~~~~ + +- ``inclu_disease_otherl2`` +- ``inclu_disease_otherl3`` + +-------------- + +.. _list: + +2. ``list`` +----------- + +.. _description-1: + +Description +~~~~~~~~~~~ + +``list`` is used for fields that support **multiple repeated selections** from a predefined value set. Like ``user_list``, the options for ``list`` fields are loaded from external CSV files in the ARC GitHub repository. + +.. _example-1: + +Example +~~~~~~~ + +| Variable: ``comor_unlisted`` +| List source: `Lists/conditions/Comorbidities.csv `__ + +.. _bridge-transformation-1: + +BRIDGE Transformation +~~~~~~~~~~~~~~~~~~~~~ + +- Multiple ``dropdown`` entries: ``0item``, ``1item``, …, ``nitem`` +- Each followed by: + + - ``text`` field for “Other” entries: ``0otherl2``, etc. + - ``radio`` field asking if there’s an additional entry: ``0addi``, etc. + +.. _derived-variables-1: + +Derived Variables +~~~~~~~~~~~~~~~~~ + +- ``comor_unlisted_0item``, ``comor_unlisted_1item``, … +- ``comor_unlisted_0otherl2`` +- ``comor_unlisted_0addi`` + +-------------- + +.. _multi-list: + +3. ``multi_list`` +----------------- + +.. _description-2: + +Description +~~~~~~~~~~~ + +``multi_list`` represents a multiselect list where several options can be checked simultaneously. Like ``user_list``, its options are also loaded from external CSV files. + +.. _example-2: + +Example +~~~~~~~ + +| Variable: ``demog_race`` +| List source: `Lists/demographics/Race.csv `__ + +.. _bridge-transformation-2: + +BRIDGE Transformation +~~~~~~~~~~~~~~~~~~~~~ + +- A ``checkbox`` group with selected options +- If value ``88`` (Other) is selected: + + - Show ``dropdown`` with less common values (``otherl2``) + - Show ``text`` field for specification (``otherl3``) + +.. _derived-variables-2: + +Derived Variables +~~~~~~~~~~~~~~~~~ + +- ``demog_race``: base checkbox +- ``demog_race_otherl2``, ``demog_race_otherl3`` + +-------------- + +.. _select-units: + +4. ``select units`` +------------------- + +.. _description-3: + +Description +~~~~~~~~~~~ + +This is a structural pattern rather than an explicit type. It applies to clinical measurements (e.g., height, weight, temperature) that may be recorded in more than one unit (e.g., cm/in, kg/lb, °C/°F). The core variable usually includes “(select units)” in its question text and is linked to two or more variants defined with specific units tha share the same prefix. + +.. _example-3: + +Example +~~~~~~~ + +- Base question: ``demog_height`` → “Height (select units)” +- Variants: + + - ``demog_height_cm``: numeric field in centimeters + - ``demog_height_in``: numeric field in inches + +- Base question: ``demog_weight`` → “Weight (select units)” +- Variants: + + - ``demog_weight_kg``: numeric field in kilograms + - ``demog_weight_lb``: numeric field in pounds + +.. _bridge-transformation-3: + +BRIDGE Transformation +~~~~~~~~~~~~~~~~~~~~~ + +- A unified ``text`` field (e.g., ``demog_height``) for the value +- A companion ``radio`` field (e.g., ``demog_height_units``) to select which unit is used + +.. _derived-variables-3: + +Derived Variables +~~~~~~~~~~~~~~~~~ + +- ``demog_height``: unified height input +- ``demog_height_units``: unit selector (e.g., cm/in) +- ``demog_weight``: unified weight input +- ``demog_weight_units``: unit selector (e.g., kg/lb) + +This approach reduces redundancy, improves clarity, and ensures that unit selection is explicit and standardized. + +Moreover, this design enables CRF customization in `ISARIC BRIDGE `__: users can choose which unit(s) to display when configuring the form for a specific data collection setting. This allows alignment with local clinical practices (e.g., countries preferring cm/in or kg/lb) while maintaining a unified structure in the backend. + +-------------- + +.. _visual-summary: + +Visual Summary +-------------- + +Below is a simplified flowchart of how each ARC type expands into REDCap-compatible fields: + +:: + + user_list + └── radio field (Selected options) if Selected options < 15 + └── dropdown field (Selected options) if Selected options >= 15 + └── dropdown (Other options) + └── text (Specify other) + + list + └── dropdown_0item + ├── text_0otherl2 + └── radio_0addi + + multi_list + └── checkbox (main options) + ├── dropdown_otherl2 + └── text_otherl3 + + select units + ├── text (numeric value) + └── radio (unit selector) + +-------------- + +.. notes: + +Notes +----- + +- Lists are stored in the ARC GitHub repo under `/Lists/… `__ +- The transformation is handled automatically during CRF genration from `ISARIC BRIDGE `__ +- These structures support modular, scalable, and interoperable CRFs diff --git a/docs/sources/arc-variable-naming.rst b/docs/sources/arc-variable-naming.rst new file mode 100644 index 0000000..e09a5d7 --- /dev/null +++ b/docs/sources/arc-variable-naming.rst @@ -0,0 +1,201 @@ +.. _arc-variable-naming: + +ARC Variable Naming Conventions +=============================== + +This document describes the variable naming conventions used in ARC, which support consistent structure, clarity, and integration with data collection and harmonization tools like `ISARIC BRIDGE `_ and `ISARIC VERTEX `_. + +-------------- + +.. _naming-structure: + +1. General Naming Structure +--------------------------- + +Variable names follow a modular convention using underscores (``_``) to separate components: + +:: + + [domain]_[topic]_[detail] + +- ``domain``: thematic area (e.g., ``demog``, ``inter``, ``labs``) +- ``topic``: clinical concept (e.g., ``sex``, ``suppleo2``, ``glucose``) +- ``detail``: optional element used to indicate format, type, or follow-up + +Example: +~~~~~~~~ + +- ``demog_occupation_oth``: Open text field specifying occupation if “Other” was selected +- ``inter_nasalprongs_dur``: Duration (in days/hours) of nasal prong oxygen therapy + +-------------- + +.. _hierarchy-depth: + +2. HierARCy Depth +----------------- + +Variable names contain varying numbers of underscores to reflect their specificity: + +===================== ========================================= +Number of Underscores Meaning +===================== ========================================= +1 (``a_b``) General field (e.g., ``pres_date``) +2 (``a_b_c``) Component of a broader concept +3+ Further detail or sub-field (less common) +===================== ========================================= + +-------------- + +.. _common-suffixes: + +3. Common Suffixes +------------------ + +Below are common suffixes that reflect variable function or logic. All examples are real variables from the dataset: + ++--------------+----------------------------------------------------+-----------------------------------------------------------+ +| Suffix | Description | Examples | ++==============+====================================================+===========================================================+ +| ``_oth`` | Text field for specifying “Other” | ``demog_sex_oth``, ``demog_gender_oth`` | ++--------------+----------------------------------------------------+-----------------------------------------------------------+ +| ``_type`` | Specifies type or category of a condition | ``comor_liverdisease_type``, ``comor_tuberculos_type`` | ++--------------+----------------------------------------------------+-----------------------------------------------------------+ +| ``_date`` | Date field | ``inclu_consent_date``, ``readm_prev_date`` | ++--------------+----------------------------------------------------+-----------------------------------------------------------+ +| ``_spec`` | Specification detail for a selected category | ``expo14_typeoth_spec``, ``adsym_neurologic_spec`` | ++--------------+----------------------------------------------------+-----------------------------------------------------------+ +| ``_dur`` | Duration of an intervention or event | ``inter_facemask_dur``, ``inter_suppleo2_dur`` | ++--------------+----------------------------------------------------+-----------------------------------------------------------+ +| ``_ongoing`` | Indicates whether a treatment/condition is ongoing | ``inter_nasalprongs_ongoing``, ``inter_facemask_ongoing`` | ++--------------+----------------------------------------------------+-----------------------------------------------------------+ +| ``_num`` | Numerical count | ``lesion_head_num``, ``readm_prev_num`` | ++--------------+----------------------------------------------------+-----------------------------------------------------------+ +| ``_site`` | Site or anatomical location | ``adsym_skinrash_site``, ``readm_prev_site`` | ++--------------+----------------------------------------------------+-----------------------------------------------------------+ +| ``_mgdl`` | Lab measurement in mg/dL | ``labs_glucose_mgdl``, ``labs_bilirubin_mgdl`` | ++--------------+----------------------------------------------------+-----------------------------------------------------------+ +| ``_pcnt`` | Percent value | ``vital_fio2spo2_pcnt``, ``comor_hba1c_pcnt`` | ++--------------+----------------------------------------------------+-----------------------------------------------------------+ +| ``_yn`` | Yes/No binary question | ``expo14_yn``, ``test_yn`` | ++--------------+----------------------------------------------------+-----------------------------------------------------------+ + +Numbered Suffixes for Repeated Instances +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Some suffixes include numbers (e.g., ``_date1``, ``_type2``) to capture repeated events or values, especially useful for vaccines, medications, and other longitudinal data. + ++------------+-------------------------------------+-------------------------------------------------+ +| Suffix | Description | Example Variables | ++============+=====================================+=================================================+ +| ``_date1`` | First date of event | ``vacci_covid19_date1``, ``vacci_dengue_date1`` | ++------------+-------------------------------------+-------------------------------------------------+ +| ``_date2`` | Second instance (e.g., second dose) | ``vacci_mpox_date2`` | ++------------+-------------------------------------+-------------------------------------------------+ +| ``_date3`` | Third instance | ``vacci_covid19_date3`` | ++------------+-------------------------------------+-------------------------------------------------+ +| ``_type1`` | First categorical instance | ``vacci_dengue_type1`` | ++------------+-------------------------------------+-------------------------------------------------+ +| ``_type2`` | Second instance | ``vacci_covid19_type2`` | ++------------+-------------------------------------+-------------------------------------------------+ +| ``_type3`` | Third instance | ``vacci_dengue_type3`` | ++------------+-------------------------------------+-------------------------------------------------+ +| ``_spec1`` | Specification field for first entry | ``medi_offlab_spec1`` | ++------------+-------------------------------------+-------------------------------------------------+ + +These suffixes are used in parallel and are crucial for distinguishing multiple entries of the same concept within a participant record. + +-------------- + + +.. _section-mapping: + +4. Section Mapping +------------------ + +Each variable is linked to a logical section (e.g., INCLUSION CRITERIA, DEMOGRAPHICS, INTERVENTIONS) that determines its role in the clinical case report form (CRF). This section assignment ensures that CRFs are structured clearly and reproducibly. + +-------------- + +.. _branching-logic: + +5. Branching Logic Patterns +--------------------------- + +Suffixes like ``_oth``, ``_spec``, ``_ongoing``, ``_dur``, and ``_site`` often imply **conditional visibility**, depending on the answer to a parent field: + +- ``expo14_yn = Yes`` → show ``expo14_typeoth_spec`` +- ``inter_suppleo2_ongoing = Yes`` → may show ``inter_suppleo2_dur`` +- ``demog_gender = Other`` → show ``demog_gender_oth`` + +These dependencies must be respected in CRF tools like BRIDGE to ensure logical flow and data consistency. + +-------------- + +.. _variable-types: + +6. Variable Types +----------------- + +ARC uses various variable types to capture structured, semi-structured, and free-text data. Each type implies specific data constraints and rendering logic: + ++------------------+-------------------------------------------------------------------------+ +| Type | Description | ++==================+=========================================================================+ +| ``text`` | Free-text entry, typically short answers | ++------------------+-------------------------------------------------------------------------+ +| ``user_list`` | A list of options drawn from an external source, modifiable by the user | ++------------------+-------------------------------------------------------------------------+ +| ``radio`` | Single choice from a set of predefined options | ++------------------+-------------------------------------------------------------------------+ +| ``checkbox`` | Multiple selections allowed from a list | ++------------------+-------------------------------------------------------------------------+ +| ``list`` | Similar to ``radio``, may be used for dropdown selection | ++------------------+-------------------------------------------------------------------------+ +| ``multi_list`` | Like ``user_list``, but allows multiple selections | ++------------------+-------------------------------------------------------------------------+ +| ``date_dmy`` | Date field (day-month-year format) | ++------------------+-------------------------------------------------------------------------+ +| ``datetime_dmy`` | Date and time field in DMY format | ++------------------+-------------------------------------------------------------------------+ +| ``number`` | Numeric input, often with ``Minimum``/``Maximum`` constraints | ++------------------+-------------------------------------------------------------------------+ +| ``calc`` | Calculated field (derived from other variables) | ++------------------+-------------------------------------------------------------------------+ +| ``file`` | Field for file upload | ++------------------+-------------------------------------------------------------------------+ +| ``notes`` | Long free-text, typically for comments or additional detail | ++------------------+-------------------------------------------------------------------------+ +| ``descriptive`` | Static text or headers, not a question or input field | ++------------------+-------------------------------------------------------------------------+ + +-------------- + +.. _unit-selectable-variables: + +7. Unit-Selectable Variables +---------------------------- + +Some numeric variables are associated with **“Select Units”** fields. These allow users to specify the measurement unit alongside the value. + +Common Unit Systems: +~~~~~~~~~~~~~~~~~~~~ + +============== ============= +Concept Example Units +============== ============= +Height cm, inches +Weight kg, pounds +Temperature °C, °F +Blood pressure mmHg +============== ============= + +Structure: +~~~~~~~~~~ + +These are typically implemented as **paired fields**, for example: + +- ``demog_weight`` → select unit (radio/dropdown) +- ``demog_weight_kg``, ``demog_weight_lb`` → numeric input fields (conditional on unit) + +Such fields allow flexibility across settings while preserving data harmonization. The recommended unit (standardized) is often **pre-selected** via presets in `BRIDGE `_. \ No newline at end of file diff --git a/docs/sources/arc.rst b/docs/sources/arc.rst new file mode 100644 index 0000000..d60f768 --- /dev/null +++ b/docs/sources/arc.rst @@ -0,0 +1,43 @@ +.. _arc-schema: + +========== +ARC Schema +========== + +The ARC schema is made available as a machine-readable `CSV `_ (also shown at the **bottom of this page**) of clinical and research questions. This file provides the standardized structure that ensures interoperability across studies and outbreak contexts. + +Each row in the CSV represents a **variable** used in the Case Report Forms (CRFs). Variables include metadata that ensures **clarity, interoperability, and reusability** across contexts. For more details on variable naming conventions see :ref:`this `, and for details on the variable data types see :ref:`this `. + +For every variable, the following fields are included: + +- **Variable**: Unique variable name identifier used in the dataset (e.g., ``comor_hypertensi``). +- **Form**: The CRF form where the variable appears (e.g., *Presentation*, *Daily*, *Outcome*, …). +- **Section**: Subdivision within the form that groups related questions (e.g., *Co-morbidities and Risk Factors*,…). +- **Type**: Format of the response field (e.g., ``radio``, ``checkbox``, ``text``, ``date``). +- **Question**: Human-readable text shown to the data collector (e.g., *Hypertension*). +- **Answer Options**: Permissible responses to the question. These may reference predefined lists in ``/lists`` (e.g., + ``1, Yes | 0, No | 99, Unknown``). +- **Validation**: Input rules for the response, such as numeric range or pattern restrictions. +- **Minimum / Maximum**: Boundaries for numeric input when applicable. +- **List**: Links to option lists in ``/lists``. +- **Skip Logic**: Rules defining when the variable should be displayed, depending on other responses. +- **Body System**: Physiological system the variable belongs to (e.g., *Cardiovascular*). +- **Definition**: Description of the concept being captured, often linked to clinical definitions. +- **Completion Guideline**: Instruction text for data collectors to standardize responses. +- **Standardized Term Codelist**: Reference ontology or terminology + system used for harmonization (e.g., *SNOMED*). +- **Standardized Term Code**: The specific code(s) from the ontology (e.g., ``38341003, Hypertensive disorder, systemic arterial (disorder)``). +- **Templates / Presets**: Links to where the variable is used in disease-specific CRFs (*COVID, Dengue, Mpox, H5Nx, ARI*) or risk scores (*Charlson CI, mSOFA*). + +The CSV serves not only as a **question bank**, but also as a **metadata dictionary** that enables: + +- Harmonized clinical data collection. +- Mapping to standard vocabularies. +- Adaptation for different diseases and study contexts. + +.. literalinclude:: ../../ARC.csv + :encoding: latin-1 + :language: csv + :lineno-start: 1 + :emphasize-lines: 1 + diff --git a/pyproject.toml b/pyproject.toml index cd6bbba..3b15cf2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -8,25 +8,52 @@ description = "ARC (Acute and Rapid onset disease Case report form) - standardised clinical data collection" readme = "README.md" license = "MIT" - requires-python = ">=3.11" + requires-python = ">=3.12" authors = [{ name = "ISARIC" }] - dependencies = ["numpy>=2.0", "pandas>=2.0", "jsonschema"] + dependencies = [ + "numpy>=2.0", + "pandas>=2.0", + "jsonschema", + ] - [project.optional-dependencies] - dev = ["pytest", "adtl"] +[project.optional-dependencies] + dev = [ + "pytest", + "adtl", + ] - [project.urls] - Homepage = "https://github.com/ISARICResearch/ARC" - Repository = "https://github.com/ISARICResearch/ARC" + docs = [ + "Sphinx", + "sphinx-autobuild", + "sphinxcontrib-email", + "sphinx-copybutton", + "sphinx-gallery", + "sphinx-design", + "myst-parser", + "pylint", + "furo", + "numpydoc", + "nb2plots", + "jupyter-sphinx", + ] + +[project.urls] + Homepage = "https://github.com/ISARICResearch/ARC" + Repository = "https://github.com/ISARICResearch/ARC" [tool.hatch.build.targets.wheel] packages = ["schemas", "units", "tests"] - [tool.hatch.build.targets.wheel.force-include] - "Lists" = "arc_data/Lists" +[tool.hatch.build.targets.wheel.force-include] + "Lists" = "arc_data/Lists" [tool.hatch.build.targets.sdist] include = ["schemas/", "units/"] [tool.pytest.ini_options] - markers = ["critical: critical severity test (must pass)", "high: high severity test", "medium: medium severity test", "low: low severity test"] + markers = [ + "critical: critical severity test (must pass)", + "high: high severity test", + "medium: medium severity test", + "low: low severity test" + ]