(ocean-customizable-viz)=

# customizable viz

The {py:class}`customizable_viz` task generates visualizations from ocean
model outputs using configurable map projection, variable selection, and
plotting options. All visualizations are done on the native MPAS mesh using
All visualizations are done on the native MPAS mesh using
`[mosaic](https://github.com/E3SM-Project/mosaic)`

The customizable_viz task can produce plots of two types, horizontal field
plots and vertical transect plots, from global MPAS fields.

```{image} images/viz_horiz_field.png
:align: center
:width: 500 px
```

```{image} images/viz_transect.png
:align: center
:width: 500 px
```

## suppported models

The task is designed to support output from global MPAS-Ocean or Omega
simulations and netcdf files generated by MPAS-Analysis. It is likely
extensible to MPAS-Seaice but this has not been tested.

## mesh

The mesh file must be pre-generated and provided via a filepath in the config
option `customizable_viz:mesh_filename`. The mesh must be global.

## vertical grid

There are no restrictions on the vertical grid specifications inherent to
the test case. The `vertical_grid` config section is not used.

Note that the vertical layer used for plotting a horizontal field will
correspond to the layer that has the closest mean z-mid value to the cfg
option `customizable_viz_horiz_field:z_target`.

## initial conditions

If the user wants to plot an MPAS initial condition, it must be pregenerated
and the path to the file must be provided in cfg option `customizable_viz:input_filename`.

## forcing

N/A

## time step and run duration

N/A

(ocean-customizable-viz-config)=
## config options

```cfg
[customizable_viz]
# Mesh file, absolute file path
mesh_file = ${MESH_FILE}

# Data file, absolute file path
input_file = ${INPUT_FILE}

[customizable_viz_horiz_field]

# Projection to use for the horizontal field plot, must be supported by mosaic
projection = PlateCarree

# Fields to plot, comma-separated
variables = temperature, salinity

# Bounding box for the plot, global by default
min_latitude = -90

max_latitude = 90

min_longitude = 0

max_longitude = 360

# Optional: name of the colormap to use, including cmocean
#colormap_name = cmo.balance

# Optional: additional arguments to provide to the colormap norm
norm_args = {}

# Optional: colormap range is set in terms of percentile from
# colormap_range_percent to 100 - colormap_range_percent
#colormap_range_percent = 5

# the type of norm used in the colormap
norm_type = linear

# Note: for some projections, choosing a different central longitude may
# result in cells spanning the plot boundary
central_longitude = 180.

# The depth in m below the surface to use for layer selection
# Only one vertical level will be selected and its depth may vary
z_target = 0.

[customizable_viz_transect]

# Fields to plot, comma-separated
variables = temperature, salinity

# The start and end coordinates for the transect
# where x is longitude and y is latitude
x_start = -5.0
y_start = -65.0
x_end = 10.0
y_end = -65.0

# Optional: limits for colormap scaling
#vmin = None
#vmax = None

# Color to use for interfaces between vertical levels
layer_interface_color = None
```

Note that the config options listed in each step section will be used for all
variables listed. For example, if a colormap cfg option is provided, all plots
will use the same colormap. If the colormap is not provided, the colormaps
derive from their defaults and may differ by variable.

## cores

N/A