### Add Family to Quick Start Documentation

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/maintenance/adding-family.md

Example of how to document a new family in the Quick Start guide. This involves adding an entry to a table listing available data types, their corresponding families, and examples.

```markdown
<!-- docs/getting-started/quickstart.md -->

| Data Type | Family | Example |
|-----------|--------|---------|
| ... | ... | ... |
| Positive right-skewed | `"inversegaussian"` | Waiting times, durations |
```

--------------------------------

### Rust Trait Definition Start

Source: https://github.com/pricingfrontier/rustystats/blob/main/site/rust-guide/code-walkthrough/index.html

Example of the start of a trait definition block in Rust.

```Rust
{
```

--------------------------------

### Install Rust Toolchain

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/getting-started/installation.md

Install Rust and its associated tools using rustup, the official installer.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

--------------------------------

### Complete Ridge Regression Example

Source: https://github.com/pricingfrontier/rustystats/blob/main/site/components/regularization/index.html

Demonstrates a full Ridge regression setup using Rustystats with Gamma family, automatic CV, '1se' selection, and a specified seed.

```python
import rustystats as rs
import polars as pl

# Load data
df = pl.read_csv("insurance.csv")

# Ridge with automatic CV
ridge_result = rs.glm_dict(
    response="ClaimAmount",
    terms={"Age": {"type": "linear"}, "VehAge": {"type": "linear"}, "BonusMalus": {"type": "linear"}, "Density": {"type": "linear"}},
    data=df,
    family="gamma"
).fit(
    cv=5,
    regularization="ridge",
    n_alphas=50,
    selection="1se",
    cv_seed=42
)

print(f"Selected alpha: {ridge_result.alpha:.4f}")
print(f"CV deviance: {ridge_result.cv_deviance:.4f}")
print(ridge_result.summary())
```

--------------------------------

### Install uv Package Manager

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/getting-started/installation.md

Install uv, the recommended Python package manager, using its official installer script.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

--------------------------------

### Clone Repository and Install Hooks

Source: https://github.com/pricingfrontier/rustystats/blob/main/CONTRIBUTING.md

Clone the RustyStats repository and install pre-commit hooks using uv.

```bash
git clone https://github.com/PricingFrontier/rustystats.git
cd rustystats

uv run pre-commit install
```

--------------------------------

### Clone and Install RustyStats from Source

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/getting-started/installation.md

Clone the RustyStats repository and install it in development mode using uv and maturin.

```bash
# Clone the repository
git clone https://github.com/PricingFrontier/rustystats.git
cd rustystats

# Install in development mode
uv run maturin develop
```

--------------------------------

### Verify Rust Installation

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/getting-started/installation.md

Confirm that the Rust compiler and Cargo build tool are installed correctly.

```bash
rustc --version  # Should show version 1.70+
cargo --version
```

--------------------------------

### Flask API Example

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/api/serialization.md

Example of how to load a serialized model and serve predictions via a Flask API.

```APIDOC
## Flask API Example

### Description
Example of how to load a serialized model and serve predictions via a Flask API.

### Endpoint
`/predict`

### Method
POST

### Request Body
- **data** (DataFrame) - Required - DataFrame containing new data for prediction.

### Response
#### Success Response (200)
- **predictions** (list) - List of predictions.

### Request Example
```python
{
  "predictions": [prediction1, prediction2, ...]
}
```
```

--------------------------------

### Install and Use flamegraph for Rust

Source: https://github.com/pricingfrontier/rustystats/blob/main/site/maintenance/performance/index.html

Install the `flamegraph` tool and use it to generate flame graphs for your Rust binary.

```bash
cargo install flamegraph
cargo flamegraph --bin benchmark
```

--------------------------------

### Quick Start: Adding Inverse Gaussian Family

Source: https://github.com/pricingfrontier/rustystats/blob/main/site/maintenance/adding-family/index.html

Illustrates how to specify the Inverse Gaussian family in the quick start guide for positive right-skewed data like waiting times or durations.

```markdown
| Data Type | Family | Example |
|-----------|--------|---------|
| ... | ... | ... |
| Positive right-skewed | `"inversegaussian"` | Waiting times, durations |
```

--------------------------------

