# dforgeek/reg_tree_from_scratch architecture

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

- Interactive diagram: https://gitdiagram.com/dforgeek/reg_tree_from_scratch
- Repository: https://github.com/dforgeek/reg_tree_from_scratch

## Overview

#### Purpose and entry points
This is an educational, pure-Python regression decision-tree implementation. Its primary API is `MyDecisionTreeRegressor.fit()` / `.predict()` in `decision_tree.py`. The executable workflow is the visualization CLI in `visualize.py`, which loads tabular data, trains a tree, and exports a Graphviz image. A notebook demonstrates interactive use: `decision_tree_usage.ipynb`.

#### Model implementation
`decision_tree.py` contains the architecture’s core: the regression-tree class, recursive node construction, split selection, and prediction traversal. Training partitions feature rows until stopping rules such as maximum depth, minimum samples per split, or minimum information gain are reached. Leaf nodes produce regression predictions, typically derived from the target values in their partition.

Grounding:
- `decision_tree.py`
- `config.py`

#### Split evaluation and feature handling
The tree supports numeric and categorical features. Candidate splits are evaluated using regression impurity/variance reduction (information gain), allowing training to choose the feature and threshold/category split that most improves target homogeneity. This is the principal algorithmic boundary: pandas-like tabular inputs enter the estimator; internal recursive node/split representations drive training and inference.

Grounding:
- `decision_tree.py`
- `utils.py`

#### Configuration boundary
Default hyperparameters and dataset-related settings are centralized in `config.py`; callers may also provide estimator arguments or visualization CLI flags. Configuration controls model complexity and search behavior, including depth, minimum split size, information-gain threshold, and categorical handling limits.

Grounding:
- `config.py`
- `decision_tree.py`
- `visualize.py`

#### Training and inference flow
1. A caller loads and cleans a CSV into feature matrix `X` and regression target `y`.
2. `MyDecisionTreeRegressor.fit(X, y)` recursively searches valid splits and builds the root-to-leaf tree.
3. `predict(X)` routes each row through stored split decisions to a leaf prediction.
4. Consumers can use predictions directly or render the learned structure.

The included sample dataset is hotel-price-oriented and is used as an example rather than a required runtime service.

Grounding:
- `example_data/hotel_data.csv`
- `decision_tree.py`
- `decision_tree_usage.ipynb`

#### Visualization pipeline
`visualize.py` is the operational entry point for inspection. It accepts dataset, output, and model-control arguments; trains the same decision-tree implementation; then translates the tree structure into Graphviz output for PNG/image generation. This separates model logic from presentation while exposing the tree’s learned split hierarchy.

Grounding:
- `visualize.py`
- `decision_tree.py`

#### Runtime and dependencies
The project runs in Python and relies on standard data-science dependencies declared in `requirements.txt`, notably for tabular loading/manipulation and visualization support. Graphviz is an external system dependency required for rendered tree output; no database, network API, hosted infrastructure, or web runtime is indicated.

Grounding:
- `requirements.txt`
- `visualize.py`

