# mouse234/ml architecture

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

- Interactive diagram: https://gitdiagram.com/mouse234/ml
- Repository: https://github.com/mouse234/ml

## Overview

##### Project Type and Purpose
This is a standalone machine‐learning pipeline for time‐series forecasting of gold prices based on astronomical (planetary degree) and temporal features. It is neither a web app nor microservice landscape but a structured ETL + training + prediction workflow with both batch preprocessing and interactive analysis components.

##### High‐Level Components
a. Data Ingestion & Storage
- Raw CSV data (Gold_Inr.csv)
- Persisted pickles: X_train.pkl, X_test.pkl, y_train.pkl, y_test.pkl, test_dates.pkl
b. Preprocessing & Feature Engineering
- Script: prepare_data.py
- Operations: temporal feature extraction, cyclical encoding, planetary aspect computation, chronological train/test split, StandardScaler fit/transform
- Persisted artifacts: scaler.pkl, feature_columns.json, X_train_scaled.pkl, X_test_scaled.pkl
c. Model Training & Evaluation
- Script: train_models.py
- Models: Linear Regression, Random Forest, XGBoost
- Validation: TimeSeriesSplit via GridSearchCV
- Outputs: best_gold_price_model.joblib, all_models.joblib, model_results.json, timeseries_cv_results.json
d. Prediction Interface
- Script: predict_gold_price.py
- Loads: best model, scaler, feature spec
- Input: command‐line args for date + deg0–deg12
- Output: formatted predicted price
e. Interactive Analysis
- Notebook: gold_price_analysis.ipynb
- Exploratory plots, feature importance, CV visualizations

##### Relationships & Data Flow
Raw CSV → prepare_data.py →
- temporal + aspect features → scale → pickle artifacts →
train_models.py consumes scaled train/test →
- hyperparameter tuning → final models + metrics JSON →
gold_price_analysis.ipynb reads artifacts + results for EDA →
predict_gold_price.py reads scaler + best model + feature spec for on‐demand inference

##### Architectural Patterns & Principles
- ETL Pipeline: clear separation of ingestion, transformation, persistence
- Batch Training: scripts driven by chronological, reproducible splits
- Modular Artifacts: pickle and JSON files describe intermediate state for reuse
- Single Responsibility: each script does one job (prepare, train, predict)
- Time‐Series Aware: no random splits; use TimeSeriesSplit

##### Essential Elements
- Clear component names matching file names
- Annotations for key design principles (e.g., “chronological split,” “GridSearchCV,” “StandardScaler”)

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Data Ingestion & Storage"
    RawCSV[(Gold_Inr.csv)]:::data
    Pick1[(X_train.pkl)]:::data
    Pick2[(X_test.pkl)]:::data
    Pick3[(y_train.pkl)]:::data
    Pick4[(y_test.pkl)]:::data
    Pick5[(test_dates.pkl)]:::data
  end

  subgraph "Preprocessing & Feature Engineering"
    Prep["prepare_data.py"]:::process
    Scaler[(scaler.pkl)]:::data
    Features[(feature_columns.json)]:::data
    Xts[(X_train_scaled.pkl)]:::data
    Xte[(X_test_scaled.pkl)]:::data
  end

  subgraph "Model Training & Evaluation"
    Train["train_models.py"]:::process
    MR[(model_results.json)]:::model
    CV[(timeseries_cv_results.json)]:::model
  end

  subgraph "Prediction Interface"
    Predict["predict_gold_price.py"]:::process
    out((Result)):::model
  end

  subgraph "Interactive Analysis"
    Notebook[/gold_price_analysis.ipynb/]:::notebook
  end

  RawCSV -->|raw data| Prep
  Prep -->|scaler.pkl| Scaler
  Prep -->|feature_columns.json| Features
  Prep -->|X_train_scaled.pkl| Xts
  Prep -->|X_test_scaled.pkl| Xte

  Xts -->|train data| Train
  Xte -->|test data| Train
  Train -->|model_results.json| MR
  Train -->|timeseries_cv_results.json| CV

  Scaler --> Predict
  Features --> Predict
  MR --> Predict
  Predict -->|predicted price| out

  Pick1 -.-> Notebook
  Pick2 -.-> Notebook
  Pick3 -.-> Notebook
  Pick4 -.-> Notebook
  Pick5 -.-> Notebook
  MR    -.-> Notebook
  CV    -.-> Notebook

  subgraph Legend
    direction LR
    data[(Data Store)]:::data
    process["Processing Script"]:::process
    model("Model/Results"):::model
    notebook["Notebook"]:::notebook
  end

  click RawCSV "https://github.com/mouse234/ml/blob/main/Gold_Inr.csv"
  click Pick1 "https://github.com/mouse234/ml/blob/main/X_train.pkl"
  click Pick2 "https://github.com/mouse234/ml/blob/main/X_test.pkl"
  click Pick3 "https://github.com/mouse234/ml/blob/main/y_train.pkl"
  click Pick4 "https://github.com/mouse234/ml/blob/main/y_test.pkl"
  click Pick5 "https://github.com/mouse234/ml/blob/main/test_dates.pkl"
  click Prep "https://github.com/mouse234/ml/blob/main/prepare_data.py"
  click Scaler "https://github.com/mouse234/ml/blob/main/scaler.pkl"
  click Features "https://github.com/mouse234/ml/blob/main/feature_columns.json"
  click Xts "https://github.com/mouse234/ml/blob/main/X_train_scaled.pkl"
  click Xte "https://github.com/mouse234/ml/blob/main/X_test_scaled.pkl"
  click Train "https://github.com/mouse234/ml/blob/main/train_models.py"
  click MR "https://github.com/mouse234/ml/blob/main/model_results.json"
  click CV "https://github.com/mouse234/ml/blob/main/timeseries_cv_results.json"
  click Predict "https://github.com/mouse234/ml/blob/main/predict_gold_price.py"
  click Notebook "https://github.com/mouse234/ml/blob/main/gold_price_analysis.ipynb"

  classDef data fill:#aed6f1,stroke:#2980b9,color:#1b4f72;
  classDef process fill:#abebc6,stroke:#27ae60,color:#145a32;
  classDef model fill:#f9e79f,stroke:#d4ac0d,color:#7d6608;
  classDef notebook fill:#ebbcec,stroke:#8e44ad,color:#4a235a;
```
