8.1.5.1. pelicun.model.asset_model

AssetModel object and methods.

Classes

AssetModel(assessment)

Asset information used in assessments.

class pelicun.model.asset_model.AssetModel(assessment: AssessmentBase)

Asset information used in assessments.

generate_cmp_sample(sample_size: int | None = None) → None

Generate a component sample.

Generates a sample of component quantity realizations based on predefined model parameters and optionally specified sample size. If no sample size is provided, the function attempts to use the sample size from an associated demand model.

Parameters:

sample_size: int, optional

The number of realizations to generate. If not specified, the sample size is taken from the demand model associated with the assessment.

Raises:

ValueError

If the model parameters are not loaded before sample generation, or if neither sample size is specified nor can be determined from the demand model.

list_unique_component_ids() → list[str]

Obtain unique component IDs.

Returns:

list | set

Unique components in the asset model.

load_cmp_model(data_source: str | dict[str, DataFrame]) → None

Load the asset model from a specified data source.

This function is responsible for loading data related to the component model of an asset. It supports loading from multiple types of data sources. If the data source is a string, it is treated as a prefix to filenames that contain the necessary data. If it is a dictionary, it directly contains the data as DataFrames.

Parameters:

data_source: str or dict

The source from where to load the component model data. If it’s a string, it should be the prefix for three files: one for marginal distributions (<prefix>_marginals.csv), one for empirical data (<prefix>_empirical.csv), and one for correlation data (<prefix>_correlation.csv). If it’s a dictionary, it should have keys ‘marginals’, ‘empirical’, and ‘correlation’, with each key associated with a DataFrame containing the corresponding data.

Notes

The function utilizes helper functions to handle complex location strings that can describe single locations, ranges, lists, or special keywords like ‘all’, ‘top’, and ‘roof’. These are used to specify which parts of the asset the data pertains to, especially useful in buildings with multiple stories or sections.

Examples

To load data using file prefixes:

>>> model.load_cmp_model('path/to/data_prefix')

To load data using a dictionary of DataFrames:

>>> data_dict = {
    'marginals': df_marginals,
    'empirical': df_empirical,
    'correlation': df_correlation
}
>>> model.load_cmp_model(data_dict)

load_cmp_sample(filepath: str) → None

Load a component quantity sample from a specified CSV file.

This method reads a CSV file that contains component quantity samples, setting up the necessary DataFrame structures within the application. It also handles unit conversions using predefined conversion factors and captures the units of each component quantity from the CSV file.

Parameters:

filepath: str

The path to the CSV file from which to load the component quantity sample.

Raises:

ValueError

If the columns have an invalid number of levels.

Notes

Upon successful loading, the method sets the component sample and units as internal attributes of the class, making them readily accessible for further operations. It also sets appropriate column names for the DataFrame to match expected indexing levels such as component (‘cmp’), location (‘loc’), direction (‘dir’), and unique identifier (‘uid’).

Examples

Assuming the filepath to the component sample CSV is known and accessible:

>>> model.load_cmp_sample('path/to/component_sample.csv')
# This will load the component quantity sample into the model
# from the specified file.

save_cmp_sample(filepath: str | None = None, *, save_units: bool = False) → DataFrame | tuple[DataFrame, Series] | None

Save or retrieve component quantity sample.

Saves the component quantity sample to a CSV file or returns it as a DataFrame with optional units. This method handles the storage of a sample of component quantities, which can either be saved directly to a file or returned as a DataFrame for further manipulation. When saving to a file, additional information such as unit conversion factors and column units can be included. If the data is not being saved to a file, the method can return the DataFrame with or without units as specified.

Parameters:

filepath: str, optional

The path to the file where the component quantity sample should be saved. If not provided, the sample is not saved to disk but returned.

save_units: bool, default: False

Indicates whether to include a row with unit information in the returned DataFrame. This parameter is ignored if a file path is provided.

Returns:

None or tuple

If filepath is provided, the function returns None after saving the data. If no filepath is specified, returns: * DataFrame containing the component quantity sample. * Optionally, a Series containing the units for each column if save_units is True.

Notes

The function utilizes internal logging to notify the start and completion of the saving process. It adjusts index types and handles unit conversions based on assessment configurations.