### Development Installation and Testing

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/index.md

Commands for setting up a development environment and running tests for the RustyStats project.

```bash
# Development installation
cd rustystats
uv run maturin develop

# Run tests
uv run pytest tests/python/ -v

```

--------------------------------

### Complete Example: Ridge, Lasso, and Elastic Net

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/components/regularization.md

A comprehensive example demonstrating the application of Ridge, Lasso, and Elastic Net regularization with automatic CV strength selection, including data loading and result interpretation.

```python
import rustystats as rs
import polars as pl

# Load data
df = pl.read_csv("insurance.csv")

# Ridge with automatic CV
ridge_result = rs.glm_dict(
    response="ClaimAmount",
    terms={"Age": {"type": "linear"}, "VehAge": {"type": "linear"}, "BonusMalus": {"type": "linear"}, "Density": {"type": "linear"}},
    data=df,
    family="gamma"
).fit(
    cv=5,
    regularization="ridge",
    n_alphas=50,
    selection="1se",
    cv_seed=42
)

print(f"Selected alpha: {ridge_result.alpha:.4f}")
print(f"CV deviance: {ridge_result.cv_deviance:.4f}")
print(ridge_result.summary())

# Lasso for variable selection
lasso_result = rs.glm_dict(
    response="ClaimCount",
    terms={f"x{i}": {"type": "linear"} for i in range(100)},
    data=df,
    family="poisson"
).fit(
    cv=5,
    regularization="lasso",
    n_alphas=30
)

# See which coefficients are non-zero
nonzero = [(name, coef) for name, coef in 
           zip(lasso_result.feature_names, lasso_result.params) 
           if abs(coef) > 1e-6]
print(f"Selected {len(nonzero)} features")

# Elastic Net for correlated groups
# Note: The original example used 'data=df' without specifying response/terms for the enet_result.
# Assuming a placeholder 'y' and some terms for demonstration.
enet_result = rs.glm_dict(response="y", terms={f"x{i}": {"type": "linear"} for i in range(1, 6)}, data=df).fit(
    cv=5,
    regularization="elastic_net",
    l1_ratio=0.5,  # 50% L1, 50% L2
    n_alphas=20
)
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/maintenance/actuarial-methodology-hardening-implementation-plan.md

Install git hooks to automatically run formatting and linting checks. This ensures code quality is maintained before commits.

```bash
uv run pre-commit install
```

--------------------------------

### Verify Rust and Cargo Installation

Source: https://github.com/pricingfrontier/rustystats/blob/main/site/getting-started/installation/index.html

Check the installed versions of the Rust compiler (rustc) and the Cargo build tool.

```bash
rustc --version  # Should show version 1.70+ cargo --version
```

--------------------------------

### Regularized Encoding Example (prior_weight = 1.0)

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/theory/target-encoding.md

Calculates an example of regularized target encoding where a single observation with target=1 is blended with a prior of 0.5 and a prior weight of 1.0.

```latex
\text{Encoded} = \frac{1.0 + 0.5 \times 1.0}{1 + 1.0} = \frac{1.5}{2} = 0.75
```

--------------------------------

### Stacked CSV Format Example (Base and Categorical)

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/api/rate-tables.md

Example of the stacked CSV format output. It shows the `_base` block with schema and model parameters, followed by a categorical term's rating table.

```text
_base
field,value
schema_version,1
family,poisson
link,log
base_eta,-3.2
base_rel,0.0408

brand_region_fts
brand,region,brand_region_fts,eta,rel
Ford,North,0.07,0.0651,1.0673
BMW,South,-0.03,-0.0279,0.9725
<default>,<default>,0.0,0.0,1.0
```

--------------------------------

### Rust Ownership Examples

Source: https://github.com/pricingfrontier/rustystats/blob/main/site/rust-guide/fundamentals/index.html

Demonstrates taking ownership, borrowing immutably, and borrowing mutably with Array1<f64>.

```rust
pub fn process(data: Array1<f64>) -> Array1<f64> {
    // data is owned here, will be dropped when function returns
    data * 2.0
}
```

```rust
pub fn calculate_mean(data: &Array1<f64>) -> f64 {
    data.sum() / data.len() as f64
}
```

```rust
pub fn normalize(data: &mut Array1<f64>) {
    let mean = data.mean().unwrap();
    *data -= mean;
}
```

--------------------------------

### Boosting Loop Example with Offset

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/api/working-response-weights.md

Demonstrates how `working_response_weights` can be used within a boosting loop. The offset (e.g., log-exposure) is held fixed, while the linear predictor `eta` is updated iteratively based on the output of a fitted tree. This example uses a Poisson family.

```python
eta = np.full_like(y, fill_value=initial_eta, dtype=np.float64)
log_exposure = np.log(exposure)

