# Metrics Dictionary

The "metrics" dictionary contains the values and metadata relevant for the
metrics associated with the parent trace. One challenge with ground motion
metric data is that different metrics exhibit very different structure. For
example, some metrics are simply scalars (e.g., PGA) while others are arrays
(e.g., response spectra, which are a function of both oscillator period and
the assumed percent of critical damping).

While it is possible to list each metric as a separate element in a list, there
are two main drawbacks to doing so:

1. It is inefficient from a file size perspective, and
2. It is difficult to parse because the properties will be different for each
   metric.

Thus, we have designed a general metrics data structure with the goals of
being easy to extend to a wide range of metric data structures, consistency in
how the metrics are stored to make parsing the data more straight-forward, and minimizing the file size.

The dictionary has the following required keys:

**properties**
: A dictionary with the following keys _(dictionary; required)_:

**description**
: Metric description _(string; required)_.

**name**
: Metric name _(string; required)_.

**units**
: Metric units _(string; required)_.

**provenance_ids**
: A list of strings giving provenance IDs relevant to this trace
_(list; optional)_.

**time_of_peak**
: Time of metric peak for the PGA metric in UTC in ISO 8601 _extended_ format
_(str; optional)_.

**dimensions**
: A dictionary with the following keys _(dictionary; required when metric is an array)_:

**number**
: The number of dimensions for this metric (`n`)
_(integer; required)_.

**names**
: A list of strings describing the metric dimension names; length must
be equal to the number of metric dimensions `n`
_(list; required)_.

**units**
: A string or list of strings describing the units of the metric dimensions;
length must be equal to the number of metric dimensions
`n` _(list; required)_.

**axis_values**
: An array giving the values of the dimensions; the first dimension of
the array must equal the number of metric dimensions `n`;
the lengths of each constituent array are are
`[p, q, ...]` _(array; required)_.

**values**
: An array giving the metric values; the dimensions of the array must be
equal to the length of each of the dimension value arrays
`p x q x ...` _(float or array; required)_.

**std_deviations**
: An array giving the standard deviation of the above metric values;
the dimensions of the array must be equal to the length of each of
the dimension value arrays
`p x q x ...` _(float or array; required)_.

An example metrics dictionary:

```{code-block} json
---
force: true
---
  ...
  "traces": [
      {
          ...
          "metrics": [
              {
                  "properties": {
                      "description": "Spectral acceleration",
                      "name": "SA",
                      "units": "g",
                      "provenance_ids": [
                          "seis_prov:sp000_sa_0000000",
                          "seis_prov:sp000_pp_0000000",
                          "seis_prov:sp000_og_0000000"
                      ]
                  },
                  "dimensions": {
                      "number": 2,
                      "names": [
                          "critical damping",
                          "period"
                      ],
                      "units": ["%", "s"],
                      "values": [
                          [5.0, 10.0, 20.0],
                          [0.5, 1.0]
                      ]
                  },
                  "values": [
                      [2.3, 2.0],
                      [1.6, 1.4],
                      [2.0, 1.8]
                  ],
                  "std_deviations": [
                      [null, 1.0, 0.2],
                      [0.8, 0.7, 0.4],
                      [1.0, 0.9, 0.5]
                    ]
              }
          ]
      }
  ]

```