# oliviergarciadev/fanalysis architecture

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

- Interactive diagram: https://gitdiagram.com/oliviergarciadev/fanalysis
- Repository: https://github.com/oliviergarciadev/fanalysis

## Overview

##### Project type and purpose
- This is an open-source Python library (“fanalysis”) that implements three factorial analysis methods (Simple Correspondence Analysis, Multiple Correspondence Analysis, Principal Components Analysis).
- It exposes these methods both as standalone functions/classes and as transformers compatible with scikit-learn pipelines.
- The repository includes source code, a test suite (unittest comparing against R FactoMineR), tutorial notebooks, and a setup script for packaging.

##### File structure
- Top-level:
- setup.py (packaging/install)
- README.md (project overview)
- LICENSE, .gitignore
- doc/ (Jupyter/PDF tutorials for each analysis)
- fanalysis/ (the Python package)
- fanalysis/tests/ (unit tests and expected-output fixtures)
- Within fanalysis/:
- base.py: abstract base class FactorialAnalysis with common logic (fit, transform, fit_transform).
- ca.py, mca.py, pca.py: concrete subclasses implementing each analysis.
- __init__.py: package entry point.
- Tests are text fixtures plus test_*.py that load fixtures, run the algorithms, and compare results.

##### Extract architecture insights from README
- Dependencies: NumPy, Pandas, scikit-learn, Matplotlib.
- Dual usage: as descriptive analysis and as reduction step in ML pipelines.
- Installation via pip (setup.py).

##### Main components
a. User/Application Layer
– Client code or Jupyter notebooks that import fanalysis and call methods or plug into scikit-learn pipelines.
b. Core Library (fanalysis package)
– base.py: abstract class
– CA, MCA, PCA modules inheriting from base
– Utilities for eigen-decomposition, coordinate computations, contributions, cos2, labels
c. External Dependencies
– NumPy (arrays, linear algebra)
– Pandas (DataFrame input/output)
– scikit-learn (pipeline interface)
– Matplotlib (optional plotting)
d. Test Suite
– Test runner (unittest)
– Fixture data (expected outputs from R FactoMineR)
e. Documentation & Tutorials
– Jupyter notebooks and PDFs under doc/

##### Component interactions & data flow
- The User/Application invokes fanalysis.FactorialAnalysis subclasses via fit/transform APIs.
- fanalysis modules internally call NumPy for matrix operations, Pandas for data handling, and optionally Matplotlib for plotting.
- When used in scikit-learn pipelines, fanalysis objects are wrapped in Pipeline objects.
- The Test Suite executes fanalysis methods on fixture data, reads expected outputs, and asserts equality.
- setup.py bundles the package and declares external dependencies for pip installation.

##### Architectural patterns & design principles
- Template Method pattern: base.py defines the skeleton (fit, transform), subclasses supply specifics.
- Adapter pattern: fanalysis classes implement scikit-learn TransformerMixin and BaseEstimator, making them pluggable in ML workflows.
- Separation of concerns: computational logic vs. I/O (Pandas) vs. plotting (Matplotlib) vs. testing.