for layer in range(n_layers):
    z, w = rs.working_response_weights(
        y, eta, family="poisson", offset=log_exposure
    )
    tree = fit_tree(X, z, sample_weight=w)   # any weighted regressor
    eta = eta + tree.predict(X)              # accumulate on link scale
```

--------------------------------

### Rust Documentation Comment

Source: https://github.com/pricingfrontier/rustystats/blob/main/site/rust-guide/code-walkthrough/index.html

Example of a documentation comment in Rust.

```Rust
/// Documentation comment (appears in generated docs)
```

--------------------------------

### Example Log Link Function Implementation in Rust

Source: https://github.com/pricingfrontier/rustystats/blob/main/site/architecture/rust-core/index.html

Shows the implementation of the log link function, including its inverse.

```rust
pub struct Log;

impl Link for Log {
    fn link(&self, mu: f64) -> f64 {
        mu.ln()
    }

    fn inv_link(&self, eta: f64) -> f64 {
        eta.exp()
    }
}
```

--------------------------------

### Verify Development Setup

Source: https://github.com/pricingfrontier/rustystats/blob/main/CONTRIBUTING.md

Run workspace tests and Python tests to ensure the development environment is correctly set up.

```bash
cargo test --workspace
uv run --extra dev pytest tests/python/ -v
```

--------------------------------

### Rust Builder-style API Example

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/rust-guide/code-walkthrough.md

Illustrates using struct initialization with `Default::default()` to set specific fields and use defaults for the rest. Useful for complex configurations.

```rust
let config = IRLSConfig {
    max_iterations: 50,
    ..Default::default()  // Fill remaining fields with defaults
};

```

--------------------------------

### Run Diagnostics with Base Predictions and Exposure

Source: https://github.com/pricingfrontier/rustystats/blob/main/specs/destyler-methodology-diagnostics-support.md

Execute the diagnostics function with specified categorical and continuous factors, base predictions, exposure, weights, and ranking strategy. This example demonstrates a comprehensive setup for diagnostics.

```python
diag = glm.diagnostics(
    train_data=train.with_columns(pl.Series("gbm_mu", gbm_train)),
    test_data=test.with_columns(pl.Series("gbm_mu", gbm_test)),
    categorical_factors=["VehBrand", "VehGas", "Region"],
    continuous_factors=["VehAge", "DrivAge", "BonusMalus"],
    base_predictions="gbm_mu",
    exposure="Exposure",
    weights="policy_weight",
    ranking="auto",
)
```

--------------------------------

### Create Rust Struct Instances

Source: https://github.com/pricingfrontier/rustystats/blob/main/site/rust-guide/fundamentals/index.html

Shows how to create struct instances using field initialization and the field shorthand. Also demonstrates copying remaining fields.

```rust
let config = IRLSConfig {
    max_iterations: 25,
    tolerance: 1e-8,
    min_weight: 1e-10,
    verbose: false,
};
```

```rust
let max_iterations = 50;
let config2 = IRLSConfig {
    max_iterations,
    ..config
};
```

--------------------------------

### Module-Level Documentation with `//!`

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/maintenance/rust-best-practices.md

Demonstrates using module-level documentation comments (`//!`) to provide an overview of a module's purpose, contents, and usage examples.

```rust
"//! # Distribution Families
///
/// This module implements distribution families for GLMs.
///
/// ## Available Families
/// - [`GaussianFamily`] - For continuous data
/// - [`PoissonFamily`] - For count data
/// - [`BinomialFamily`] - For binary data
///
/// ## Example
/// ```
/// use rustystats_core::families::{Family, PoissonFamily};
/// ```

