Make the consequence module more generic and flexible

[micheles]

The script in oq-risk-tests by @raoanirudh does not work with engine 3.12+ for several reasons (changed sap, changed the datastore, moved modules around). A good idea would be to integrate it in the engine since now the event based damage calculator is a lot more powerful that it was in the past. This is a lot of work.

[raoanirudh]

For a generic and flexible consequence module, we would need to handle the following things cleanly and consistently:

• Consequence name: What is the consequence called? Should we support a limited set of pre-defined consequence names or permit the user to define more? Where’s the best place to specify the name? Currently six consequence names are supported (loss, losses, collapsed, injured, fatalities, homeless) and these are hardcoded in risklib/scientific.py. In demos/risk/ScenarioDamage/consequences.csv, the consequence being calculated is losses.
• Exposure tag(s): The field(s) from the exposure file that will be associated with the consequence function, akin to the taxonomy field used for the taxonomy mapping for fragility and vulnerability. In demos/risk/ScenarioDamage/consequences.csv, the exposure field associated with the consequence functions is taxonomy. This link is also currently explicitly declared in the job file demos/risk/ScenarioDamage/job_risk.ini

  [consequence]
  consequence_file = {'taxonomy': 'consequences.csv'}

• Consequence ratios: The ratios that will get multiplied by the damage state probabilities, one set of ratios for each consequence function. The consequence ratios are currently provided by the user in the consequence CSV file, eg. demos/risk/ScenarioDamage/consequences.csv. The total number and names of the damage states in the consequences CSV file should match the number of limit states defined in the fragility model NRML file demos/risk/ScenarioDamage/structural_fragility_model.xml.
• Damage type: Should the consequence ratios be multiplied by the structural damage state probabilities, nonstructural damage state probabilities, or contents damage state probabilities? This is currently controlled by the loss_type field in the consequences CSV file. In demos/risk/ScenarioDamage/consequences.csv the user indicates that the structural damage state probabilities are to be used.
• Consequence multiplier: In most cases, this is a field in the exposure (eg. structural value, number of buildings, or number of occupants) that should be multiplied to the sumprod of the consequence ratios and damage state probabilities. In a few other cases, this field could be a function of one or more exposure fields (eg. debris). In the current implementation, this is the last term in the equations in https://github.com/gem/oq-engine/blob/engine-3.17/openquake/risklib/scientific.py#L1645-L1654

  elif consequence == 'losses':
      return dmgdist @ coeffs * asset['value-' + loss_type]
  elif consequence == 'collapsed':
      return dmgdist @ coeffs * asset['value-number']
  elif consequence == 'injured':
      return dmgdist @ coeffs * asset['occupants_night']
  elif consequence == 'fatalities':
      return dmgdist @ coeffs * asset['occupants_night']
  elif consequence == 'homeless':
      return dmgdist @ coeffs * asset['occupants_avg']

• Aggregation of consequences: If the job file includes aggregate_by = .. the engine must perform the usual aggregation by tag(s) for each consequence, similar to what's done by the scenario risk and event based risk calculators for losses and the scenario damage and event based damage calculators for damage results.

[nicolepaul]

Please note that the homeless calculations should be using residents (and not occupants_avg or occupants_night). More background here: https://github.com/gem/oq-engine/issues/8788