Skip to content

Quick Start Guide

This guide will get you up and running with Econometrust in minutes.

Basic Usage

Import and Setup

import numpy as np
import econometrust as et

# Set random seed for reproducibility
np.random.seed(42)

1. Ordinary Least Squares (OLS)

# Generate sample data
n, k = 200, 3
X = np.random.randn(n, k)
true_beta = [1.5, -2.0, 0.5]
y = X @ true_beta + np.random.randn(n) * 0.2

# Fit OLS model
ols = et.OLS(fit_intercept=True, robust=True)
ols.fit(X, y)

# View results
print(ols.summary())
print(f"R²: {ols.r_squared:.4f}")

2. Weighted Least Squares (WLS)

# Generate heteroskedastic data
weights = np.exp(X[:, 0])  # Variance proportional to exp(X)
error_std = 1.0 / np.sqrt(weights)
y_hetero = X @ true_beta + np.random.randn(n) * error_std

# Fit WLS model
wls = et.WLS(fit_intercept=True)
wls.fit(X, y_hetero, weights)

print(f"WLS R²: {wls.r_squared:.4f}")
print(f"WLS Coefficients: {wls.coefficients}")

3. Generalized Least Squares (GLS)

# Create AR(1) error covariance matrix
rho = 0.6
Sigma = np.array([[rho**abs(i - j) for j in range(n)] for i in range(n)])

# Generate correlated errors
errors = np.random.multivariate_normal(np.zeros(n), Sigma)
y_corr = X @ true_beta + errors

# Fit GLS model
gls = et.GLS(fit_intercept=True)
gls.fit(X, y_corr, Sigma)

print(f"GLS R²: {gls.r_squared:.4f}")
print(f"GLS Standard Errors: {gls.standard_errors()}")

4. Instrumental Variables (IV)

# Generate data with endogenous regressor
Z = np.random.randn(n, k)  # Instruments
u = np.random.randn(n)  # Unobserved factor

# Endogenous regressors (correlated with error)
X_endo = Z @ [0.8, 0.6, 0.4] + 0.5 * u + np.random.randn(n, k) * 0.1
y_endo = X_endo @ true_beta + u + np.random.randn(n) * 0.1

# Fit IV model (exactly identified)
iv = et.IV(fit_intercept=True)
iv.fit(Z, X_endo, y_endo)

print(f"IV Coefficients: {iv.coefficients}")
print(f"IV Standard Errors: {iv.standard_errors()}")

5. Two-Stage Least Squares (TSLS)

# Add extra instruments for overidentification
Z_over = np.column_stack([Z, np.random.randn(n, 2)])  # 5 instruments, 3 regressors

# Fit TSLS model (overidentified)
tsls = et.TSLS(fit_intercept=True)
tsls.fit(Z_over, X_endo, y_endo)

print(f"TSLS Coefficients: {tsls.coefficients}")
print(f"TSLS Standard Errors: {tsls.standard_errors()}")

Common Workflow

1. Data Preparation

# Load your data
# X = ... # Feature matrix (n_samples, n_features)
# y = ... # Target vector (n_samples,)

# Check data quality
print(f"Data shape: X={X.shape}, y={y.shape}")
print(f"Missing values: X={np.isnan(X).sum()}, y={np.isnan(y).sum()}")
print(f"Data ranges: X=[{X.min():.2f}, {X.max():.2f}], "
      f"y=[{y.min():.2f}, {y.max():.2f}]")

2. Model Selection

# Choose appropriate estimator based on your problem:

# Standard linear regression
no_endogeneity = True
homoskedastic = True
if no_endogeneity and homoskedastic:
    model = et.OLS(fit_intercept=True, robust=False)

# Heteroskedasticity concerns
heteroskedastic = True
unknown_pattern = True
if heteroskedastic and unknown_pattern:
    model = et.OLS(fit_intercept=True, robust=True)

# Known heteroskedastic weights
known_weights = True
if known_weights:
    model = et.WLS(fit_intercept=True)
    # model.fit(X, y, weights=weights)

# Known error correlation
known_correlation_structure = True
if known_correlation_structure:
    model = et.GLS(fit_intercept=True)
    # model.fit(X, y, sigma=Sigma)

# Endogeneity with exactly identified instruments
endogenous = True
exactly_identified = True
if endogenous and exactly_identified:
    model = et.IV(fit_intercept=True)
    # model.fit(instruments=Z, regressors=X, targets=y)