pub struct PoissonFamily;
```

--------------------------------

### List Installed Python Packages with uv

Source: https://github.com/pricingfrontier/rustystats/blob/main/site/getting-started/installation/index.html

Check if RustyStats is installed in the current Python environment using uv.

```bash
uv pip list | grep rustystats
```

--------------------------------

### Basic Rust Test Implementation

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/maintenance/testing.md

Demonstrates the fundamental structure of a Rust unit test, including setup, action, and assertion phases.

```rust
#[cfg(test)]
mod tests {
    use super::*;
    use ndarray::array;
    use approx::assert_relative_eq;
    
    #[test]
    fn test_basic_functionality() {
        // Arrange
        let input = array![1.0, 2.0, 3.0];
        
        // Act
        let result = process(&input);
        
        // Assert
        assert_eq!(result.len(), 3);
    }
}
```

--------------------------------

### Recommended Metadata for Destyler

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/maintenance/input-transforms.md

Provides an example of recommended metadata for the 'destyler' producer when using lookup transforms. This metadata aids in auditing and understanding the transform's origin and configuration.

```python
{
    "producer": "destyler",
    "kind": "frozen_categorical_main",
    "teacher_family": "poisson",
    "teacher_depth": 2,
    "default_meaning": "centered_no_effect",
    "shrinkage": "buhlmann_median_mass",
}
```

--------------------------------

### Verify Docs Build

Source: https://github.com/pricingfrontier/rustystats/blob/main/site/maintenance/adding-link/index.html

Build the project documentation using MkDocs. This command checks if the documentation can be successfully generated.

```bash
mkdocs build
```

--------------------------------

### AWS Lambda Example

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/api/serialization.md

Example of how to load a serialized model and serve predictions within an AWS Lambda function.

```APIDOC
## AWS Lambda Example

### Description
Example of how to load a serialized model and serve predictions within an AWS Lambda function.

### Endpoint
(Lambda Function Handler)

### Method
POST (via API Gateway)

### Request Body
- **body** (string) - Required - JSON string representing a DataFrame containing new data for prediction.

### Response
#### Success Response (200)
- **statusCode** (integer) - 200
- **body** (string) - JSON string containing a list of predictions.

### Request Example
```json
{
  "statusCode": 200,
  "body": "{\"predictions\": [prediction1, prediction2, ...] }"
}
```
```

--------------------------------

### Builder Pattern Implementation Methods

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/rust-guide/fundamentals.md

Provides example implementation methods for the Builder pattern, demonstrating how `new` initializes the struct and chained methods (`max_iterations`, `tolerance`) modify and return `self`.

```rust
impl IRLSConfig {
    pub fn new() -> Self { ... }
    
    pub fn max_iterations(mut self, n: usize) -> Self {
        self.max_iter = n;
        self
    }
    
    pub fn tolerance(mut self, tol: f64) -> Self {
        self.tolerance = tol;
        self
    }
}
```

--------------------------------

### Install rustystats

Source: https://github.com/pricingfrontier/rustystats/blob/main/README.md

Use `uv add` to install the rustystats package. This command adds the package to your project's dependencies.

```bash
uv add rustystats
```

--------------------------------

### Python User Code Example

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/architecture/overview.md

Example of how a Python user would import and use the rustystats library for a GLM fit.

```python
import rustystats as rs; rs.glm_dict(...).fit()
```

--------------------------------

### FormulaGLMDict Class Initialization and Fit Method

Source: https://github.com/pricingfrontier/rustystats/blob/main/site/architecture/data-flow/index.html

Illustrates the internal structure of `FormulaGLMDict`, showing how it initializes with a dictionary specification and prepares data for fitting. It extracts the response, builds the design matrix, handles optional offsets, and calls the core fitting function.

```python
class FormulaGLMDict:
    def __init__(self, response, terms, data, family, offset=None, ...):
        self.response = response
        self.data = data

        # Convert dict spec to ParsedFormula
        parsed = dict_to_parsed_formula(
            response=response, terms=terms, ...
        )
    
    def fit(self):
        # 1. Extract response
        y = self.data[self.response].to_numpy()

        # 2. Build design matrix (already done in __init__)
        X = self.X

        # 3. Handle offset
        offset = None
        if self.offset_col:
            offset = np.log(self.data[self.offset_col].to_numpy())

        # 4. Call array API
        result = fit_glm(y, X, family=self.family, offset=offset, ...)

        # 5. Attach metadata
        result._feature_names = self._feature_names
        return result
