8.1.5.2. pelicun.model.damage_model

DamageModel object and methods.

Classes

DamageModel(assessment)	Manages damage information used in assessments.
DamageModel_Base(assessment)	Base class for damage models.
DamageModel_DS(assessment)	Damage model for components that have discrete Damage States (DS).

class pelicun.model.damage_model.DamageModel(assessment: AssessmentBase)

Manages damage information used in assessments.

calculate(dmg_process: dict | None = None, block_batch_size: int = 1000, scaling_specification: dict | None = None) → None

Calculate the damage of each component block.

Parameters:

dmg_process: dict, optional

Allows simulating damage processes, where damage to some component can alter the damage state of other components.

block_batch_size: int

Maximum number of components in each batch.

scaling_specification: dict, optional

A dictionary defining the shift in median. Example: {‘CMP-1-1’: ‘1.2’, ‘CMP-1-2’: ‘/1.4’} The keys are individual components that should be present in the `capacity_sample`. The values should be strings containing an operation followed by the value formatted as a float. The operation can be ‘+’ for addition, ‘-’ for subtraction, ‘’ for multiplication, and ‘/’ for division.

load_damage_model(data_paths: list[str | DataFrame], *, warn_missing: bool = False) → None

<backwards compatibility>.

load_model_parameters(data_paths: list[str | DataFrame], cmp_set: set[str], *, warn_missing: bool = False) → None

Load damage model parameters.

Parameters:

data_paths: list of (string | DataFrame)

List of paths to data or files with damage model information. Default XY datasets can be accessed as PelicunDefault/XY. Order matters. Parameters defined in prior elements in the list take precedence over the same parameters in subsequent data paths. I.e., place the Default datasets in the back.

cmp_set: set

Set of component IDs that are present in the asset model. Damage parameters in the input files for components outside of that set are omitted for performance.

warn_missing: bool

Whether to check if there are components in the asset model that do not have specified damage parameters. Should be set to True if all components in the asset model are damage state-driven, or if only a damage estimation is performed, without a subsequent loss estimation.

Raises:

ValueError

If the method can’t parse the damage parameters in the specified paths.

load_sample(filepath: str) → None

Load damage state sample data.

property sample: DataFrame

<backwards compatibility>.

Returns:

pd.DataFrame

The damage sample of the ds_model.

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

Save or return the damage sample data.

Saves the damage sample data to a CSV file or returns it directly with an option to include units.

This function handles saving the sample data of damage assessments to a specified file path or, if no path is provided, returns the data as a DataFrame. The function can optionally include a row for unit information when returning data.

Parameters:

filepath: str, optional

The path to the file where the damage 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 damage sample. - Optionally, a Series containing the units for each column if save_units is True.

class pelicun.model.damage_model.DamageModel_Base(assessment: AssessmentBase)

Base class for damage models.

convert_damage_parameter_units() → None

Convert previously loaded damage parameters to base units.

drop_unused_damage_parameters(cmp_set: set[str]) → None

Remove info for non existent components.

Removes damage parameter definitions for component IDs not present in the given list.

Parameters:

cmp_set: set

Set of component IDs to be preserved in the damage parameters.

load_model_parameters(data: DataFrame) → None

Load model parameters from a DataFrame.

Loads model parameters from a DataFrame, extending those already available. Parameters already defined take precedence, i.e. redefinitions of parameters are ignored.

Parameters:

data: DataFrame

Data with damage model information.

remove_incomplete_components() → None

Remove components with incompelte damage parameter info.

Removes components that have incomplete damage model definitions from the damage model parameters.

class pelicun.model.damage_model.DamageModel_DS(assessment: AssessmentBase)

Damage model for components that have discrete Damage States (DS).

complete_ds_cols(dmg_sample: DataFrame) → DataFrame

Complete damage state columns.

Completes the damage sample DataFrame with all possible damage states for each component.

Parameters:

dmg_sample: DataFrame

A DataFrame containing the damage state information for each component block in the asset model. The columns are MultiIndexed with levels corresponding to component information (‘cmp’, ‘loc’, ‘dir’, ‘uid’) and the damage state (‘ds’).

Returns:

DataFrame

A DataFrame similar to dmg_sample but with additional columns for missing damage states for each component, ensuring that all possible damage states are represented. The new columns are filled with zeros, indicating no occurrence of those damage states in the sample.

Notes

• The method assumes that the damage model parameters (self.damage_params) are available and contain the necessary information to determine the total number of damage states for each component.

obtain_ds_sample(demand_sample: DataFrame, component_blocks: DataFrame, block_batch_size: int, scaling_specification: dict | None, missing_components: list[str], nondirectional_multipliers: dict[str, float]) → None

Obtain the damage state of each performance group.

perform_dmg_task(task: tuple) → None

Perform a task from a damage process.

The method performs a task from a damage process on a given damage state sample. The events of the task are triggered by a damage state occurrence. The method assigns target component(s) into the target damage state based on the damage state of the source component. If the target event is “NA”, the method removes damage state information from the target components.

Parameters:

task: list

A list representing a task from the damage process. The list contains two elements: - The first element is a string representing the source component, e.g., ‘1_CMP_A’. The number in the beginning is used to order the tasks and is not considered here. - The second element is a dictionary representing the events triggered by the damage state of the source component. The keys of the dictionary are strings that represent the damage state of the source component, e.g., ‘DS1’. The values are lists of strings representing the target component(s) and event(s), e.g., [‘CMP_B.DS1’, ‘CMP_C.DS1’]. They could also be a single element instead of a list.

Examples of a task:

[‘1_CMP.A’, {‘DS1’: [‘CMP.B_DS1’, ‘CMP.C_DS2’]}] [‘1_CMP.A’, {‘DS1’: ‘CMP.B_DS1’, ‘DS2’: ‘CMP.B_DS2’}] [‘1_CMP.A-LOC’, {‘DS1’: ‘CMP.B_DS1’}]

Raises:

ValueError

Raises an error if the source or target event descriptions do not follow expected formats.

prepare_dmg_quantities(component_sample: DataFrame, component_marginal_parameters: DataFrame | None, *, dropzero: bool = True) → DataFrame

Combine component quantity and damage state information.

This method assumes that a component quantity sample is available in the asset model and a damage state sample is available in the damage model.

Parameters:

component_sample: pd.DataFrame

Component quantity sample from the AssetModel.

component_marginal_parameters: pd.DataFrame

Component marginal parameters from the AssetModel.

dropzero: bool, optional, default: True

If True, the quantity of non-damaged components is not saved.

Returns:

DataFrame

A DataFrame that combines the component quantity and damage state information.

probabilities() → DataFrame

Return the probability of each observed damage state.

Returns:

pd.DataFrame

DataFrame with the probability of each damage state for each component block.