eclipse-ml 0.1.0

Build, understand, and publish machine learning research.

Eclipse

Build, understand, and publish machine learning research.

Eclipse guides researchers through every important machine learning decision rather than hiding everything behind automation. Designed for Public Health, Medicine, Agriculture, Biology, Social Science, Economics, and other non computer science fields.

---

Installation Process

pip install eclipse-ml

For full functionality (XGBoost, LightGBM, CatBoost, SHAP, Excel export):

pip install "eclipse-ml[all]"

Note: Install the package as eclipse-ml, then import it in code as eclipse:

import eclipse as ec

---

How to Run

1. Profile your dataset

import pandas as pd
from eclipse.io.metadata import DataProfiler

# Load your data
df = pd.read_csv("your_data.csv")

# Profile it — Eclipse automatically detects feature types,
# missing values, duplicates, constant columns, class imbalance, etc.
profiler = DataProfiler(df, target="target_column_name")
profile = profiler.profile()

# View the summary
print(profile.summary())

2. Get recommendations from the wizard

from eclipse.dialogue.advisor import Wizard

# The wizard asks only relevant questions and explains every option
wizard = Wizard(profile, interactive=True)
session = wizard.conduct()

# In non-interactive mode (for scripts), it auto-selects defaults:
# wizard = Wizard(profile, interactive=False)
# session = wizard.conduct()

# See all decisions made
for decision in session.decisions:
    print(f"{decision.topic}: {decision.selected}")

3. Build a preprocessing pipeline

from eclipse.preprocessing.builder import PipelineBuilder

# Assemble a sklearn Pipeline from the wizard's decisions
builder = PipelineBuilder(profile.columns, session.config)
plan = builder.build()

# View the preprocessing plan with explanations
print(builder.explain())

# Split data
from eclipse.preprocessing.splitter import split_data

X = df.drop(columns=["target_column_name"])
y = df["target_column_name"]

split = split_data(X, y, session.config.get("split", "80/20 split with stratification"))

4. Train models

from eclipse.modeling.trainer import ModelTrainer

# Train one model
trainer = ModelTrainer("Random Forest", task_kind="classification")
result_rf = trainer.train(split.X_train, split.y_train)

# Train another for comparison
trainer_lr = ModelTrainer("Logistic Regression", task_kind="classification")
result_lr = trainer_lr.train(split.X_train, split.y_train)

# See model explanation
print(trainer.explain())

5. Evaluate and compare

from eclipse.evaluation.comparator import ModelComparator

# Compare all trained models
comparator = ModelComparator(
    [result_rf, result_lr],
    split.X_test,
    split.y_test,
    primary_metric="ROC AUC",
)
report = comparator.evaluate()

# View the comparison table
print(report.table)

# See which model is best and why
print(report.explanation)

6. Generate figures

from eclipse.reporting.figure import FigureBuilder

fb = FigureBuilder(dpi=300)

# Get predictions from the best model
from eclipse.modeling.trainer import ModelTrainer

best = report.best_model
trainer = ModelTrainer(best, "classification")
result = trainer.train(split.X_train, split.y_train)

y_pred = result.estimator.predict(split.X_test)
y_proba = result.estimator.predict_proba(split.X_test)[:, 1]

# ROC curve
fig_roc = fb.roc_curve(split.y_test, y_proba, model_name=best)
fb.save_figure(fig_roc, "roc_curve.pdf")

# Confusion matrix
fig_cm = fb.confusion_matrix(split.y_test, y_pred, normalize=True)
fb.save_figure(fig_cm, "confusion_matrix.pdf")

# Feature importance
fig_fi = fb.feature_importance(result.estimator, list(X.columns), top_n=10)
fb.save_figure(fig_fi, "feature_importance.pdf")

# Close figures to free memory
import matplotlib.pyplot as plt

plt.close("all")

7. Generate a full explanation

from eclipse.assistant import ResearchAssistant

assistant = ResearchAssistant(
    profile=profile,
    wizard_session=session,
    preprocessing_plan=plan,
    trained_models=[result_rf, result_lr],
    evaluation_report=report,
)

