API Reference

Module Overview

graph TB
    subgraph "Public API"
        A[lib.rs] --> B[data::KoiDataset]
        A --> C[features::FeatureEngineer]
        A --> D[two_stage_model::TwoStageClassifier]
        A --> E[evaluation::ModelEvaluator]
        A --> F[report::generate_report]
        A --> G[logger::Logger]
    end

    subgraph "Internal Modules"
        H[decision_tree.rs]
        I[model.rs]
    end

    D --> H
    D --> I

data::KoiDataset

Loads and manages the KOI dataset from CSV using Polars.

graph LR
    A[CSV File] -->|Polars| B[KoiDataset]
    B --> C[n_samples]
    B --> D[n_features]
    B --> E[features Array2]
    B --> F[labels Array1]
    B --> G[class_distribution]

Methods

Usage

#![allow(unused)]
fn main() {
use astrophage::data::KoiDataset;

let dataset = KoiDataset::load("data/koi_dataset.csv")?;
println!("Loaded {} samples with {} features", 
    dataset.n_samples(), 
    dataset.n_features()
);

let dist = dataset.class_distribution();
for (class, count) in &dist {
    println!("{}: {}", class, count);
}
}

features::FeatureEngineer

Transforms raw data into model-ready features through imputation, standardization, and derived feature computation.

graph LR
    A[KoiDataset] -->|process| B[FeatureEngineer]
    B --> C[Imputation]
    C --> D[Standardization]
    D --> E[Derived Features]
    E --> F[ProcessedDataset]
    F --> G[split]
    G --> H[Train Set]
    G --> I[Test Set]

Methods

ProcessedDataset Methods

Usage

#![allow(unused)]
fn main() {
use astrophage::features::FeatureEngineer;

let mut engineer = FeatureEngineer::new();
let processed = engineer.process(&dataset)?;

let (train, test) = processed.split(0.2, 42); // 80/20, seed=42
println!("Train: {}, Test: {}", train.n_samples(), test.n_samples());
}

two_stage_model::TwoStageClassifier

The main two-stage random forest classifier.

graph TB
    A[TwoStageClassifier] --> B[Stage 1 RF]
    A --> C[Stage 2 RF]
    B --> D[train Stage 1]
    C --> E[train Stage 2]
    D --> F[predict]
    E --> F
    F --> G[feature_importance]

Methods

Usage

#![allow(unused)]
fn main() {
use astrophage::two_stage_model::TwoStageClassifier;

let mut classifier = TwoStageClassifier::new();
classifier.train(&train)?;

// Predictions
let predictions = classifier.predict(test.features());

// Feature importance
for (name, score) in classifier.feature_importance().iter().take(10) {
    println!("{}: {:.4}", name, score);
}
}

evaluation::ModelEvaluator

Computes comprehensive classification metrics.

graph LR
    A[TwoStageClassifier] -->|+ Test Data| B[ModelEvaluator]
    B --> C[Accuracy]
    B --> D[Precision]
    B --> E[Recall]
    B --> F[F1-Score]
    B --> G[Per-Class Metrics]

Methods

Metrics Structure

#![allow(unused)]
fn main() {
pub struct Metrics {
    pub accuracy: f64,
    pub macro_f1: f64,
    pub weighted_f1: f64,
    pub per_class: HashMap<String, ClassMetrics>,
}

pub struct ClassMetrics {
    pub precision: f64,
    pub recall: f64,
    pub f1_score: f64,
}
}

Usage

#![allow(unused)]
fn main() {
use astrophage::evaluation::ModelEvaluator;

let evaluator = ModelEvaluator::new(&classifier, &test);
let metrics = evaluator.evaluate()?;

println!("Accuracy: {:.4f}", metrics.accuracy);
println!("Macro F1: {:.4f}", metrics.macro_f1);

for (class, m) in &metrics.per_class {
    println!("{}: P={:.4f} R={:.4f} F1={:.4f}", 
        class, m.precision, m.recall, m.f1_score);
}
}

report::generate_report

Generates the comprehensive JSON report.

graph LR
    A[Metrics] -->|+ Classifier| B[generate_report]
    B --> C[report.json]
    C --> D[Feature Importance]
    C --> E[Per-Class Metrics]
    C --> F[Astrophysical Insights]
    C --> G[Recommendations]

Function

#![allow(unused)]
fn main() {
pub fn generate_report(
    metrics: &Metrics, 
    classifier: &TwoStageClassifier
) -> Result<()>
}

Output: output/report.json

Report Structure

{
  "project_name": "Astrophage",
  "version": "0.2.0",
  "summary": { ... },
  "metrics": { ... },
  "feature_importance": [ ... ],
  "astrophysical_insights": [ ... ],
  "recommendations": [ ... ]
}

logger::Logger

Structured logging with tracing.

graph LR
    A[Logger] --> B[Console Output]
    A --> C[File Output]
    B --> D[Colored Logs]
    C --> E[app.log]

Methods

Usage

#![allow(unused)]
fn main() {
use astrophage::logger::Logger;

Logger::init(true).await?;
tracing::info!("Training started...");
}

Internal: decision_tree::DecisionTree

Custom decision tree implementation using Gini impurity.

graph TD
    A[DecisionTree] --> B[fit]
    B --> C[find_best_split]
    C --> D[compute_gini]
    D --> E[split_node]
    E --> F[recurse_left]
    E --> G[recurse_right]
    F --> H[Leaf or Split]
    G --> H

Key Parameters

Internal: model::RandomForest

Ensemble of decision trees with bootstrap sampling.

graph TD
    A[RandomForest] --> B[n_estimators: 100]
    B --> C[Tree 1]
    B --> D[Tree 2]
    B --> E[...]
    B --> F[Tree N]
    C --> G[Majority Vote]
    D --> G
    F --> G
    G --> H[Final Prediction]

Key Parameters

Data Schema

Expected columns in koi_dataset.csv:

Orbital Parameters

Physical Parameters

Signal Quality

False Positive Flags

Stellar Parameters