Struct lace::Engine

pub struct Engine {
    pub states: Vec<State>,
    pub state_ids: Vec<usize>,
    pub codebook: Codebook,
    pub rng: Xoshiro256Plus,
}

The engine runs states in parallel

Fields

states: Vec<State>

Vector of states

state_ids: Vec<usize>

codebook: Codebook

rng: Xoshiro256Plus

Implementations

impl Engine

Maintains and samples states

pub fn new( n_states: usize, codebook: Codebook, data_source: DataSource, id_offset: usize, rng: Xoshiro256Plus ) -> Result<Self, NewEngineError>

Create a new engine

Arguments

• n_states: number of states
• id_offset: the state IDs will start at id_offset. This is useful for when you run multiple engines on multiple machines and want to easily combine the states in a single Oracle after the runs
• data_source: struct defining the type or data and path
• id_offset: the state IDs will be 0+id_offset, ..., n_states + id_offset. If offset is helpful when you want to run a single model on multiple machines and merge the states into the same metadata folder.
• rng: Random number generator

pub fn seed_from_u64(&mut self, seed: u64)

Re-seed the RNG

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

Load a lacefile into an Engine.

pub fn del_rows_at(&mut self, ix: usize, n: usize)

Delete n rows starting at index ix.

If ix + n exceeds the number of rows, all of the rows starting at ix will be deleted.

pub fn del_column<Ix: ColumnIndex>( &mut self, col_ix: Ix ) -> Result<(), IndexError>

Delete the column at col_ix

Example

use lace::examples::Example;
use lace::OracleT;

let mut engine = Example::Animals.engine().unwrap();

let shape = engine.shape();
assert_eq!(shape, (50, 85, 16));

// String index
engine.del_column("swims");
assert_eq!(engine.shape(), (50, 84, 16));

// Integer index
engine.del_column(3);
assert_eq!(engine.shape(), (50, 83, 16));

Deleting a column that does not exist returns and IndexError

let mut engine = Example::Animals.engine().unwrap();

let result = engine.del_column("likes_milk_in_coffee");
assert!(result.is_err());

pub fn insert_data<R: RowIndex, C: ColumnIndex>( &mut self, rows: Vec<Row<R, C>>, new_metadata: Option<ColMetadataList>, mode: WriteMode ) -> Result<InsertDataActions, InsertDataError>

Insert new, or overwrite existing data

Notes

It is assumed that the user will run a transition after the new data are inserted. No effort is made to update any of the state according to the MCMC kernel, so the state will likely be sub optimal.

New columns are assigned to a random existing view; new rows are reassigned using the Gibbs kernel. Overwritten cells are left alone.

When extending the support of a categorical column with a value_map, you must supply an entry in column_metadata for that column, and the entry must have a value_map that contains mapping for all valid values including those being added.

Arguments

• rows: The rows of data containing the cells to insert or re-write
• new_metadata: Contains the column metadata for columns to be inserted. The columns will be inserted in the order they appear in the metadata list. If there are columns that appear in the column metadata that do not appear in rows, it will cause an error.
• mode: Defines how states may be modified.

Example

Add a pegasus row with a few important values.

use lace::{OracleT, HasStates};
use lace_data::Datum;
use lace::{Row, Value, WriteMode};

let mut engine = Example::Animals.engine().unwrap();
let starting_rows = engine.n_rows();

let rows = vec![
    Row::<&str, &str> {
        row_ix: "pegasus".into(),
        values: vec![
            Value {
                col_ix: "flys".into(),
                value: Datum::Categorical(1_u8.into()),
            },
            Value {
                col_ix: "hooves".into(),
                value: Datum::Categorical(1_u8.into()),
            },
            Value {
                col_ix: "swims".into(),
                value: Datum::Categorical(0_u8.into()),
            },
        ]
    }
];

// Allow insert_data to add new rows, but not new columns, and prevent
// any existing data (even missing cells) from being overwritten.
let result = engine.insert_data(
    rows,
    None,
    WriteMode::unrestricted()
);

assert!(result.is_ok());
assert_eq!(engine.n_rows(), starting_rows + 1);

Add a column that may help us categorize a new type of animal. Note that Rows can be constructed from other simpler representations.

