aequilibrae.matrix package

Submodules

aequilibrae.matrix.aequilibrae_data module

class aequilibrae.matrix.aequilibrae_data.AequilibraeData

Bases: object

AequilibraE dataset

__init__()

create_empty(file_path=None, entries=1, field_names=None, data_types=None, memory_mode=False)

Creates a new empty dataset

Args:

file_path (str, Optional): Full path for the output data file. If memory_false is ‘false’ and path is missing, then the file is created in the temp folder

entries (int, Optional): Number of records in the dataset. Default is 1

field_names (list, Optional): List of field names for this dataset. If no list is provided, the field ‘data’ will be created

data_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.float64

memory_mode (bool, Optional): If true, dataset will be kept in memory. If false, the dataset will be a memory-mapped numpy array

vectors = "D:/release/Sample models/Chicago_2020_02_15/vectors.aed"
args = {
     "file_path": vectors,
     "entries": vec_1.shape[0],
     "field_names": ["origins", "destinations"],
     "data_types": [np.float64, np.float64],
 }
dataset = AequilibraeData()
dataset.create_empty(**args)

load(file_path)

Loads dataset from file

Args:

file_path (str): Full file path to the AequilibraeData to be loaded

dataset = AequilibraeData()
dataset.load("D:/datasets/vectors.aed")

export(file_name, table_name='aequilibrae_table')

Exports the dataset to another format. Supports CSV and SQLite

Args:

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

dataset = AequilibraeData()
dataset.load("D:/datasets/vectors.aed")
dataset.export("D:/datasets/vectors.csv")

static random_name()

Returns a random name for a dataset with root in the temp directory of the user

  name = AequilibraeData().random_name()
'/tmp/Aequilibrae_data_5werr5f36-b123-asdf-4587-adfglkjhqwe.aed'

aequilibrae.matrix.aequilibrae_matrix module

class aequilibrae.matrix.aequilibrae_matrix.AequilibraeMatrix

Bases: object

Matrix class

__init__()

Creates a memory instance for a matrix, that can be used to load an existing matrix or to create an empty one

save(names=()) → None

Saves matrix data back to file.

If working with AEM file, it flushes data to disk. If working with OMX, requires new names

Args:

names (tuple(str), Optional): New names for the matrices. Required if working with OMX files

create_empty(file_name: typing.Optional[str] = None, zones: typing.Optional[int] = None, matrix_names: typing.Optional[typing.List[str]] = None, data_type: numpy.dtype = <class 'numpy.float64'>, index_names: typing.Optional[typing.List[str]] = None, compressed: bool = False)

Creates an empty matrix in the AequilibraE format

Args:

file_name (str): Local path to the matrix file

zones (int): Number of zones in the model (Integer). Maximum number of zones in a matrix is 4,294,967,296

matrix_names (list): A regular Python list of names of the matrix. Limit is 50 characters each. Maximum number of cores per matrix is 256

file_name (str): Local path to the matrix file

data_type (np.dtype, optional): Data type of the matrix as NUMPY data types (NP.int32, np.int64, np.float32, np.float64). Defaults to np.float64

index_names (list, optional): A regular Python list of names for indices. Limit is 20 characters each). Maximum number of indices per matrix is 256

compressed (bool, optional): Whether it is a flat matrix or a compressed one (Boolean - Not yet implemented)

  zones_in_the_model = 3317
  names_list = ['Car trips', 'pt trips', 'DRT trips', 'bike trips', 'walk trips']

  mat = AequilibraeMatrix()
  mat.create_empty(file_name='my/path/to/file',
                   zones=zones_in_the_model,
                   matrix_names= names_list)
  mat.num_indices
1
  mat.zones
3317
  np.sum(mat[trips])
0.0

get_matrix(core: str, copy=False) → numpy.ndarray

Returns the data for a matrix core

Args:

core (str): name of the matrix core to be returned

copy (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: Optional[List[str]] = None, mappings: Optional[List[str]] = None, robust: bool = True, compressed: bool = False) → None

Creates an AequilibraeMatrix from an original OpenMatrix

Args:

file_path (str): Path for the output AequilibraEMatrix

omx_path (str): Path to the OMX file one wants to import

cores (list): List of matrix cores to be imported

mappings (list): List of the matrix mappings (i.e. indices, centroid numbers) to be imported

robust (bool, optional): Boolean for whether AequilibraE should try to adjust the names for cores and indices in case they are too long. Defaults to True

compressed (bool, optional): Boolean for whether we should compress the output matrix. Not yet implemented