```

--------------------------------

### Formula API User Code Example

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/architecture/data-flow.md

Example of using the Formula API in Python with Polars and Rustystats to fit a GLM model.

```python
import rustystats as rs
import polars as pl

data = pl.read_parquet("insurance.parquet")

result = rs.glm_dict(
    response="ClaimNb",
    terms={
        "Age": {"type": "linear"},
        "Region": {"type": "categorical"},
        "VehPower": {"type": "bs", "df": 4},
    },
    data=data,
    family="poisson",
    exposure="Exposure",
).fit()
```

--------------------------------

### Rebuild, Test, and Verify Documentation

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/maintenance/adding-family.md

Commands to rebuild the Rust library, run all tests, and verify the documentation build. These steps are crucial after adding new functionality.

```bash
# Rebuild
maturin develop

# Run all tests
cargo test -p rustystats-core
uv run pytest tests/python/ -v

# Verify docs build
mkdocs build
```

--------------------------------

### Verify RustyStats Installation with a GLM Test

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/getting-started/installation.md

Run a simple Generalized Linear Model (GLM) using the installed RustyStats library to confirm it's functioning correctly.

```python
import rustystats as rs
import numpy as np

# Quick test
y = np.array([1.0, 2.0, 3.0, 4.0, 5.0])
X = np.column_stack([np.ones(5), np.array([1, 2, 3, 4, 5])])

result = rs.fit_glm(y, X, family="gaussian")
print(f"Coefficients: {result.params}")
print(f"RustyStats is working!")
```

--------------------------------

### Rust Module Structure Example

Source: https://github.com/pricingfrontier/rustystats/blob/main/site/rust-guide/fundamentals/index.html

Illustrates a typical Rust crate structure with nested modules and submodules. Shows how to declare and re-export modules and traits.

```text
crate_name/
├── src/
│   ├── lib.rs           // Crate root
│   ├── families/        // Module directory
│   │   ├── mod.rs       // Module root
│   │   ├── poisson.rs   // Submodule
│   │   └── gaussian.rs  // Submodule
│   └── solvers/
│       ├── mod.rs
│       └── irls.rs
```

```rust
pub mod families;  // Declares the families module
pub mod solvers;
```

```rust
mod poisson;   // Private submodule
mod gaussian;

pub use poisson::PoissonFamily;   // Re-export publicly
pub use gaussian::GaussianFamily;

pub trait Family { ... }
```

--------------------------------

### Rust Memory View Example

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/architecture/data-flow.md

Demonstrates how to create a view of NumPy memory in Rust without copying the data, useful for read-only access.

```rust
let y_view = y.as_array();  // Borrows NumPy memory
```

--------------------------------

### Example: AWS Lambda Function for Model Prediction

Source: https://github.com/pricingfrontier/rustystats/blob/main/site/api/serialization/index.html

Provides an example of an AWS Lambda function handler that loads a serialized model and performs predictions. This is suitable for serverless deployment.

```python
from rustystats.serialization import GLMModel
import json

# Load the model once when the Lambda function is initialized
with open("model.bytes", "rb") as f:
    model = GLMModel.from_bytes(f.read())

def lambda_handler(event, context):
    # Assuming input data is in the event object
    # The exact structure depends on your Lambda trigger (e.g., API Gateway)
    features = event.get("features")
    
    if not features:
        return {
            "statusCode": 400,
            "body": json.dumps({"error": "'features' not found in request body"})
        }
        
    try:
        predictions = model.predict(features)
        return {
            "statusCode": 200,
            "body": json.dumps({"predictions": predictions})
        }
    except Exception as e:
        return {
            "statusCode": 500,
            "body": json.dumps({"error": str(e)})
        }