# Endogeneity with overidentified instruments
overidentified = True
if endogenous and overidentified:
    model = et.TSLS(fit_intercept=True)
    # model.fit(instruments=Z, regressors=X, targets=y)

3. Model Fitting and Diagnostics

# Fit the model
model.fit(X, y)

# Basic diagnostics
print(f"Model fitted: {model.is_fitted()}")
print(f"Sample size: {model.n_samples}")
print(f"Features: {model.n_features}")
print(f"R²: {model.r_squared:.4f}")
print(f"MSE: {model.mse:.6f}")

# Coefficient analysis
coefs = model.coefficients
se = model.standard_errors()
t_stats = model.t_statistics()
p_vals = model.p_values()

print("\nCoefficient Summary:")
for i in range(len(coefs)):
    if p_vals[i] < 0.01:
        significance = "***"
    elif p_vals[i] < 0.05:
        significance = "**"
    elif p_vals[i] < 0.10:
        significance = "*"
    else:
        significance = ""
    print(f"  β{i}: {coefs[i]:.4f} (SE: {se[i]:.4f}, "
          f"p: {p_vals[i]:.4f}) {significance}")

4. Model Validation

# Residual analysis
residuals = model.residuals
print(f"\nResidual Statistics:")
print(f"  Mean: {np.mean(residuals):.6f}")
print(f"  Std Dev: {np.std(residuals):.4f}")
skewness = (np.mean((residuals - np.mean(residuals))**3) / 
            np.std(residuals)**3)
print(f"  Skewness: {skewness:.4f}")

# Confidence intervals
ci_95 = model.confidence_intervals(alpha=0.05)
print("\n95% Confidence Intervals:")
for i, (lower, upper) in enumerate(ci_95):
    print(f"  β{i}: [{lower:.4f}, {upper:.4f}]")

5. Prediction

# Generate predictions
X_new = np.random.randn(10, X.shape[1])  # New data points
predictions = model.predict(X_new)

print(f"\nPredictions:")
print(f"  Shape: {predictions.shape}")
print(f"  Mean: {np.mean(predictions):.4f}")
print(f"  Range: [{np.min(predictions):.4f}, "
      f"{np.max(predictions):.4f}]")

Performance Tips

1. Data Types

# Use appropriate data types for better performance
X = X.astype(np.float64)  # Recommended for numerical stability
y = y.astype(np.float64)

# For very large datasets, consider float32 if precision allows
# X = X.astype(np.float32)  # Faster but less precise

2. Memory Management

# For large datasets, consider chunked processing
def fit_large_dataset(X, y, chunk_size=10000):
    """Example of chunked processing for very large datasets."""
    n_samples = X.shape[0]

    if n_samples <= chunk_size:
        # Small enough to fit in memory
        model = et.OLS()
        model.fit(X, y)
        return model
    else:
        # For very large datasets, consider online/streaming algorithms
        # This is a placeholder - Econometrust currently requires full data
        print(f"Large dataset detected ({n_samples} samples)")
        print("Consider using sampling or online methods for massive datasets")
        return None

3. Algorithm Selection

# Econometrust automatically selects algorithms, but you can influence this:

# For well-conditioned problems (default: Cholesky)
model = et.OLS()  # Will use efficient Cholesky decomposition

# For potentially ill-conditioned problems, SVD is automatically used
# No user intervention needed - the library handles this intelligently

Next Steps

  • Detailed Examples: Each estimator's API documentation includes comprehensive usage examples
  • API Reference: Complete API documentation

Common Patterns

Model Comparison

models = {
    "OLS": et.OLS(robust=False),
    "OLS_Robust": et.OLS(robust=True),
    "WLS": et.WLS(),
    "GLS": et.GLS()
}

results = {}
for name, model in models.items():
    if name == "WLS":
        model.fit(X, y, np.ones(len(y)))  # Unit weights
    elif name == "GLS":
        model.fit(X, y, np.eye(len(y)))  # Identity covariance
    else:
        model.fit(X, y)

    results[name] = {
        "r_squared": model.r_squared,
        "mse": model.mse,
        "coefficients": model.coefficients
    }

# Compare results
for name, res in results.items():
    print(f"{name}: R² = {res['r_squared']:.4f}, "
          f"MSE = {res['mse']:.6f}")