Helper Utilities

Helper utilities for Macrodata Refinement (MDR).

This module provides utility functions for data validation, transformation, and management.

mdr.utils.helpers.validate_numeric_array(arr, allow_nan=True, min_val=None, max_val=None)[source]

Validate that an array consists of numeric values.

Parameters:

arr (<MagicMock id='136017403753136'>) – Input array to validate
allow_nan (bool) – Whether to allow NaN values
min_val (float | None) – Minimum allowed value (optional)
max_val (float | None) – Maximum allowed value (optional)

Returns:

True if the array is valid, False otherwise

Return type:

bool

mdr.utils.helpers.validate_range(value, min_val, max_val, inclusive=True)[source]

Check if a value is within a specified range.

Parameters:

value (float) – The value to check
min_val (float) – Minimum allowed value
max_val (float) – Maximum allowed value
inclusive (bool) – Whether the range bounds are inclusive

Returns:

True if the value is within the range, False otherwise

Return type:

bool

mdr.utils.helpers.moving_average(data, window_size, center=False)[source]

Calculate the moving average of a data array.

Parameters:

data (<MagicMock id='136017403744352'>) – Input data array
window_size (int) – Size of the moving window
center (bool) – Whether to center the window

Returns:

Array of moving averages

Return type:

mdr.utils.helpers.detect_seasonality(data, max_lag=365, threshold=0.3)[source]

Detect seasonality in a time series using autocorrelation.

Parameters:

data (<MagicMock id='136017403508768'>) – Input time series data
max_lag (int) – Maximum lag to consider
threshold (float) – Correlation threshold for seasonality detection

Returns:

Tuple of (is_seasonal, period), where period is the detected seasonal period or None if no seasonality is detected

Return type:

Tuple[bool, int | None]

mdr.utils.helpers.interpolate_missing(data, method='linear', max_gap=None, order=None)[source]

Interpolate missing values in a data array.

Parameters:

data (<MagicMock id='136017403844240'>) – Input data array with potential NaN values
method (str) – Interpolation method (‘linear’, ‘nearest’, ‘cubic’, ‘spline’)
max_gap (int | None) – Maximum gap size to interpolate (None for no limit)
order (int | None)

Returns:

Data array with missing values interpolated

Return type:

mdr.utils.helpers.flatten_dict(d, parent_key='', sep='.')[source]

Flatten a nested dictionary.

Parameters:

d (Dict[str, Any]) – Input dictionary to flatten
parent_key (str) – Prefix for flattened keys
sep (str) – Separator for nested keys

Returns:

Flattened dictionary

Return type:

Dict[str, Any]

mdr.utils.helpers.unflatten_dict(d, sep='.')[source]

Convert a flattened dictionary back to a nested dictionary.

Parameters:

d (Dict[str, Any]) – Flattened dictionary
sep (str) – Separator used in flattened keys

Returns:

Nested dictionary

Return type:

Dict[str, Any]

mdr.utils.helpers.get_memory_usage(obj=None, unit='MB')[source]

Get the memory usage of an object or the current process.

Parameters:

obj (Any | None) – Python object to measure (None for current process)
unit (str) – Unit for the result (‘B’, ‘KB’, ‘MB’, ‘GB’)

Returns:

Memory usage in the specified unit

Return type:

float

Overview

The helpers module provides utility functions that support various operations across the MDR package. These helper functions include data type conversion, validation utilities, statistical functions, and more.

Core Functions

Helper Functions

mdr.utils.helpers.moving_average(data, window_size, center=False)[source]

Calculate the moving average of a data array.

Parameters:

data (<MagicMock id='136017403744352'>) – Input data array
window_size (int) – Size of the moving window
center (bool) – Whether to center the window

Returns:

Array of moving averages

Return type:

Usage Examples

Moving average example:

import numpy as np
from mdr.utils.helpers import moving_average

# Create sample data
data = np.array([1.0, 2.0, 3.0, 4.0, 5.0])

# Calculate moving average with window size 3
ma_data = moving_average(data, window_size=3)

print(f"Original data: {data}")
print(f"Moving average: {ma_data}")