# Export Plot configuration: JSON Format

We use [matplotlib v3.1.3](https://matplotlib.org/3.1.3/index.html) for our plot generation. The plot report is configured using JSON. The top level `global` applies global configuration. It currently supports a limited subset of the [rcParams](https://matplotlib.org/3.1.3/tutorials/introductory/customizing.html?highlight=path.simplify): `font_size`, `font_family`, `agg_path_chunksize`. Future versions will support all rcParams keys. The `global["plot_options"]` can be used to configure plot options for all series. This is convenient if you want to apply an option to all series without having to define it for each one. 

`plot_options` can also be defined at the `plots` level, which will apply to each series within a plot, or at the `series` level, which will apply to a specific series. All `plot_options` (global, plot, and series) are merged together when plotting each series, with the `series` `plot_options` having the highest precedence, then plot, then global. The `plot_options` at any level supports all matplotlib [Line2D properties](https://matplotlib.org/3.1.3/api/_as_gen/matplotlib.lines.Line2D.html#matplotlib.lines.Line2D).

You may define the `plots_hspace` as part of the `page` object to control horizontal spacing between all of the plots on a page. This can be used to control the spacing when there are overlap issues. We recommend starting with a value of 1, exporting a small amount of data, and then increasing or decreasing the value to achieve the desired results.

You may define the `height_ratio` as part of the `plot` object to control how much vertical space it takes up. Defaults to a value of 1.

Any option may be omitted entirely and a default value will be used.

##### Trend Series Options:

Since the Export Plot configs are also used/referenced by the Trend Exports, we support options that are only used by the Trend Export plot generation. These option can be defined at the top level or per series. The top level will apply to all series but the per series definition will override it. 

The `trend_series` option can be defined to control which trend series are plotted. If not defined, then the min, avg, and max series will be plotted. 

Example: `"trend_series": ["min", "avg", "max"]`. If you want to only plot the average series, use `"trend_series": ["avg"]`.

The `trend_line` option can be defined to draw the trend line on the plot. A trend line will be drawn for each trend series. For example, if you are plotting a mnemonic's min, avg, max, then a trend line will be drawn for each series. If ommitted, then no trend line will be drawn. We currently only support `"linear"` to display the linear trend line.

Example: `"trend_line": "linear"`


Below is an example JSON plot config file. Note that `pages` and `plots` are JSON arrays which implies the generated pages and plots are ordered accordingly. **Any comments are for descriptive purposes only; they are not allowed in the actual configs.**

```json
{
  "global": {
      "plot_options": {
        "linewidth": 0.3,
        "marker": "d",
        "markersize": 3
      },
      "font_size" : 10,
      "font_family" : "monospace",
      "agg_path_chunksize": 10000
  },
  // Define the trend series that will be plotted for each mnemonic. This can be omitted
  // and it will default to min, avg, max.
  "trend_series": ["min", "avg", "max"],
  // A linear trend line will be drawn for all series. If omitted, no trend line will be drawn.
  "trend_line": "linear",
  "pages": [
    {
      "plots": [
        {
          "title": "1st plot on page 1",
          "series": [
              { 
                  "mnemonic": "oci.dau.boxrack.power.PS01.m1curoutp",
                  "plot_options": {"marker": "x"},
                  // Only plot the avg series for this mnemonic. This will override the top
                  // level "trend_series" option if it exists.
                  "trend_series": ["avg"],
                  // Display a linear trend line for this mnemonic.
                  "trend_line": "linear"
              }
          ],
          "plot_options": { "color": "red" },
          "y_min": -5,
          "y_max": 5
        }
      ]
    },
    {
      "plots_hspace": 1.2,
      "plots": [
        {
          "title": "2 plots on page 2",
          "height_ratio": 2,
          "series": [
            {
              "mnemonic": "oci.dau.dauc.Tlm.Red_BdTemp3",
              "plot_options": {
                "color": "r"
              }
            },
            {
              "mnemonic": "oci.dau.dauc.Tlm.Blue_BdTemp3",
              "plot_options": {
                "color": "b"
              }
            }
          ]
        },
        {
          "height_ratio": 1,
          "series": [
            {
              "mnemonic": "oci.dau.ddc.FPGA.CcdOpMode",
              "plot_options": {
                "color": "k"
              }
            }
          ]
        }
      ]
    }
  ]
}
```