# n-ys-kk/pcmf architecture

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

- Interactive diagram: https://gitdiagram.com/n-ys-kk/pcmf
- Repository: https://github.com/n-ys-kk/pcmf

## Overview

##### Main Components
- Data Input:
– Represent the relational input matrices (e.g., matrix X for patient-disease and matrix Y for patient attributes).
- Core Algorithm Module (PCMF Engine):
– This includes the main class or function defined in Positive_CMF.py.
– Internal processes where the factor matrices (U, V^T, Z^T) are generated.
- Preprocessing / Transformation:
– Include the use of the softplus function to convert the raw factor matrices into positive values.
- Link Function Application:
– Show that after the softplus step, the module applies a link function (which could be sigmoid, linear, or log depending on the data range) to produce the predicted matrices (X′ and Y′).
- Training / Optimization Loop:
– Capture the iterative training process (using backpropagation and a suitable optimizer such as Adam) with configurable parameters (learning rate, number of optimization steps, etc.).
- Output:
– Clearly indicate the predicted matrices as outcomes and the extracted feature representations that can be used for subsequent analysis.

##### Relationships and Data Flow
- Data Flow:
– Inside the core module, show how the data flows first to the factorization block (which computes U, V, and Z) and then through a transformation block (applying the softplus function).
– From the transformed matrices, show two parallel flows where each is processed by a different link function (f₁ for the product of U′ and V′ to predict X′, and f₂ for the product of U′ and Z′ to predict Y′).
- Feedback Loop during Training:
– Indicate that the optimization loop adjusts the factor matrices by comparing predictions with the actual relational matrices over multiple iterations (train method).

##### Architectural Patterns and Design Principles
- Modular Design:
– The code is separated in a way that the core functionality is encapsulated under the src/PCMF directory. Each module has a clear responsibility (e.g., setting up the factorization, applying transformations, training).
- Reusability and Extensibility:
- Clear Separation of Concerns:

##### Relevant Technologies and Frameworks
- Python Package Structure:
– The presence of pyproject.toml indicates a modern packaging approach.
- Numerical / Machine Learning Libraries:
– Although not explicitly listed, hint at the dependency on libraries (e.g., NumPy, possibly TensorFlow or PyTorch if backpropagation is implemented using such frameworks) for optimization and numerical computations.
- Jupyter Notebooks for Demonstration:
– Optionally include a note that the example notebook in the examples folder is intended to guide the end user in applying the package.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Data Input
    InputData("Input Matrices (X, Y)"):::input

    %% Core Algorithm Module - Factorization Engine
    CoreAlgorithm("Core Algorithm Module (PCMF Engine)"):::process

    %% Preprocessing / Transformation
    Transformation("Softplus Transformation"):::process

    %% Link Function Application for two predicted outputs
    LinkFunctionX("Link Function f₁ (predict X')"):::process
    LinkFunctionY("Link Function f₂ (predict Y')"):::process

    %% Output component
    Output("Predicted Matrices (X', Y')"):::output

    %% Training / Optimization Loop
    TrainingLoop("Training/Optimization Loop"):::optimizer

    %% Data Flow
    InputData -->|"feeds"| CoreAlgorithm
    CoreAlgorithm -->|"computes factors (U, V, Z)"| Transformation
    Transformation -->|"applies to factor matrices"| LinkFunctionX
    Transformation -->|"applies to factor matrices"| LinkFunctionY
    LinkFunctionX -->|"produces X'"| Output
    LinkFunctionY -->|"produces Y'"| Output

    %% Feedback Loop for Training
    Output -->|"error feedback"| TrainingLoop
    TrainingLoop -->|"updates parameters"| CoreAlgorithm

    %% Click Events
    click InputData "https://github.com/n-ys-kk/pcmf/blob/main/examples/How_to_use_PCMF.ipynb"
    click CoreAlgorithm "https://github.com/n-ys-kk/pcmf/blob/main/src/PCMF/Positive_CMF.py"
    click Transformation "https://github.com/n-ys-kk/pcmf/blob/main/src/PCMF/Positive_CMF.py"
    click LinkFunctionX "https://github.com/n-ys-kk/pcmf/blob/main/src/PCMF/Positive_CMF.py"
    click LinkFunctionY "https://github.com/n-ys-kk/pcmf/blob/main/src/PCMF/Positive_CMF.py"
    click TrainingLoop "https://github.com/n-ys-kk/pcmf/blob/main/src/PCMF/Positive_CMF.py"

    %% Style Definitions
    classDef input fill:#ADE792,stroke:#333,stroke-width:2px;
    classDef process fill:#A9D0F5,stroke:#333,stroke-width:2px;
    classDef output fill:#F5A9A9,stroke:#333,stroke-width:2px;
    classDef optimizer fill:#F3DCA7,stroke:#333,stroke-width:2px;
```
