Spec for yaml format of logic tree definition

yaml-logic-tree.yaml

# Lines starting with symbol # are comments.

# On the top level each logic tree definition should have
# two specific items: SourceModelLogicTree and GMPELogicTree.

# SourceModelLogicTree node allows to specify the first level
# of branching: uncertainty on source model definition.
SourceModelLogicTree:
    # The next line means "take source_model1.xml with chance of 1/2".
    - 0.5: source_model1.xml
    # This branch has no subbranches: there are no uncertainties
    # with this particular source model.

    # Note that branches are specified as "- WEIGHT: VALUE",
    # where "-" just means "list item", "WEIGHT" represents
    # the probability of VALUE's correctness and "VALUE" itself
    # shows the consequence of choosing that branch (depends
    # on where are we branching from).

    # Indentation is important everywhere.

    - 0.3: source_model2.xml
      # Here we start branching on maxMagGR parameter.
      # Note there are no "-" in front of the line
      # and indentation is increased.
      maxMagGR absolute source=1:
          # Same format: "- WEIGHT: VALUE".
          - 0.2: +7.3
          - 0.6: +7.5
          - 0.2: +7.8
          # As before weights must sum to 1.
      # There is no way to set uncertainties on many parameters
      # on the first level.

    - 0.1: source_model2.xml

      # Branching on parameters is specified like this:
      # "PARAM_NAME <relative|absolute> [<options>]".
      maxMagGR relative tectonic-region-type=SubductionInterface:
      # First we show what parameter are we uncertain on (maxMagGR
      # in this case).

      # Then we choose the way we want to modify the value: type
      # either "relative" or "absolute", which mean "increment by"
      # or "replace with" respectively.

      # Options allow to filter the sources by some classifiers,
      # which include:
      #
      # * "source-type=area" -- filter sources by type. Could
      #   be "area", "point", "simple-fault", "complex-fault".
      # * "sources=[1,2,3]" -- the uncertainty is applied then
      #   only to listed sources.
      # * "source=1" -- the same as previous, but only for one
      #   source. Useful with "absolute" change.
      # * "tectonic-region-type=ActiveShallowCrust": filter
      #   by tectonic region type.

      # In addition to filters there is one more pair of options:
      # "source-correlation" and "no-source-correlation", which
      # mean "apply the same values to all sources" and "every
      # source samples value independently".
          - 0.2: +0.2
            # Here we specify another branching level on another
            # parameter.
            bValGR relative no-source-correlation: &uncert1
                # We assign a unique id to this list of values.
                # Parameter name and its options are not caught.
                - 0.2: +0.1
                - 0.6: +0.0
                - 0.2: -0.1
          - 0.6: +0.0
            # "+" is not required, but helps to look through
            # when positive and negative values are mixed.
          - 0.2: -0.2
            # We now can refer on uncertainty list defined above.
            # Basically it means "use the same list of weights and
            # values as in &uncert1".
            bValGR relative no-source-correlation: *uncert1

GMPELogicTree:
    # GMPE should be specified for all source types which occur
    # in source model definitions. There is no uncertainty on this
    # level -- for each source the appropriate GMPE logic tree
    # is taken.
    ActiveShallowCrust:
        # However there can be uncertainty on GMPE within
        # the same tectonic region type. Syntax is the same
        # as in uncertainties on parameters.
        - 0.5: BA_2008_AttenRel
        - 0.5: CB_2008_AttenRel
    StableShallowCrust:
        - 1.0: CY_2008_AttenRel


---

# The same example without comments:

SourceModelLogicTree:
    - 0.5: source_model1.xml

    - 0.3: source_model2.xml
      maxMagGR absolute source=1:
          - 0.2: +7.3
          - 0.6: +7.5
          - 0.2: +7.8

    - 0.2: source_model2.xml
      maxMagGR relative tectonic-region-type=SubductionInterface:
          - 0.2: +0.2
            bValGR relative no-source-correlation: &uncert1
                - 0.2: +0.1
                - 0.6: +0.0
                - 0.2: -0.1
          - 0.6: +0.0
          - 0.2: -0.2
            bValGR relative no-source-correlation: *uncert1

GMPELogicTree:
    ActiveShallowCrust:
        - 0.5: BA_2008_AttenRel
        - 0.5: CB_2008_AttenRel
    StableShallowCrust:
        - 1.0: CY_2008_AttenRel


---

# This example uses back-referencing extensively.
# It can be seen that complex uncertainty trees could
# be built with no resorting to copy-paste and parameters
# uncertainties could be separated from source model
# uncertainty.


Parameters:
    mMagGRRel: &mmag1
        - 0.2: +0.2
        - 0.6: +0.0
        - 0.2: -0.2
    bValGRRel: &bval1
        - 0.2: +0.1
        - 0.6: +0.0
          mMaxGRRel: *mmag1
        - 0.2: -0.1

SourceModelLogicTree:
    - 0.5: source_model1.xml
      bValGRRel: *bval1
    - 0.5: source_model2.xml
      bValGRRel: *bval1


GMPELogicTree:
    ActiveShallowCrust:
        - 1.0: BA_2008_AttenRel

Personally I would rename:
SourceModels -> SourceModelLogicTree
GMPEs -> GMPELogicTree

'absolute' uncertainties must require the 'sources' filter, and in this case it must contain only one ID (that is absolute uncertainties make sense only for a single source)

Made changes, thanks!