set_index(index_to_set: str) → None

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

Args:

index_to_set (str): Name of the index to be used. The default index name is ‘main_index’

  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='my/path/to/file',
                   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()

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: Optional[List[str]] = None)

Exports the matrix to other formats. 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

Args:

output_name (str): Path to the output file

cores (list): Names of the cores to be exported.

  zones_in_the_model = 3317
  names_list = ['Car trips', 'pt trips', 'DRT trips', 'bike trips', 'walk trips']

  mat = AequilibraeMatrix()
  mat.create_empty(file_name='my/path/to/file', zones=zones_in_the_model, matrix_names= names_list)
  mat.cores
['Car trips', 'pt trips', 'DRT trips', 'bike trips', 'walk trips']

  mat.export('my_new_path', ['Car trips', 'bike trips'])

  mat2 = AequilibraeMatrix()
  mat2.load('my_new_path')
  mat2.cores
['Car trips', 'bike trips']

load(file_path: str)

Loads matrix from disk. All cores and indices are load. First index is default

Args:

file_path (str): Path to AEM or OMX file on disk

  zones_in_the_model = 3317
  names_list = ['Car trips', 'pt trips', 'DRT trips', 'bike trips', 'walk trips']

  mat = AequilibraeMatrix()
  mat.create_empty(file_name='my/path/to/file', zones=zones_in_the_model, matrix_names= names_list)
  mat.close()

  mat2 = AequilibraeMatrix()
  mat2.load('my/path/to/file.omx')
  mat2.zones
3317

is_omx()

Returns True if matrix data source is OMX, False otherwise

computational_view(core_list: Optional[List[str]] = None)

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

Args:

core_list (list): List with the names of all matrices that need to be in the buffer

  zones_in_the_model = 3317
  names_list = ['Car trips', 'pt trips', 'DRT trips', 'bike trips', 'walk trips']

  mat = AequilibraeMatrix()
  mat.create_empty(file_name='my/path/to/file', 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: Optional[str] = None, cores: Optional[List[str]] = None, names: Optional[List[str]] = None, compress: Optional[bool] = None) → None

Copies a list of cores (or all cores) from one matrix file to another one

Args:

output_name (str): Name of the new matrix file

cores (list):List of the matrix cores to be copied

names (list, optional): List with the new names for the cores. Defaults to current names

compress (bool, optional): Whether you want to compress the matrix or not. Defaults to False Not yet implemented

  zones_in_the_model = 3317
  names_list = ['Car trips', 'pt trips', 'DRT trips', 'bike trips', 'walk trips']

  mat = AequilibraeMatrix()
  mat.create_empty(file_name='my/path/to/file', zones=zones_in_the_model, matrix_names= names_list)
  mat.copy('my/new/path/to/file', cores=['bike trips', 'walk trips'], names=['bicycle', 'walking'])

  mat2 = AequilibraeMatrix()
  mat2.load('my/new/path/to/file')
  mat.cores
['bicycle', 'walking']

rows() → numpy.ndarray

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

  mat = AequilibraeMatrix()
  mat.load('my/path/to/file')
  mat.computational_view(mat.cores[0])
  mat.rows()
array([0.,...,0.])

columns() → numpy.ndarray

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

  mat = AequilibraeMatrix()
  mat.load('my/path/to/file')
  mat.computational_view(mat.cores[0])
  mat.columns()
array([0.34,.0.,...,14.03])

nan_to_num()

Converts all NaN values in all cores in the computational view to zeros

mat = AequilibraeMatrix()
mat.load('my/path/to/file')
mat.computational_view(mat.cores[0])
mat.nan_to_num()

setName(matrix_name: str)

Sets the name for the matrix itself

Args:

matrix_name (str): matrix name. Maximum length is 50 characters

  mat = AequilibraeMatrix()
  mat.load('my/path/to/file')
  mat.setName('This is my example')
  mat.name
'This is my example'

setDescription(matrix_description: str)

Sets description for the matrix

Args:

matrix_description (str): Text with matrix description . Maximum length is 144 characters

  mat = AequilibraeMatrix()
  mat.load('my/path/to/file')
  mat.setDescription('This is some text about this matrix of mine')
  mat.description
'This is some text about this matrix of mine'

static random_name() → str

Returns a random name for a matrix with root in the temp directory of the user

  name = AequilibraeMatrix().random_name()
'/tmp/Aequilibrae_matrix_54625f36-bf41-4c85-80fb-7fc2e3f3d76e.aem'

Module contents