# common-longitudinal-icu-data-format/pyclif architecture

> Architecture diagram of the GitHub repository common-longitudinal-icu-data-format/pyclif, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/common-longitudinal-icu-data-format/pyclif
- Repository: https://github.com/common-longitudinal-icu-data-format/pyclif

## Overview

##### Project type and purpose
- pyCLIF is an open-source Python library (not a web or full-stack app) designed to load, validate, transform, and analyze CLIF (Common Longitudinal ICU Data Format) data.
- Its primary users are data engineers, clinical data scientists, and developers who need a standardized interface over ICU-related clinical tables.

##### File structure
Top-level directories and files:
- src/pyclif/          ← main package
– clif.py            ← core orchestrator class
– data/              ← demo datasets + loader
– mCIDE/             ← JSON schemas for each CLIF table
– tables/            ← implementations of the nine CLIF table classes
– utils/             ← I/O, validation, timezone handling, dataset transforms
- config/config.json   ← default configuration for loader or validation
- CQODE/               ← R-based demo functions (separate client code)
- examples/            ← Jupyter notebooks demonstrating usage
- tests/               ← pytest suite covering core, tables, utils
- pyproject.toml       ← build and dependency definitions
- README.md            ← high-level overview, usage, status

##### README for additional insights
- Confirms nine CLIF-2.0.0 tables, validation against mCIDE schemas, timezone handling, filtering, chunked processing, and a core CLIF class API.
- Mentions key dependencies: pandas, duckdb, pyarrow, pydantic, pytz.
- Demonstrates two usage patterns: high-level CLIF orchestrator vs. per-table direct loading.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Sources
    extData["External Data Sources"]:::external
    click extData "https://github.com/common-longitudinal-icu-data-format/pyclif/tree/main/src/pyclif/data/clif_demo/"

    %% Configuration
    config["Configuration Module\n(config/config.json)"]:::external
    click config "https://github.com/common-longitudinal-icu-data-format/pyclif/blob/main/config/config.json"

    %% I/O & Loader Layer
    io["I/O Utils\n(io.py)"]:::io
    click io "https://github.com/common-longitudinal-icu-data-format/pyclif/blob/main/src/pyclif/utils/io.py"
    loader["Data Loader\n(loader.py)"]:::io
    click loader "https://github.com/common-longitudinal-icu-data-format/pyclif/blob/main/src/pyclif/data/loader.py"

    %% Schema Validation Service
    schemas["mCIDE JSON Schemas"]:::validation
    click schemas "https://github.com/common-longitudinal-icu-data-format/pyclif/tree/main/src/pyclif/mCIDE/"
    validator["Validator\n(validator.py)"]:::validation
    click validator "https://github.com/common-longitudinal-icu-data-format/pyclif/blob/main/src/pyclif/utils/validator.py"

    %% Timezone & Transformation Utilities
    sofa["SOFA\n(sofa.py)"]:::io
    click sofa "https://github.com/common-longitudinal-icu-data-format/pyclif/blob/main/src/pyclif/utils/sofa.py"
    waterfall["Waterfall\n(waterfall.py)"]:::io
    click waterfall "https://github.com/common-longitudinal-icu-data-format/pyclif/blob/main/src/pyclif/utils/waterfall.py"
    wide["Wide Dataset\n(wide_dataset.py)"]:::io
    click wide "https://github.com/common-longitudinal-icu-data-format/pyclif/blob/main/src/pyclif/utils/wide_dataset.py"

    %% Table Classes
    adt["ADT\n(adt.py)"]:::domain
    click adt "https://github.com/common-longitudinal-icu-data-format/pyclif/blob/main/src/pyclif/tables/adt.py"
    hosp["Hospitalization\n(hospitalization.py)"]:::domain
    click hosp "https://github.com/common-longitudinal-icu-data-format/pyclif/blob/main/src/pyclif/tables/hospitalization.py"
    labs["Labs\n(labs.py)"]:::domain
    click labs "https://github.com/common-longitudinal-icu-data-format/pyclif/blob/main/src/pyclif/tables/labs.py"
    med["Medication Admin\n(medication_admin_continuous.py)"]:::domain
    click med "https://github.com/common-longitudinal-icu-data-format/pyclif/blob/main/src/pyclif/tables/medication_admin_continuous.py"
    patient["Patient\n(patient.py)"]:::domain
    click patient "https://github.com/common-longitudinal-icu-data-format/pyclif/blob/main/src/pyclif/tables/patient.py"
    assess["Patient Assessments\n(patient_assessments.py)"]:::domain
    click assess "https://github.com/common-longitudinal-icu-data-format/pyclif/blob/main/src/pyclif/tables/patient_assessments.py"
    pos["Position\n(position.py)"]:::domain
    click pos "https://github.com/common-longitudinal-icu-data-format/pyclif/blob/main/src/pyclif/tables/position.py"
    resp["Respiratory Support\n(respiratory_support.py)"]:::domain
    click resp "https://github.com/common-longitudinal-icu-data-format/pyclif/blob/main/src/pyclif/tables/respiratory_support.py"
    vitals["Vitals\n(vitals.py)"]:::domain
    click vitals "https://github.com/common-longitudinal-icu-data-format/pyclif/blob/main/src/pyclif/tables/vitals.py"

    %% Orchestration/API
    clif["CLIF Orchestrator\n(clif.py)"]:::orchestration
    click clif "https://github.com/common-longitudinal-icu-data-format/pyclif/blob/main/src/pyclif/clif.py"

    %% User Interface
    ui["User Interface\n(examples/*.ipynb)"]:::external
    click ui "https://github.com/common-longitudinal-icu-data-format/pyclif/tree/main/examples/"

    %% Testing Suite
    tests["Testing Suite\n(tests/)"]:::external
    click tests "https://github.com/common-longitudinal-icu-data-format/pyclif/tree/main/tests/"

    %% Packaging & Distribution
    packaging["Packaging & Distribution\n(pyproject.toml)"]:::external
    click packaging "https://github.com/common-longitudinal-icu-data-format/pyclif/blob/main/pyproject.toml"

    %% Relationships
    extData --> io
    extData --> loader
    config --> io
    config --> validator

    io --> validator
    loader --> validator

    validator --> adt
    validator --> hosp
    validator --> labs
    validator --> med
    validator --> patient
    validator --> assess
    validator --> pos
    validator --> resp
    validator --> vitals

    adt --> clif
    hosp --> clif
    labs --> clif
    med --> clif
    patient --> clif
    assess --> clif
    pos --> clif
    resp --> clif
    vitals --> clif

    sofa --> clif
    waterfall --> clif
    wide --> clif

    clif --> ui

    tests --> io
    tests --> validator
    tests --> adt
    tests --> clif

    %% Styles
    classDef external fill:#eeeeee,stroke:#888888,color:#333333,stroke-width:1px;
    classDef io fill:#b3d1ff,stroke:#336699,color:#000000,stroke-width:1px;
    classDef validation fill:#d1f2b3,stroke:#339933,color:#000000,stroke-width:1px;
    classDef domain fill:#ffd9b3,stroke:#ff9933,color:#000000,stroke-width:1px;
    classDef orchestration fill:#e6b3ff,stroke:#9933cc,color:#000000,stroke-width:1px;
```
