Package: matrix-utils
matrix_utilsLibrary for building matrices from data packages frombw_processing. Designed for use with theBrightway life cycle assessment framework.Table of ContentsBackgroundInstallUsageAPIContributingMaintainersLicenseBackgroundThecalculation libraryof theBrightway LCA frameworkhas traditionally include matrix-building functionality. As the new capabilities inbw_processinghave increased matrix-building complexity, this library is a refactoring to split matrix utilities from the LCA classes, which will remain in the calculation library.matrix_utilssupports all the features made available inbw_processing: static and dynamic resources, data package policies, vector and array resources. It also improves on the previous matrix building code by speeding up the mapping from data source ids to row and column ids.Backwards compatibilityThis library presents a completely different API than the functions previously present inbw2calc. Most ideas become easier, or even possible; however, some things are more complicated. In particular, the notion that we have a single array that defines a matrix is no longer true - a matrix can be defined by many input arrays, and they can interact with each other (either adding to existing matrix values or replacing them altogether).InstallInstall using pip or conda (channelcmutel).Depends on numpy, scipy, pandas, bw_processing, stats_arrays.UsageMappedMatrixclassThe primary use case formatrix_utilsis theMappedMatrixclass:In[1]:frommatrix_utilsimportMappedMatrixIn[2]:mm=MappedMatrix(packages=[some_datapackage],matrix="foo")In[3]:mm.matrixOut[3]:<8x8sparsematrixoftype'<class 'numpy.float32'>'with11storedelementsinCompressedSparseRowformat>MappedMatrixtakes the following arguments. Note that all argumentsmust bekeyword arguments:packages: list, required. List ofbw_processingdata packages. The packages must be instantiated, you can't give file locations ofPyFilesystem2file systems.matrix: str, required. Label of matrix to build. Used to filter data inpackages, so must be identical to thematrixvalue in the package(s).use_vectors: bool, default True. Include vector data resources when building matrices.use_arrays: bool, default True. Include array data resources when building matrices. Note that each data package resource group can only provide either vector or array data.use_distributions: bool, default False. Include probability distribution data resources when building matrices.row_mapper:matrix_utils.ArrayMapper, defaultNone. Optional mapping class used to translate data source ids to matrix row indices. In LCA, one would reuse this mapping class to make sure the dimensions of multiple matrices align.col_mapper:matrix_utils.ArrayMapper, defaultNone. Optional mapping class used to translate data source ids to matrix column indices. In LCA, one would reuse this mapping class to make sure the dimensions of multiple matrices align.seed_override: int, defaultNone. Override the random seed given in the data package. Note that this is ignored if the data package is combinatorial.MappedMatrixis iterable; callingnext()will draw new samples from all included stochastic resources, and rebuild the matrix.You may also find it useful to iterate throughMappedMatrix.groups, which are instances ofResourceGroup, documented below.ResourceGroupclassAbw_processingdata package is essentially a metadata file and a bag of data resources. These resources aregrouped, for multiple resources are needed to build one matrix, or one component of one matrix. For example, one needs not only the data vector, but also the row and column indices to build a simple matrix. One could also have aflipvector, in another file, used to flip the signs of data elements before matrix insertion.TheResourceGroupclass provides a single interface to these data files and their metadata.ResourceGroupinstances are created automatically byMappedMatrix, and available viaMappedMatrix.groups. Thesource codeis pretty readable, and in general you probably don't need to worry about this low-level class, but the following could be useful:ResourceGroup.data_original: The data as it is present in the datapackage, before masking (i.e. the Numpy data vector or array, or the data interface). This is the raw input data, duplicate elements are not aggregated (if applicable).ResourceGroup.data_current: The data sample used (before aggregation) to build the matrix. It is both masked and flipped.ResourceGroup.row|col_mapped: Mapped row and column indices. Has the same length as the datapackage resource, but uses-1for values which weren't mapped.ResourceGroup.row|col_masked: The data after the custom filter and mapping mask have been applied.rResourceGroup.row|col_matrix: Row and column indices (but not data) for insertion into the matrix. These indices are after aggregation within the resource group (if any).ResourceGroup.calculate(vector=None): Function to recalculate matrix row, column, and data vectors. Uses the current state of the indexers, but re-draws values from data iterators. Ifvectoris given, use this instead of the given data source.ResourceGroup.indexer: The instance of theIndexerclass applicable for thisResourceGroup. Only used for data arrays.ResourceGroup.ncols: The integer number of columns in a data array. ReturnsNoneif a data vector is present.ContributingYour contribution is welcome! Please follow thepull request workflow, even for minor changes.When contributing to this repository with a major change, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository.Please note we have acode of conduct, please follow it in all your interactions with the project.Documentation and coding standardsBlack formattingSemantic versioningMaintainersChris MutelLicenseBSD-3-Clause. Copyright 2020 Chris Mutel.