use lace_codebook::{ColMetadataList, ColMetadata, ColType, ValueMap};
use lace_stats::prior::csd::CsdHyper;

let rows: Vec<Row<&str, &str>> = vec![
    ("bat", vec![("drinks+blood", Datum::Categorical(1_u8.into()))]).into(),
    ("beaver", vec![("drinks+blood", Datum::Categorical(0_u8.into()))]).into(),
];

// The partial codebook is required to define the data type and
// distribution of new columns
let col_metadata = ColMetadataList::new(
    vec![
        ColMetadata {
            name: "drinks+blood".into(),
            coltype: ColType::Categorical {
                k: 2,
                hyper: Some(CsdHyper::default()),
                prior: None,
                value_map: ValueMap::U8(2),
            },
            notes: None,
            missing_not_at_random: false,
        }
    ]
).unwrap();
let starting_cols = engine.n_cols();

// Allow insert_data to add new columns, but not new rows, and prevent
// any existing data (even missing cells) from being overwritten.
let result = engine.insert_data(
    rows,
    Some(col_metadata),
    WriteMode::unrestricted(),
);

assert!(result.is_ok());
assert_eq!(engine.n_cols(), starting_cols + 1);

Add several new columns.

use lace_codebook::{ColMetadataList, ColMetadata, ColType, ValueMap};
use lace_stats::prior::csd::CsdHyper;

let rows: Vec<Row<&str, &str>> = vec![
    ("bat", vec![
            ("drinks+blood", Datum::Categorical(1_u8.into())),
    ]).into(),
    ("wolf", vec![
            ("drinks+blood", Datum::Categorical(1_u8.into())),
            ("howls+at+the+moon", Datum::Categorical(1_u8.into())),
    ]).into(),
];

// The partial codebook is required to define the data type and
// distribution of new columns. It must contain metadata for only the
// new columns.
let col_metadata = ColMetadataList::new(
    vec![
        ColMetadata {
            name: "drinks+blood".into(),
            coltype: ColType::Categorical {
                k: 2,
                hyper: Some(CsdHyper::default()),
                prior: None,
                value_map: ValueMap::U8(2),
            },
            notes: None,
            missing_not_at_random: false,
        },
        ColMetadata {
            name: "howls+at+the+moon".into(),
            coltype: ColType::Categorical {
                k: 2,
                hyper: Some(CsdHyper::default()),
                prior: None,
                value_map: ValueMap::U8(2),
            },
            notes: None,
            missing_not_at_random: false,
        }
    ]
).unwrap();
let starting_cols = engine.n_cols();

// Allow insert_data to add new columns, but not new rows, and prevent
// any existing data (even missing cells) from being overwritten.
let result = engine.insert_data(
    rows,
    Some(col_metadata),
    WriteMode::unrestricted(),
);

assert!(result.is_ok());
assert_eq!(engine.n_cols(), starting_cols + 2);

We could also insert to a new category. In the animals data set all values are binary, {0, 1}. What if we decided a pig was neither fierce or docile, that it was something else, that we will capture with the value ‘2’?

use lace::examples::animals;

// Get the value before we edit.
let x_before = engine.datum("pig", "fierce").unwrap();

// Turns out pigs are fierce.
assert_eq!(x_before, Datum::Categorical(1_u8.into()));

let rows: Vec<Row<&str, &str>> = vec![
    // Inserting a 2 into a binary column
    ("pig", vec![("fierce", Datum::Categorical(2_u8.into()))]).into(),
];

let result = engine.insert_data(
    rows,
    None,
    WriteMode::unrestricted(),
);

assert!(result.is_ok());

// Make sure that the 2 exists in the table
let x_after = engine.datum("pig", "fierce").unwrap();

assert_eq!(x_after, Datum::Categorical(2_u8.into()));

To add a category to a column with value_map

let mut engine = Example::Satellites.engine().unwrap();
use lace_codebook::{ColMetadata, ColType, ValueMap};
use std::collections::HashMap;

let rows: Vec<Row<&str, &str>> = vec![(
    "Artemis (Advanced Data Relay and Technology Mission Satellite)",
    vec![("Class_of_Orbit", Datum::Categorical("MEO".into()))]
).into()];

