ASTRAL User Guide & Practical API Manual

01 Installation

ASTRAL is a pure-NumPy tabular learning library with zero mandatory external C++ or deep learning compiler dependencies.

# Install official package from PyPI
pip install astral-model

# Or install with optional extras (Torch acceleration, Scikit-Learn benchmarking)
pip install "astral-model[all]"

# Editable installation from local source repository
pip install -e .

02 5-Minute Quickstart

ASTRAL follows the familiar Scikit-Learn estimator pattern (fit, predict, predict_proba, score):

from astral import AstralModel, AstralScaler, astral_train_test_split
from sklearn.datasets import load_breast_cancer

# 1. Load data
X, y = load_breast_cancer(return_X_y=True)

# 2. Train/Test split with stratification
X_train, X_test, y_train, y_test = astral_train_test_split(
    X, y, test_size=0.2, random_state=42, stratify=y
)

# 3. Fit scaler & model
scaler = AstralScaler()
X_train_s = scaler.fit_transform(X_train)
X_test_s = scaler.transform(X_test)

model = AstralModel(ridge="auto", random_state=42)
model.fit(X_train_s, y_train)

# 4. Predict & evaluate
y_pred = model.predict(X_test_s)
metrics = model.score(X_test_s, y_test)
print(f"Test Accuracy: {metrics['accuracy']:.4f}, Macro F1: {metrics['f1_macro']:.4f}")

03 Constructor Parameters Reference

Detailed breakdown of all parameters accepted by AstralModel(...):

04 Methods & API Reference

05 Classification with Conformal Prediction Sets

from astral import AstralModel, astral_train_test_split
import numpy as np

# Train model
model = AstralModel(task="classification", ridge="auto", random_state=42)
model.fit(X_train, y_train)

# Conformal prediction sets with 90% guaranteed coverage (alpha=0.1)
pred_sets = model.predict_set(X_test, alpha=0.1)

# Inspect sample predictions
for i in range(5):
    probs = model.predict_proba(X_test[i:i+1])[0]
    print(f"Sample {i}: Pred={model.predict(X_test[i:i+1])[0]}, Set={pred_sets[i]}, Probs={np.round(probs, 3)}")

06 Regression & Uncertainty Intervals

model = AstralModel(task="regression", ridge="auto", random_state=42)
model.fit(X_train, y_train)

# Predict with calibrated conformal interval
y_pred, y_lower, y_upper = model.predict_with_uncertainty(X_test, alpha=0.05) # 95% coverage

# Calculate empirical coverage
coverage = np.mean((y_test >= y_lower) & (y_test <= y_upper))
print(f"Empirical Coverage: {coverage * 100:.2f}% (Target: 95%)")
print(f"Average Interval Width: {np.mean(y_upper - y_lower):.2f}")

07 Model Explainability & Invariance Inspection

# 1. Inspect global basis importances and causal invariance
for item in model.get_feature_importance()[:8]:
    status = "[INVARIANT]" if item["is_stable"] else "[UNSTABLE]"
    print(f"{status:<12} {item['name']:<30} Importance: {item['importance']:.4f}")

# 2. Local instance explanation
explanation = model.explain(X_test[0], top_k=3)
print("\nLocal Instance Prediction Breakdown:")
for contribution in explanation["contributions"]:
    print(f"  {contribution['basis_name']}: contribution = {contribution['value']:+.4f}")

08 Empirical Benchmark Results

Empirical performance across three benchmark datasets compared to 10 mainstream algorithms:

09 Frequently Asked Questions (FAQ)