README.md

---
title: Actuarial Model Point Generator
emoji: 🏗️
colorFrom: green
colorTo: red
sdk: gradio
sdk_version: 5.31.0
app_file: app.py
pinned: false
license: mit
short_description: Generate synthetic actuarial model points
tags:
- actuarial
- insurance
- model-points
- synthetic-data
- data-generation
- gradio
- dashboard
- excel
---

# 🏗️ Actuarial Model Point Generator

A flexible Gradio app to generate fully customized **synthetic seriatim model points** for use in actuarial testing, clustering, or analytics. This tool now also provides immediate data insights through interactive summaries and visualizations.

[![Open in Spaces](https://huggingface.co/datasets/huggingface/badges/raw/main/open-in-hf-spaces-sm.svg)](https://huggingface.co/spaces/alidenewade/actuarial-model-point-generator)

---

## 🌟 What’s New

This version enhances data generation with **complete UI control** and adds **interactive data analysis features**:

- 👥 Number of policies (100 to 50,000)
- 🎲 Random seed for reproducibility
- 👶 Age range (min/max)
- 💵 Sum assured range
- 📆 Multiple selectable policy terms (5–30 years)
- 🧑 Include or exclude sex (M/F)
- 📦 Choose between fixed or variable policy count
- 📊 **In-depth Data Insights**:
    - Descriptive statistics for key numerical fields.
    - Distribution plot for 'Sum Assured' with a fitted normal curve.
    - Frequency tables for categorical data like 'Sex' and 'Policy Term'.
    - All summaries presented in an easy-to-use Tabbed interface below the main data table.

---

## 🧮 Output Columns

Each generated row represents a policy and includes the following columns:

- `policy_id`: A unique identifier for each policy, starting from 1.
- `age_at_entry`: Issue age.
- `sex`: "M", "F", or "U" (unspecified).
- `policy_term`: Chosen from selected terms.
- `policy_count`: Fixed (1) or random (1–100).
- `sum_assured`: Uniformly distributed between min/max.
- `duration_mth`: In-force duration, capped by policy term.

---

## 📊 Data Analysis & Insights

Beyond data generation, the app now provides immediate analytical feedback on the generated dataset through dedicated tabs:

-   **Numerical Summary Tab**: Get a quick overview of the numerical columns (`age_at_entry`, `sum_assured`, `duration_mth`, `policy_count`) with key descriptive statistics like mean, standard deviation, min/max values, and quartiles.
-   **Distribution Plot Tab**: Visualize the distribution of the `sum_assured` column. A histogram shows the actual generated data's distribution (which is uniform based on inputs), and a normal bell curve is fitted and overlaid for illustrative comparison, helping to understand the data's spread and central tendency.
-   **Categorical Summary Tab**: Understand the composition of your synthetic portfolio with frequency counts and percentages for `sex` and `policy_term` distributions.

---

## ✅ How to Use

1.  Adjust your generation parameters using the filters on the left panel.
2.  Click the **“Generate Model Points”** button.
3.  Preview the generated data in the main table.
4.  Explore the interactive summaries (descriptive statistics, distribution plots, categorical breakdowns) in the tabs located below the main data table.
5.  Click the **“Download Excel”** button to save the generated data table.

---

## 🧠 Use Cases

- Cluster-based model point selection and analysis.
- Stress testing actuarial models and validating assumptions.
- Developing and testing new insurance products or features.
- Scenario planning for different product mixes or demographic profiles.
- Educational tool for teaching actuarial concepts and data analysis.
- Rapidly creating datasets for model validation or machine learning tasks in an insurance context.

---

## 📦 File Export

The download button exports the generated data table to an Excel file (`.xlsx`). The **`policy_id`** is included as the first column, and the DataFrame index is omitted from the file.
Warnings will be shown if input parameters are invalid (e.g., minimum age ≥ maximum age).

---

## 🛠️ Local Installation

```bash
# Clone the repo
git clone [https://github.com/alidenewade/actuarial-model-point-generator.git](https://github.com/alidenewade/actuarial-model-point-generator.git)
cd actuarial-model-point-generator

# Install dependencies
pip install -r requirements.txt
```

## Run the app
python app.py

## 🙌 Acknowledgements
Huge thanks to the Lifelib community for their open-source contributions to life actuarial modeling in Python.
This project draws inspiration from their work on model point clustering and stochastic modeling tools.

Check them out at: https://github.com/lifelib-dev/lifelib

## 📄 License
This project is released under the MIT License.

Created with ❤️ by @alidenewade for the actuarial analytics community.