Input / Output

Input/output helpers for Aurora-GLM.

This module provides data loading and model serialization utilities.

Reading Data

>>> from aurora.io import read_csv, read_design_matrix
>>>
>>> # Read CSV to dict of arrays
>>> data = read_csv("data.csv")
>>> X = np.column_stack([data['x1'], data['x2']])
>>> y = data['y']
>>>
>>> # Or directly extract X, y
>>> X, y = read_design_matrix("data.csv", response="y")

Saving Results

>>> from aurora.io import save_result, export_coefficients
>>>
>>> # Save full result
>>> save_result(result, "model.json")
>>>
>>> # Load it back
>>> loaded = load_result("model.json")
>>>
>>> # Export coefficients to CSV
>>> export_coefficients(result, "coef.csv")

Submodules

readers

Data ingestion from CSV, JSON, Excel, Stata

writers

Result export and serialization

converters

Data format conversion utilities (planned)

aurora.io.read_csv(filepath, *, delimiter=',', header=True, columns=None, dtype=None, na_values=None, skip_rows=0, max_rows=None, **kwargs)[source]

Read a CSV file into a dictionary of arrays.

Parameters:

  • filepath (str or Path) – Path to the CSV file.

  • delimiter (str, default=',') – Field delimiter character.

  • header (bool or int, default=True) – If True, first row is used as column names. If int, specifies row number for headers (0-indexed). If False, columns are named ‘col_0’, ‘col_1’, etc.

  • columns (sequence of str, optional) – Subset of columns to read.

  • dtype (type or dict, optional) – Data type for columns. Can be a single type or dict mapping column names to types.

  • na_values (sequence of str, optional) – Additional strings to recognize as NA/NaN.

  • skip_rows (int, default=0) – Number of rows to skip at the beginning.

  • max_rows (int, optional) – Maximum number of rows to read.

  • **kwargs – Additional arguments passed to pandas.read_csv if available.

Returns:

data – Dictionary mapping column names to numpy arrays.

Return type:

dict[str, ndarray]

Examples

>>> data = read_csv("data.csv")
>>> X = np.column_stack([data['x1'], data['x2'], data['x3']])
>>> y = data['y']

Notes

If pandas is installed, uses pandas.read_csv for robust parsing. Otherwise, falls back to Python’s csv module.

aurora.io.read_design_matrix(filepath, *, response, predictors=None, intercept=True, delimiter=',', **kwargs)[source]

Read a CSV file and extract design matrix X and response y.

This is a convenience function for the common case of reading a data file for regression modeling.

Parameters:

  • filepath (str or Path) – Path to the CSV file.

  • response (str) – Name of the response (y) column.

  • predictors (sequence of str, optional) – Names of predictor (X) columns. If None, uses all non-response columns.

  • intercept (bool, default=True) – If True, prepends a column of ones for the intercept.

  • delimiter (str, default=',') – Field delimiter character.

  • **kwargs – Additional arguments passed to read_csv.

Returns:

  • X (ndarray of shape (n_samples, n_features)) – Design matrix.

  • y (ndarray of shape (n_samples,)) – Response vector.

Return type:

tuple[ndarray, ndarray]

Examples

>>> X, y = read_design_matrix("data.csv", response="y")
>>> result = fit_glm(X, y)

>>> # Select specific predictors
>>> X, y = read_design_matrix("data.csv", response="price",
...                           predictors=["sqft", "bedrooms", "age"])
aurora.io.read_json(filepath, *, orient='records')[source]

Read a JSON file into a dictionary of arrays.

Parameters:

  • filepath (str or Path) – Path to the JSON file.

  • orient ({'records', 'columns', 'values'}, default='records') – Expected JSON structure: - ‘records’: List of {column: value} dicts - ‘columns’: {column: [values]} dict - ‘values’: List of lists (rows)

Returns:

data – Dictionary mapping column names to numpy arrays.

Return type:

dict[str, ndarray]

Examples

