Helpers¶

High-level convenience functions.

High-level convenience functions for Aurora-GLM.

This module provides unified helper functions that work with any Aurora result:

summary(result): Formatted model summary
plot(result): Diagnostic plots
compare(*results): Model comparison

These are also available at the package level: >>> import aurora >>> aurora.summary(result) >>> aurora.plot(result) >>> aurora.compare(model1, model2, model3)

Examples

>>> from aurora import fit_glm, summary, plot, compare
>>>
>>> # Fit models
>>> result1 = fit_glm(X, y, family=Gaussian())
>>> result2 = fit_glm(X, y, family=Poisson())
>>>
>>> # Get summaries
>>> print(summary(result1))
>>>
>>> # Plot diagnostics
>>> plot(result1, kind='diagnostics')
>>>
>>> # Compare models
>>> compare(result1, result2, criterion='aic')

aurora.helpers.summary(result, *, style='default', print_output=True)[source]¶

Generate a formatted summary of a fitted model result.

This is a unified interface for summarizing any Aurora model result. It automatically dispatches to the appropriate summary method based on the result type.

Parameters:

result (ModelResult) – A fitted model result from fit_glm, fit_gam, fit_gamm, etc.
style ({'default', 'brief', 'detailed'}, default='default') – Summary style: - ‘default’: Standard coefficient table with fit statistics - ‘brief’: One-line summary with key metrics - ‘detailed’: Full output including diagnostics
print_output (bool, default=True) – If True, print the summary. If False, only return the string.

Returns:

summary_str – Formatted summary string.

Return type:

str

Examples

>>> from aurora import fit_glm, summary, Gaussian
>>> result = fit_glm(X, y, family=Gaussian())
>>> print(summary(result))
======================================================================
                      Linear Model Results
======================================================================
No. Observations:        100    R-squared:          0.8542
...

>>> # Brief summary
>>> summary(result, style='brief')
'GLM(n=100, converged=True, R²=0.854)'

>>> # Detailed with diagnostics
>>> summary(result, style='detailed')

Notes

The function works with any result object that has a .summary() method. For custom result classes, implement .summary() to integrate with this.

See also

plot: Diagnostic plots for model results
compare: Compare multiple models

aurora.helpers.plot(result, *, kind='diagnostics', ax=None, **kwargs)[source]¶

Create diagnostic plots for a fitted model result.

This is a unified interface for plotting any Aurora model result. It automatically creates appropriate plots based on the model type.

Parameters:

result (ModelResult) – A fitted model result from fit_glm, fit_gam, fit_gamm, etc.
kind ({'diagnostics', 'residuals', 'qq', 'smooth', 'all'}, default='diagnostics') – Type of plot: - ‘diagnostics’: Standard 4-panel diagnostic plot - ‘residuals’: Residuals vs fitted values - ‘qq’: Q-Q plot of residuals - ‘smooth’: Smooth function plots (GAM/GAMM only) - ‘all’: All available plots
ax (matplotlib.axes.Axes, optional) – Axes to plot on. If None, creates new figure.
**kwargs – Additional arguments passed to the underlying plot function.

Returns:

fig – The created figure(s).

Return type:

matplotlib.figure.Figure or list of Figures

Examples

>>> from aurora import fit_glm, plot, Gaussian
>>> result = fit_glm(X, y, family=Gaussian())
>>>
>>> # Standard diagnostics
>>> plot(result)
>>>
>>> # Just residuals
>>> plot(result, kind='residuals')
>>>
>>> # For GAM, plot smooth terms
>>> gam_result = fit_gam(X, y)
>>> plot(gam_result, kind='smooth')

See also

summary: Formatted model summary
compare: Compare multiple models
plot_diagnostics: Low-level diagnostic plots
plot_smooth: Low-level smooth term plots

aurora.helpers.compare(*results, criterion='aic', names=None, print_output=True)[source]¶

Compare multiple fitted models.

This function provides a unified interface for comparing different model specifications using information criteria or likelihood ratio tests.

Parameters:

*results (ModelResult) – Two or more fitted model results to compare.
criterion ({'aic', 'bic', 'loglik', 'all'}, default='aic') – Criterion for comparison: - ‘aic’: Akaike Information Criterion - ‘bic’: Bayesian Information Criterion - ‘loglik’: Log-likelihood - ‘all’: All available criteria
names (sequence of str, optional) – Names for the models. If None, uses ‘Model 1’, ‘Model 2’, etc.
print_output (bool, default=True) – If True, print the comparison table.

Returns:

comparison – Dictionary with comparison results: - ‘summary’: Formatted comparison table (str) - ‘criteria’: DataFrame or dict with criterion values - ‘best’: Index of best model - ‘delta’: Differences from best model

Return type:

dict

Examples

>>> from aurora import fit_glm, compare, Gaussian, Poisson
>>>
>>> # Fit different models
>>> m1 = fit_glm(X, y, family=Gaussian())
>>> m2 = fit_glm(X, y, family=Poisson())
>>> m3 = fit_glm(X[:, :2], y, family=Gaussian())  # Fewer predictors
>>>
>>> # Compare models
>>> compare(m1, m2, m3, criterion='aic')
======================================================================
                        Model Comparison (AIC)
======================================================================
       Model        AIC      ΔAIC   Rank
----------------------------------------------------------------------
   Model 1     234.56      0.00      1   ← best
   Model 2     245.12     10.56      2
   Model 3     267.89     33.33      3
======================================================================

>>> # With custom names
>>> compare(m1, m2, names=['Linear', 'Poisson'], criterion='bic')

Notes

Lower AIC/BIC indicates better fit (with parsimony)
For nested models, likelihood ratio tests can also be performed
Models should be fit on the same data for meaningful comparison