# dmey/synthia architecture

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

- Interactive diagram: https://gitdiagram.com/dmey/synthia
- Repository: https://github.com/dmey/synthia

## Overview

1. **Project shape**
   - Synthia is a Python library, not an application service.
   - The main architectural boundary is a small public API over statistical model implementations for synthetic data generation.

2. **Core workflow**
   - The central flow is: **fit on labeled data → parameterize marginals/latent structure → generate new samples → return data in the original xarray-shaped structure**.
   - The library is designed around `xarray` datasets/data arrays, so labeled dimensions and coordinates are preserved through generation.

3. **Main public subsystems**
   - `synthia.generators`: high-level orchestration for synthetic sample generation.
   - `synthia.copulas`: dependency models for multivariate continuous/discrete/categorical data.
   - `synthia.parameterizers`: marginal/distribution fitting and transformation logic.
   - `synthia.transform` and `synthia.distribution`: supporting statistical transformation and distribution abstractions.
   - `synthia.util`: shared helpers and dataset-loading utilities used by examples/tests.

4. **Generator layer**
   - `generators/copula.py` and `generators/fpca.py` are the user-facing model builders.
   - The generator layer coordinates fitting and sampling, hiding the lower-level details of copula fitting, quantile transforms, and inverse transforms.
   - This is the main entry point for users, e.g. “fit then generate”.

5. **Copula modeling subsystem**
   - `copulas/copula.py` defines the copula abstraction.
   - `copulas/gaussian.py` provides a pure-Python Gaussian copula implementation.
   - `copulas/independence.py` represents a baseline no-dependence model.
   - `copulas/vine.py` supports vine copulas and is the one that depends on the external `pyvinecopulib`/`vinecopulib` stack for efficient C++-backed computation.

6. **Marginal parameterization subsystem**
   - `parameterizers/parameterizer.py` appears to define the common parameterizer interface.
   - `parameterizers/distribution.py`, `quantile.py`, and `const.py` cover different ways of modeling marginals:
     - fitted distributions,
     - empirical/quantile-based transforms,
     - constant-valued variables.
   - This layer is what maps real-valued or categorical observations into the latent space used by copulas and back again.

7. **Functional PCA path**
   - The fPCA generator is a separate modeling path alongside copulas.
   - It is intended for structured continuous data such as profiles or functional observations, where variation is represented through principal components rather than dependence copulas.
   - In architecture terms, it is an alternate generation pipeline sharing the same high-level “fit/generate” user contract.

8. **Data transformation boundary**
   - `transform.py` likely holds the conversions between original observations, normalized latent variables, and reconstructed samples.
   - Conceptually this is the bridge between marginal models and multivariate dependency models: data is standardized/transformed before fitting the latent structure and then inverted after sampling.

9. **External dependencies that matter**
   - `xarray` is a key architectural dependency because the library preserves labeled dimension/coordinate metadata.
   - `pyvinecopulib` is the main non-Python runtime dependency and enables vine copula support via C++ bindings.
   - The rest of the stack is largely pure Python, which keeps the Gaussian copula and fPCA paths portable.

10. **Documentation and examples**
   - `docs/` is substantial and includes notebooks for univariate, multivariate Gaussian, vine, discrete/categorical, and fPCA examples.
   - This suggests the repo’s usage model is example-driven and that the docs are part of the primary interface for understanding data flow and supported variable types.

11. **Testing and CI**
   - `tests/` contains unit/benchmark coverage for generators and utilities, with `pytest.ini` configuring the test run.
   - `.github/workflows/ci.yml` shows standard CI automation, so architecture changes are expected to be validated through automated tests rather than runtime deployment.

12. **Packaging and distribution**
   - `setup.py`, environment files, and release metadata indicate a standard Python package distribution workflow.
   - The repository is versioned and publishable to PyPI, with citation metadata and a paper included, reinforcing that this is a scientific software package with reproducible-model semantics rather than a service-oriented system.

