.. _json: 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: .. currentmodule:: canopy.visualization .. list-table:: :header-rows: 1 :widths: 14 26 40 20 * - ``"figure"`` key - Function reference - JSON example file - Remark * - ``map_simple`` - :func:`map.make_simple_map` - `simple_map.json `_ - Can unite multiple fields (see example below) * - ``map_diff`` - :func:`map.make_diff_map` - `diff_map.json `_ - Compute the difference between two fields * - ``time_series`` - :func:`line_plot.make_time_series` - `time_series.json `_, `unite_time_series.json `_ - Unite: hist+scenario * - ``latitudinal_plot`` - :func:`line_plot.make_latitudinal_plot` - `multiple_latitudinal_plot.json `_ - * - ``static`` - :func:`static_plot.make_static_plot` - `static_plot.json `_ - * - ``distribution`` - :func:`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. .. currentmodule:: canopy.visualization.map 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: .. code-block:: python { "figure": "map_simple", "input_file": ["example_data/hist/anpp.out.gz", "example_data/ssp1A/anpp.out.gz"], "unite": true, ... } .. currentmodule:: canopy.visualization.line_plot 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 `_: .. code-block:: 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 } .. currentmodule:: canopy.core.field **Other features** - **Grid types and source:** You can specify which ``file_format``, ``grid_type``, and ``source`` (to retrieve metadata) to use from the :meth:`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 :meth:`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 :meth:`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 :func:`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 ------------------ .. currentmodule:: canopy.visualization.visualization_helpers - **No multiple figures function:** You cannot use the :func:`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.