State API

State([context])

The encapsulated state of an ActivitySim model.

Constructors

State.__init__([context])	Initialize the encapsulated state of an ActivitySim model.
State.make_default([working_dir, settings])	Convenience constructor for mostly default States.
State.make_temp([source, checkpoint_name])	Initialize state with a temporary directory.
create_example(example_name[, directory, temp])	Create an example model.

Model Setup

State.init_state()	Initialize this state.
State.import_extensions([ext, append])	Import one or more extension modules for use with this model.
State.initialize_filesystem([working_dir, ...])	Initialize the state's filesystem.
State.default_settings([force])	Initialize with all default settings, rather than reading from a file.
State.load_settings()	Read and parse settings file(s) from config dirs.
State.settings	The overall settings for the ActivitySim model system.
State.filesystem	Manage finding and loading files for ActivitySim's command line interface.
State.network_settings	Network level of service and skims settings

Basic Context Management

The most basic function of the State object is to serve as a defined namespace for storing model-relevant variables. This includes the top-level model settings, data tables, skims, and any other Python variables that represent the current state of a particular modeling system (or when multiprocessing, sub-system). Below are the basic methods to get and set values in this context in their “raw” form, with minimal additional processing.

State.get(key[, default])	Automated access to values stored in this state's context.
State.set(key, value)	Set a new value for a key in the context.
State.drop(key)	Remove a key from the context.
State.access(key[, initializer])	Raw access to values stored in this state's context.
State.get_injectable(key[, default])	Alias for State.get().
State.add_injectable(key, value)	Alias for State.set().

Data Access and Manipulation

In addition to “raw” access to context variable, several methods are provided to simplify different kinds access to the “tables” that represent the simulation inputs and outputs of ActivitySim. We say “tables” here in the abstract sense – historically these tables have been stored internally by ORCA as pandas.DataFrames, but the exact internal storage format is abstracted away here in favor of providing access to the data in several specific formats.

Methods

State.get_dataset(table_name[, ...])	Get a workflow table or dataset as a xarray.Dataset.
State.get_dataframe(tablename[, columns, ...])	Get a workflow table as a pandas.DataFrame.
State.get_dataarray(tablename, item[, as_copy])	Get a workflow table item as a xarray.DataArray.
State.get_dataframe_index_name(tablename)	Get the index name for a workflow table.
State.get_pyarrow(tablename[, columns])	Get a workflow table as a pyarrow.Table.
State.add_table(name, content[, salient])	Add a data table to this context, and potentially mark it for checkpointing.
State.is_table(name)	Check if a name corresponds to a table in this state's context.
State.registered_tables()	Return a list of the names of all currently registered dataframe tables
State.get_table(table_name[, checkpoint_name])	Return pandas dataframe corresponding to table_name

Accessor

State.dataset

This accessor provides easy access to state tables and datasets.

Run

Executing model components is handled by methods in the run accessor.

Accessor

State.run(models[, resume_after, ...])

run the specified list of models, optionally loading checkpoint and resuming after specified checkpoint.

Attributes

State.run.heading_level

Individual component heading level to use when running in a notebook.

Methods

State.run.by_name(model_name, **kwargs)	Run the specified model and add checkpoint for model_name
State.run.all([resume_after, ...])

Checkpoints

The State object provides access to checkpointing functions within the checkpoint accessor.

Accessor

State.checkpoint

State accessor for checkpointing operations.

Attributes

State.checkpoint.last_checkpoint	Metadata about the last saved checkpoint.
State.checkpoint.checkpoints	Metadata about various saved checkpoint(s).
State.checkpoint.store	The store where checkpoints are written.

Methods

State.checkpoint.store_is_open()	Whether this checkpoint store is open.
State.checkpoint.open_store([...])	Open the checkpoint store.
State.checkpoint.close_store()	Close the checkpoint storage.
State.checkpoint.add(checkpoint_name)	Create a new checkpoint with specified name.
State.checkpoint.list_tables()	Return a list of the names of all checkpointed tables
State.checkpoint.load(checkpoint_name[, store])	Load dataframes and restore random number channel state from pipeline hdf5 file.
State.checkpoint.get_inventory()	Get pandas dataframe of info about all checkpoints stored in pipeline
State.checkpoint.restore([resume_after, mode])	Restore state from checkpoints.
State.checkpoint.restore_from(location[, ...])	Restore state from an alternative pipeline store.
State.checkpoint.check_against(location, ...)	Check that the tables in this State match those in an archived pipeline.
State.checkpoint.cleanup()	Remove intermediate checkpoints from pipeline.
State.checkpoint.load_dataframe(table_name)	Return pandas dataframe corresponding to table_name
State.checkpoint.last_checkpoint_name()
State.checkpoint.is_readonly()
State.checkpoint.default_pipeline_file_path()

Tracing

Attributes

State.tracing.traceable_tables
State.tracing.traceable_table_ids
State.tracing.traceable_table_indexes
State.tracing.run_id
State.tracing.validation_directory

Methods

State.tracing.initialize()
State.tracing.register_traceable_table(...)	Register traceable table
State.tracing.deregister_traceable_table(...)	un-register traceable table
State.tracing.write_csv(df, file_name[, ...])	Print write_csv
State.tracing.trace_df(df, label[, slicer, ...])	Slice dataframe by traced household or person id dataframe and write to CSV
State.tracing.trace_interaction_eval_results(...)	Trace model design eval results for interaction_simulate
State.tracing.get_trace_target(df, slicer[, ...])	get target ids and column or index to identify target trace rows in df
State.tracing.trace_targets(df[, slicer, column])
State.tracing.has_trace_targets(df[, ...])
State.tracing.dump_df(dump_switch, df, ...)
State.tracing.delete_output_files(file_type)	Delete files in output directory of specified type.
State.tracing.delete_trace_files()	Delete CSV files in output_dir

Logging

Methods

State.logging.config_logger([basic])	Configure logger
State.logging.rotate_log_directory()

Reporting

Accessor

State.report

Tools for reporting and visualization

Methods

Extending

Methods to extend ActivitySim’s functionality are available under the extend accessor.

Accessor

State.extend

Methods to extend the capabilities of ActivitySim.

Methods

State.extend.declare_table(table_name[, ...])

Declare a new table.