```

--------------------------------

### Stacked CSV Format Example

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/maintenance/input-transforms.md

Illustrates the structure of a `stacked_csv` file, showing how different tables (base, manifest, and effect tables) are organized with titles, headers, and data rows.

```text
_base
field,value
schema_version,1
family,poisson
link,log
base_eta,-3.2
base_rel,0.0408

brand_region
brand,region,frozen_effect,eta,rel
Ford,North,0.07,0.0651,1.0673
BMW,South,-0.03,-0.0279,0.9725
<default>,<default>,0.0,0.0,1.0

postcode
postcode,group,eta,rel
AB1,grp_1,0.1133,1.1200
AB2,grp_7,-0.0513,0.9500
<unseen>,other,0.0,1.0
```

--------------------------------

### Python GLM Dict API Examples

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/maintenance/actuarial-methodology-hardening.md

Examples demonstrating the preferred new spelling for exposure in GLM dict construction, the continued support for link-scale offsets, and the legacy spelling.

```python
# Preferred new spelling
rs.glm_dict(..., family="poisson", exposure="Exposure")
```

```python
# Link-scale offset remains supported
rs.glm_dict(..., family="poisson", offset=np.log(exposure), exposure=exposure)
```

```python
# Legacy spelling remains accepted for now
rs.glm_dict(..., family="poisson", offset="Exposure")
```

--------------------------------

### Dictionary Format Example

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/api/rate-tables.md

An example structure of the dictionary format returned by `to_rate_tables(format='dict')`. It includes schema version, model kind, family, link, base rates, manifest, and tables.

```json
{
    "schema_version": 1,
    "kind": "rustystats_rate_tables",
    "family": "poisson",
    "link": "log",
    "base": {"eta": -3.2, "rel": 0.0408},
    "manifest": [...],
    "tables": [...],
}
```

--------------------------------

### High-Cardinality Features Example in Rustystats

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/api/dict-api.md

Demonstrates handling high-cardinality features using target encoding in Rustystats. This example includes interactions with target encoding for combined features like Brand:Region.

```python
result = rs.glm_dict(
    response="ClaimCount",
    terms={
        "Age": {"type": "bs"},
        "Brand": {"type": "target_encoding"},
        "Model": {"type": "target_encoding"},
        "ZipCode": {"type": "target_encoding", "prior_weight": 2.0},
    },
    interactions=[
        {
            "Brand": {"type": "categorical"},
            "Region": {"type": "categorical"},
            "target_encoding": True,  # TE(Brand:Region)
        },
    ],
    data=data,
    family="poisson",
    exposure="Exposure",
).fit()
```

--------------------------------

### Profiling Rust Code with flamegraph

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/maintenance/performance.md

Generate flame graphs for Rust applications using the `cargo-flamegraph` tool. Install it via `cargo install flamegraph` and run it with `cargo flamegraph --bin <your_binary>`.

```bash
# Install
cargo install flamegraph

# Generate
cargo flamegraph --bin benchmark
```

--------------------------------

### Rust: X'WX Computation

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/maintenance/performance.md

Illustrates the Gram matrix computation in Rust, which is often a performance bottleneck. Optimization advice suggests using a flat Vec for better cache performance.

```rust
// O(np²) - parallelized
let xtwx = compute_gram_matrix(x, w);
```

--------------------------------

### SIMD-Friendly Loop Structure

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/components/solvers.md

Illustrates loop structures optimized for SIMD auto-vectorization. Contiguous memory access (like in the 'good' example) is preferred over strided access (like in the 'bad' example) for better performance.

```rust
// Good: contiguous memory access
for i in 0..n {
    result += x[i] * w[i];
}

// Bad: strided access
for i in 0..n {
    result += x[[i, j]] * w[i];  // Column access is strided
}
```

--------------------------------

### Best Practices for Production and Reproducibility

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/components/regularization.md

Provides examples for applying best practices in production, such as using the '1se' selection method for conservatism, and ensuring reproducibility by setting a CV seed.

```python
# Production: use "1se" for more conservative selection
result = model.fit(regularization="ridge", selection="1se")

# Reproducibility: set seed
result = model.fit(regularization="ridge", cv_seed=42)
```

--------------------------------

### Example: Flask API for Model Prediction

Source: https://github.com/pricingfrontier/rustystats/blob/main/site/api/serialization/index.html

Demonstrates how to create a simple Flask API endpoint that loads a serialized model and uses it for predictions.

```python
from flask import Flask, request, jsonify
from rustystats.serialization import GLMModel