Main entry points: [`visualize.py`](https://github.com/dforgeek/reg_tree_from_scratch/blob/master/visualize.py) (Visualization CLI), [`decision_tree.py`](https://github.com/dforgeek/reg_tree_from_scratch/blob/master/decision_tree.py) (MyDecisionTreeRegressor), [`decision_tree_usage.ipynb`](https://github.com/dforgeek/reg_tree_from_scratch/blob/master/decision_tree_usage.ipynb) (Usage notebook), [`utils.py`](https://github.com/dforgeek/reg_tree_from_scratch/blob/master/utils.py) (Feature handling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_model["Tree model"]
  node_regressor_api["MyDecisionTreeRegressor<br/>regression estimator<br/>[decision_tree.py]"]
  node_training["Recursive tree builder<br/>training algorithm<br/>[decision_tree.py]"]
  node_split_search["Split selection<br/>split evaluator<br/>[decision_tree.py]"]
  node_feature_handling["Feature handling<br/>tabular utilities<br/>[utils.py]"]
  node_learned_tree{{"Learned tree<br/>node hierarchy<br/>[decision_tree.py]"}}
  node_prediction["Prediction traversal<br/>inference algorithm<br/>[decision_tree.py]"]
end

subgraph group_workflow["Usage and visualization"]
  node_sample_csv["Hotel sample CSV<br/>sample data<br/>[hotel_data.csv]"]
  node_notebook["Usage notebook<br/>interactive example"]
  node_visualize_cli["Visualization CLI<br/>Python CLI<br/>[visualize.py]"]
  node_cli_arguments["CLI arguments<br/>runtime settings<br/>[visualize.py]"]
  node_csv_loading["CSV loading and cleaning<br/>data preparation<br/>[visualize.py]"]
  node_graphviz_export["Graphviz image output<br/>rendered artifact<br/>[visualize.py]"]
end

node_tabular_input["Tabular X and y<br/>input"]
node_defaults["Default settings<br/>model configuration<br/>[config.py]"]
node_requirements["Python dependencies<br/>dependency manifest<br/>[requirements.txt]"]
node_graphviz["Graphviz<br/>external renderer"]

node_sample_csv -->|"input"| node_csv_loading
node_csv_loading -->|"prepares"| node_tabular_input
node_notebook -->|"provides"| node_tabular_input
node_notebook -->|"uses"| node_regressor_api
node_cli_arguments -->|"configures"| node_visualize_cli
node_visualize_cli -->|"loads"| node_csv_loading
node_visualize_cli -->|"trains"| node_regressor_api
node_tabular_input -->|"fit / predict input"| node_regressor_api
node_defaults -->|"defaults"| node_regressor_api
node_regressor_api -->|"fit"| node_training
node_training -->|"evaluates candidates"| node_split_search
node_feature_handling -->|"supports"| node_split_search
node_split_search -->|"selected splits"| node_learned_tree
node_training -->|"builds"| node_learned_tree
node_regressor_api -->|"predict"| node_prediction
node_learned_tree -->|"routes rows"| node_prediction
node_visualize_cli -->|"inspects"| node_learned_tree
node_learned_tree -->|"translated to graph"| node_graphviz_export
node_visualize_cli -->|"invokes"| node_graphviz
node_graphviz -->|"renders"| node_graphviz_export
node_requirements -.->|"runtime dependencies"| node_visualize_cli

click node_sample_csv "https://github.com/dforgeek/reg_tree_from_scratch/blob/master/example_data/hotel_data.csv"
click node_notebook "https://github.com/dforgeek/reg_tree_from_scratch/blob/master/decision_tree_usage.ipynb"
click node_visualize_cli "https://github.com/dforgeek/reg_tree_from_scratch/blob/master/visualize.py"
click node_cli_arguments "https://github.com/dforgeek/reg_tree_from_scratch/blob/master/visualize.py"
click node_csv_loading "https://github.com/dforgeek/reg_tree_from_scratch/blob/master/visualize.py"
click node_regressor_api "https://github.com/dforgeek/reg_tree_from_scratch/blob/master/decision_tree.py"
click node_training "https://github.com/dforgeek/reg_tree_from_scratch/blob/master/decision_tree.py"
click node_split_search "https://github.com/dforgeek/reg_tree_from_scratch/blob/master/decision_tree.py"
click node_feature_handling "https://github.com/dforgeek/reg_tree_from_scratch/blob/master/utils.py"
click node_learned_tree "https://github.com/dforgeek/reg_tree_from_scratch/blob/master/decision_tree.py"
click node_prediction "https://github.com/dforgeek/reg_tree_from_scratch/blob/master/decision_tree.py"
click node_defaults "https://github.com/dforgeek/reg_tree_from_scratch/blob/master/config.py"
click node_graphviz_export "https://github.com/dforgeek/reg_tree_from_scratch/blob/master/visualize.py"
click node_requirements "https://github.com/dforgeek/reg_tree_from_scratch/blob/master/requirements.txt"

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_regressor_api,node_training,node_split_search,node_feature_handling,node_learned_tree,node_prediction toneBlue
class node_sample_csv,node_notebook,node_visualize_cli,node_cli_arguments,node_csv_loading,node_graphviz_export toneAmber
class node_tabular_input,node_defaults,node_requirements,node_graphviz toneNeutral
```

## Components

### Tree model

Core regression-tree training and inference.

- [MyDecisionTreeRegressor](https://github.com/dforgeek/reg_tree_from_scratch/blob/master/decision_tree.py): regression estimator · Public fit and predict API. · `decision_tree.py`
- [Recursive tree builder](https://github.com/dforgeek/reg_tree_from_scratch/blob/master/decision_tree.py): training algorithm · Partitions rows until configured stopping rules are met. · `decision_tree.py`
- [Split selection](https://github.com/dforgeek/reg_tree_from_scratch/blob/master/decision_tree.py): split evaluator · Chooses numeric or categorical splits by variance reduction. · `decision_tree.py`
- [Feature handling](https://github.com/dforgeek/reg_tree_from_scratch/blob/master/utils.py): tabular utilities · Supports numeric and categorical feature evaluation. · `utils.py`
- [Learned tree](https://github.com/dforgeek/reg_tree_from_scratch/blob/master/decision_tree.py): node hierarchy · Stored root-to-leaf split structure and leaf predictions. · `decision_tree.py`
- [Prediction traversal](https://github.com/dforgeek/reg_tree_from_scratch/blob/master/decision_tree.py): inference algorithm · Routes each row to a leaf prediction. · `decision_tree.py`

### Usage and visualization

Interactive and CLI entry points.

- [Hotel sample CSV](https://github.com/dforgeek/reg_tree_from_scratch/blob/master/example_data/hotel_data.csv): sample data · Example hotel-price dataset. · `example_data/hotel_data.csv`
- [Usage notebook](https://github.com/dforgeek/reg_tree_from_scratch/blob/master/decision_tree_usage.ipynb): interactive example · Demonstrates estimator use. · `decision_tree_usage.ipynb`
- [Visualization CLI](https://github.com/dforgeek/reg_tree_from_scratch/blob/master/visualize.py): Python CLI · Loads data, trains a tree, and exports a visualization. · `visualize.py`
- [CLI arguments](https://github.com/dforgeek/reg_tree_from_scratch/blob/master/visualize.py): runtime settings · Dataset, output, and model-control options. · `visualize.py`
- [CSV loading and cleaning](https://github.com/dforgeek/reg_tree_from_scratch/blob/master/visualize.py): data preparation · Prepares features and regression targets. · `visualize.py`
- [Graphviz image output](https://github.com/dforgeek/reg_tree_from_scratch/blob/master/visualize.py): rendered artifact · PNG or other image of the learned split hierarchy. · `visualize.py`

### Other components

- **Tabular X and y**: input · Cleaned feature matrix and regression target.
- [Default settings](https://github.com/dforgeek/reg_tree_from_scratch/blob/master/config.py): model configuration · Centralizes depth, split, gain, and categorical limits. · `config.py`
- [Python dependencies](https://github.com/dforgeek/reg_tree_from_scratch/blob/master/requirements.txt): dependency manifest · Declares tabular and visualization dependencies. · `requirements.txt`
- **Graphviz**: external renderer · System dependency for rendered tree output.

## Connections

- Hotel sample CSV → CSV loading and cleaning: input
- CSV loading and cleaning → Tabular X and y: prepares
- Usage notebook → Tabular X and y: provides
- Usage notebook → MyDecisionTreeRegressor: uses
- CLI arguments → Visualization CLI: configures
- Visualization CLI → CSV loading and cleaning: loads
- Visualization CLI → MyDecisionTreeRegressor: trains
- Tabular X and y → MyDecisionTreeRegressor: fit / predict input
- Default settings → MyDecisionTreeRegressor: defaults
- MyDecisionTreeRegressor → Recursive tree builder: fit
- Recursive tree builder → Split selection: evaluates candidates
- Feature handling → Split selection: supports
- Split selection → Learned tree: selected splits
- Recursive tree builder → Learned tree: builds
- MyDecisionTreeRegressor → Prediction traversal: predict
- Learned tree → Prediction traversal: routes rows
- Visualization CLI → Learned tree: inspects
- Learned tree → Graphviz image output: translated to graph
- Visualization CLI → Graphviz: invokes
- Graphviz → Graphviz image output: renders
- Python dependencies → Visualization CLI: runtime dependencies