# himoto/hillfit architecture

> Architecture diagram of the GitHub repository himoto/hillfit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/himoto/hillfit
- Repository: https://github.com/himoto/hillfit

## Overview

##### Project type and purpose
- This is an open-source Python library (`hillfit`) for fitting experimental or modeled data to the Hill equation.
- It provides a single core class (`HillFit`) with methods for performing nonlinear regression (via SciPy), generating/visualizing figures (via Matplotlib), and exporting results (to the file system).

##### File structure
- Top-level folders
- `.github/workflows`: CI pipelines for tests, security scans, PyPI publish
- `examples/`: sample data & Jupyter notebook demonstrating usage
- `hillfit/`: the library source (init + `fitting.py`)
- `test/`: unit tests for the fitting logic
- Configuration & packaging
- `pyproject.toml`, `setup.py`, `requirements.txt`
- Pre-commit and style configs
- No “frontend” or “backend” directories – this is purely a library/tool.

##### README for additional insights
- Describes `HillFit` class API, parameters for calling `fitting()` and `export()`
- Mentions core dependencies: `scipy.optimize.curve_fit`, `matplotlib`, `numpy`
- Shows example usage in code and Jupyter notebook

##### Components
a. Main components
- User environment (Python REPL, IDE, Jupyter)
- hillfit library
- HillFit class
- fitting() sub-module
- export() sub-module
- External libraries
- NumPy (data arrays)
- SciPy (curve_fit)
- Matplotlib (plotting)
- File System (examples/raw_data.csv, export folder)
- CI/CD pipeline (GitHub Actions → PyPI)
b. Relationships & data flows
- User → imports hillfit → constructs HillFit(x_data,y_data)
- HillFit.fitting()
- reads x_data/y_data
- calls SciPy curve_fit
- produces fitted parameters & x_fit/y_fit
- calls Matplotlib to generate figs
- Results → accessible as object attrs (hf.top, hf.nH, hf.equation, hf.figure)
- HillFit.export() → writes files (CSV, equation.txt, image) to disk
- Developer push → GitHub → triggers workflows (tests, codeql, pre-commit) → PyPI publish
c. Architectural patterns and design principles
- Single-responsibility: `HillFit` handles data + fitting + export
- Dependency inversion: underlying numeric libraries are swappable via `curve_fit_kws`
- Modular separation: core logic (`hillfit/`) vs. examples vs. tests vs. CI
d. Technologies, frameworks, libraries
- Python packaging: setuptools/pyproject
- SciPy, NumPy, Matplotlib
- GitHub Actions, pre-commit, isort, black

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors
    User["User (REPL / IDE / Jupyter)"]:::external
    Developer["Developer"]:::external

    %% Hillfit Library
    subgraph "Hillfit Library" 
        HF_init["__init__.py"]:::internal
        HF_class["HillFit Class\n(fitting(), export())"]:::internal
    end

    %% External Libraries
    Numpy["NumPy"]:::third
    SciPy["SciPy\n(curve_fit)"]:::third
    Matplotlib["Matplotlib\n(plotting)"]:::third

    %% Examples
    subgraph "Examples" 
        ExamplesNB["modeling_data.ipynb"]:::external
        ExamplesDir["examples/"]:::external
        ProcessedCSV["processed_data.csv"]:::external
        ExReg1["Hillfit-reg/"]:::external
        ExReg2["hillfit-reg-linear/"]:::external
        ExReg3["hillfit-reg-logarithmic/"]:::external
    end

    %% Tests
    Test["test_fitting.py"]:::internal

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        GPActions["GitHub Actions"]:::external
        CodeQL["CodeQL Scan"]:::external
        PyPI["PyPI Publish"]:::external
    end

    %% File System
    FS["File System\n(export folder)"]:::external

    %% Packaging & Config
    Config["pyproject.toml\nsetup.py\nrequirements.txt\n.pre-commit-config.yaml\n.gitignore"]:::internal
    Docs["LICENSE\nREADME.rst"]:::internal

    %% Relationships
    User -->|"imports hillfit"| HF_init
    HF_init -->|"exposes HillFit"| HF_class
    HF_class -->|"x_data, y_data arrays"| Numpy
    HF_class -->|"curve_fit call"| SciPy
    SciPy -->|"fitted params"| HF_class
    HF_class -->|"plot call"| Matplotlib
    Matplotlib -->|"figure output"| HF_class
    HF_class -->|"export() writes CSV, eqn, image"| FS

    User -->|"runs notebook"| ExamplesNB
    ExamplesNB -->|"reads sample data"| ExamplesDir
    ExamplesNB -->|"generates processed CSV"| ProcessedCSV
    ExamplesNB -->|"outputs in dirs"| ExReg1
    ExamplesNB -->|"outputs in dirs"| ExReg2
    ExamplesNB -->|"outputs in dirs"| ExReg3

    Developer -->|"push code"| GPActions
    GPActions -->|"run tests"| Test
    GPActions -->|"security scan"| CodeQL
    GPActions -->|"publish package"| PyPI

    HF_class -->|"dependencies swap via curve_fit_kws"| SciPy

    %% Click Events
    click HF_init "https://github.com/himoto/hillfit/blob/master/hillfit/__init__.py"
    click HF_class "https://github.com/himoto/hillfit/blob/master/hillfit/fitting.py"
    click ExamplesNB "https://github.com/himoto/hillfit/blob/master/examples/modeling_data.ipynb"
    click ExamplesDir "https://github.com/himoto/hillfit/tree/master/examples/"
    click ExReg1 "https://github.com/himoto/hillfit/tree/master/examples/Hillfit-reg/"
    click ExReg2 "https://github.com/himoto/hillfit/tree/master/examples/hillfit-reg-linear/"
    click ExReg3 "https://github.com/himoto/hillfit/tree/master/examples/hillfit-reg-logarithmic/"
    click ProcessedCSV "https://github.com/himoto/hillfit/blob/master/examples/processed_data.csv"
    click Test "https://github.com/himoto/hillfit/blob/master/test/test_fitting.py"
    click GPActions "https://github.com/himoto/hillfit/tree/master/.github/workflows/"
    click CodeQL "https://github.com/himoto/hillfit/blob/master/.github/workflows/codeql.yml"
    click Test "https://github.com/himoto/hillfit/blob/master/.github/workflows/unit_test-action.yaml"
    click PyPI "https://github.com/himoto/hillfit/blob/master/.github/workflows/pypi-publish.yml"
    click Config "https://github.com/himoto/hillfit/blob/master/pyproject.toml"
    click Config "https://github.com/himoto/hillfit/blob/master/setup.py"
    click Config "https://github.com/himoto/hillfit/blob/master/requirements.txt"
    click Config "https://github.com/himoto/hillfit/blob/master/.pre-commit-config.yaml"
    click Config "https://github.com/himoto/hillfit/blob/master/.gitignore"
    click Docs "https://github.com/himoto/hillfit/tree/master/LICENSE"
    click Docs "https://github.com/himoto/hillfit/blob/master/README.rst"

    %% Styles
    classDef internal fill:#D0E8FF,stroke:#0366d6
    classDef third fill:#D0FFD6,stroke:#22863a
    classDef external fill:#FFE0B2,stroke:#d15704
```
