# 04-eda.md

## Analytical Goal

### Restated Question from Problem Spec

The exploratory analysis phase supports all three analytical questions from `specs/01-problem.md`:

1. Given information available at presentation, can we predict whether a patient with COVID-like symptoms is likely to require hospital admission?
2. For an already admitted patient with COVID-like symptoms, can we predict whether the patient is appropriate for discharge within a defined near-term decision window?
3. What clinical, demographic, and operational patterns are associated with admission decisions and discharge timing for patients with COVID-like symptoms?

### What EDA Must Establish Before Modeling Is Justified

EDA must establish the following before Phase 5 modeling is justified:

* the cleaned dataset is trustworthy enough to support descriptive analysis and candidate feature review
* the likely COVID-like cohort can be identified consistently enough for downstream modeling subsets
* variables needed for Question 1 admission modeling exist at or before the likely decision point
* the current dataset appears sufficient for at least one interpretable baseline model, even if only for the admission question
* current field timing, distributions, and subgroup structure do not show fatal leakage or data-quality problems
* the discharge-readiness question is either operationally supportable from available fields or should be deferred

### What Would Cause Us to Revise the Question

We must revise the problem framing if EDA shows any of the following:

* the current dataset is too broad or too synthetic to support a defensible COVID-like cohort without major reconstruction
* `visit_type` is not an acceptable proxy for admission status or lacks the timing needed for Question 1
* the current data does not contain reliable discharge labels, inpatient time slices, or post-discharge safety outcomes for Question 2
* temporal artifacts, policy changes, or source-system issues dominate the observed patterns
* candidate predictors are mostly missing, post-outcome, or operationally ambiguous

## Data Validation Checks (Stage 1-2: Trust & Provenance)

### Critical Field: `visit_occurrence_id`

* [ ] Values fall within domain-valid ranges
* [ ] No unexpected format changes across time
* [ ] Distributions match domain expectations
* [ ] Cross-field consistency holds
* [ ] No signs of system artifacts
* [ ] Sampling appears representative

Checks:
* confirm row-level uniqueness in cleaned data
* verify no duplicate encounters emerge after cohort filtering
* inspect encounter counts by month for abrupt ID or count discontinuities

### Critical Field: `person_id`

* [ ] Values fall within domain-valid ranges
* [ ] No unexpected format changes across time
* [ ] Distributions match domain expectations
* [ ] Cross-field consistency holds
* [ ] No signs of system artifacts
* [ ] Sampling appears representative

Checks:
* profile encounters per patient and inspect heavy repeat-utilizer tails
* verify birth date, sex, race, and ethnicity are stable within patient where repeated encounters exist

### Critical Fields: `visit_start_date`, `visit_end_date`, `measurement_date`

* [ ] Values fall within domain-valid ranges
* [ ] No unexpected format changes across time
* [ ] Distributions match domain expectations
* [ ] Cross-field consistency holds
* [ ] No signs of system artifacts
* [ ] Sampling appears representative

Checks:
* verify no `visit_end_date < visit_start_date`
* quantify same-day visits, pre-2020 visits, pre-2020 measurements, and measurements after visit start
* inspect date histograms for implausible spikes, default dates, and sudden regime changes
* inspect weekday and day-of-month patterns for artifacts

### Critical Field: `visit_type`

* [ ] Values fall within domain-valid ranges
* [ ] No unexpected format changes across time
* [ ] Distributions match domain expectations
* [ ] Cross-field consistency holds
* [ ] No signs of system artifacts
* [ ] Sampling appears representative

Checks:
* verify categories are limited to expected care settings
* inspect monthly setting mix for discontinuities
* compare visit_type against symptom severity and mortality to assess whether it is a plausible admission proxy

### Critical Fields: `condition`, `condition_terms_cleaned`, `observation_source`

* [ ] Values fall within domain-valid ranges
* [ ] No unexpected format changes across time
* [ ] Distributions match domain expectations
* [ ] Cross-field consistency holds
* [ ] No signs of system artifacts
* [ ] Sampling appears representative

Checks:
* quantify repeated condition-term rows and top symptom terms
* inspect whether likely respiratory/COVID-like observations concentrate in the expected time window
* compare `observation_source` and `condition` overlap to understand cohort-definition reliability

### Critical Fields: demographics

Fields:
* `birth_datetime`
* `age_at_visit_years`
* `gender_source_value`
* `race_source_value`
* `ethnicity_source_value`

* [ ] Values fall within domain-valid ranges
* [ ] No unexpected format changes across time
* [ ] Distributions match domain expectations
* [ ] Cross-field consistency holds
* [ ] No signs of system artifacts
* [ ] Sampling appears representative

Checks:
* verify age is consistent with birth date and visit date
* inspect age distribution and subgroup representation by time and visit_type
* review whether demographic composition shifts abruptly across the pre-2020 and 2020-era partitions

### Critical Fields: vitals and anthropometrics

Fields:
* `body_temperature_c`
* `body_weight_kg`
* `body_height_cm`
* `bmi`
* `systolic`
* `diastolic`
* `heart_rate_bpm`
* `oxygen_saturation_percent`
* `respiratory_rate_per_minute`