app = Flask(__name__)

# Load the model once when the application starts
with open("model.bytes", "rb") as f:
    model = GLMModel.from_bytes(f.read())

@app.route("/predict", methods=["POST"])
def predict():
    data = request.get_json()
    # Assuming input data is a list of lists or similar structure
    predictions = model.predict(data["features"])
    return jsonify({"predictions": predictions})

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=8000)
```

--------------------------------

### Documenting Public Rust Functions with Doc Comments

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/maintenance/rust-best-practices.md

Shows how to use Rust's documentation comments (`///`) to explain public functions, including arguments, return values, and usage examples.

```rust
/// Compute the variance function V(μ) for the Poisson family.
/// 
/// For Poisson, V(μ) = μ (variance equals mean).
/// 
/// # Arguments
/// * `mu` - Array of mean values, must be positive
/// 
/// # Returns
/// Array of variance values
/// 
/// # Example
/// ```
/// use rustystats_core::families::PoissonFamily;
/// use ndarray::array;
/// 
/// let family = PoissonFamily;
/// let mu = array![1.0, 2.0, 3.0];
/// let var = family.variance(&mu);
/// assert_eq!(var, mu);
/// ```
pub fn variance(&self, mu: &Array1<f64>) -> Array1<f64> {
    mu.clone()
}
```

--------------------------------

### Regularized Model Example in Rustystats

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/api/dict-api.md

Example of fitting a regularized model using elastic net with cross-validation selection. It demonstrates how to specify regularization parameters and access results like selected alpha and non-zero features.

```python
result = rs.glm_dict(
    response="ClaimCount",
    terms={
        "Age": {"type": "linear"},
        "Income": {"type": "linear"},
        "Region": {"type": "categorical"},
    },
    data=data,
    family="poisson",
).fit(regularization="elastic_net", selection="1se")

