Skip to content

teanijarv/HLR

Repository files navigation

HLR - Hierarchical Linear Regression in Python

DOI image CI testing Documentation Status

HLR is a simple Python package for running hierarchical linear regression.

Features

It is built to work with Pandas dataframes, uses SciPy, statsmodels and pingouin under the hood, and runs diagnostic tests for testing assumptions while plotting figures with matplotlib and seaborn.

Installation

HLR is meant to be used with Python 3.9 or above, and has been tested on Python 3.9-3.12.

Dependencies

User installation

To install HLR, run this command in your terminal:

pip install hlr

This is the preferred method to install HLR, as it will always install the most recent stable release.

If you don’t have pip installed, this Python installation guide can guide you through the process.

Usage

Importing the module and running hierarchical linear regression, summarising the results, running assumption tests, and plotting.

import pandas as pd
from HLR import HierarchicalLinearRegression

# Example dataframe which includes some columns which are also mentioned below
nba = pd.read_csv('NBA_train.csv')

# Define the models for hierarchical regression including predictors for each model
X = {1: ['PTS'], 
     2: ['PTS', 'ORB'], 
     3: ['PTS', 'ORB', 'BLK']}

# Define the outcome variable
y = 'W'

# Initiate the HLR object (missing_data and ols_params are optional parameters)
hreg = HierarchicalLinearRegression(df, X, y, ols_params=None)

# Generate a summarised report of HLR
hreg.summary()

# Run diagnostics on all the models (displayed output below only shows the first model)
hreg.diagnostics(verbose=True)

# Different plots (see docs for more)
fig1 = hreg.plot_studentized_residuals_vs_fitted()
fig2 = hreg.plot_qq_residuals()
fig3 = hreg.plot_influence()
fig4 = hreg.plot_std_residuals()
fig5 = hreg.plot_histogram_std_residuals()
fig_list = hreg.plot_partial_regression()

Output:

Model Level Predictors N (observations) DF (residuals) DF (model) R-squared F-value P-value (F) SSE SSTO MSE (model) MSE (residuals) MSE (total) Beta coefs P-values (beta coefs) Failed assumptions (check!) R-squared change F-value change P-value (F change)
0 1 [PTS] 835.0 833.0 1.0 0.089297 81.677748 1.099996e-18 123292.827686 135382.0 12089.172314 148.010597 162.328537 {'Constant': -13.846261266053896, 'points': 0.... {'Constant': 0.023091997486255577, 'points': 1... [Homoscedasticity, Normality] NaN NaN NaN
1 2 [PTS, ORB] 835.0 832.0 2.0 0.168503 84.302598 4.591961e-34 112569.697267 135382.0 11406.151367 135.300117 162.328537 {'Constant': -14.225561767669713, 'points': 0.... {'Constant': 0.014660145903221372, 'points': 1... [Normality, Multicollinearity] 0.079206 79.254406 3.372595e-18
2 3 [PTS, ORB, BLK] 835.0 831.0 3.0 0.210012 73.638176 3.065838e-42 106950.174175 135382.0 9477.275275 128.700571 162.328537 {'Constant': -21.997353037483723, 'points': 0.... {'Constant': 0.00015712851466562279, 'points':... [Normality, Multicollinearity, Outliers/Levera... 0.041509 43.663545 6.962046e-11
Model Level 1 Diagnostics:
  Independence of residuals (Durbin-Watson test):
    DW stat: 1.9913212248708367
    Passed: True
  Linearity (Pearson r):
    PTS: {'Pearson r': 0.29882561440469596, 'p-value': 1.099996182226575e-18, 'Passed': True}
  Linearity (Rainbow test):
    Rainbow Stat: 0.9145095390107386
    p-value: 0.8189528030224006
    Passed: True
  Homoscedasticity (Breusch-Pagan test):
    Lagrange Stat: 5.183865793060617
    p-value: 0.022797547646224846
    Passed: False
  Homoscedasticity (Goldfeld-Quandt test):
    F-Stat: 1.0462467498084154
    p-value: 0.3225733517317874
    Passed: True
  Multicollinearity (pairwise correlations):
    Correlations: {}
    Passed: True
  Multicollinearity (Variance Inflation Factors):
    VIFs: {}
    Passed: True
  Outliers (extreme standardized residuals):
    Indices: []
    Passed: True
  Outliers (high Cooks distance):
    Indices: []
    Passed: True
  Normality (mean of residuals):
    Mean: 4.465782367986833e-14
    Passed: True
  Normality (Shapiro-Wilk test):
    SW Stat: 0.9873111844062805
    p-value: 1.2462886616049218e-06
    Passed: False

Model Level 2 Diagnostics:
...
diagnostic_plot1 diagnostic_plot2

Documentation (WIP)

Find more comprehensive overview of the usage of HLR.

https://hlr-hierarchical-linear-regression.readthedocs.io

Citation

Please use Zenodo DOI for citing the package in your work.

DOI

Example

Anijärv, T. E., Mitchell, J. and Boyle, R. (2024) ‘teanijarv/HLR: v0.2.3’. Zenodo. https://doi.org/10.5281/zenodo.7683808

@software{toomas_erik_anijarv_2024_7683808,
  author       = {Toomas Erik Anijärv, Jules Mitchell, Rory Boyle},
  title        = {teanijarv/HLR: v0.2.3},
  month        = mar,
  year         = 2024,
  publisher    = {Zenodo},
  version      = {v0.2.3},
  doi          = {10.5281/zenodo.7683808},
  url          = {https://doi.org/10.5281/zenodo.7683808}
}

Development

The HLR package was created and is maintained by Toomas Erik Anijärv. It is updated during spare time, thereby contributions are more than welcome!

This program is provided with no warranty of any kind and it is still under development. However, this code has been checked and validated against multiple same analyses conducted in SPSS.

To-do

  • Better summary printing (something similar as statsmodels summary?)
  • Include t-statistics for the coefficients in the results
  • Add regression type option (e.g., logistic regression)?

Contributors

Toomas Erik Anijärv Rory Boyle Jules Mitchell Cate Scanlon