Things to document in the manual

[micheles]

(current pdf)

Hazard

• Fix duplicate listings: listing 3 (simple fault, pg 28) and listing 4 (directivity, pg 29)
• Document the csv outputs for:
  • Hazard curves
  • Hazard maps
  • UHS
  • Disaggregation
  • Sigma-Epsilon output for scenario and event_based
  • Events output for scenario and event_based
  • Earthquake ruptures output for event_based
• Document the multi-rupture scenario hazard feature (Scenario Hazard Calculator - Support for multiple ruptures and TRs #5603, Implemented multi-rupture scenario calculator #5942)
• Document new parameters
  • individual_rlzs
  • individual_curves
  • pointsource_distance
  • ses_seed
  • filter_distance
  • shift_hypo
  • point_rupture_bins
  • collapse_level
  • discard_trts
• Document the secondary perils module
• Add a scenario hazard example in "Chapter 5. Demonstrative Examples"
• New magnitude-scaling relationships: AllenHayes, Leonard, GermanyMSR
• Document the griddedRupture typology
• Document MultiPointSources
• Document site amplification implementation
• Describe the various site model parameters for:
  • those describing uniform site conditions in the job file (eg. reference_depth_to_2pt5km_per_sec)
  • those listed in a site model file (eg. backarc, custom_site_id , z1pt0, z1pt4, z2pt5, xvf, backarc_distance, eshm20_region)
  • those related to site amplification (eg. ampcode, ec8, ec8_p18, h800, geology, amplfactor)
• Mention the units for the different IMTs available
• Period dependent weights in the logic tree
• MetaGSIM, AvgGMPE, NRCan15SiteTerm (maybe too specific for user manual?)

Risk

• Document classical_damage and classical_risk calculations starting from hazard curve csv files
• Clarify input parameters for fragility and vulnerability
• Document the event_based_damage calculator
• Document the change in algorithm for scenario_damage
• Document new/modified parameters
  • ignore_covs
  • individual_curves
  • asset_loss_table (discontinued in Removed asset_loss_table from ebrisk #5186)
  • approx_ddd (extremely limited use)
  • modal_damage_state (extremely limited use)
  • collapse_threshold (currently unused by the engine)
• Rewrite §7.1 Exposure to use primarily csv exposure examples
• Mention that zipped exposures can be provided
• Document the new scenario damage / risk outputs dmg_by_event and losses_by_event

General

• Glossary was last seen in v3.1 (01 Jun 2018), absconding in all later versions

Document in a manual for advanced users

• Document new parameters:
  • discard_assets
  • aggregate_by
  • ignore_missing_costs
  • minimum_asset_loss
• Describe the (correct?) expected behavior of the stochastic event set
  generator for different values of the three parameters:
  ses_per_logic_tree_path, investigation_time, number_of_logic_tree_samples,
  for both sampling and full enumeration
• The ses_seed is not mentioned, but it is important since it is the one used for generating the ruptures in event based — short explanation of the behaviors governed by ses_seed, random_seed and master_seed would be useful
• Document the new ebrisk calculator

[g-weatherill]

Is there any documentation available explaining the use of the sourceGroup, and on the multiPointSource and the griddedRupture typologies? The only examples I can find are in the QA tests data, but no explanation is given regarding the logic of the calculators. If not in manual this should be added in the next version.

[micheles]

@g-weatherill MultiPoint sources are documented here https://github.com/gem/oq-engine/blob/master/doc/adv-manual/multipoint.rst while there is nothing at all on GriddedRuptures.

[Pritishchugh22]

Dear @micheles
I am writing this to express my interest in participating in the Google Season of Docs program, 2023. I am a final year student at IIT Mandi, pursuing Bachelors of Technology in Computer Science. I am doing minors in Data Science and have done a significant number of courses as well as projects in this domain.

Could you please guide me on how to proceed. I would appreciate any advice or recommendations you may have regarding the project.
Regards
Pritish Chugh

[vinayakgavariya]

Hello @micheles

I am Vinayak
I would love to contribute to this project through documentation, I would love to know the ways in which I can contribute to it.
If you have something for me can you please guide me ?
I would appreciate your help.

Thank you :)

[micheles]

Please send an email to andres.abarca@globalquakemodel.org if you want to partecipate to the documentation project.

[nicolepaul]

I think we may also need to document the taxonomy_mapping_csv parameter. It has come up twice in support requests I've received recently, and I'm not aware of any place where it is documented.

[micheles]

It is now documented in user-guide/inputs/taxonomy-mapping.rst