# wangyuhsin/random-forest architecture

> Architecture diagram of the GitHub repository wangyuhsin/random-forest, 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/wangyuhsin/random-forest
- Repository: https://github.com/wangyuhsin/random-forest

## Overview

##### Project type and purpose
- This is a Python algorithm‐library project implementing Random Forest for regression and classification.
- It exposes two main classes (`RandomForestRegressor621`, `RandomForestClassifier621`) in `rf.py` and uses decision‐tree utilities in `dtree.py`.

##### File structure
- Top‐level:
- LICENSE, README.md – meta and documentation
- dtree.py – core decision‐tree building blocks (nodes, split functions, tree classes)
- rf.py – orchestrates ensemble logic (bootstrapping, feature sampling, tree collection, prediction aggregation)
- No frontend/backend or database layers – it’s a standalone library.

##### README insights
- Describes:
- Bootstrapping → sampling data subsets
- Random feature selection at each split
- Separate classes for regression vs. classification trees
- OOB error estimation
- Highlights comparable accuracy to scikit‐learn, so integration/use‐case is “drop‐in” for ML workflows.

##### Core components & interactions (to show
a. User/Application Layer
- “Client Code” that imports and calls `RandomForestRegressor621` or `RandomForestClassifier621`
b. Random Forest Module (`rf.py`)
- Bootstrapping Engine (samples data)
- Tree Factory (spawns multiple tree instances)
- Aggregator (averages or votes predictions)
- OOB‐Error Estimator
c. Decision Tree Utility Module (`dtree.py`)
- `DecisionNode` / `LeafNode` classes
- `gini()` or variance reduction functions
- `find_best_split()`
- Specialized tree classes: `DecisionTree621`, `RegressionTree621`, `ClassifierTree621`
d. External Dependencies (implicit)
- Python standard lib, NumPy (assumed for array ops), scikit‐learn (for comparison examples)

Relationships & data flow:
1. Client → instantiates RF class → calls `.fit(X, y)`
2. RF.fit → Bootstrapping Engine produces N data subsets → for each subset:
→ calls Tree Factory → uses dtree utilities to build a tree
3. RF holds an array of tree objects
4. Client → calls `.predict(X_new)` → RF Aggregator loops over trees → collects tree predictions → averages or majority‐votes → returns final vector
5. OOB module inside RF.fit uses unused samples per tree → calls Tree.predict on those → aggregates for OOB error estimate

##### Architectural patterns & principles
- Ensemble (Composite) pattern: treats the forest as a composite of many trees
- Separation of concerns: `rf.py` orchestrates ensemble logic; `dtree.py` encapsulates tree‐building algorithms
- Factory approach: RF class constructs multiple tree instances with varying data/feature subsets
- Dependency Injection: RF passes parameters (max_features, min_samples_leaf) down to tree constructors

##### Essential elements
- Clear component labels (module names, class names, engines)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User layer
    subgraph "User Code / Client"
        Client["Client Code"] 
    end

    %% Data artifacts
    D1((Dataset X, y)):::data
    D2((Bootstrapped Subsets)):::data
    D3((OOB Samples)):::data
    D4((Predictions)):::data

    %% Random Forest Module
    subgraph "Random Forest Module" 
        direction TB
        RFReg["RandomForestRegressor621"]:::module
        RFCls["RandomForestClassifier621"]:::module
        BootstrappingEngine["Bootstrapping Engine"]:::component
        TreeFactory["Tree Factory"]:::component
        Aggregator["Aggregator"]:::component
        OOBEstimator["OOB-Error Estimator"]:::component
    end

    %% Decision Tree Utilities
    subgraph "Decision Tree Utilities"
        direction TB
        DecisionNode["DecisionNode / LeafNode"]:::component
        SplitFunctions["gini() / variance_reduction()"]:::component
        BestSplit["find_best_split()"]:::component
        DecisionTree["DecisionTree621"]:::component
        RegrTree["RegressionTree621"]:::component
        ClsTree["ClassifierTree621"]:::component
    end

    %% External Comparison
    subgraph "External / Comparison"
        sklearn["scikit-learn models"]:::external
    end

    %% Connections: Data flow and invocations
    Client -->|".fit()"| D1
    D1 -->|"sample()"| BootstrappingEngine
    BootstrappingEngine --> D2
    D2 -->|"build_tree()"| TreeFactory
    TreeFactory --> DecisionTree
    TreeFactory --> RegrTree
    TreeFactory --> ClsTree
    DecisionTree --> DecisionNode
    DecisionNode --> SplitFunctions
    SplitFunctions --> BestSplit
    TreeFactory -->|"trees[]"| RFReg
    TreeFactory --> RFCls
    RFReg --> Aggregator
    RFCls --> Aggregator
    Aggregator --> D4
    D4 -->|".predict()"| Client

    BootstrappingEngine -->|unused samples| D3
    D3 --> OOBEstimator
    OOBEstimator --> DecisionTree
    OOBEstimator --> RegrTree
    OOBEstimator --> ClsTree

    Client ---|comparison| sklearn

    %% Click Events
    click RFReg "https://github.com/wangyuhsin/random-forest/blob/main/rf.py"
    click RFCls "https://github.com/wangyuhsin/random-forest/blob/main/rf.py"
    click BootstrappingEngine "https://github.com/wangyuhsin/random-forest/blob/main/rf.py"
    click TreeFactory "https://github.com/wangyuhsin/random-forest/blob/main/rf.py"
    click Aggregator "https://github.com/wangyuhsin/random-forest/blob/main/rf.py"
    click OOBEstimator "https://github.com/wangyuhsin/random-forest/blob/main/rf.py"
    click DecisionNode "https://github.com/wangyuhsin/random-forest/blob/main/dtree.py"
    click SplitFunctions "https://github.com/wangyuhsin/random-forest/blob/main/dtree.py"
    click BestSplit "https://github.com/wangyuhsin/random-forest/blob/main/dtree.py"
    click DecisionTree "https://github.com/wangyuhsin/random-forest/blob/main/dtree.py"
    click RegrTree "https://github.com/wangyuhsin/random-forest/blob/main/dtree.py"
    click ClsTree "https://github.com/wangyuhsin/random-forest/blob/main/dtree.py"

    %% Styles
    classDef module fill:#D0E6FF,stroke:#0366D6,stroke-width:2px
    classDef component fill:#E6FFEA,stroke:#0F9D58,stroke-width:2px
    classDef data fill:#FFE6CC,stroke:#D9730D,stroke-width:2px
    classDef external fill:#F2F2F2,stroke:#999999,stroke-dasharray: 5 5,stroke-width:2px
```