>>> data = read_json("data.json")
>>> X, y = data['X'], data['y']
aurora.io.read_excel(filepath, *, sheet_name=0, header=True, columns=None, **kwargs)[source]

Read an Excel file into a dictionary of arrays.

Requires openpyxl (for .xlsx) or xlrd (for .xls).

Parameters:

  • filepath (str or Path) – Path to the Excel file.

  • sheet_name (str or int, default=0) – Sheet to read (name or 0-indexed position).

  • header (bool or int, default=True) – Row to use for column names.

  • columns (sequence of str, optional) – Subset of columns to read.

  • **kwargs – Additional arguments passed to pandas.read_excel.

Returns:

data – Dictionary mapping column names to numpy arrays.

Return type:

dict[str, ndarray]

aurora.io.read_stata(filepath, *, columns=None, convert_categoricals=True, **kwargs)[source]

Read a Stata .dta file into a dictionary of arrays.

Requires pandas.

Parameters:

  • filepath (str or Path) – Path to the Stata file.

  • columns (sequence of str, optional) – Subset of columns to read.

  • convert_categoricals (bool, default=True) – Whether to convert labeled integers to Categorical.

  • **kwargs – Additional arguments passed to pandas.read_stata.

Returns:

data – Dictionary mapping column names to numpy arrays.

Return type:

dict[str, ndarray]

aurora.io.save_result(result, filepath, *, format='auto', include_data=False)[source]

Save a model result to file.

Parameters:

  • result (ModelResult) – A fitted model result from fit_glm, fit_gam, etc.

  • filepath (str or Path) – Output file path.

  • format ({'json', 'pickle', 'auto'}, default='auto') – Output format. ‘auto’ infers from file extension.

  • include_data (bool, default=False) – If True, includes training data (X, y) in the output.

Return type:

None

Examples

>>> from aurora import fit_glm, Gaussian
>>> result = fit_glm(X, y, family=Gaussian())
>>> save_result(result, "model.json")
>>> save_result(result, "model.pkl", format='pickle')
aurora.io.load_result(filepath, *, format='auto')[source]

Load a saved model result.

Parameters:

  • filepath (str or Path) – Path to the saved result file.

  • format ({'json', 'pickle', 'auto'}, default='auto') – Input format. ‘auto’ infers from file extension.

Returns:

result – The loaded result. JSON files return dicts, pickle files return the original object.

Return type:

dict or object

Warning

Pickle files can execute arbitrary code. Only load .pkl files from trusted sources. Prefer JSON format for untrusted input.

Examples

>>> result = load_result("model.json")
>>> print(result['coefficients'])
aurora.io.export_coefficients(result, filepath, *, include_std_errors=True, include_pvalues=True)[source]

Export model coefficients to CSV.

Parameters:

  • result (ModelResult) – A fitted model result.

  • filepath (str or Path) – Output CSV file path.

  • include_std_errors (bool, default=True) – Include standard errors if available.

  • include_pvalues (bool, default=True) – Include p-values if available.

Return type:

None

Examples

>>> export_coefficients(result, "coefficients.csv")
aurora.io.export_predictions(result, X, filepath, *, include_se=False, include_ci=False, ci_level=0.95)[source]

Export model predictions to CSV.

Parameters:

  • result (ModelResult) – A fitted model result with a predict method.

  • X (ndarray) – Design matrix for predictions.

  • filepath (str or Path) – Output CSV file path.

  • include_se (bool, default=False) – Include standard errors of predictions.

  • include_ci (bool, default=False) – Include confidence intervals.

  • ci_level (float, default=0.95) – Confidence level for intervals.

Return type:

None

Examples

>>> export_predictions(result, X_new, "predictions.csv", include_ci=True)

Readers

Data ingestion interfaces for Aurora-GLM.

This module provides functions for reading data from various formats into arrays suitable for Aurora-GLM model fitting.

