# karki2004/louisiana_oxygen_case_study architecture

> Architecture diagram of the GitHub repository karki2004/louisiana_oxygen_case_study, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/karki2004/louisiana_oxygen_case_study
- Repository: https://github.com/karki2004/louisiana_oxygen_case_study

## Overview

This repository is a reproducible data-science case study, not a general-purpose software service. A researcher supplies public USGS observations to a single analysis script, which validates and prepares the time series, trains a model, simulates gaps, compares reconstruction methods, and writes results. A separate script assembles selected results into a PDF brief. Analysis stages are represented as distinct responsibilities within `analyze.py`; the README documents the experiment and outputs, but the sampled code is the main implementation evidence.

Main entry points: [`create_brief.py`](https://github.com/karki2004/louisiana_oxygen_case_study/blob/main/create_brief.py) (Brief generation), [`analyze.py`](https://github.com/karki2004/louisiana_oxygen_case_study/blob/main/analyze.py) (Data validation), [`summary.csv`](https://github.com/karki2004/louisiana_oxygen_case_study/blob/main/summary.csv) (Method summary), [`audit.json`](https://github.com/karki2004/louisiana_oxygen_case_study/blob/main/audit.json) (Run audit)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_analysis["Analysis workflow"]
  node_analysis_run["Analysis run<br/>[analyze.py]"]
  node_validation["Data validation<br/>[analyze.py]"]
  node_feature_prep["Feature preparation<br/>[analyze.py]"]
  node_model_fit["Forest training<br/>[analyze.py]"]
  node_test_cohort["Complete-day cohort<br/>[analyze.py]"]
  node_gap_trials["Gap simulation<br/>[analyze.py]"]
  node_reconstruction["Reconstruction methods<br/>[analyze.py]"]
  node_evaluation["Daily metrics<br/>[analyze.py]"]
end

subgraph group_results["Analysis outputs"]
  node_trial_results["Trial results<br/>[trials.csv]"]
  node_summary_results["Method summary<br/>[summary.csv]"]
  node_audit_results["Run audit<br/>[audit.json]"]
  node_comparison_plot["Method comparison"]
  node_context_plot["Data context"]
end

subgraph group_brief["Research brief"]
  node_brief_run["Brief generation<br/>[create_brief.py]"]
  node_pdf_brief["Case-study PDF"]
end

node_researcher(("Researcher"))
node_usgs_data["USGS observations"]
node_metadata["USGS metadata"]

node_researcher -->|"runs analysis"| node_analysis_run
node_usgs_data -->|"provides observations"| node_analysis_run
node_analysis_run -->|"loads and checks"| node_validation
node_metadata -.->|"describes source"| node_researcher
node_validation -->|"prepares series"| node_feature_prep
node_feature_prep -->|"supplies predictors"| node_model_fit
node_model_fit -->|"predicts oxygen"| node_test_cohort
node_validation -->|"selects test days"| node_test_cohort
node_test_cohort -->|"samples gaps"| node_gap_trials
node_gap_trials -->|"masks observations"| node_reconstruction
node_reconstruction -->|"supplies estimates"| node_evaluation
node_evaluation -->|"writes trials"| node_trial_results
node_evaluation -->|"aggregates metrics"| node_summary_results
node_analysis_run -->|"writes run metadata"| node_audit_results
node_evaluation -->|"plots metric errors"| node_comparison_plot
node_validation -->|"plots observed context"| node_context_plot
node_researcher -->|"runs brief"| node_brief_run
node_summary_results -->|"provides metrics"| node_brief_run
node_audit_results -->|"provides counts"| node_brief_run
node_comparison_plot -->|"provides figure"| node_brief_run
node_brief_run -->|"generates PDF"| node_pdf_brief

click node_metadata "https://github.com/karki2004/louisiana_oxygen_case_study/blob/main/source_metadata.xml"
click node_analysis_run "https://github.com/karki2004/louisiana_oxygen_case_study/blob/main/analyze.py"
click node_validation "https://github.com/karki2004/louisiana_oxygen_case_study/blob/main/analyze.py"
click node_feature_prep "https://github.com/karki2004/louisiana_oxygen_case_study/blob/main/analyze.py"
click node_model_fit "https://github.com/karki2004/louisiana_oxygen_case_study/blob/main/analyze.py"
click node_test_cohort "https://github.com/karki2004/louisiana_oxygen_case_study/blob/main/analyze.py"
click node_gap_trials "https://github.com/karki2004/louisiana_oxygen_case_study/blob/main/analyze.py"
click node_reconstruction "https://github.com/karki2004/louisiana_oxygen_case_study/blob/main/analyze.py"
click node_evaluation "https://github.com/karki2004/louisiana_oxygen_case_study/blob/main/analyze.py"
click node_trial_results "https://github.com/karki2004/louisiana_oxygen_case_study/blob/main/trials.csv"
click node_summary_results "https://github.com/karki2004/louisiana_oxygen_case_study/blob/main/summary.csv"
click node_audit_results "https://github.com/karki2004/louisiana_oxygen_case_study/blob/main/audit.json"
click node_brief_run "https://github.com/karki2004/louisiana_oxygen_case_study/blob/main/create_brief.py"
click node_pdf_brief "https://github.com/karki2004/louisiana_oxygen_case_study/blob/main/Louisiana_Oxygen_Gap_Case_Study.pdf"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_analysis_run,node_validation,node_feature_prep,node_model_fit,node_test_cohort,node_gap_trials,node_reconstruction,node_evaluation toneBlue
class node_trial_results,node_summary_results,node_audit_results,node_comparison_plot,node_context_plot toneAmber
class node_brief_run,node_pdf_brief toneMint
class node_researcher,node_usgs_data toneIndigo
class node_metadata toneTeal
```

## Components

### Analysis workflow

- [Analysis run](https://github.com/karki2004/louisiana_oxygen_case_study/blob/main/analyze.py): `analyze.py`
- [Data validation](https://github.com/karki2004/louisiana_oxygen_case_study/blob/main/analyze.py): `analyze.py`
- [Feature preparation](https://github.com/karki2004/louisiana_oxygen_case_study/blob/main/analyze.py): `analyze.py`
- [Forest training](https://github.com/karki2004/louisiana_oxygen_case_study/blob/main/analyze.py): `analyze.py`
- [Complete-day cohort](https://github.com/karki2004/louisiana_oxygen_case_study/blob/main/analyze.py): `analyze.py`
- [Gap simulation](https://github.com/karki2004/louisiana_oxygen_case_study/blob/main/analyze.py): `analyze.py`
- [Reconstruction methods](https://github.com/karki2004/louisiana_oxygen_case_study/blob/main/analyze.py): `analyze.py`
- [Daily metrics](https://github.com/karki2004/louisiana_oxygen_case_study/blob/main/analyze.py): `analyze.py`

### Analysis outputs

- [Trial results](https://github.com/karki2004/louisiana_oxygen_case_study/blob/main/trials.csv): `trials.csv`
- [Method summary](https://github.com/karki2004/louisiana_oxygen_case_study/blob/main/summary.csv): `summary.csv`
- [Run audit](https://github.com/karki2004/louisiana_oxygen_case_study/blob/main/audit.json): `audit.json`
- **Method comparison**
- **Data context**

### Research brief

- [Brief generation](https://github.com/karki2004/louisiana_oxygen_case_study/blob/main/create_brief.py): `create_brief.py`
- [Case-study PDF](https://github.com/karki2004/louisiana_oxygen_case_study/blob/main/Louisiana_Oxygen_Gap_Case_Study.pdf): `Louisiana_Oxygen_Gap_Case_Study.pdf`

### Other components

- **Researcher**
- **USGS observations**
- [USGS metadata](https://github.com/karki2004/louisiana_oxygen_case_study/blob/main/source_metadata.xml): `source_metadata.xml`

## Connections

- Researcher → Analysis run: runs analysis
- USGS observations → Analysis run: provides observations
- Analysis run → Data validation: loads and checks
- USGS metadata → Researcher: describes source
- Data validation → Feature preparation: prepares series
- Feature preparation → Forest training: supplies predictors
- Forest training → Complete-day cohort: predicts oxygen
- Data validation → Complete-day cohort: selects test days
- Complete-day cohort → Gap simulation: samples gaps
- Gap simulation → Reconstruction methods: masks observations
- Reconstruction methods → Daily metrics: supplies estimates
- Daily metrics → Trial results: writes trials
- Daily metrics → Method summary: aggregates metrics
- Analysis run → Run audit: writes run metadata
- Daily metrics → Method comparison: plots metric errors
- Data validation → Data context: plots observed context
- Researcher → Brief generation: runs brief
- Method summary → Brief generation: provides metrics
- Run audit → Brief generation: provides counts
- Method comparison → Brief generation: provides figure
- Brief generation → Case-study PDF: generates PDF