Metadata-Version: 2.4
Name: eclipse-ml
Version: 0.1.0
Summary: Build, understand, and publish machine learning research.
Author: Eclipse Developers
License: MIT
Project-URL: Homepage, https://github.com/md-naim-molla/eclipse
Project-URL: Documentation, https://github.com/md-naim-molla/eclipse#readme
Project-URL: Repository, https://github.com/md-naim-molla/eclipse.git
Project-URL: Bug Tracker, https://github.com/md-naim-molla/eclipse/issues
Keywords: machine-learning,research-assistant,data-science,explainable-ml,public-health
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scikit-learn>=1.3
Requires-Dist: scipy>=1.11
Requires-Dist: matplotlib>=3.7
Requires-Dist: seaborn>=0.12
Requires-Dist: statsmodels>=0.14
Requires-Dist: PyYAML>=6.0
Requires-Dist: jinja2>=3.1
Requires-Dist: joblib>=1.3
Requires-Dist: rich>=13.0
Provides-Extra: io
Requires-Dist: openpyxl>=3.1; extra == "io"
Requires-Dist: pyreadstat>=1.2; extra == "io"
Requires-Dist: rdata>=0.9; extra == "io"
Requires-Dist: fastparquet>=2023.0; extra == "io"
Requires-Dist: sqlalchemy>=2.0; extra == "io"
Requires-Dist: pymysql>=1.0; extra == "io"
Requires-Dist: psycopg2-binary>=2.9; extra == "io"
Provides-Extra: xgb
Requires-Dist: xgboost>=1.7; extra == "xgb"
Provides-Extra: lgb
Requires-Dist: lightgbm>=3.3; extra == "lgb"
Provides-Extra: cat
Requires-Dist: catboost>=1.1; extra == "cat"
Provides-Extra: interpret
Requires-Dist: shap>=0.41; extra == "interpret"
Requires-Dist: lime>=0.2; extra == "interpret"
Provides-Extra: tune
Requires-Dist: optuna>=3.2; extra == "tune"
Provides-Extra: report
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: pytest-mock>=3.11; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: mypy>=1.6; extra == "dev"
Requires-Dist: sphinx>=7.2; extra == "dev"
Requires-Dist: sphinx-rtd-theme>=1.3; extra == "dev"
Requires-Dist: pre-commit>=3.5; extra == "dev"
Requires-Dist: openpyxl>=3.1; extra == "dev"
Requires-Dist: tabulate>=0.9; extra == "dev"
Provides-Extra: all
Requires-Dist: eclipse-ml[cat,dev,interpret,io,lgb,report,tune,xgb]; extra == "all"
Dynamic: license-file

# Eclipse

[![CI](https://github.com/md-naim-molla/eclipse/actions/workflows/ci.yml/badge.svg)](https://github.com/md-naim-molla/eclipse/actions/workflows/ci.yml)
[![Lint](https://github.com/md-naim-molla/eclipse/actions/workflows/lint.yml/badge.svg)](https://github.com/md-naim-molla/eclipse/actions/workflows/lint.yml)
[![PyPI version](https://img.shields.io/pypi/v/eclipse-ml.svg)](https://pypi.org/project/eclipse-ml/)
[![Python versions](https://img.shields.io/pypi/pyversions/eclipse-ml.svg)](https://pypi.org/project/eclipse-ml/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**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

```bash
pip install eclipse-ml
```

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

```bash
pip install "eclipse-ml[all]"
```

> **Note:** Install the package as `eclipse-ml`, then import it in code as `eclipse`:
> ```python
> import eclipse as ec
> ```

---

## How to Run

### 1. Profile your dataset

```python
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

```python
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

```python
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

```python
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

```python
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

```python
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

```python
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

```python
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)

```python
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