##### Final checklist
- [ ] Core library split into base + three analysis modules
- [ ] External dependencies labeled and connected
- [ ] User/client and test suite entry points shown
- [ ] Packaging/install layer indicated
- [ ] Notes on architectural patterns (Template Method, Adapter)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Packaging and Distribution Layer
    Packaging["setup.py / pip installation"]:::pack
    Packaging -->|"defines dependencies & packages"| CoreInit

    %% User/Application Layer
    subgraph "User / Client Code" 
        direction TB
        Notebooks["Jupyter Notebooks"]:::docs
        Client["Client Code (scripts)"]:::user
    end
    Notebooks -->|import fanalysis| CoreInit
    Client -->|import fanalysis| CoreInit

    %% Core Library
    subgraph "fanalysis (Core Library)"
        direction TB
        CoreInit["fanalysis/__init__.py"]:::internal
        Base["fanalysis/base.py\nFactorialAnalysis"]:::internal
        CA["fanalysis/ca.py\nCA"]:::internal
        MCA["fanalysis/mca.py\nMCA"]:::internal
        PCA["fanalysis/pca.py\nPCA"]:::internal
    end
    CoreInit --> Base
    Base --> CA
    Base --> MCA
    Base --> PCA

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        NumPy["NumPy"]:::external
        Pandas["Pandas"]:::external
        Sklearn["scikit-learn"]:::external
        Matplot["Matplotlib"]:::external
    end
    CA -->|uses| NumPy
    CA -->|uses| Pandas
    CA -->|optional| Matplot
    MCA -->|uses| NumPy
    MCA -->|uses| Pandas
    MCA -->|optional| Matplot
    PCA -->|uses| NumPy
    PCA -->|uses| Pandas
    PCA -->|optional| Matplot
    Sklearn -->|adapts via TransformerMixin| CA
    Sklearn -->|adapts via TransformerMixin| MCA
    Sklearn -->|adapts via TransformerMixin| PCA

    %% Test Suite
    subgraph "Test Suite" 
        direction TB
        TestRunner["unittest Runner"]:::test
        Fixtures["Fixture Data"]:::test
    end
    TestRunner -->|executes| Base
    TestRunner -->|executes| CA
    TestRunner -->|executes| MCA
    TestRunner -->|executes| PCA
    Fixtures -->|provides expected outputs| TestRunner

    %% Documentation & Tutorials
    subgraph "Documentation & Tutorials" 
        direction TB
        CA_IPYNB["doc/ca_tutorial.ipynb"]:::docs
        CA_PDF["doc/ca_tutorial.pdf"]:::docs
        MCA_IPYNB["doc/mca_tutorial.ipynb"]:::docs
        MCA_PDF["doc/mca_tutorial.pdf"]:::docs
        PCA_IPYNB["doc/pca_tutorial.ipynb"]:::docs
        PCA_PDF["doc/pca_tutorial.pdf"]:::docs
    end
    Notebooks -->|refer| CA_IPYNB
    Notebooks -->|refer| MCA_IPYNB
    Notebooks -->|refer| PCA_IPYNB

    %% Repository Metadata
    subgraph "Repository Metadata"
        direction TB
        README["README.md"]:::meta
        License["LICENSE"]:::meta
        Gitignore[".gitignore"]:::meta
    end
    Packaging -->|includes| README
    Packaging -->|includes| License
    Packaging -->|includes| Gitignore

    %% Click events
    click Packaging "https://github.com/oliviergarciadev/fanalysis/blob/master/setup.py"
    click CA_IPYNB "https://github.com/oliviergarciadev/fanalysis/blob/master/doc/ca_tutorial.ipynb"
    click CA_PDF "https://github.com/oliviergarciadev/fanalysis/blob/master/doc/ca_tutorial.pdf"
    click MCA_IPYNB "https://github.com/oliviergarciadev/fanalysis/blob/master/doc/mca_tutorial.ipynb"
    click MCA_PDF "https://github.com/oliviergarciadev/fanalysis/blob/master/doc/mca_tutorial.pdf"
    click PCA_IPYNB "https://github.com/oliviergarciadev/fanalysis/blob/master/doc/pca_tutorial.ipynb"
    click PCA_PDF "https://github.com/oliviergarciadev/fanalysis/blob/master/doc/pca_tutorial.pdf"
    click CoreInit "https://github.com/oliviergarciadev/fanalysis/blob/master/fanalysis/__init__.py"
    click Base "https://github.com/oliviergarciadev/fanalysis/blob/master/fanalysis/base.py"
    click CA "https://github.com/oliviergarciadev/fanalysis/blob/master/fanalysis/ca.py"
    click MCA "https://github.com/oliviergarciadev/fanalysis/blob/master/fanalysis/mca.py"
    click PCA "https://github.com/oliviergarciadev/fanalysis/blob/master/fanalysis/pca.py"
    click TestRunner "https://github.com/oliviergarciadev/fanalysis/blob/master/fanalysis/tests/test_base.py"
    click TestRunner "https://github.com/oliviergarciadev/fanalysis/blob/master/fanalysis/tests/test_ca.py"
    click TestRunner "https://github.com/oliviergarciadev/fanalysis/blob/master/fanalysis/tests/test_mca.py"
    click TestRunner "https://github.com/oliviergarciadev/fanalysis/blob/master/fanalysis/tests/test_pca.py"
    click Fixtures "https://github.com/oliviergarciadev/fanalysis/tree/master/fanalysis/tests"
    click README "https://github.com/oliviergarciadev/fanalysis/blob/master/README.md"
    click License "https://github.com/oliviergarciadev/fanalysis/tree/master/LICENSE"
    click Gitignore "https://github.com/oliviergarciadev/fanalysis/blob/master/.gitignore"

    %% Styling
    classDef internal fill:#cfe2f3,stroke:#085394,color:#000;
    classDef external fill:#d9ead3,stroke:#38761d,color:#000;
    classDef user fill:#fff2cc,stroke:#bf9000,color:#000;
    classDef docs fill:#ead1dc,stroke:#c27ba0,color:#000;
    classDef test fill:#f9cb9c,stroke:#b45f06,color:#000;
    classDef pack fill:#d0d0d0,stroke:#666666,color:#000;
    classDef meta fill:#eeeeee,stroke:#999999,color:#000;
```