Supported Formats

  • CSV files (via pandas or built-in csv)

  • Excel files (.xlsx, .xls)

  • JSON files

  • Stata files (.dta)

  • R data files (.rds, .rdata) - if pyreadr installed

Examples

>>> from aurora.io.readers import read_csv, read_design_matrix
>>>
>>> # Simple CSV reading
>>> X, y = read_design_matrix("data.csv", response="y")
>>>
>>> # With pandas-style options
>>> data = read_csv("data.csv", index_col=0, na_values=['NA', '.'])
aurora.io.readers.read_csv(filepath, *, delimiter=',', header=True, columns=None, dtype=None, na_values=None, skip_rows=0, max_rows=None, **kwargs)[source]

Read a CSV file into a dictionary of arrays.

Parameters:

  • filepath (str or Path) – Path to the CSV file.

  • delimiter (str, default=',') – Field delimiter character.

  • header (bool or int, default=True) – If True, first row is used as column names. If int, specifies row number for headers (0-indexed). If False, columns are named ‘col_0’, ‘col_1’, etc.

  • columns (sequence of str, optional) – Subset of columns to read.

  • dtype (type or dict, optional) – Data type for columns. Can be a single type or dict mapping column names to types.

  • na_values (sequence of str, optional) – Additional strings to recognize as NA/NaN.

  • skip_rows (int, default=0) – Number of rows to skip at the beginning.

  • max_rows (int, optional) – Maximum number of rows to read.

  • **kwargs – Additional arguments passed to pandas.read_csv if available.

Returns:

data – Dictionary mapping column names to numpy arrays.

Return type:

dict[str, ndarray]

Examples

>>> data = read_csv("data.csv")
>>> X = np.column_stack([data['x1'], data['x2'], data['x3']])
>>> y = data['y']

Notes

If pandas is installed, uses pandas.read_csv for robust parsing. Otherwise, falls back to Python’s csv module.

aurora.io.readers.read_design_matrix(filepath, *, response, predictors=None, intercept=True, delimiter=',', **kwargs)[source]

Read a CSV file and extract design matrix X and response y.

This is a convenience function for the common case of reading a data file for regression modeling.

Parameters:

  • filepath (str or Path) – Path to the CSV file.

  • response (str) – Name of the response (y) column.

  • predictors (sequence of str, optional) – Names of predictor (X) columns. If None, uses all non-response columns.

  • intercept (bool, default=True) – If True, prepends a column of ones for the intercept.

  • delimiter (str, default=',') – Field delimiter character.

  • **kwargs – Additional arguments passed to read_csv.

Returns:

  • X (ndarray of shape (n_samples, n_features)) – Design matrix.

  • y (ndarray of shape (n_samples,)) – Response vector.

Return type:

tuple[ndarray, ndarray]

Examples

>>> X, y = read_design_matrix("data.csv", response="y")
>>> result = fit_glm(X, y)

>>> # Select specific predictors
>>> X, y = read_design_matrix("data.csv", response="price",
...                           predictors=["sqft", "bedrooms", "age"])
aurora.io.readers.read_json(filepath, *, orient='records')[source]

Read a JSON file into a dictionary of arrays.

Parameters:

  • filepath (str or Path) – Path to the JSON file.

  • orient ({'records', 'columns', 'values'}, default='records') – Expected JSON structure: - ‘records’: List of {column: value} dicts - ‘columns’: {column: [values]} dict - ‘values’: List of lists (rows)

Returns:

data – Dictionary mapping column names to numpy arrays.

Return type:

dict[str, ndarray]

Examples

>>> data = read_json("data.json")
>>> X, y = data['X'], data['y']
aurora.io.readers.read_excel(filepath, *, sheet_name=0, header=True, columns=None, **kwargs)[source]

Read an Excel file into a dictionary of arrays.

Requires openpyxl (for .xlsx) or xlrd (for .xls).