Main entry points: [`synthia/generators/copula.py`](https://github.com/dmey/synthia/blob/master/synthia/generators/copula.py) (Copula gen), [`synthia/transform.py`](https://github.com/dmey/synthia/blob/master/synthia/transform.py) (Transform), [`synthia/copulas/copula.py`](https://github.com/dmey/synthia/blob/master/synthia/copulas/copula.py) (Copula base), [`synthia/parameterizers/parameterizer.py`](https://github.com/dmey/synthia/blob/master/synthia/parameterizers/parameterizer.py) (Parameterizer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_pkg["Library core"]
  node_n_init["Public API<br/>package entrypoint<br/>[__init__.py]"]
  node_n_gen_copula["Copula gen<br/>generator builder<br/>[copula.py]"]
  node_n_gen_fpca["fPCA gen<br/>generator builder<br/>[fpca.py]"]
  node_n_copula_base["Copula base<br/>dependency abstraction<br/>[copula.py]"]
  node_n_copula_gauss["Gaussian<br/>pure-python copula<br/>[gaussian.py]"]
  node_n_copula_ind["Independence<br/>baseline copula<br/>[independence.py]"]
  node_n_copula_vine["Vine copula<br/>pyvinecopulib backend<br/>[vine.py]"]
  node_n_param_base["Parameterizer<br/>marginal interface<br/>[parameterizer.py]"]
  node_n_param_dist["Dist fit<br/>distribution parameterizer<br/>[distribution.py]"]
  node_n_param_quant["Quantile fit<br/>empirical parameterizer<br/>[quantile.py]"]
  node_n_param_const["Constant<br/>degenerate parameterizer<br/>[const.py]"]
  node_n_transform["Transform<br/>data bridge<br/>[transform.py]"]
  node_n_distribution["Distribution<br/>statistical abstractions<br/>[distribution.py]"]
  node_n_util["Utilities<br/>shared helpers<br/>[util.py]"]
end

subgraph group_grp_docs["Docs and examples"]
  node_n_docs["Docs<br/>documentation<br/>[index.rst]"]
  node_n_examples["Examples<br/>notebook gallery<br/>[examples.rst]"]
end

subgraph group_grp_quality["Quality checks"]
  node_n_tests["Tests<br/>pytest suite<br/>[test_generators.py]"]
  node_n_ci["CI<br/>workflow<br/>[ci.yml]"]
end

subgraph group_grp_release["Packaging"]
  node_n_packaging["Packaging<br/>[setup.py]"]
  node_n_paper["Paper<br/>scholarly metadata<br/>[paper.md]"]
end

node_n_init -->|"exports"| node_n_gen_copula
node_n_init -->|"exports"| node_n_gen_fpca
node_n_gen_copula -->|"fits"| node_n_param_base
node_n_gen_copula -->|"uses"| node_n_transform
node_n_gen_copula -->|"samples"| node_n_copula_base
node_n_gen_fpca -->|"uses"| node_n_transform
node_n_gen_fpca -->|"uses"| node_n_util
node_n_copula_base -->|"implements"| node_n_copula_gauss
node_n_copula_base -->|"implements"| node_n_copula_ind
node_n_copula_base -->|"implements"| node_n_copula_vine
node_n_copula_vine -.->|"depends on"| node_n_distribution
node_n_param_base -->|"implements"| node_n_param_dist
node_n_param_base -->|"implements"| node_n_param_quant
node_n_param_base -->|"implements"| node_n_param_const
node_n_param_dist -->|"uses"| node_n_distribution
node_n_param_quant -->|"uses"| node_n_transform
node_n_param_const -->|"uses"| node_n_transform
node_n_transform -->|"uses"| node_n_distribution
node_n_docs -->|"includes"| node_n_examples
node_n_tests -->|"covers"| node_n_util
node_n_tests -->|"covers"| node_n_gen_copula
node_n_ci -->|"runs"| node_n_tests
node_n_packaging -->|"packages"| node_n_init
node_n_paper -.->|"supports"| node_n_docs

click node_n_init "https://github.com/dmey/synthia/blob/master/synthia/__init__.py"
click node_n_gen_copula "https://github.com/dmey/synthia/blob/master/synthia/generators/copula.py"
click node_n_gen_fpca "https://github.com/dmey/synthia/blob/master/synthia/generators/fpca.py"
click node_n_copula_base "https://github.com/dmey/synthia/blob/master/synthia/copulas/copula.py"
click node_n_copula_gauss "https://github.com/dmey/synthia/blob/master/synthia/copulas/gaussian.py"
click node_n_copula_ind "https://github.com/dmey/synthia/blob/master/synthia/copulas/independence.py"
click node_n_copula_vine "https://github.com/dmey/synthia/blob/master/synthia/copulas/vine.py"
click node_n_param_base "https://github.com/dmey/synthia/blob/master/synthia/parameterizers/parameterizer.py"
click node_n_param_dist "https://github.com/dmey/synthia/blob/master/synthia/parameterizers/distribution.py"
click node_n_param_quant "https://github.com/dmey/synthia/blob/master/synthia/parameterizers/quantile.py"
click node_n_param_const "https://github.com/dmey/synthia/blob/master/synthia/parameterizers/const.py"
click node_n_transform "https://github.com/dmey/synthia/blob/master/synthia/transform.py"
click node_n_distribution "https://github.com/dmey/synthia/blob/master/synthia/distribution.py"
click node_n_util "https://github.com/dmey/synthia/blob/master/synthia/util.py"
click node_n_docs "https://github.com/dmey/synthia/blob/master/docs/index.rst"
click node_n_examples "https://github.com/dmey/synthia/blob/master/docs/examples.rst"
click node_n_tests "https://github.com/dmey/synthia/blob/master/tests/test_generators.py"
click node_n_ci "https://github.com/dmey/synthia/blob/master/.github/workflows/ci.yml"
click node_n_packaging "https://github.com/dmey/synthia/blob/master/setup.py"
click node_n_paper "https://github.com/dmey/synthia/blob/master/paper/paper.md"

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_n_init,node_n_gen_copula,node_n_gen_fpca,node_n_copula_base,node_n_copula_gauss,node_n_copula_ind,node_n_copula_vine,node_n_param_base,node_n_param_dist,node_n_param_quant,node_n_param_const,node_n_transform,node_n_distribution,node_n_util toneBlue
class node_n_docs,node_n_examples toneAmber
class node_n_tests,node_n_ci toneMint
class node_n_packaging,node_n_paper toneRose
```

## Components

### Library core

Main Python package implementing generators, copulas, parameterization, and transforms.

- [Public API](https://github.com/dmey/synthia/blob/master/synthia/__init__.py): package entrypoint · Top-level package exports and user-facing surface. · `synthia/__init__.py`
- [Copula gen](https://github.com/dmey/synthia/blob/master/synthia/generators/copula.py): generator builder · High-level fit/generate workflow built around copula models. · `synthia/generators/copula.py`
- [fPCA gen](https://github.com/dmey/synthia/blob/master/synthia/generators/fpca.py): generator builder · Alternative fit/generate pipeline for structured continuous data. · `synthia/generators/fpca.py`
- [Copula base](https://github.com/dmey/synthia/blob/master/synthia/copulas/copula.py): dependency abstraction · Shared copula interface and common behavior. · `synthia/copulas/copula.py`
- [Gaussian](https://github.com/dmey/synthia/blob/master/synthia/copulas/gaussian.py): pure-python copula · Gaussian copula implementation for multivariate dependence. · `synthia/copulas/gaussian.py`
- [Independence](https://github.com/dmey/synthia/blob/master/synthia/copulas/independence.py): baseline copula · No-dependence baseline model. · `synthia/copulas/independence.py`
- [Vine copula](https://github.com/dmey/synthia/blob/master/synthia/copulas/vine.py): pyvinecopulib backend · Vine copula implementation backed by external C++ bindings. · `synthia/copulas/vine.py`
- [Parameterizer](https://github.com/dmey/synthia/blob/master/synthia/parameterizers/parameterizer.py): marginal interface · Common interface for fitting and transforming marginals. · `synthia/parameterizers/parameterizer.py`
- [Dist fit](https://github.com/dmey/synthia/blob/master/synthia/parameterizers/distribution.py): distribution parameterizer · Fits marginal distributions and transforms values. · `synthia/parameterizers/distribution.py`
- [Quantile fit](https://github.com/dmey/synthia/blob/master/synthia/parameterizers/quantile.py): empirical parameterizer · Quantile-based empirical marginal transform. · `synthia/parameterizers/quantile.py`
- [Constant](https://github.com/dmey/synthia/blob/master/synthia/parameterizers/const.py): degenerate parameterizer · Handles constant-valued variables. · `synthia/parameterizers/const.py`
- [Transform](https://github.com/dmey/synthia/blob/master/synthia/transform.py): data bridge · Converts between observed data, latent variables, and reconstructed samples. · `synthia/transform.py`
- [Distribution](https://github.com/dmey/synthia/blob/master/synthia/distribution.py): statistical abstractions · Shared distribution helpers and abstractions. · `synthia/distribution.py`
- [Utilities](https://github.com/dmey/synthia/blob/master/synthia/util.py): shared helpers · Common helpers and dataset-loading utilities. · `synthia/util.py`

### Docs and examples

User-facing documentation and notebook examples that demonstrate supported workflows.

- [Docs](https://github.com/dmey/synthia/blob/master/docs/index.rst): documentation · Narrative documentation and API guides. · `docs/index.rst`
- [Examples](https://github.com/dmey/synthia/blob/master/docs/examples.rst): notebook gallery · Notebook examples covering univariate, multivariate, categorical, vine, and fPCA usage. · `docs/examples.rst`

### Quality checks

Tests and CI used to validate the package.

- [Tests](https://github.com/dmey/synthia/blob/master/tests/test_generators.py): pytest suite · Unit and benchmark coverage for generators and utilities. · `tests/test_generators.py`
- [CI](https://github.com/dmey/synthia/blob/master/.github/workflows/ci.yml): workflow · Automated validation workflow. · `.github/workflows/ci.yml`

### Packaging

Distribution and scientific publication metadata.

- [Packaging](https://github.com/dmey/synthia/blob/master/setup.py): python packaging · Build and distribution configuration for the library. · `setup.py`
- [Paper](https://github.com/dmey/synthia/blob/master/paper/paper.md): scholarly metadata · Citation and publication materials for the scientific package. · `paper/paper.md`

## Connections

- Public API → Copula gen: exports · Public API exposes the main generator path.
- Public API → fPCA gen: exports · Public API exposes the alternative generator path.
- Copula gen → Parameterizer: fits · Generator coordinates marginal parameterization.
- Copula gen → Transform: uses · Generator bridges observed data and latent space.
- Copula gen → Copula base: samples · Generator relies on copula abstractions for dependence modeling.
- fPCA gen → Transform: uses · fPCA pipeline preserves the labeled data shape through transforms.
- fPCA gen → Utilities: uses · fPCA path shares helper utilities.
- Copula base → Gaussian: implements · Gaussian copula is one concrete implementation.
- Copula base → Independence: implements · Independence model is another concrete implementation.
- Copula base → Vine copula: implements · Vine copula extends the same abstraction.
- Vine copula → Distribution: depends on · Vine path interacts with statistical support code.
- Parameterizer → Dist fit: implements · Distribution-based parameterizer is a concrete strategy.
- Parameterizer → Quantile fit: implements · Quantile-based parameterizer is a concrete strategy.
- Parameterizer → Constant: implements · Constant-valued parameterizer is a concrete strategy.
- Dist fit → Distribution: uses · Distribution parameterization shares distribution abstractions.
- Quantile fit → Transform: uses · Quantile transforms are part of the latent-space bridge.
- Constant → Transform: uses · Constant handling participates in transform/inverse-transform flow.
- Transform → Distribution: uses · Transform layer relies on distribution abstractions.
- Docs → Examples: includes · Docs organize the notebook gallery and narrative examples.
- Tests → Utilities: covers · Utility behavior is exercised by tests.
- Tests → Copula gen: covers · Generator workflows are validated by tests.
- CI → Tests: runs · CI executes the test suite.
- Packaging → Public API: packages · Build configuration packages the library entrypoint and modules.
- Paper → Docs: supports · Publication materials reinforce the documentation and scientific framing.