Skip to content
Snippets Groups Projects
Model-Files.md 6.97 KiB
Newer Older
  • Learn to ignore specific revisions
  • Powers, Peter M.'s avatar
    Powers, Peter M. committed
    # Model Files
    
    A variety of logic tree, configuration, and data files that are common to all models and source
    types are described below and on related pages for specific model components, for example, ground
    motion models (GMMs) or magnitude-frequency distributions (MFDs).
    
    [[_TOC_]]
    
    ## Model and Calculation Configuration
    
    **model-info.json:** Required model identifying metadata. Currently the model name and
    definitions of Vs30 values for each NEHRP site class that were used when computing design ground
    motions from the model.
    
    ```json
    {
      "name": "NSHM Conterminous U.S. 2018",
      "site-class-vs30": {
        "AB": 1500,
        "B": 1080,
        "BC": 760,
        "C": 530,
        "CD": 365,
        "D": 260,
        "DE": 185,
        "E": 150
      }
    }
    ```
    
    **calc-config.json:** Optional calculation configuration file specifies the default
    calculation settings used for a NSHM. This file overrides any built in default values. See
    
    the [calculation configuration](./Calculation-Configuration.md) page for more details.
    
    Powers, Peter M.'s avatar
    Powers, Peter M. committed
    
    ## Logic Trees
    
    Any file or JSON member name containing `-tree` implies that the file contents or member value
    will be an array of logic tree branches. Branches are defined with an `id`, `weight`, and `value`.
    Depending on context, value can be a number, string, or object. For example:
    
     ```json
     [
      {
        "id": "string",
        "value": "number | string | object",
        "weight": 0.4
      }, {
        "id": "string",
        "value": "number | string | object",
        "weight": 0.6
      }
    ]
    ```
    
    If the `value` member is absent, then the branch `id` is also the `value`. Logic tree weights must
    
    Powers, Peter M.'s avatar
    Powers, Peter M. committed
    sum to one. Examples of logic trees present in a hazard model are described below. An `id` or
    `value` member value in ALL_CAPS indicates the value is one of a fixed number of options commonly
    referred to as an enum.
    
    Powers, Peter M.'s avatar
    Powers, Peter M. committed
    
    ### Source Model Logic Trees
    
    **source-tree.json:** Defines a single logic tree branching point where each branch `value` points
    to a subdirectory of nested branches. Source-tree weights are used to scale hazard curves when
    computing mean hazard and for source event-set selection. When loading a model, a source-tree
    governs all subsequent processing of nested directories. Only those resources required by the tree
    or its children will be processed; any standalone sources will be ignored. For example:
    
    ```json
    [
      {
        "id": "segmented",
        "weight": 0.5
      },
      {
        "id": "unsegmented",
        "weight": 0.5
      }
    ]
    ```
    
    **source-group.json:** A specialized form of logic tree that describes model branches that are
    
    Powers, Peter M.'s avatar
    Powers, Peter M. committed
    additivd and therefore does not include weights. Examples from the NSHM for the conterminous U.S.
    
    Powers, Peter M.'s avatar
    Powers, Peter M. committed
    NSHM include the Cascadia segmented partial-rupture models and the New Madrid 1500-yr cluster
    branches. The branch objects in a source group _may_ include an optional `scale` member that can
    be used to impose a probability of occurrence or other scaling requred by a NSHM. If absent, the
    `scale` value is one.
    
    ```json
    [
      {
        "id": "all",
        "scale": 0.2
      },
      {
        "id": "center-south",
        "scale": 1.5
      }
    ]
    ```
    
    ### GMM Logic Trees
    
    **gmm-tree.json:** Defines the logic tree of ground motion models to use in each tectonic setting.
    For example:
    
    ```json
    [
      { "id": "ASK_14", "weight": 0.25 },
      { "id": "BSSA_14", "weight": 0.25 },
      { "id": "CB_14", "weight": 0.25 },
      { "id": "CY_14", "weight": 0.25 }
    ]
    ```
    
    
    See the [ground motion models](./Ground-Motion-Models.md) page for details on GMMs supported in
    
    _nshmp-haz_ and the related `gmm-config.json` files that governs GMM behavior.
    
    Powers, Peter M.'s avatar
    Powers, Peter M. committed
    
    ### MFD Logic Trees
    
    
    Powers, Peter M.'s avatar
    Powers, Peter M. committed
    MFD logic trees are common to all source types and are defined as JSON members nested in other
    files. For example:
    
    Powers, Peter M.'s avatar
    Powers, Peter M. committed
    
    ```json
    "mfd-tree": [
      { "id": "M1", "weight": 0.3, "value": { "type": "SINGLE", "m": 6.8, "rate": 0.001 }},
      { "id": "M2", "weight": 0.3, "value": { "type": "SINGLE", "m": 7.0, "rate": 0.001 }},
      { "id": "M3", "weight": 0.3, "value": { "type": "SINGLE", "m": 7.2, "rate": 0.001 }},
      { "id": "M4", "weight": 0.1, "value": { "type": "SINGLE", "m": 7.4, "rate": 0.001 }}
    ]
    ```
    
    An `mfd-tree` may be included as a `properties` member of a GeoJSON feature or as a member of a
    `rupture-set.json` file. In both cases the tree may alternatively be identified with a string, in
    
    Powers, Peter M.'s avatar
    Powers, Peter M. committed
    which case the `mfd-tree` will be pulled from the collection of shared trees defined in a
    `mfd-map.json` file. A `mfd-map.json` file is typicaly located high in the source tree heirarchy
    and faciltates using the same MFDs on multiple branches of a source tree. The branches of a
    mfd-tree commonly have the generic ID's: `[M1, M2, M3, ...]` to support mfd-tree matching across
    source-tree branches.
    
    Powers, Peter M.'s avatar
    Powers, Peter M. committed
    
    How MFDs are intialized (or realized) depends on the presence and contents of `mfd-config.json` and
    `rate-tree.json` files. See the
    
    Powers, Peter M.'s avatar
    Powers, Peter M. committed
    [magnitude frequency distributions](./Magnitude-Frequency-Distributions.md) page for details on
    these files and the types of MFDs supported in _nshmp-haz_.
    
    Powers, Peter M.'s avatar
    Powers, Peter M. committed
    
    ## Rupture Sets
    
    
    Powers, Peter M.'s avatar
    Powers, Peter M. committed
    **rupture-set.json**: A `rupture-set` is the terminal file of a source-tree branch and defines the
    fault sections and MFD's required to intialize a source.
    
    Powers, Peter M.'s avatar
    Powers, Peter M. committed
    
    ```json
    {
      "name": "New Madrid - USGS (center)",
      "id": 3023,
      "sections": [3020, 3021, 3022],
      "mfd-tree": "usgs-hi-mag"
    }
    ```
    
    In the example above, one set of New Madrid ruptures is assigned the specified numeric `id`. The
    fault geometry of the rupture-set is constructed by stitching the specified fault `sections`
    together, and earthquake magnitudes and rates are governed by the specified `mfd-tree`. In this
    case, `mfd-tree` points to a named tree that will be present in an `mfd-map.json` accompanying
    the source-tree. The `sections` member may be absent. In this case, the `id` of the rupture-set
    is the same as the single, associated fault section.
    
    
    Powers, Peter M.'s avatar
    Powers, Peter M. committed
    **cluster-set.json**: A specialized form of a rupture set. Fault sources also support cluster
    models where the total hazard is computed from the probability of exceeding some ground motion
    level is conditioned on the occurrence of 2 or more, roughly contemporaneous events. A cluster-set
    is composed of an array of rupture-sets.
    
    Powers, Peter M.'s avatar
    Powers, Peter M. committed
    
    ```json
    {
      "name": "New Madrid - USGS (center, center-south)",
      "id": 3025,
      "rupture-sets": [
        {
          "name": "USGS (center, center)",
          "id": 3021,
          "mfd-tree": "usgs-hi-mag"
        },
        {
          "name": "USGS (center, south)",
          "id": 3022,
          "mfd-tree": "usgs-hi-mag"
        }
      ]
    }
    ```
    
    ## Related Pages
    
    * [Hazard Model](./Hazard-Model.md#hazard-model)
      * [Model Structure](./Model-Structure.md#model-structure)
      * [Model Files](./Model-Files.md#model-files)
      * [Source Types](./Source-Types.md#source-types)
      * [Magnitude Frequency Distributions (MFDs)](./Magnitude-Frequency-Distributions.md#magnitude-frequency-distributions)
      * [Rupture Scaling Relations](./Rupture-Scaling-Relations.md#rupture-scaling-relations)
      * [Ground Motion Models (GMMs)](./Ground-Motion-Models.md#ground-motion-models)
    * [**Documentation Index**](../README.md)
    
    ![USGS logo](./images/usgs-icon.png)  [U.S. Geological Survey](https://www.usgs.gov)
    
    National Seismic Hazard Mapping Project ([NSHMP](https://earthquake.usgs.gov/hazards/))