Elderly Mortality Analysis

A lightweight Python workflow for preparing, documenting, and exploring hospital mortality records among older adults.

The repository currently uses synthetic data to validate the full analysis pipeline before applying the workflow to sensitive real-world medical records.

Overview

This project helps structure a reproducible analysis of elderly patients who died during hospital admission. It focuses on turning raw chart-review data into analysis-ready tables, applying eligibility rules, producing quality-control outputs, and generating descriptive reports and figures.

The workflow is designed for clinical and epidemiological review, not for direct causal inference. Since the current dataset represents patients who died, comparisons are interpreted within the eligible mortality cohort. Comparisons between death and survival outcomes require an additional survivor cohort.

Features

• CSV ingestion with delimiter and encoding handling.
• Data cleaning into one row per patient.
• Exclusion of residential/home deaths from the hospital mortality cohort.
• Descriptive frequency tables and numeric summaries.
• Quality-control reports for missingness and eligibility checks.
• Export of a formatted Excel data-collection workbook.
• Publication-ready exploratory figures using Matplotlib, Seaborn, and SciencePlots.
• Human-readable documentation for variables, scoring rules, and analysis guidelines.

Repository Structure

.
├── data/
│   └── data_generator.py
├── docs/
│   ├── analysis_guidelines_en.md
│   ├── data_dictionary_en.md
│   ├── dicionario_dados.md
│   └── diretrizes_analise.md
├── examples/
│   ├── data.csv
│   ├── figures/
│   └── output/
├── output/
├── tests/
├── main.py
├── plots.py
├── LICENSE
├── requirements.txt
└── README.md

Generated files are written to output/. Figures are written to figures/ when plots.py is executed.

Getting Started

Create a virtual environment and install the dependencies:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

If you need a local synthetic dataset for testing, generate it first:

python3 data/data_generator.py

Run the data-processing pipeline:

python3 main.py

Or provide custom paths:

python3 main.py --input data/data.csv --output-dir output

Generate figures after the pipeline output exists:

python3 plots.py

Run the test suite:

python3 -m unittest discover

Example Data

The repository includes a complete synthetic dataset at examples/data.csv, generated with data/data_generator.py. It contains 1,300 records and is intended for testing, documentation, and demos without exposing real medical records.

To regenerate the example dataset and outputs:

python3 data/data_generator.py --output examples/data.csv
python3 main.py --input examples/data.csv --output-dir examples/output
python3 plots.py --input-dir examples/output --figure-dir examples/figures

The generated example outputs are available in examples/output/, and the generated figures are available in examples/figures/.

Example Preview

The current example run contains 1,300 synthetic records, 1,300 eligible hospital deaths, and 0 exclusions. The synthetic generator currently produces hospital-sector death locations only, so no residential/home deaths are excluded in this demo.

The charts are intentionally kept in Brazilian Portuguese because the underlying study, field names, and clinical review context are in Portuguese from Brazil. The English captions below describe what each chart represents.

Eligibility Flow

Shows the raw dataset, excluded records, and final eligible analytical cohort.

Deaths by Age Group and Sex

Shows how eligible deaths are distributed by age group and sex as a heatmap.

Shows the same age-and-sex distribution as grouped bars.

Shows the age-and-sex distribution as mirrored bars for quick comparison between sex categories.

Chronic Diseases

Shows the most frequent pre-existing chronic diseases in the eligible cohort.

Shows the relative participation of chronic disease categories.

Shows how chronic diseases are distributed across recorded death diagnoses.

Death Diagnoses

Shows the frequency of recorded diagnoses or causes associated with death.

Shows death diagnoses as a Pareto chart, combining counts and cumulative percentage.

Shows death diagnoses as a dot plot ranking.

Hospital Factors

Shows the hospital unit or sector where death occurred.

Shows the distribution of hospital length of stay until death.

Shows selected care-quality indicators as percentages.

Main Outputs

The processing script creates:

• output/patients_all.csv: all records with eligibility flags.
• output/patients.csv: eligible cohort used for analysis.
• output/exclusions.csv: excluded records and exclusion reasons.
• output/metadata.csv: extracted variable metadata.
• output/frequencies.csv: descriptive categorical frequencies.
• output/numeric_summary.csv: numeric summaries.
• output/report.md: preliminary descriptive report.
• output/analysis_focus.md: report aligned with the project analysis guidelines.
• output/eligibility.md: eligibility summary.
• output/quality_control.md: basic data-quality checks.
• output/planilha_coleta_dados.xlsx: formatted workbook for data review and collection.

Analysis Scope

The project is organized around four descriptive questions:

• Which age groups and sex categories are most frequent among eligible deaths?
• Which chronic conditions appear most often in the cohort?
• What are the main diagnoses or causes associated with death records?
• How do hospital factors such as length of stay, care indicators, clinical evolution, and death location describe the eligible cohort?

Data Privacy

Real medical-record data should not be committed to this repository. Keep identifiable or sensitive files outside version control, and use synthetic or anonymized data for development, demos, and public examples.

Documentation

Supporting documentation is available in:

• docs/dicionario_dados.md: variable dictionary and scoring notes.
• docs/diretrizes_analise.md: analysis guidelines and methodological notes.
• docs/data_dictionary_en.md: English version of the data dictionary.
• docs/analysis_guidelines_en.md: English version of the analysis guidelines.

License

This project is licensed under the MIT License. See LICENSE for details.