* [ ] Values fall within domain-valid ranges
* [ ] No unexpected format changes across time
* [ ] Distributions match domain expectations
* [ ] Cross-field consistency holds
* [ ] No signs of system artifacts
* [ ] Sampling appears representative

Checks:
* inspect missingness and value ranges by age and visit_type
* look for round-number clustering, truncation, default values, and value caps
* confirm physiological consistency where possible, such as `systolic >= diastolic`
* review whether oxygen saturation’s narrow range reflects clipping or source-system formatting

### Critical Field: `deceased`

* [ ] Values fall within domain-valid ranges
* [ ] No unexpected format changes across time
* [ ] Distributions match domain expectations
* [ ] Cross-field consistency holds
* [ ] No signs of system artifacts
* [ ] Sampling appears representative

Checks:
* verify only expected labels are present
* compare mortality proportions by visit_type, candidate COVID-like status, and time
* confirm whether `deceased` behaves like an outcome variable rather than a cohort flag

### Critical Fields: immunization dates

Fields:
* `flu_last_administered`
* `tdap_last_administered`
* `mmr_last_administered`
* `polio_last_administered`

* [ ] Values fall within domain-valid ranges
* [ ] No unexpected format changes across time
* [ ] Distributions match domain expectations
* [ ] Cross-field consistency holds
* [ ] No signs of system artifacts
* [ ] Sampling appears representative

Checks:
* inspect whether immunization dates occur after the visit date
* review default/placeholder date patterns
* determine whether these fields are plausible predictors or mostly data-availability artifacts

## Exploration Plan (Stage 3: Four Dimensions)

### Distributional

For each key variable:

#### `age_at_visit_years`

* Expected distribution and why:
  broad, multimodal age distribution because the dataset appears to include pediatric and adult encounters
* What would be surprising:
  an implausible spike at exact rounded ages or abrupt disappearance of older adults in likely inpatient/COVID-like subsets

#### `visit_type`

* Expected distribution and why:
  outpatient visits should dominate overall volume, with inpatient visits carrying higher severity
* What would be surprising:
  inpatient visits not differing materially from outpatient visits on vitals or mortality

#### `observation_source`

* Expected distribution and why:
  substantial missingness plus a dominant `Suspected COVID-19` category among candidate respiratory visits
* What would be surprising:
  non-COVID observations dominating the 2020 respiratory-like subset

#### `condition_terms_cleaned`

* Expected distribution and why:
  respiratory symptoms and pneumonia-related terms should dominate the likely COVID-like subset
* What would be surprising:
  mostly allergy/sinusitis terms in the subset intended for admission modeling

#### vitals and anthropometrics

* Expected distribution and why:
  clinically plausible ranges with missingness varying strongly by visit_type
* What would be surprising:
  impossible values, strong clipping, or nearly identical distributions across inpatient and outpatient settings

#### `deceased`

* Expected distribution and why:
  minority positive class overall, with materially higher prevalence in inpatient and severe respiratory groups
* What would be surprising:
  no mortality gradient by setting or symptom severity

Acceptance:
* [ ] all key variables have documented distributions with outlier assessment

### Relational

For each hypothesis about variable relationships:

#### Hypothesis 1

* Variables: `visit_type` and `deceased`
* Expected relationship: inpatient visits should have higher mortality than outpatient visits
* Confounders to check:
  age, candidate COVID-like status, pre-2020 vs 2020-era encounters

#### Hypothesis 2

* Variables: `oxygen_saturation_percent` and `visit_type`
* Expected relationship: lower oxygen saturation should be associated with inpatient care
* Confounders to check:
  measurement availability, age, respiratory symptom burden

#### Hypothesis 3

* Variables: `body_temperature_c` and `has_suspected_covid_observation`
* Expected relationship: higher temperatures should be more common among suspected COVID-like encounters
* Confounders to check:
  age, encounter period, measurement missingness

#### Hypothesis 4

* Variables: `condition_term_count` and `visit_type`
* Expected relationship: more complex respiratory condition strings may be associated with inpatient visits
* Confounders to check:
  source-system concatenation behavior, repeated condition terms, pre-2020 artifact rows

Acceptance:
* [ ] correlation matrix computed, key relationships visualized with alternatives noted

### Comparative

For each segment comparison:

#### Comparison 1

* Groups: `Inpatient Visit` vs `Outpatient Visit`
* Metric: age, vitals, candidate COVID-like prevalence, mortality, missingness

#### Comparison 2

* Groups: pre-2020 vs `2020-01-01` and later
* Metric: visit volume, visit_type mix, observation_source mix, respiratory symptom burden

#### Comparison 3

* Groups: candidate COVID-like vs not candidate COVID-like
* Metric: visit_type, mortality, vital distributions, measurement completeness

#### Comparison 4

* Groups: demographic strata by race, ethnicity, sex, and age band
* Metric: visit_type mix, candidate COVID-like prevalence, missingness, mortality

Acceptance:
* [ ] group distributions visualized, Simpson's Paradox checked

