JSON

The JSON mode allows you to use high-level visualization functions to easily and quickly create figures.

What you can do

You can generate the following types of figures by specifying the figure key in your JSON file:

`"figure"` key	Function reference	JSON example file	Remark
`map_simple`	`map.make_simple_map()`	simple_map.json	Can unite multiple fields (see example below)
`map_diff`	`map.make_diff_map()`	diff_map.json	Compute the difference between two fields
`time_series`	`line_plot.make_time_series()`	time_series.json, unite_time_series.json	Unite: hist+scenario
`latitudinal_plot`	`line_plot.make_latitudinal_plot()`	multiple_latitudinal_plot.json
`static`	`static_plot.make_static_plot()`	static_plot.json
`distribution`	`distribution_plot.make_distribution_plot()`	distribution_plot.json

For a complete list of available arguments, refer to the documentation for each function, and consult the corresponding JSON example file for practical usage.

With "figure": "map_simple", you can unite multiple fields into one and visualize them in a single map. Set "unite": true when you have multiple input files to combine them (e.g., concatenating a historical run with a scenario run, or joining spatial pieces). For example:

{
    "figure": "map_simple",
    "input_file": ["example_data/hist/anpp.out.gz", "example_data/ssp1A/anpp.out.gz"],
    "unite": true,
    ...
}

With "figure": "time_series", you can unite multiple fields to create a single continuous time series (e.g., historical + scenario). See unite_time_series.json:

{
  "figure": "time_series",
  "input_file": [
    "example_data/hist/cpool.out.gz",
    "example_data/ssp1A/cpool.out.gz"
  ],
  "unite": true,
  "output_file": "figures/test_json_examples/united_cpool_ts.png",
  "grid_type": "lonlat",
  "gridop": "sum",
  "convert_units": [1e-12, "GtC"],
  "layers": ["Total"],
  "yaxis_label": "Carbon Pools",
  "title": "Total carbon pools (historical + SSP1A united)",
  "palette": "Dark2",
  "x_fig": 12,
  "y_fig": 8
}

Other features

Grid types and source: You can specify which file_format, grid_type, and source (to retrieve metadata) to use from the Field.from_file() arguments.
Slice reduction: You can reduce data along time, lat, or lon dimensions using the time_slice, lat_slice, or lon_slice keys.
Drop layers: Remove unwanted layers from your data using the drop_layers key (accept a list).
Transform layers: Apply transformations to layers using the reduce_layers key and the Field.reduce_layers() function (accept a dictionary, see stacked_time_series.json for an example).
Apply operations: Apply arithmetic operations to layers using the apply key and the Field.apply() function. The config accepts op (e.g. "*", "+", "-", "/"), operand (a constant or layer name), optional layers (default: all layers), and optional how ("left" or "right" for non-commutative ops). For example, to multiply the Total layer by 100, use "apply": {"op": "*", "operand": 100, "layers": "Total"}. See apply_map.json for an example.
Convert units: Convert the units of your data using the convert_units key. This accepts a list with exactly two elements: the conversion factor (a number) and the new units string. For example, to convert from kg to GtC, use "convert_units": [1e-12, "GtC"]. See multiple_time_series.json for an example.
Filter data: Filter your data using the filter key with a query string. For example, to filter for values where Total > 0.4 and Que_rob < 0.15, use "filter": "Total > 0.4 and Que_rob < 0.15". See time_series.json for an example.
Filter region: Filter your data by a named geographical region using the region and optional region_type keys. Supported region_type values are country (Natural Earth), giorgi, SREX (IPCC SREX), and AR6 (IPCC AR6). See region_filter_map.json for an example.
Unite fields: Combine multiple input files into a single field using unite. When unite is true and multiple files are listed in input_file, they are concatenated along the time or spatial axes using canopy.unite(). Fields must have compatible grids and at least one overlapping layer. See unite_time_series.json for an example combining historical and scenario carbon pool data.

What you cannot do

No multiple figures function: You cannot use the multiple_figs() function.
No function keyword arguments as JSON keys: You cannot specify function keyword arguments (kwargs) directly as JSON keys.
No FLUXNET data and functions: You cannot use FLUXNET data and corresponding functions.