# Comprehensive analysis explanation
print(assistant.explain())

# Publication-ready Methods section (LaTeX)
print(assistant.methods(fmt="latex"))

# Critical review with strengths and recommendations
print(assistant.review())

8. Export a complete report

from eclipse.reporting.report import ReportGenerator

generator = ReportGenerator(assistant, figure_builder=fb)

# Excel report (multi-sheet workbook)
generator.to_excel("eclipse_report.xlsx")

# HTML report (standalone page with embedded plots)
generator.to_html("eclipse_report.html")

# PDF report (requires weasyprint: pip install weasyprint)
# generator.to_pdf("eclipse_report.pdf")

---

Full Pipeline (Copy-Paste Example)

import pandas as pd
from eclipse.io.metadata import DataProfiler
from eclipse.dialogue.advisor import Wizard
from eclipse.preprocessing.builder import PipelineBuilder
from eclipse.preprocessing.splitter import split_data
from eclipse.modeling.trainer import ModelTrainer
from eclipse.evaluation.comparator import ModelComparator
from eclipse.reporting.figure import FigureBuilder
from eclipse.reporting.report import ReportGenerator
from eclipse.assistant import ResearchAssistant
import matplotlib.pyplot as plt

# 1. Load & profile
df = pd.read_csv("your_data.csv")
profiler = DataProfiler(df, target="target_column")
profile = profiler.profile()
print(profile.summary())

# 2. Wizard
wizard = Wizard(profile, interactive=False)
session = wizard.conduct()

# 3. Preprocessing
builder = PipelineBuilder(profile.columns, session.config)
plan = builder.build()
print(builder.explain())

X, y = df.drop(columns=["target_column"]), df["target_column"]
split = split_data(X, y, session.config.get("split"))

# 4. Train
models = []
for name in ("Logistic Regression", "Random Forest"):
    t = ModelTrainer(name, "classification")
    models.append(t.train(split.X_train, split.y_train))

# 5. Evaluate
comp = ModelComparator(models, split.X_test, split.y_test, primary_metric="ROC AUC")
report = comp.evaluate()
print(report.table)
print(report.explanation)

# 6. Figures
fb = FigureBuilder(dpi=300)
best_model = next(m for m in models if m.name == report.best_model)
y_pred = best_model.estimator.predict(split.X_test)
y_proba = best_model.estimator.predict_proba(split.X_test)[:, 1]
fb.save_figure(fb.roc_curve(split.y_test, y_proba, best_model.name), "roc.pdf")
fb.save_figure(fb.confusion_matrix(split.y_test, y_pred, normalize=True), "cm.pdf")
if hasattr(best_model.estimator, "feature_importances_"):
    fb.save_figure(
        fb.feature_importance(best_model.estimator, list(X.columns), top_n=10),
        "importance.pdf",
    )
plt.close("all")

# 7. Report
assistant = ResearchAssistant(profile, session, plan, models, report)
generator = ReportGenerator(assistant, fb)
generator.to_excel("report.xlsx")
generator.to_html("report.html")
print("Done! Open report.html in your browser.")

---

Features

• Dataset profiling — automatic detection of feature types, missing values, duplicates, constant columns, near-zero variance, class imbalance, high cardinality
• Interactive wizard — asks only relevant questions, provides recommendations with plain-language reasons and alternatives
• Preprocessing pipelines — missing value imputation, categorical encoding, feature scaling, train/test splitting, class imbalance handling (all via sklearn Pipeline)
• 10 model families — Logistic Regression, Decision Tree, Random Forest, Extra Trees, SVM, KNN, Naive Bayes, XGBoost, LightGBM, CatBoost through a unified interface
• Evaluation — 9 classification metrics with explanations, model comparison tables, best-model recommendation
• Publication-quality figures — ROC/PR curves, confusion matrix, feature importance, learning curve at 300 DPI
• Research Assistant — generates comprehensive explain(), publication-ready methods(), and critical review() output
• Report generation — multi-sheet Excel, standalone HTML with embedded plots, PDF output

License

MIT