### Structural / Temporal

For each time-dependent pattern:

#### Pattern 1

* Variable and time grain:
  encounter counts by week and month using `visit_start_date`
* Expected patterns:
  a major regime change entering the COVID era and possible concentration in early 2020

#### Pattern 2

* Variable and time grain:
  candidate COVID-like share by week
* Expected patterns:
  increase during the COVID period, with possible abrupt changes if source logic changed

#### Pattern 3

* Variable and time grain:
  inpatient share by week
* Expected patterns:
  higher inpatient burden during severe respiratory surges

#### Pattern 4

* Variable and time grain:
  mortality share by month
* Expected patterns:
  temporal clustering rather than flat prevalence across all periods

Acceptance:
* [ ] time-series decomposition completed, structural breaks identified

## Hypotheses to Test

### Hypothesis 1

* Statement:
  candidate COVID-like respiratory encounters are more likely to be inpatient than non-candidate encounters
* What would confirm it:
  materially higher inpatient share after stratifying by age and time period
* What would refute it:
  similar or lower inpatient share once confounders are considered

### Hypothesis 2

* Statement:
  lower oxygen saturation and higher respiratory rate are associated with inpatient visits
* What would confirm it:
  consistent separation in distributions and monotonic trend in admission-like proxy rates
* What would refute it:
  overlapping distributions with no meaningful directional pattern

### Hypothesis 3

* Statement:
  the pre-2020 portion of the dataset reflects a different underlying source process than the 2020-era portion
* What would confirm it:
  sharp shifts in setting mix, symptom mix, observation labels, or missingness around 2020
* What would refute it:
  stable distributions and cohort logic across the entire time span

### Hypothesis 4

* Statement:
  `deceased` behaves as a downstream severity outcome and should not be used as an admission-time predictor
* What would confirm it:
  strong association with inpatient status and respiratory severity, with clear risk of leakage
* What would refute it:
  evidence that the field is a pre-existing status rather than an outcome

### Hypothesis 5

* Statement:
  the current dataset is sufficient for admission-focused exploratory modeling but not yet for discharge-readiness modeling
* What would confirm it:
  admission proxy and pre-encounter variables are available, but discharge labels and time-indexed inpatient snapshots are absent
* What would refute it:
  discovery of reliable discharge-timing and post-discharge safety fields in the current data

## Assumptions to Validate

### Patients with COVID-like symptoms can be identified consistently

* Test:
  compare candidate cohort definitions using `observation_source`, `condition_terms_cleaned`, `visit_type`, and time period; assess agreement and disagreement cases

### Admission decisions are recorded clearly enough for labeling

* Test:
  evaluate whether `visit_type` and visit-duration fields provide a defensible admission proxy and quantify ambiguity cases

### Discharge decisions and timestamps are reliable

* Test:
  look for explicit discharge-related fields or inpatient longitudinal structure; if absent, flag the assumption as unsupported

### Timestamped data is accurate enough to prevent leakage

* Test:
  quantify measurements after visit start, inspect immunization dates after visit date, and assess whether timestamps are only date-level

### Sufficient pre-admission predictors exist

* Test:
  measure missingness and availability for demographics, respiratory symptoms, and vital-sign fields in likely admission-time subsets

### Sufficient inpatient longitudinal data exists

* Test:
  assess whether repeated within-stay measurements or time-indexed inpatient records exist per encounter

### Sample size is adequate

* Test:
  compute cohort sizes for overall, likely COVID-like, inpatient, and candidate admission subsets, including subgroup counts

### Data quality is adequate across key variables

* Test:
  run range checks, missingness profiling, outlier review, and temporal consistency checks for key fields

### Stakeholders can agree on operational definitions

* Test:
  prepare EDA findings that isolate ambiguity points in cohort, admission proxy, and discharge proxy definitions for stakeholder review

### Unsafe-discharge proxies are available

* Test:
  search current fields for readmission, ICU transfer, deterioration, or downstream adverse event proxies; if none exist, flag as unavailable

### Historical clinical decisions are suitable as labels for an initial modeling phase

* Test:
  inspect whether current proxies look operationally stable across time and subgroups or appear dominated by source artifacts

### Variation in hospital policy, staffing, or pandemic phase does not make the data unusably inconsistent

* Test:
  compare key distributions across time segments and identify structural breaks in care setting, symptom burden, and outcome rates

### Ethical and regulatory review will permit use of the required healthcare data

* Test:
  confirm no EDA workflow or exported artifact includes direct patient identifiers beyond internal development use and document any governance concerns

## Acceptance Criteria

* [ ] All validation checks passed (or failures documented with impact assessment)
* [ ] All four EDA dimensions explored for key variables
* [ ] At least two competing explanations documented for each strong pattern
* [ ] Assumptions from problem spec validated or flagged
* [ ] EDA findings do NOT overstate confidence (hypotheses, not conclusions)
* [ ] `progress.md` updated with key findings and revised hypotheses

## Phase Gate

EDA spec must be reviewed. Decide one of the following after EDA execution:

* communicate findings
* build model
* collect more data
* refine question
