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

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

pip install hse_ml

From Source

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)

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)

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)

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 - see the LICENSE file for details.