# sadeghkarimpouli/family_based_features architecture

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

- Interactive diagram: https://gitdiagram.com/sadeghkarimpouli/family_based_features
- Repository: https://github.com/sadeghkarimpouli/family_based_features

## Overview

This is a research workflow for extracting seismicity features from earthquake catalogs and categorizing event families to study preparatory behavior. The principal path is catalog input → moving-window feature extraction → feature outputs and plots; the documented follow-on path builds families, summarizes them, and clusters them. The three case-study notebooks represent applied analyses. Source excerpts show feature calculation and plotting calls, but do not show how the family utilities are orchestrated, so that connection is marked unverified.

Main entry points: [`Event_based_Catalog_Features.py`](https://github.com/sadeghkarimpouli/family_based_features/blob/main/Event_based_Catalog_Features.py) (Feature workflow), [`util/Create_families.py`](https://github.com/sadeghkarimpouli/family_based_features/blob/main/util/Create_families.py) (Family construction), [`util/Event_based_Features_functions.py`](https://github.com/sadeghkarimpouli/family_based_features/blob/main/util/Event_based_Features_functions.py) (Windowed features), [`Extracted_features`](https://github.com/sadeghkarimpouli/family_based_features/tree/main/Extracted_features) (Feature tables)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Catalog inputs"]
  node_catalogs[("Earthquake catalogs")]
end

subgraph group_extraction["Feature extraction"]
  node_runner["Feature workflow"]
  node_windows["Windowed features"]
  node_kernels["Feature calculations"]
  node_featuredata["Feature tables"]
end

subgraph group_categorization["Family categorization"]
  node_familybuilder["Family construction<br/>[Create_families.py]"]
  node_familyfeatures["Family descriptors"]
  node_familylabels["Family categories"]
end

subgraph group_presentation["Analysis outputs"]
  node_plotter["Feature plots<br/>[Plot_features.py]"]
  node_amatrice["Amatrice analysis"]
  node_laquila["L'Aquila analysis"]
  node_kahramanmaras["Kahramanmaraş analysis"]
end

node_researcher(("Earthquake analyst"))

node_researcher -->|"runs"| node_runner
node_catalogs -->|"loads"| node_runner
node_runner -->|"computes"| node_windows
node_windows -->|"uses"| node_kernels
node_runner -->|"plots"| node_plotter
node_runner -->|"writes"| node_featuredata
node_researcher -.->|"categorizes"| node_familybuilder
node_featuredata -.->|"informs"| node_familybuilder
node_familybuilder -.->|"summarizes"| node_familyfeatures
node_familyfeatures -->|"clusters"| node_familylabels
node_researcher -->|"analyzes"| node_amatrice
node_researcher -->|"analyzes"| node_laquila
node_researcher -->|"analyzes"| node_kahramanmaras

click node_catalogs "https://github.com/sadeghkarimpouli/family_based_features/tree/main/Data"
click node_runner "https://github.com/sadeghkarimpouli/family_based_features/blob/main/Event_based_Catalog_Features.py"
click node_windows "https://github.com/sadeghkarimpouli/family_based_features/blob/main/util/Event_based_Features_functions.py"
click node_kernels "https://github.com/sadeghkarimpouli/family_based_features/blob/main/util/Feature_functions.py"
click node_featuredata "https://github.com/sadeghkarimpouli/family_based_features/tree/main/Extracted_features"
click node_plotter "https://github.com/sadeghkarimpouli/family_based_features/blob/main/util/Plot_features.py"
click node_familybuilder "https://github.com/sadeghkarimpouli/family_based_features/blob/main/util/Create_families.py"
click node_familyfeatures "https://github.com/sadeghkarimpouli/family_based_features/blob/main/util/Cluster_families.py"
click node_familylabels "https://github.com/sadeghkarimpouli/family_based_features/blob/main/util/Cluster_families.py"
click node_amatrice "https://github.com/sadeghkarimpouli/family_based_features/blob/main/Amatrice_Family_clustering.ipynb"
click node_laquila "https://github.com/sadeghkarimpouli/family_based_features/blob/main/LAquila_Family_clustering.ipynb"
click node_kahramanmaras "https://github.com/sadeghkarimpouli/family_based_features/blob/main/Kahramanmaras_Family_clustering.ipynb"

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_catalogs toneBlue
class node_runner,node_windows,node_kernels,node_featuredata toneAmber
class node_familybuilder,node_familyfeatures,node_familylabels toneMint
class node_plotter,node_amatrice,node_laquila,node_kahramanmaras toneRose
class node_researcher toneIndigo
```

## Components

### Catalog inputs

- [Earthquake catalogs](https://github.com/sadeghkarimpouli/family_based_features/tree/main/Data): `Data`

### Feature extraction

- [Feature workflow](https://github.com/sadeghkarimpouli/family_based_features/blob/main/Event_based_Catalog_Features.py): `Event_based_Catalog_Features.py`
- [Windowed features](https://github.com/sadeghkarimpouli/family_based_features/blob/main/util/Event_based_Features_functions.py): `util/Event_based_Features_functions.py`
- [Feature calculations](https://github.com/sadeghkarimpouli/family_based_features/blob/main/util/Feature_functions.py): `util/Feature_functions.py`
- [Feature tables](https://github.com/sadeghkarimpouli/family_based_features/tree/main/Extracted_features): `Extracted_features`

### Family categorization

- [Family construction](https://github.com/sadeghkarimpouli/family_based_features/blob/main/util/Create_families.py): `util/Create_families.py`
- [Family descriptors](https://github.com/sadeghkarimpouli/family_based_features/blob/main/util/Cluster_families.py): `util/Cluster_families.py`
- [Family categories](https://github.com/sadeghkarimpouli/family_based_features/blob/main/util/Cluster_families.py): `util/Cluster_families.py`

### Analysis outputs

- [Feature plots](https://github.com/sadeghkarimpouli/family_based_features/blob/main/util/Plot_features.py): `util/Plot_features.py`
- [Amatrice analysis](https://github.com/sadeghkarimpouli/family_based_features/blob/main/Amatrice_Family_clustering.ipynb): `Amatrice_Family_clustering.ipynb`
- [L'Aquila analysis](https://github.com/sadeghkarimpouli/family_based_features/blob/main/LAquila_Family_clustering.ipynb): `LAquila_Family_clustering.ipynb`
- [Kahramanmaraş analysis](https://github.com/sadeghkarimpouli/family_based_features/blob/main/Kahramanmaras_Family_clustering.ipynb): `Kahramanmaras_Family_clustering.ipynb`

### Other components

- **Earthquake analyst**

## Connections

- Earthquake analyst → Feature workflow: runs (evidence: `Event_based_Catalog_Features.py`)
- Earthquake catalogs → Feature workflow: loads (evidence: `Event_based_Catalog_Features.py`)
- Feature workflow → Windowed features: computes (evidence: `Event_based_Catalog_Features.py`)
- Windowed features → Feature calculations: uses (evidence: `util/Event_based_Features_functions.py`)
- Feature workflow → Feature plots: plots (evidence: `Event_based_Catalog_Features.py`)
- Feature workflow → Feature tables: writes (evidence: `Event_based_Catalog_Features.py`)
- Earthquake analyst → Family construction: categorizes (evidence: `README.md`)
- Feature tables → Family construction: informs
- Family construction → Family descriptors: summarizes
- Family descriptors → Family categories: clusters (evidence: `util/Cluster_families.py`)
- Earthquake analyst → Amatrice analysis: analyzes (evidence: `README.md`)
- Earthquake analyst → L'Aquila analysis: analyzes (evidence: `README.md`)
- Earthquake analyst → Kahramanmaraş analysis: analyzes (evidence: `README.md`)