print(f"Selected alpha: {result.alpha}")
print(f"Non-zero features: {result.n_nonzero()}")
```

--------------------------------

### Stacked CSV Format Example (Spline Approximation)

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/api/rate-tables.md

Example of a spline approximation table in stacked CSV format. It lists grid values for a term (e.g., 'Age') and their corresponding evaluated 'eta' and 'rel' values.

```text
Age,eta,rel
18,-0.1200,0.8869
21,-0.0830,0.9203
25,-0.0200,0.9802
```

--------------------------------

### Factor Level Metrics Example

Source: https://github.com/pricingfrontier/rustystats/blob/main/examples/frequency_code.ipynb

Displays metrics for categorical factors, showing counts, exposure, actual vs. predicted values, AE ratio, and residual means for each level.

```python
FactorLevelMetrics(level='D', n=90936, exposure=46259.62, actual=0.107675, predicted=0.105298, ae_ratio=1.0226, residual_mean=-0.173313), FactorLevelMetrics(level='E', n=82103, exposure=38213.29, actual=0.121738, predicted=0.12036, ae_ratio=1.0115, residual_mean=-0.173818), FactorLevelMetrics(level='A', n=62417, exposure=37146.86, actual=0.078526, predicted=0.081878, ae_ratio=0.9591, residual_mean=-0.17944), FactorLevelMetrics(level='B', n=45118, exposure=25768.6, actual=0.087471, predicted=0.087028, ae_ratio=1.0051, residual_mean=-0.174214), FactorLevelMetrics(level='F', n=10707, exposure=4849.01, actual=0.137554, predicted=0.147441, ae_ratio=0.9329, residual_mean=-0.19044)], 'VehBrand': [FactorLevelMetrics(level='B1', n=97668, exposure=57234.42, actual=0.089859, predicted=0.089086, ae_ratio=1.0087, residual_mean=-0.177411), FactorLevelMetrics(level='B2', n=95912, exposure=56844.23, actual=0.090335, predicted=0.089764, ae_ratio=1.0064, residual_mean=-0.178467), FactorLevelMetrics(level='B12', n=99403, exposure=38883.59, actual=0.132987, predicted=0.133056, ae_ratio=0.9995, residual_mean=-0.167002), FactorLevelMetrics(level='B3', n=32061, exposure=17150.42, actual=0.101863, predicted=0.099137, ae_ratio=1.0275, residual_mean=-0.173186), FactorLevelMetrics(level='B5', n=20895, exposure=12017.6, actual=0.100519, predicted=0.096421, ae_ratio=1.0425, residual_mean=-0.174623), FactorLevelMetrics(level='B6', n=17027, exposure=9393.85, actual=0.091443, predicted=0.094426, ae_ratio=0.9684, residual_mean=-0.180019), FactorLevelMetrics(level='B4', n=15088, exposure=8239.36, actual=0.090056, predicted=0.096738, ae_ratio=0.9309, residual_mean=-0.183574), FactorLevelMetrics(level='B10', n=10638, exposure=5718.14, actual=0.08919, predicted=0.08801, ae_ratio=1.0134, residual_mean=-0.170544), FactorLevelMetrics(level='B11', n=8061, exposure=4064.79, actual=0.102342, predicted=0.096743, ae_ratio=1.0579, residual_mean=-0.165649), FactorLevelMetrics(level='B13', n=7275, exposure=4027.57, actual=0.093853, predicted=0.092716, ae_ratio=1.0123, residual_mean=-0.177057), FactorLevelMetrics(level='B14', n=2411, exposure=1356.92, actual=0.072959, predicted=0.082077, ae_ratio=0.8889, residual_mean=-0.183957)], 'VehGas': [FactorLevelMetrics(level='Regular', n=207225, exposure=112390.29, actual=0.102073, predicted=0.100832, ae_ratio=1.0123, residual_mean=-0.175434), FactorLevelMetrics(level='Diesel', n=199214, exposure=102540.61, actual=0.096898, predicted=0.097199, ae_ratio=0.9969, residual_mean=-0.173723)]}
```

--------------------------------

### Insurance Frequency Model Example in Rustystats

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/api/dict-api.md

A complete example demonstrating how to build and fit an insurance frequency model using the glm_dict function. It includes defining response, terms, interactions, data, and family, with optional exposure and seed.

```python
import rustystats as rs
import polars as pl

data = pl.read_parquet("insurance.parquet")

result = rs.glm_dict(
    response="ClaimCount",
    terms={
        "VehAge": {"type": "bs", "monotonicity": "increasing"},
        "DrivAge": {"type": "bs"},
        "BonusMalus": {"type": "linear", "monotonicity": "increasing"},
        "VehPower": {"type": "linear"},
        "Region": {"type": "categorical"},
        "Brand": {"type": "target_encoding"},
    },
    interactions=[
        {
            "VehAge": {"type": "linear"},
            "Region": {"type": "categorical"},
            "include_main": True,
        },
    ],
    data=data,
    family="poisson",
    exposure="Exposure",
    seed=42,
).fit()

print(result.summary())
```

--------------------------------

### Rust Memory Copy Example

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/architecture/data-flow.md

Shows how to create an owned copy of NumPy data in Rust, which is necessary when Rust needs to take ownership of the data.

```rust
let y_owned = y.as_array().to_owned();  // Copies to Rust memory
```

--------------------------------

### Lasso Path Computation with Warm Starts

Source: https://github.com/pricingfrontier/rustystats/blob/main/docs/components/solvers.md

Computes the regularization path for Lasso regression using coordinate descent. It utilizes warm starts by initializing the coefficient vector from the previous alpha's solution, improving performance for sequential alpha values.

```rust
pub fn lasso_path(
    y: &Array1<f64>,
    x: &Array2<f64>,
    alphas: &[f64],  // Decreasing sequence
    ...
) -> Vec<IRLSResult> {
    let mut results = Vec::with_capacity(alphas.len());
    let mut beta = Array1::zeros(p);  // Start from zero
    
    for &alpha in alphas {
        // Warm start from previous solution
        let config = RegularizationConfig { alpha, ... };
        let result = fit_glm_coordinate_descent(
            ...,
            initial_beta: Some(&beta),
        )?;
        
        beta = result.coefficients.clone();
        results.push(result);
    }
    
    results
}
```