Metadata-Version: 2.4
Name: hse_ml
Version: 0.1.0
Summary: Hypercuboid Subspace Estimator for non-linear feature engineering and selection.
Author-email: Peter Lung <peterlungdatascience@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/peterlungdatascience/HSE
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: numpy>=1.20.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: matplotlib>=3.4.0
Requires-Dist: numba>=0.54.0
Dynamic: license-file

# HSE: Hypercuboid Spline Estimator, Density Estimator & Causal Inference Engine

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Python 3.8+](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)

A high-performance Python package for non-parametric baseline estimation, smooth heteroskedastic univariate and multivariate density estimation, causal estimation, and interactive model diagnostics.

Designed for low to medium-scale and low-dimension datasets with interest in high-performance causal estimation and univariate or multivariate density modeling, `hse` combines flexible spline regression with hypercuboid technology to avoid overfitting without cross validation.

---

## Package Architecture

`hse` consists of five unified modules:

- **`hse.estimator.HSE`**: Non-parametric baseline modeling using multi-round forward knot selection and $O(N)$ hypercuboid partitioning for fast spline fitting.
- **`hse.density.HSE_Density`**: Smooth, non-parametric, heteroskedasticity-robust conditional density estimator ($\sigma^2 = \text{HSE}(X_{\text{var}})$) for modeling complete residual probability distributions.
- **`hse.diagnostics`**: Production diagnostic suite returning statistical summary tables (OLS/Logistic), 1D/2D feature fit grids with 90% data intervals, Q-Q loss plots, and residual distribution scatterplots.
- **`hse.mv_density`**: Multivariate, chained nonparametric density estimator returning a spline-based conditional multivariate density function.
- **`hse.hse_causal`**: High-performance machine learning for estimation of DAG-based causal model which takes in target and feature data with user-specification of treatment and control variables as well as functional form options for the treatment, returning causal estimates and average treatment effects.

---

## Installation

### From PyPI
```bash
pip install hse_ml
```

### From Source
```bash
git clone https://github.com/your-repo/hse.git
cd hse
pip install -e .
```

### Dependencies

* numpy >= 1.20.0

* scipy >= 1.7.0

* pandas >= 1.3.0

* matplotlib >= 3.4.0

* scikit-learn >= 1.0.0

## Quickstart Examples

### 1. Continuous Causal Inference & Counterfactual Dose-Response (hse_causal.py)

```python
import numpy as np
import pandas as pd
from hse.hse_causal import HSECausalEstimator

# Fit Causal Estimator with treatment interactions
causal_model = HSECausalEstimator(
    var_of_interest="treatment",
    control=["confounder_1", "confounder_2"],
    interactions="all"
)
causal_model.fit(df, depvar="outcome")

# Estimate Average Treatment Effect (ATE)
ate = causal_model.estimate_treatment_effect(df)
print(f"Population ATE: {ate['average_treatment_effect']:.4f}")

# Print diagnostic statistical summary table
causal_model.summary(df)
```

### 2. Heteroskedastic Conditional Density Estimation (density.py)

```python
import numpy as np
from hse.density import HSE_Density
from hse.estimator import HSE

# Fit base mean model
base_model = HSE().fit(X, y)

# Fit conditional density estimator on residuals
density = HSE_Density(base_estimator=base_model)
density.fit(X=X, y=y)

# Plot conditional PDF in a single function call
density.plot_density(X[0:1])

# Generate Monte Carlo draws and evaluate 37th percentile target
samples = density.rvs(X[0:1], size=1000)
q37 = density.predict_ppf(X[0:1], q=0.37)
```

### 3. Model Diagnostics & Statistical Summaries (diagnostics.py)

```python
from hse.estimator import HSE
from hse.diagnostics import print_statistical_summary, plot_feature_fits, plot_qq_diagnostics

# Fit base spline estimator
model = HSE().fit(X, y)

# Print full OLS statistical summary
print_statistical_summary(model, X, y)

# Plot binned feature fits with 90% data confidence intervals
plot_feature_fits(model, X, y, target_feature=0)

# Generate hypercuboid Z-score Q-Q plot
plot_qq_diagnostics(model, X, y)
```

## Module Overview

### `hse.estimator`

- **HSE**: Primary non-parametric regressor with automated 1D/2D hinge knot selection.

### `hse.hse_causal`

- **HSE Causal Estimator**: HSE-based causal estimation engine with fit(), predict() and diagnostic tables and plots

### `hse.density`

- **HSE Density**: Estimates conditional variance surfaces and fits non-negative B-spline residual probability density functions (predict_pdf, predict_cdf, predict_sigma).

### `hse.diagnostics`

- **Visual & Statistical Tools**: plot_qq_diagnostics, plot_feature_fits, plot_feature_fits_x2, print_statistical_summary, plot_roc_curve, plot_confusion_matrix, plot_residual_histogram, plot_residual_scatter.

### `hse.mv_density`

- **Multivariate Conditional Density Estimator**: Estimates density function for 2 or more targets conditional on additional feature variables using HSE engine for mean estimation


## License

This project is licensed under the [Apache License, Version 2.0](LICENSE) - see the LICENSE file for details.






