blr-active 0.1.0

Active learning orchestration for Bayesian Linear Regression with Automatic Relevance Determination
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

# blr-active: Active Learning Orchestration for Sensor Calibration

**4-phase active learning workflow for noise-aware, precision-targeted sensor calibration.**

[![Crates.io](https://img.shields.io/crates/v/blr-active.svg)](https://crates.io/crates/blr-active)
[![Docs](https://img.shields.io/docsrs/blr-active/latest)](https://docs.rs/blr-active/)
[![License](https://img.shields.io/crates/l/blr-active.svg)](https://github.com/wamli/blr-active/blob/main/LICENSE)

## Overview

`blr-active` implements a 4-phase active learning workflow for precision-targeted sensor calibration,
built on top of the `blr-core` crate's Bayesian Linear Regression with Automatic Relevance Determination.

```text
blr-core  (pure BLR+ARD math)
    └── blr-active  (this crate: active learning loop, precision tiers)
```

## Features

- ✓ **4-Phase Calibration Workflow**: Noise characterisation → exploration → active learning → completion
- ✓ **Noise-Aware Precision Tiers**: Map sensor noise floor to realistic precision goals (Low/Moderate/High/Max)
- ✓ **5 Active Learning Algorithms**: Variance sampling, mutual information, goal-based, noise-floor detection
- ✓ **Feasibility Assessment**: Predicts whether a precision goal is achievable before collecting data
- ✓ **Session History Export**: JSON export of all measurements, precision records, and convergence data
- ✓ **Zero panics on valid input**: All errors returned as `ALError`

## Installation

```toml
[dependencies]
blr-active = "0.1"
blr-core   = "0.1"  # required for BLR+ARD fitting
```

## Quick Start: Noise Characterisation

```rust,no_run
use blr_active::{NoiseCalibrationSession, PrecisionLevel};
use blr_core::noise_estimation::estimate_noise_with_confidence;

// After an initial fit on 15 calibration points (beta from blr-core):
let noise_est = estimate_noise_with_confidence(25.0, 15, 6);
let mut noise_session = NoiseCalibrationSession::new(noise_est);

// Inspect precision tiers
for tier in noise_session.precision_tiers() {
    println!("{:?}: target std = {:.4}", tier.level, tier.target_std);
}

// Set precision goal
noise_session.set_goal(PrecisionLevel::Moderate).expect("feasible goal");
```

## Quick Start: Active Learning Loop

```rust,no_run
use blr_active::{CalibrationSession, SessionConfig, IterationOutcome};

let config = SessionConfig::default();
let mut session = CalibrationSession::new(config);

// Seed with initial measurements
for (x, y) in initial_data {
    session.add_measurement(x, y);
}

loop {
    match session.next_iteration()? {
        IterationOutcome::RecommendNext { sample } => {
            let y = measure_sensor(sample.x);
            session.add_measurement(sample.x, y);
        }
        IterationOutcome::PrecisionMet { final_std } => {
            println!("Done! Precision std: {:.4}", final_std);
            break;
        }
        IterationOutcome::NoiseFloorHit => { println!("At noise floor."); break; }
        IterationOutcome::MaxIterationsReached => { break; }
    }
}
```

## The 4-Phase Workflow

| Phase | Component | Description |
|-------|-----------|-------------|
| 0 | `NoiseCalibrationSession` | Noise characterisation → choose precision tier |
| 1 | `CalibrationSession` | Initial data collection across sensor range |
| 2 | `CalibrationSession::next_iteration()` | Active sample selection → converge |
| 3 | `export_history_json()` | Store calibration results and provenance |

## Precision Tiers

| Tier | Factor × σ_noise | Est. samples | Use case |
|------|-----------------|--------------|----------|
| Low | 5.0× | ~10 | Rapid commissioning |
| Moderate | 3.0× | ~25 | Typical production calibration |
| High | 1.5× | ~60 | Demanding applications |
| Max | 1.0× | ~200 | Theoretical sensor limit |

## Algorithm Summary

| Module | Algorithm | Description |
|--------|-----------|-------------|
| `active_learning::variance` | Alg. 1 | Posterior variance computation |
| `active_learning::acquisition` | Alg. 2 | Variance-maximizing acquisition |
| `active_learning::precision` | Alg. 3 | Precision assessment and goal checking |
| `active_learning::noise_floor` | Alg. 4 | Noise floor (plateau) detection |
| `active_learning::orchestration` | Alg. 5 | Synchronous calibration state machine |

## Examples

```bash
cargo run --example quick_start -p blr-active
cargo run --example multi_sensor_workflow -p blr-active
```

## Compatibility

- **Rust**: 1.70+
- **Platforms**: Linux, macOS, Windows, WebAssembly (WASI Preview 2)
- **License**: Apache 2.0

## References

- Settles, B. (2009). "Active Learning Literature Survey." UW-Madison TR 1648.
- MacKay, D. J. C. (1992). "Information-Based Objective Functions for Active Data Selection."
  *Neural Computation*, 4(4), 590–604.
- Tipping, M. E. (2001). "Sparse Bayesian Learning and the Relevance Vector Machine."
  *JMLR*, 1, 211–244.

## License

Licensed under the Apache License, Version 2.0. See [`LICENSE`](LICENSE) for details.

## Contributing

Contributions are welcome. Please ensure:
- All tests pass: `cargo test -p blr-active`
- Documentation is updated: `cargo doc -p blr-active --no-deps --open`
- Code follows project conventions (see blr-core for style reference)