Parameters:

  • filepath (str or Path) – Path to the Excel file.

  • sheet_name (str or int, default=0) – Sheet to read (name or 0-indexed position).

  • header (bool or int, default=True) – Row to use for column names.

  • columns (sequence of str, optional) – Subset of columns to read.

  • **kwargs – Additional arguments passed to pandas.read_excel.

Returns:

data – Dictionary mapping column names to numpy arrays.

Return type:

dict[str, ndarray]

aurora.io.readers.read_stata(filepath, *, columns=None, convert_categoricals=True, **kwargs)[source]

Read a Stata .dta file into a dictionary of arrays.

Requires pandas.

Parameters:

  • filepath (str or Path) – Path to the Stata file.

  • columns (sequence of str, optional) – Subset of columns to read.

  • convert_categoricals (bool, default=True) – Whether to convert labeled integers to Categorical.

  • **kwargs – Additional arguments passed to pandas.read_stata.

Returns:

data – Dictionary mapping column names to numpy arrays.

Return type:

dict[str, ndarray]

Writers

Result serialization and export utilities for Aurora-GLM.

This module provides functions for saving model results and data to various formats.

Supported Formats

  • CSV: Coefficients, predictions, residuals

  • JSON: Full result serialization

  • Pickle: Python-native serialization

  • HDF5: Large array storage (if h5py installed)

Examples

>>> from aurora.io.writers import save_result, export_coefficients
>>>
>>> # Save full result
>>> save_result(result, "model.json")
>>>
>>> # Export just coefficients
>>> export_coefficients(result, "coef.csv")
>>>
>>> # Export predictions
>>> export_predictions(result, X_new, "predictions.csv")
aurora.io.writers.save_result(result, filepath, *, format='auto', include_data=False)[source]

Save a model result to file.

Parameters:

  • result (ModelResult) – A fitted model result from fit_glm, fit_gam, etc.

  • filepath (str or Path) – Output file path.

  • format ({'json', 'pickle', 'auto'}, default='auto') – Output format. ‘auto’ infers from file extension.

  • include_data (bool, default=False) – If True, includes training data (X, y) in the output.

Return type:

None

Examples

>>> from aurora import fit_glm, Gaussian
>>> result = fit_glm(X, y, family=Gaussian())
>>> save_result(result, "model.json")
>>> save_result(result, "model.pkl", format='pickle')
aurora.io.writers.load_result(filepath, *, format='auto')[source]

Load a saved model result.

Parameters:

  • filepath (str or Path) – Path to the saved result file.

  • format ({'json', 'pickle', 'auto'}, default='auto') – Input format. ‘auto’ infers from file extension.

Returns:

result – The loaded result. JSON files return dicts, pickle files return the original object.

Return type:

dict or object

Warning

Pickle files can execute arbitrary code. Only load .pkl files from trusted sources. Prefer JSON format for untrusted input.

Examples

>>> result = load_result("model.json")
>>> print(result['coefficients'])
aurora.io.writers.export_coefficients(result, filepath, *, include_std_errors=True, include_pvalues=True)[source]

Export model coefficients to CSV.

Parameters:

  • result (ModelResult) – A fitted model result.

  • filepath (str or Path) – Output CSV file path.

  • include_std_errors (bool, default=True) – Include standard errors if available.

  • include_pvalues (bool, default=True) – Include p-values if available.

Return type:

None

Examples

>>> export_coefficients(result, "coefficients.csv")
aurora.io.writers.export_predictions(result, X, filepath, *, include_se=False, include_ci=False, ci_level=0.95)[source]

Export model predictions to CSV.

Parameters:

  • result (ModelResult) – A fitted model result with a predict method.

  • X (ndarray) – Design matrix for predictions.

  • filepath (str or Path) – Output CSV file path.

  • include_se (bool, default=False) – Include standard errors of predictions.

  • include_ci (bool, default=False) – Include confidence intervals.

  • ci_level (float, default=0.95) – Confidence level for intervals.

Return type:

None

Examples

>>> export_predictions(result, X_new, "predictions.csv", include_ci=True)