aequilibrae.matrix package#
Submodules#
aequilibrae.matrix.aequilibrae_data module#
- class aequilibrae.matrix.aequilibrae_data.AequilibraeData[source]#
Bases:
object
AequilibraE dataset
- create_empty(file_path=None, entries=1, field_names=None, data_types=None, memory_mode=False, fill=None, index=None)[source]#
Creates a new empty dataset
- Arguments:
file_path (
str
, Optional): Full path for the output data file. If memory_mode is ‘false’ and path is missing, then the file is created in the temp folderentries (
int
, Optional): Number of records in the dataset. Default is 1field_names (
list
, Optional): List of field names for this dataset. If no list is provided, the field ‘data’ will be createddata_types (
np.dtype
, Optional): List of data types for the dataset. Types need to be NumPy data types (e.g. np.int16, np.float64). If no list of types are provided, type will be np.float64memory_mode (
bool
, Optional): If true, dataset will be kept in memory. If false, the dataset will be a memory-mapped numpy array
>>> from aequilibrae.matrix import AequilibraeData, AequilibraeMatrix >>> mat = AequilibraeMatrix() >>> mat.load('/tmp/test_project/matrices/demand.omx') >>> mat.computational_view() >>> vectors = "/tmp/test_project/vectors.aed" >>> args = { ... "file_path": vectors, ... "entries": mat.zones, ... "field_names": ["origins", "destinations"], ... "data_types": [np.float64, np.float64] ... } >>> dataset = AequilibraeData() >>> dataset.create_empty(**args)
- load(file_path)[source]#
Loads dataset from file
- Arguments:
file_path (
str
): Full file path to the AequilibraeData to be loaded
>>> from aequilibrae.matrix import AequilibraeData >>> dataset = AequilibraeData() >>> dataset.load("/tmp/test_project/vectors.aed")
- export(file_name, table_name='aequilibrae_table')[source]#
Exports the dataset to another format. Supports CSV and SQLite
- Arguments:
file_name (
str
): File name with PATH and extension (csv, or sqlite3, sqlite or db)table_name (
str
): It only applies if you are saving to an SQLite table. Otherwise ignored
>>> from aequilibrae.matrix import AequilibraeData >>> dataset = AequilibraeData() >>> dataset.load("/tmp/test_project/vectors.aed") >>> dataset.export("/tmp/test_project/vectors.csv")
- static random_name()[source]#
Returns a random name for a dataset with root in the temp directory of the user
>>> from aequilibrae.matrix import AequilibraeData >>> name = AequilibraeData().random_name() # This is an example of output # '/tmp/Aequilibrae_data_5werr5f36-b123-asdf-4587-adfglkjhqwe.aed'
aequilibrae.matrix.aequilibrae_matrix module#
- class aequilibrae.matrix.aequilibrae_matrix.AequilibraeMatrix[source]#
Bases:
object
Matrix class
- save(names=(), file_name=None) None [source]#
Saves matrix data back to file.
If working with AEM file, it flushes data to disk. If working with OMX, requires new names.
- Arguments:
names (
tuple(str)
, Optional): New names for the matrices. Required if working with OMX files
- create_empty(file_name: str | None = None, zones: int | None = None, matrix_names: ~typing.List[str] | None = None, data_type: ~numpy.dtype = <class 'numpy.float64'>, index_names: ~typing.List[str] | None = None, compressed: bool = False, memory_only: bool = True)[source]#
Creates an empty matrix in the AequilibraE format
- Arguments:
file_name (
str
): Local path to the matrix filezones (
int
): Number of zones in the model (Integer). Maximum number of zones in a matrix is 4,294,967,296matrix_names (
list
): A regular Python list of names of the matrix. Limit is 50 characters each. Maximum number of cores per matrix is 256data_type (
np.dtype
, optional): Data type of the matrix as NUMPY data types (NP.int32, np.int64, np.float32, np.float64). Defaults to np.float64index_names (
list
, optional): A regular Python list of names for indices. Limit is 20 characters each). Maximum number of indices per matrix is 256compressed (
bool
, optional): Whether it is a flat matrix or a compressed one (Boolean - Not yet implemented)memory_only (
bool
, optional): Whether you want to keep the matrix copy in memory only. Defaults to True
>>> from aequilibrae.matrix import AequilibraeMatrix >>> zones_in_the_model = 3317 >>> names_list = ['Car trips', 'pt trips', 'DRT trips', 'bike trips', 'walk trips'] >>> mat = AequilibraeMatrix() >>> mat.create_empty(file_name='/tmp/path_to_matrix.aem', ... zones=zones_in_the_model, ... matrix_names=names_list, ... memory_only=False,) >>> mat.num_indices 1 >>> mat.zones 3317
- get_matrix(core: str, copy=False) ndarray [source]#
Returns the data for a matrix core
- Arguments:
core (
str
): name of the matrix core to be returnedcopy (
bool
, optional): return a copy of the data. Defaults to False- Returns:
object (
np.ndarray
): NumPy array
- create_from_omx(file_path: str, omx_path: str, cores: List[str] | None = None, mappings: List[str] | None = None, robust: bool = True, compressed: bool = False, memory_only: bool = True) None [source]#
Creates an AequilibraeMatrix from an original OpenMatrix
- Arguments:
file_path (
str
): Path for the output AequilibraEMatrixomx_path (
str
): Path to the OMX file one wants to importcores (
list
): List of matrix cores to be importedmappings (
list
): List of the matrix mappings (i.e. indices, centroid numbers) to be importedrobust (
bool
, optional): Boolean for whether AequilibraE should try to adjust the names for cores and indices in case they are too long. Defaults to Truecompressed (
bool
, optional): Boolean for whether we should compress the output matrix. Not yet implementedmemory_only (
bool
, optional): Whether you want to keep the matrix copy in memory only. Defaults to True
- create_from_trip_list(path_to_file: str, from_column: str, to_column: str, list_cores: List[str]) str [source]#
Creates an AequilibraeMatrix from a trip list csv file The output is saved in the same folder as the trip list file
- Arguments:
path_to_file (
str
): Path for the trip list csv filefrom_column (
str
): trip list file column containing the origin zones numbersfrom_column (
str
): trip list file column containing the destination zones numberslist_cores (
list
): list of core columns in the trip list file
- set_index(index_to_set: str) None [source]#
Sets the standard index to be the one the user wants to have be the one being used in all operations during run time. The first index is ALWAYS the default one every time the matrix is instantiated
- Arguments:
index_to_set (
str
): Name of the index to be used. The default index name is ‘main_index’
>>> from aequilibrae.matrix import AequilibraeMatrix >>> zones_in_the_model = 3317 >>> names_list = ['Car trips', 'pt trips', 'DRT trips', 'bike trips', 'walk trips'] >>> index_list = ['tazs', 'census'] >>> mat = AequilibraeMatrix() >>> mat.create_empty(file_name="/tmp/path_to_new_matrix.aem", ... zones=zones_in_the_model, ... matrix_names=names_list, ... index_names=index_list ) >>> mat.num_indices 2 >>> mat.current_index 'tazs' >>> mat.set_index('census') >>> mat.current_index 'census'
- close()[source]#
Removes matrix from memory and flushes all data to disk, or closes the OMX file if that is the case
- export(output_name: str, cores: List[str] | None = None)[source]#
Exports the matrix to other formats, rather than AEM. Formats currently supported: CSV, OMX
When exporting to AEM or OMX, the user can chose to export only a set of cores, but all indices are exported
When exporting to CSV, the active index will be used, and all cores will be exported as separate columns in the output file
- Arguments:
output_name (
str
): Path to the output filecores (
list
): Names of the cores to be exported.
>>> from aequilibrae.matrix import AequilibraeMatrix >>> zones_in_the_model = 3317 >>> names_list = ['Car trips', 'pt trips', 'DRT trips', 'bike trips', 'walk trips'] >>> mat = AequilibraeMatrix() >>> mat.create_empty(file_name='/tmp/path_to_matrix.aem', ... zones=zones_in_the_model, ... matrix_names=names_list) >>> mat.cores 5 >>> mat.export('/tmp/my_new_path.aem', ['Car trips', 'bike trips']) >>> mat2 = AequilibraeMatrix() >>> mat2.load('/tmp/my_new_path.aem') >>> mat2.cores 2
- load(file_path: str)[source]#
Loads matrix from disk. All cores and indices are load. First index is default.
- Arguments:
file_path (
str
): Path to AEM or OMX file on disk
>>> from aequilibrae.matrix import AequilibraeMatrix >>> mat = AequilibraeMatrix() >>> mat.load('/tmp/path_to_matrix.aem') >>> mat.computational_view(["bike trips"]) >>> mat.names ['Car trips', 'pt trips', 'DRT trips', 'bike trips', 'walk trips']
- computational_view(core_list: List[str] | None = None)[source]#
Creates a memory view for a list of matrices that is compatible with Cython memory buffers
It allows for AequilibraE matrices to be used in all parallelized algorithms within AequilibraE
In case of OMX matrices, the computational view is held only in memory
- Arguments:
core_list (
list
): List with the names of all matrices that need to be in the buffer
>>> from aequilibrae.matrix import AequilibraeMatrix >>> zones_in_the_model = 3317 >>> names_list = ['Car trips', 'pt trips', 'DRT trips', 'bike trips', 'walk trips'] >>> mat = AequilibraeMatrix() >>> mat.create_empty(file_name='/tmp/path_to_matrix.aem', ... zones=zones_in_the_model, ... matrix_names=names_list) >>> mat.computational_view(['bike trips', 'walk trips']) >>> mat.view_names ['bike trips', 'walk trips']
- copy(output_name: str | None = None, cores: List[str] | None = None, names: List[str] | None = None, compress: bool | None = None, memory_only: bool = True)[source]#
Copies a list of cores (or all cores) from one matrix file to another one
- Arguments:
output_name (
str
): Name of the new matrix file. If none is provided, returns a copy in memory onlycores (
list
):List of the matrix cores to be copiednames (
list
, optional): List with the new names for the cores. Defaults to current namescompress (
bool
, optional): Whether you want to compress the matrix or not. Defaults to False Not yet implementedmemory_only (
bool
, optional): Whether you want to keep the matrix copy in memory only. Defaults to True
>>> from aequilibrae.matrix import AequilibraeMatrix >>> zones_in_the_model = 3317 >>> names_list = ['Car trips', 'pt trips', 'DRT trips', 'bike trips', 'walk trips'] >>> mat = AequilibraeMatrix() >>> mat.create_empty(file_name='/tmp/path_to_matrix.aem', zones=zones_in_the_model, matrix_names= names_list) >>> mat.copy('/tmp/path_to_copy.aem', ... cores=['bike trips', 'walk trips'], ... names=['bicycle', 'walking'], ... memory_only=False) <aequilibrae.matrix.aequilibrae_matrix.AequilibraeMatrix object at 0x...> >>> mat2 = AequilibraeMatrix() >>> mat2.load('/tmp/path_to_copy.aem') >>> mat2.cores 2
- rows() ndarray [source]#
Returns row vector for the matrix in the computational view
Computational view needs to be set to a single matrix core
- Returns:
object (
np.ndarray
): the row totals for the matrix currently on the computational view
>>> from aequilibrae.matrix import AequilibraeMatrix >>> mat = AequilibraeMatrix() >>> mat.load('/tmp/test_project/matrices/skims.omx') >>> mat.computational_view(["distance_blended"]) >>> mat.rows() array([357.68202084, 358.68778868, 310.68285491, 275.87964738, 265.91709918, 268.60184371, 267.32264726, 281.3793747 , 286.15085073, 242.60308705, 252.1776242 , 305.56774194, 303.58100777, 270.48841269, 263.20417379, 253.92665702, 277.1655432 , 258.84368258, 280.65697316, 272.7651157 , 264.06806038, 252.87533845, 273.45639965, 281.61102767])
- columns() ndarray [source]#
Returns column vector for the matrix in the computational view
Computational view needs to be set to a single matrix core
- Returns:
object (
np.ndarray
): the column totals for the matrix currently on the computational view
>>> from aequilibrae.matrix import AequilibraeMatrix >>> mat = AequilibraeMatrix() >>> mat.load('/tmp/test_project/matrices/skims.omx') >>> mat.computational_view(["distance_blended"]) >>> mat.columns() array([357.54256811, 357.45109051, 310.88655449, 276.6783439 , 266.70388637, 270.62976319, 266.32888632, 279.6897402 , 285.89821842, 242.79743295, 252.34085912, 301.78116548, 302.97058146, 270.61855294, 264.59944248, 257.83842251, 276.63310578, 257.74513863, 281.15724257, 271.63886077, 264.62215032, 252.79791125, 273.18139747, 282.7636574 ])
- nan_to_num()[source]#
Converts all NaN values in all cores in the computational view to zeros
>>> from aequilibrae.matrix import AequilibraeMatrix >>> mat = AequilibraeMatrix() >>> mat.load('/tmp/path_to_matrix.aem') >>> mat.computational_view(["bike trips"]) >>> mat.nan_to_num()
- setName(matrix_name: str)[source]#
Sets the name for the matrix itself
- Arguments:
matrix_name (
str
): matrix name. Maximum length is 50 characters
>>> from aequilibrae.matrix import AequilibraeMatrix >>> mat = AequilibraeMatrix() >>> mat.create_empty(file_name="matrix.aem", zones=3317, memory_only=False) >>> mat.setName('This is my example') >>> mat.name ''
- setDescription(matrix_description: str)[source]#
Sets description for the matrix
- Arguments:
matrix_description (
str
): Text with matrix description . Maximum length is 144 characters
>>> from aequilibrae.matrix import AequilibraeMatrix >>> mat = AequilibraeMatrix() >>> mat.create_empty(file_name="matrix.aem", zones=3317, memory_only=False) >>> mat.setDescription('This is some text about this matrix of mine') >>> mat.save() >>> mat.close() >>> mat = AequilibraeMatrix() >>> mat.load("matrix.aem") >>> mat.description.decode('utf-8') 'This is some text ab'
- static random_name() str [source]#
Returns a random name for a matrix with root in the temp directory of the user
>>> from aequilibrae.matrix import AequilibraeMatrix >>> name = AequilibraeMatrix().random_name() # This is an example of output # '/tmp/Aequilibrae_matrix_54625f36-bf41-4c85-80fb-7fc2e3f3d76e.aem'