Skip to main content

Router

Struct Router 

Source
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

Source

pub fn from_json_value(data: &Value) -> Result<Self>

Available on crate feature 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.

Source

pub fn from_json(text: &str) -> Result<Self>

Available on crate feature 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.

Source

pub fn load<P: AsRef<Path>>(path: P) -> Result<Self>

Available on crate feature json only.

Reads a router file.

§Errors

UcciError::InvalidRouter naming the path, for an unreadable file, invalid JSON or an invalid document.

Source

pub fn to_json_value(&self) -> Value

Available on crate feature json only.

The router as a ucci-router version 1 document. tau is written as null when unknown and created_by is CREATED_BY.

Source

pub fn to_json(&self) -> String

Available on crate feature 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.

Source

pub fn save<P: AsRef<Path>>(&self, path: P) -> Result<()>

Available on crate feature 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

Source

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.

Source

pub fn calibrator(&self) -> &IsotonicCalibrator

The calibration map g (Section 4.2).

Source

pub fn theta(&self) -> f64

The escalation threshold theta* (Eq. 6).

Source

pub fn costs(&self) -> &Costs

Per-query costs and cost model.

Source

pub fn grid_step(&self) -> f64

Resolution of the threshold grid used to choose theta*.

Source

pub fn tau(&self) -> Option<f64>

Accuracy target tau the threshold was chosen for, if known.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub fn route(&self, u: f64) -> Result<Route>

Decision and calibrated probability for one query.

§Errors

UcciError::NonFinite if u is NaN or infinite.

Source

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.

Source

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

As crate::policy::evaluate.

Source

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 Clone for Router

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for Router

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
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.

Source§

fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error>

Deserialize this value from the given Serde deserializer. Read more
Source§

impl PartialEq for Router

Source§

fn eq(&self, other: &Self) -> bool

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=. Read more
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.

Source§

fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error>

Serialize this value into the given Serde serializer. Read more
Source§

impl StructuralPartialEq for Router

Auto Trait Implementations§

§

impl Forget for Router

§

impl Freeze for Router

§

impl Move for Router

§

impl RefUnwindSafe for Router

§

impl Send for Router

§

impl Sync for Router

§

impl Unpin for Router

§

impl UnsafeUnpin for Router

§

impl UnwindSafe for Router

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> DeserializeOwned for T
where T: for<'de> Deserialize<'de>,

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.