pub struct Router { /* private fields */ }Expand description
A calibrated small-to-large cascade router with a chosen threshold.
See the module documentation for how to obtain one.
Implementations§
Source§impl Router
impl Router
Sourcepub fn from_json_value(data: &Value) -> Result<Self>
Available on crate feature json only.
pub fn from_json_value(data: &Value) -> Result<Self>
json only.Builds a router from a decoded ucci-router document, applying
every rule of the format (see the module documentation).
§Errors
UcciError::InvalidRouter naming the first problem found.
Sourcepub fn from_json(text: &str) -> Result<Self>
Available on crate feature json only.
pub fn from_json(text: &str) -> Result<Self>
json only.Parses a ucci-router JSON document (as written by the Python
package’s UCCIRouter.save or by Router::to_json).
§Errors
UcciError::InvalidRouter for invalid JSON or a document that
breaks a rule of the format.
Sourcepub fn load<P: AsRef<Path>>(path: P) -> Result<Self>
Available on crate feature json only.
pub fn load<P: AsRef<Path>>(path: P) -> Result<Self>
json only.Reads a router file.
§Errors
UcciError::InvalidRouter naming the path, for an unreadable
file, invalid JSON or an invalid document.
Sourcepub fn to_json_value(&self) -> Value
Available on crate feature json only.
pub fn to_json_value(&self) -> Value
json only.The router as a ucci-router version 1 document. tau is written
as null when unknown and created_by is CREATED_BY.
Sourcepub fn to_json(&self) -> String
Available on crate feature json only.
pub fn to_json(&self) -> String
json only.The router as a ucci-router JSON document, laid out like the
Python package writes it: one top-level key per line, lists on one
line (a calibrator with hundreds of knots stays a short,
diff-friendly file), trailing newline. Floats are written in
shortest round-trip form, so the file loads back bit for bit in
Rust and in Python.
Sourcepub fn save<P: AsRef<Path>>(&self, path: P) -> Result<()>
Available on crate feature json only.
pub fn save<P: AsRef<Path>>(&self, path: P) -> Result<()>
json only.Writes the router to path atomically: the JSON goes to a
temporary file in the same directory, which is then renamed over
path, so readers never see a half-written file.
§Errors
UcciError::InvalidRouter naming the path if the file cannot be
written.
Source§impl Router
impl Router
Sourcepub fn new(
calibrator: IsotonicCalibrator,
theta: f64,
costs: Costs,
) -> Result<Self>
pub fn new( calibrator: IsotonicCalibrator, theta: f64, costs: Costs, ) -> Result<Self>
A router from a calibrator, a threshold and costs, with the default grid step (0.005) and no accuracy target.
§Errors
UcciError::InvalidParameter for a non-finite theta or invalid
costs.
Sourcepub fn calibrator(&self) -> &IsotonicCalibrator
pub fn calibrator(&self) -> &IsotonicCalibrator
The calibration map g (Section 4.2).
Sourcepub fn budget(&self) -> Option<f64>
pub fn budget(&self) -> Option<f64>
Cost budget the threshold was chosen for (budget form of Eq. 7), if any. Not stored in router files.
Sourcepub fn choice(&self) -> Option<&ThresholdChoice>
pub fn choice(&self) -> Option<&ThresholdChoice>
Validation cost and accuracy of the chosen threshold, when the router
was built with CalibratedRouter::choose_threshold or
CalibratedRouter::choose_threshold_for_budget. Not stored in router
files.
Sourcepub fn created_by(&self) -> Option<&str>
pub fn created_by(&self) -> Option<&str>
The created_by field of the file this router was read from, if any.
Files written by this crate carry CREATED_BY.
Sourcepub fn with_grid_step(self, step: f64) -> Result<Self>
pub fn with_grid_step(self, step: f64) -> Result<Self>
A copy with a different grid step (recorded in router files).
§Errors
UcciError::InvalidParameter unless step lies in (0, 1] and
divides 1.
Sourcepub fn error_probability(&self, u: f64) -> Result<f64>
pub fn error_probability(&self, u: f64) -> Result<f64>
Calibrated forecast p_hat(x) = g(u(x)) (Section 4.3).
§Errors
UcciError::NonFinite if u is NaN or infinite.
Sourcepub fn escalate(&self, u: f64) -> Result<bool>
pub fn escalate(&self, u: f64) -> Result<bool>
True when a query with uncertainty u should go to the large model
(Eq. 6: g(u) > theta).
§Errors
UcciError::NonFinite if u is NaN or infinite.
Sourcepub fn route(&self, u: f64) -> Result<Route>
pub fn route(&self, u: f64) -> Result<Route>
Decision and calibrated probability for one query.
§Errors
UcciError::NonFinite if u is NaN or infinite.
Sourcepub fn route_many(&self, u: &[f64]) -> Result<Vec<Route>>
pub fn route_many(&self, u: &[f64]) -> Result<Vec<Route>>
Router::route for a batch of queries.
§Errors
UcciError::NonFinite naming the first NaN or infinite element.
Sourcepub fn evaluate(
&self,
u_test: &[f64],
small_score: &[f64],
large_score: &[f64],
) -> Result<ThresholdChoice>
pub fn evaluate( &self, u_test: &[f64], small_score: &[f64], large_score: &[f64], ) -> Result<ThresholdChoice>
Routes a labelled test split end to end and reports the actual cost, accuracy and escalation rate (step 3 of the protocol in Section 6.1).
§Errors
Sourcepub fn escalate_many(&self, u: &[f64]) -> Result<Vec<bool>>
pub fn escalate_many(&self, u: &[f64]) -> Result<Vec<bool>>
Escalation mask for a batch of queries.
§Errors
UcciError::NonFinite naming the first NaN or infinite element.
Trait Implementations§
Source§impl<'de> Deserialize<'de> for Router
Available on crate feature json only.Deserializes from a ucci-router document with the same validation
as Router::from_json. Needs a self-describing format.
impl<'de> Deserialize<'de> for Router
json only.Deserializes from a ucci-router document with the same validation
as Router::from_json. Needs a self-describing format.
Source§fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error>
fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error>
Source§impl Serialize for Router
Available on crate feature json only.Serializes as a ucci-router version 1 document, keys in the order
the Python package writes them.
impl Serialize for Router
json only.Serializes as a ucci-router version 1 document, keys in the order
the Python package writes them.