let result = engine.insert_data(
    rows,
    None,
    WriteMode::unrestricted(),
);
assert!(result.is_ok());

pub fn remove_data<R: RowIndex, C: ColumnIndex>( &mut self, indices: Vec<TableIndex<R, C>> ) -> Result<(), RemoveDataError>

Remove data from the engine

Notes

• Removing a Datum::Missing cell will do nothing
• Removing all the cells in a row or column will completely remove that row or column

Arguments

• indices: A Vec of Index.

Example

Remove a cell.

use lace::{TableIndex, OracleT};
use lace_data::Datum;

let mut engine = Example::Animals.engine().unwrap();

assert_eq!(
    engine.datum("horse", "flys").unwrap(),
    Datum::Categorical(0_u8.into()),
);

// Row and Column implement Into<TableIndex>
engine.remove_data(vec![("horse", "flys").into()]);

assert_eq!(engine.datum("horse", "flys").unwrap(), Datum::Missing);

Remove a row and column.

let mut engine = Example::Animals.engine().unwrap();

assert_eq!(engine.n_rows(), 50);
assert_eq!(engine.n_cols(), 85);

engine.remove_data(vec![
    TableIndex::Row("horse"),
    TableIndex::Column("flys"),
]);

assert_eq!(engine.n_rows(), 49);
assert_eq!(engine.n_cols(), 84);

Removing all the cells in a row, will delete the row

let mut engine = Example::Animals.engine().unwrap();

assert_eq!(engine.n_rows(), 50);
assert_eq!(engine.n_cols(), 85);

// You can convert a tuple of (row_ix, col_ix) to an Index
let ixs = (0..engine.n_cols())
    .map(|ix| TableIndex::from((6, ix)))
    .collect();

engine.remove_data(ixs);

assert_eq!(engine.n_rows(), 49);
assert_eq!(engine.n_cols(), 85);

pub fn cell_gibbs(&mut self, row_ix: usize, col_ix: usize)

Run the Gibbs reassignment kernel on a specific column and row withing a view. Used when the user would like to focus more updating on specific regions of the table.

Notes

• The entire column will be reassigned, but only the part of row within the view to which column col_ix is assigned will be updated.
• Do not use a part of Geweke. This function assumes all transitions will be run, so it cannot be guaranteed to be valid for all Geweke configurations.

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

Save the Engine to a lacefile

pub fn run(&mut self, n_iters: usize) -> Result<(), Error>

Run each State in the Engine for n_iters iterations using the default algorithms and transitions. If the Engine is empty, update will immediately return.

pub fn update<U>( &mut self, config: EngineUpdateConfig, update_handler: U ) -> Result<(), Error>

where U: UpdateHandler,

Run each State in the Engine according to the config. If the Engine is empty, update will return immediately.

pub fn flatten_cols(&mut self)

Flatten the column assignment of each state so that each state has only one view

pub fn n_states(&self) -> usize

Returns the number of states

Trait Implementations

impl Clone for Engine

fn clone(&self) -> Engine

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Engine

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Engine

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl From<&Engine> for Metadata

fn from(engine: &Engine) -> Self

Converts to this type from the input type.

impl From<Engine> for Metadata

fn from(engine: Engine) -> Self

Converts to this type from the input type.

impl From<Oracle> for Engine

fn from(oracle: Oracle) -> Self

Converts to this type from the input type.

impl HasData for Engine

fn summarize_feature(&self, ix: usize) -> SummaryStatistics

Summarize the data in a feature

fn cell(&self, row_ix: usize, col_ix: usize) -> Datum

Return the datum in a cell

impl HasStates for Engine

fn states(&self) -> &Vec<State>

Get a reference to the States

fn states_mut(&mut self) -> &mut Vec<State>

Get a mutable reference to the States

fn n_states(&self) -> usize

Get the number of states

fn n_rows(&self) -> usize

Get the number of rows in the states

fn n_cols(&self) -> usize

Get the number of columns in the states

impl Serialize for Engine

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl TryFrom<Metadata> for Engine

type Error = DataFieldNoneError

The type returned in the event of a conversion error.

fn try_from(md: Metadata) -> Result<Self, Self::Error>

Performs the conversion.