Skip to content

Commit

Permalink
update descriptions for analyses and their inputs and outputs
Browse files Browse the repository at this point in the history
  • Loading branch information
@Rashmil-1999
Rashmil-1999 committed Feb 24, 2025
1 parent 6c85fb8 commit e16c4d5
Show file tree
Hide file tree
Showing 11 changed files with 193 additions and 106 deletions.
6 changes: 6 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](http://keepachangelog.com/)
and this project adheres to [Semantic Versioning](http://semver.org/).

## [Unreleased]

### Changed

- Descriptions of the analyses to be more verbose. [#645](https://github.com/IN-CORE/pyincore/issues/645)

## [1.21.0] - 2025-02-12

### Changed
Expand Down
46 changes: 31 additions & 15 deletions pyincore/analyses/bridgedamage/bridgedamage.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -328,91 +328,107 @@ def get_spec(self):
"""
return {
"name": "bridge-damage",
"description": "bridge damage analysis",
"description": (
"This analysis computes bridge damage based on a particular hazard. Currently "
"supported hazards are: earthquake, tsunami, tornado, and hurricane.\n"
"The process for computing the structural damage is similar to other parts of "
"the built environment. First, a fragility is obtained based on the hazard type "
"and attributes of the bridge. Based on the fragility, the hazard intensity at "
"the location of the bridge is computed. Using this information, the probability "
"of exceeding each limit state is computed, along with the probability of damage.\n"
"For the case of an earthquake hazard, if the bridge dataset contains soil "
"information, the median value of the associated fragility can be modified to "
"account for liquefaction in the damage.\n"
"The outputs of this analysis are a CSV file with probabilities of damage and "
"a JSON file with information about hazards and fragilities."
),
"input_parameters": [
{
"id": "result_name",
"required": True,
"description": "result dataset name",
"description": "Set custom result dataset name.",
"type": str,
},
{
"id": "fragility_key",
"required": False,
"description": "Fragility key to use in mapping dataset",
"description": "Fragility key used in mapping dataset.",
"type": str,
},
{
"id": "use_liquefaction",
"required": False,
"description": "Use liquefaction",
"description": "Use liquefaction, if applicable to the hazard. Default is False.",
"type": bool,
},
{
"id": "liquefaction_geology_dataset_id",
"required": False,
"description": "Geology dataset id",
"description": "Liquefaction geology/susceptibility dataset id. If not provided, liquefaction will be ignored.",
"type": str,
},
{
"id": "use_hazard_uncertainty",
"required": False,
"description": "Use hazard uncertainty",
"description": (
"For model based hazard events, if the model supports uncertainty, "
"then you can set this flag to indicate using the mean plus one standard deviation when computing damage. "
"Default is false."
),
"type": bool,
},
{
"id": "num_cpu",
"required": False,
"description": "If using parallel execution, the number of cpus to request",
"description": "If using parallel execution, the number of cpus to request. Default is 1.",
"type": int,
},
{
"id": "hazard_id",
"required": False,
"description": "Hazard object id",
"description": "ID of the hazard from the Hazard service.",
"type": str,
},
{
"id": "hazard_type",
"required": False,
"description": "Hazards type",
"description": "Hazard type (earthquake, tsunami, tornado, hurricaneWindfields).",
"type": str,
},
],
"input_hazards": [
{
"id": "hazard",
"required": False,
"description": "Hazard object",
"description": "Supported hazard object for using local and remote hazards.",
"type": ["earthquake", "tornado", "hurricane", "flood", "tsunami"],
},
],
"input_datasets": [
{
"id": "bridges",
"required": True,
"description": "Bridge Inventory",
"description": "Set the Bridge Inventory Dataset.",
"type": ["ergo:bridges", "ergo:bridgesVer2", "ergo:bridgesVer3"],
},
{
"id": "dfr3_mapping_set",
"required": True,
"description": "DFR3 Mapping Set Object",
"description": "Set the DFR3 Mapping Set Object.",
"type": ["incore:dfr3MappingSet"],
},
],
"output_datasets": [
{
"id": "result",
"parent_type": "bridges",
"description": "CSV file of bridge structural damage",
"description": "CSV file of bridge structural damage.",
"type": "ergo:bridgeDamageVer3",
},
{
"id": "metadata",
"parent_type": "bridges",
"description": "additional metadata in json file about applied hazard value and "
"fragility",
"description": "Information about applied hazard value and fragility in JSON format.",
"type": "incore:bridgeDamageSupplement",
},
],
Expand Down
38 changes: 22 additions & 16 deletions pyincore/analyses/buildingclusterrecovery/buildingclusterrecovery.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,95 +32,101 @@ def __init__(self, incore_client):
def get_spec(self):
return {
"name": "building-cluster-recovery-analysis",
"description": "Building Cluster Recovery Analysis (with uncertainty)",
"description": (
"The Building Portfolio Recovery analysis uses damage probabilities of structural components,"
"nonstructural drift-sensitive components, and nonstructural acceleration-sensitive components"
"to calculate building’s initial functionality loss."
),
"input_parameters": [
{
"id": "result_name",
"required": False,
"description": "Result dataset name",
"description": "Set custom result dataset name.",
"type": str,
},
{
"id": "uncertainty",
"required": True,
"description": "Use uncertainty",
"description": "Include uncertainty in the recovery time.",
"type": bool,
},
{
"id": "sample_size",
"required": False,
"description": "No. of buildings to be considered from input buildings",
"description": "Number of buildings to be considered from buildings dataset.",
"type": int,
},
{
"id": "random_sample_size",
"required": True,
"description": "Number of iterations for Monte Carlo Simulation",
"description": "Number of iterations for the Monte Carlo simulation.",
"type": int,
},
{
"id": "no_of_weeks",
"required": True,
"description": "Number of weeks to run the recovery model",
"description": "Number of weeks to run the recovery model.",
"type": int,
},
{
"id": "num_cpu",
"required": False,
"description": "If using parallel execution, the number of cpus to request",
"description": "If using parallel execution, the number of cpus to request. Dafault is 1.",
"type": int,
},
],
"input_datasets": [
{
"id": "building_data",
"required": True,
"description": "Building Data",
"description": "Set the Building inventory dataset.",
"type": ["incore:portfolioBuildingInventory"],
},
{
"id": "occupancy_mapping",
"required": True,
"description": "Occupancy code mapping",
"description": "Occupancy code mapping, An occupancy of buildings dataset.",
"type": ["incore:portfolioOccupancyMapping"],
},
{
"id": "building_damage",
"required": True,
"description": "Building Damage Results",
"description": "Building Damage Results. This dataset should contain the damage state of each building.",
"type": ["incore:portfolioBuildingDamage"],
},
{
"id": "dmg_ratios",
"required": True,
"description": "Percentage of mean repair by occupancy / building type",
"description": "Percentage of mean repair by occupancy / building type.",
"type": ["incore:portfolioDamageRatios"],
},
{
"id": "utility",
"required": True,
"description": "Full utility availability at each utility service area - joint area of power"
'and water (row), at each week (column)"',
"description": (
"Full utility availability at each utility service area - joint area of power"
"and water (row), at each week (column)."
),
"type": ["incore:portfolioUtilityAvailability"],
},
{
"id": "utility_partial",
"required": True,
"description": "Partial utility availability at each utility service area",
"description": "Partial utility availability at each utility service area.",
"type": ["incore:portfolioUtilityAvailability"],
},
{
"id": "coefFL",
"required": True,
"description": "Correlation coefficient of initial functionality states",
"description": "Correlation coefficient of initial functionality states.",
"type": ["incore:portfolioCoefficients"],
},
],
"output_datasets": [
{
"id": "result",
"parent_type": "buildingClusterRecovery",
"description": "Building cluster recovery result.",
"description": "Building cluster recovery result in CSV format.",
"type": "incore:clusterRecovery",
}
],
Expand Down
16 changes: 11 additions & 5 deletions pyincore/analyses/buildingeconloss/buildingeconloss.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -155,26 +155,32 @@ def get_spec(self):
"""
return {
"name": "building-economy-damage",
"description": "building economy damage analysis",
"description": (
"This analysis calculates the building loss based on building appraisal value, mean damage, and an inflation multiplier. "
"A user must supply the inflation rate (as a percentage) between building appraisal year and year of interest "
"(current, date of hazard, etc.) and optional Occupancy multiplier. The analysis can be used for with building mean damage "
"results for either Structural, Drift-Sensitive Nonstructural, Acceleration-Sensitive Nonstructural or Contents Damage component."
"The output of this analysis is a CSV file with structural losses based on damage."
),
"input_parameters": [
{
"id": "result_name",
"required": True,
"description": "result dataset name",
"description": "Set custom result dataset name.",
"type": str,
},
{
"id": "inflation_factor",
"required": False,
"description": "Inflation factor to adjust the appraisal values of buildings. Default 0.0",
"description": "Inflation factor to adjust the appraisal values of buildings. Default 0.0.",
"type": float,
},
],
"input_datasets": [
{
"id": "buildings",
"required": True,
"description": "Building Inventory",
"description": "Building Inventory dataset.",
"type": [
"ergo:buildingInventory",
"ergo:buildingInventoryVer4",
Expand Down Expand Up @@ -205,7 +211,7 @@ def get_spec(self):
{
"id": "result",
"parent_type": "buildings",
"description": "CSV file of building economy damages",
"description": "CSV file of building economy damages.",
"type": "incore:buildingEconomicLoss",
}
],
Expand Down
23 changes: 15 additions & 8 deletions pyincore/analyses/buildingfunctionality/buildingfunctionality.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,50 +35,57 @@ def get_spec(self):
"""
return {
"name": "functionality_probability",
"description": "calculate the functionality probability of each building",
"description": (
"The building functionality analysis can be used to calculate building functionality probabilities considering"
"two situations: buildings are in at least a damage state 2 or greater or buildings are not damaged but electric"
"power is not available to the building. Whether buildings can receive electrical power is assumed to depend on"
"the interdependency between buildings and substations, and between buildings and poles in close proximity."
"If both the nearest pole to the building and the substation where buildings belong to its service area are"
"functional, buildings are considered to be able to receive electric power."
),
"input_parameters": [
{
"id": "result_name",
"required": False,
"description": "result dataset name",
"description": "Set a custom result dataset name.",
"type": str,
}
],
"input_datasets": [
{
"id": "building_damage_mcs_samples",
"required": True,
"description": "building damage samples",
"description": "Set the building damage samples dataset from MCS.",
"type": ["incore:sampleFailureState"],
},
{
"id": "substations_damage_mcs_samples",
"required": False,
"description": "substations damage samples",
"description": "Set the substations damage samples dataset from MCS.",
"type": ["incore:sampleFailureState"],
},
{
"id": "poles_damage_mcs_samples",
"required": False,
"description": "poles damage samples",
"description": "Set the poles damage samples from MCS.",
"type": ["incore:sampleFailureState"],
},
{
"id": "interdependency_dictionary",
"required": False,
"description": "JSON file of interdependency between buildings and substations and poles",
"description": "JSON file of interdependency between buildings and substations and poles.",
"type": ["incore:buildingInterdependencyDict"],
},
],
"output_datasets": [
{
"id": "functionality_samples",
"description": "CSV file of functionality samples",
"description": "A dataset containing results of functionality samples (format: CSV).",
"type": "incore:funcSample",
},
{
"id": "functionality_probability",
"description": "CSV file of functionality probability",
"description": "A dataset containing results of functionality probability (format: CSV).",
"type": "incore:funcProbability",
},
],
Expand Down
Loading

0 comments on commit e16c4d5

Please sign in to comment.