# `limen.utils`

> Hold the smaller cross-cutting helpers that support experiments without belonging to one primary domain package.

## Canonical docs

- [Utilities](../../docs/Utilities.md)
- [Universal Experiment Loop](../../docs/Universal-Experiment-Loop.md)
- [Standard Metrics Library](../../docs/Standard-Metrics-Library.md)
- [Log](../../docs/Log.md)

## In the research projects

The [Python project](../../docs/examples/python-research/README.md) and the [Compiled project](../../docs/examples/compiled-research/README.md) keep parameter traversal, recorded inputs and availability clocks explicit throughout `search`. The utilities reference describes the lower-level helpers and the distinct legacy ParamSpace contract; it does not replace either project’s entry point.

## What this package owns

Owns general utilities such as legacy parameter sampling, `data_dict` conversion, confidence filtering, stationarity testing, price-line helpers, and report formatting.
Does **not** own the canonical experiment, feature, metric, or backtest surfaces.

## Key entry points

| Entry point | Use case | Notes |
|-------------|-------------|-------|
| `ParamSpace` | Legacy `UEL.run()` compatibility and direct permutation sampling | CLI and Python/MSQ runs use `SearchStrategy` and `ParamDomain` |
| `data_dict_to_numpy` | Numpy arrays from the standard Limen `data_dict` | Common inside sklearn-style model functions |
| `confidence_filtering_system` | Post-prediction filtering based on model agreement | An optional downstream helper, not part of the main UEL contract |
| `adf_test` | Augmented Dickey-Fuller stationarity test | Requires the `stats` extra |
| `AdfResult` | Typed ADF result | Returned by `adf_test` |
| `find_price_lines`, `filter_lines_by_quantile` | Price-line discovery and filtering | Used by line-based research surfaces |
| `binary_metrics`, `continuous_metrics`, `safe_ovr_auc` | Metric convenience re-exports | Canonical ownership remains in `limen.metrics` |
| `format_report_header`, `format_report_section`, `format_report_footer` | Formatted text summaries | Utility surface, not a canonical reporting framework |

## Adjacent modules

- `limen.experiment` uses `ParamSpace` on the legacy run path.
- `limen.metrics` provides the canonical scoring helpers that this package partially re-exports for convenience.
- `limen.sfd.reference_architecture` often calls `data_dict_to_numpy`.

## Quick orientation

| Module or family | Responsibility |
|---|---|
| `param_space.py` | Legacy permutation sampler |
| `data_dict_to_numpy.py` | Convert Limen data_dict to numpy arrays |
| `confidence_filtering_system.py` | Confidence-based prediction filtering |
| `adf_test.py` | Optional statsmodels-backed ADF test |
| `find_price_lines.py` | Price-line discovery |
| `filter_lines_by_quantile.py` | Price-line filtering |
| `reporting.py` | Text-formatting helpers |

<!-- reference: package-utils-layout source=limen/utils/README.md region=layout:package role=layout -->
```text
utils/
├── README.md
├── __init__.py
├── _computation_cache.py
├── _line_arrays.py
├── adf_test.py
├── confidence_filtering_system.py
├── data_dict_to_numpy.py
├── filter_lines_by_quantile.py
├── find_price_lines.py
├── param_space.py
└── reporting.py
```

## Things to know

- This package is intentionally mixed. If a helper grows into a coherent subsystem, move it out of `utils`.
- `ParamSpace` retains the [legacy execution contract](../../docs/Universal-Experiment-Loop.md#legacy-execution-reference); new Python examples use MSQ.
- `data_dict_to_numpy` assumes the standard Limen split schema and supports model code.

## Read next

- [Utilities](../../docs/Utilities.md)
- [Universal Experiment Loop](../../docs/Universal-Experiment-Loop.md)
- [Standard Metrics Library](../../docs/Standard-Metrics-Library.md)
- [Single-File Decoder](../../docs/Single-File-Decoder.md)