README.md

---
language: en
license: mit
library_name: thrml
tags:
- mortality-prediction
- actuarial-science
- probabilistic-modeling
- thermal-computing
- energy-based-models
- life-expectancy
- death-probability
- uncertainty-quantification
pipeline_tag: tabular-classification
---

# Thermal-Enhanced Morbid AI Model v0.1.1

## Model Description

Initial THRML integration with basic probabilistic mortality modeling capabilities. Includes uncertainty quantification and demographic factor interactions.

This model integrates THRML (Thermodynamic HypergRaphical Model Library) with Morbid AI's mortality prediction capabilities, providing probabilistic predictions with uncertainty quantification.

## Model Architecture

**Type**: thermal_energy_based_model
**Framework**: THRML + JAX
**Version**: 0.1.1

### Thermal Features

- Probabilistic graphical models for mortality factors
- Block Gibbs sampling with demographic blocking
- Energy-based life expectancy prediction
- Confidence intervals for all predictions
- Risk factor analysis and contribution scoring

## Performance Metrics

- **baseline_accuracy**: 0.8500
- **uncertainty_coverage**: 0.9500
- **demographic_factors**: 4.0000
- **sampling_efficiency**: 0.9200

## Usage

```python
from thermal.models.life_expectancy import LifeExpectancyEBM
from thermal.graph.mortality_graph import MortalityRecord

# Load mortality data
mortality_data = [...]  # List of MortalityRecord objects

# Initialize thermal model
model = LifeExpectancyEBM(mortality_data)

# Make prediction with uncertainty quantification
prediction = model.predict_life_expectancy(
    age=45,
    country="USA", 
    sex=1,  # 1=male, 2=female, 3=both
    n_samples=1000,
    confidence_level=0.95
)

print(f"Life Expectancy: {prediction.mean_life_expectancy:.1f} years")
print(f"95% CI: {prediction.confidence_interval}")
print(f"Uncertainty: {prediction.uncertainty:.2f}")
```

## Model Configuration

### THRML Parameters

**sampling**:
  - default_samples: 1000
  - burn_in: 200
  - thinning: 2
  - blocking_strategy: demographic
**model**:
  - energy_based: True
  - uncertainty_quantification: True
  - demographic_interactions: True
**performance**:
  - gpu_acceleration: True
  - jax_backend: True
  - memory_efficient: True

### Sampling Configuration

- **Block Gibbs Sampling**: Two-color and demographic blocking strategies
- **Default Samples**: 1000 MCMC samples
- **Burn-in**: 200 steps
- **Thinning**: Every 2nd sample

## Training Data

The model is trained on mortality data including:
- **Countries**: Global mortality statistics from major countries
- **Age Range**: 0-100+ years
- **Time Period**: 2010-2025
- **Demographic Factors**: Age, sex, country, year

## Limitations

- Model performance depends on availability of demographic-specific training data
- Uncertainty estimates are calibrated on historical data and may not capture unprecedented events
- Requires THRML and JAX dependencies for optimal performance

## Version History

### v0.1.1 - 2025-10-29

- Initial THRML integration framework
- MortalityGraphBuilder for demographic interactions
- LifeExpectancyEBM with uncertainty quantification
- Block Gibbs sampling implementation
- Basic API integration structure

## Citation

```
@software{thermal_morbid_ai_0_1_1,
  title={Thermal-Enhanced Morbid AI Model},
  version={0.1.1},
  year={2025},
  url={https://huggingface.co/MorbidCorp/thermal-mortality-model}
}
```

## License

MIT License - see LICENSE file for details.

## Contact

For questions about this model, please open an issue in the [Morbid AI repository](https://github.com/AlphaTONCapital/morbid-ai).