Ploting Routines

gcmprocpy provides a range of functions for data visualization. Below are the key plotting routines along with their detailed parameters and usage examples.

Note

For live examples with output, see the Plotting notebook.

Mode: API

Jupyter notebooks

gcmprocpy can be used in two modes in Jupyter notebooks: Regular plotting and Interactive plotting.

For regular plotting in Jupyter notebooks, use the following code snippet in an executable cell:

%matplotlib inline

Note

Use %config InlineBackend.figure_format = 'retina' for high quality plots.

For interactive plotting in Jupyter notebooks, use the following code snippet in an executable cell:

%matplotlib widget

Warning

The interactive plotting mode doesn’t work in Jupyter notebooks on NCAR JupyterHub.

Loading Datasets

This function loads the netCDF datasets for the plotting routines.

gcmprocpy.io.load_datasets(directory, dataset_filter=None)[source]

Loads netCDF datasets for the plotting routines.

Parameters:

directory (str) – The location of the directory where the files are stored or the path to a single file.
dataset_filter (str, optional) – The string to filter the NetCDF files to select from (e.g., ‘prim’, ‘sech’). Defaults to None.

Returns:

A list of ModelDataset objects, each containing an xarray.Dataset, filename, and model type.

Return type:

list[ModelDataset]

Closing Datasets

This function closes the netCDF datasets.

Warning

This function should be called after the plotting routines have been executed.

gcmprocpy.io.close_datasets(datasets)[source]

Closes the xarray datasets.

Parameters:: datasets (list[ModelDataset]) – A list of ModelDataset objects.
Returns:: None

Saving Output

This function saves a plot to a file.

gcmprocpy.io.save_output(output_directory, filename, output_format, plot_object)[source]

Example:

Save a plot as a PNG file.

datasets = gy.load_datasets(directory, dataset_filter)
plot = gy.plt_lat_lon(datasets, 'TN', mtime=[360, 0, 0, 0], level=4.0)
gy.save_output('/output/path', 'my_plot', 'png', plot)

Latitude vs Longitude Contour Plots

This function generates a contour plot of a variable against latitude and longitude.

gcmprocpy.plot_gen.plt_lat_lon(datasets, variable_name, time=None, mtime=None, level=None, level_type='pressure', variable_unit=None, center_longitude=0, central_latitude=0, projection='mercator', contour_intervals=None, contour_value=None, symmetric_interval=False, cmap_color=None, cmap_lim_min=None, cmap_lim_max=None, line_color='white', coastlines=False, nightshade=False, gm_equator=False, latitude_minimum=None, latitude_maximum=None, longitude_minimum=None, longitude_maximum=None, wind=False, wind_density=15, wind_scale=None, wind_color='black', polar_label='lt', grid=False, clean_plot=False, verbose=False)[source]

Generates a Latitude vs Longitude contour plot for a variable.

Parameters:

datasets (xarray.Dataset) – The loaded dataset/s using xarray.
variable_name (str) – The name of the variable with latitude, longitude, and lev/ilev dimensions.
time (np.datetime64, optional) – The selected time, e.g., ‘2022-01-01T12:00:00’.
mtime (list[int], optional) – The selected time as a list, e.g., [1, 12, 0] for 1st day, 12 hours, 0 mins.
level (float, optional) – The selected lev/ilev value.
variable_unit (str, optional) – The desired unit of the variable.
center_longitude (float, optional) – The central longitude for the plot. Defaults to 0.
central_latitude (float, optional) – The central latitude for the plot. Used by the orthographic projection to set the viewing angle. Defaults to 0.
projection (str, optional) – Map projection type. Options: ‘mercator’ (default), ‘north_polar’, ‘south_polar’, ‘polar’ (both hemispheres side by side), ‘orthographic’ (satellite view), ‘mollweide’ (equal-area).
contour_intervals (int, optional) – The number of contour intervals. Defaults to 20. Ignored if contour_value is provided.
contour_value (int, optional) – The value between each contour interval.
symmetric_interval (bool, optional) – If True, the contour intervals will be symmetric around zero. Defaults to False.
cmap_color (str, optional) – The color map of the contour. Defaults to ‘viridis’ for Density, ‘inferno’ for Temp, ‘bwr’ for Wind, ‘viridis’ for undefined.
cmap_lim_min (float, optional) – Minimum limit for the color map. Defaults to the minimum value of the variable.
cmap_lim_max (float, optional) – Maximum limit for the color map. Defaults to the maximum value of the variable.
line_color (str, optional) – The color for all lines in the plot. Defaults to ‘white’.
coastlines (bool, optional) – Shows coastlines on the plot. Defaults to False.
nightshade (bool, optional) – Shows nightshade on the plot. Defaults to False.
gm_equator (bool, optional) – Shows geomagnetic equator on the plot. Defaults to False.
latitude_minimum (float, optional) – Minimum latitude to slice plots. Defaults to -87.5.
latitude_maximum (float, optional) – Maximum latitude to slice plots. Defaults to 87.5.
longitude_minimum (float, optional) – Minimum longitude to slice plots. Defaults to -180.
longitude_maximum (float, optional) – Maximum longitude to slice plots. Defaults to 175.
wind (bool, optional) – Overlay wind vectors on the plot. Uses model-specific defaults (TIE-GCM: UN/VN, WACCM-X: U/V). Defaults to False.
wind_density (int, optional) – Stride for thinning wind vectors (every Nth point). Defaults to 15.
wind_scale (float, optional) – Scale factor for quiver arrows. Larger values make arrows shorter. Defaults to None (auto-scaled).
wind_color (str, optional) – Color of the wind vectors. Defaults to ‘black’.
polar_label (str, optional) – Perimeter labels for polar projections. ‘lt’ (default) draws solar local-time labels at every 30° azimuth (the tgcmproc look), ‘lon’ draws geographic longitude labels, None disables ring labels and falls back to inline gridline labels. Ignored for non-polar projections.
grid (bool, optional) – Overlay coordinate grid lines on the plot (cartopy gridlines on maps, axis grid elsewhere). Defaults to False.
clean_plot (bool, optional) – A flag indicating whether to display the subtext. Defaults to False.
verbose (bool, optional) – A flag indicating whether to print execution data. Defaults to False.

Returns:

Contour plot.

Return type:

matplotlib.figure.Figure

Example:

Load datasets and generate a Latitude vs Longitude contour plot.

datasets = gy.load_datasets(directory, dataset_filter)
variable_name = 'TN'
value_of_mtime = [360, 0, 0, 0]
pressure_level = 4.0
unit_of_variable = 'K'
intervals = 20
plot = gy.plt_lat_lon(datasets, variable_name, mtime=value_of_mtime, level=pressure_level, variable_unit=unit_of_variable, contour_intervals=intervals)

Height Mode:

Use level_type='height' to specify the level as height in km instead of pressure.

# Lat-lon plot at 300 km altitude (automatically finds nearest pressure level)
plot = gy.plt_lat_lon(datasets, 'TN', time='2022-01-01T12:00:00',
                      level=300.0, level_type='height')

Polar Projections:

The projection parameter supports polar stereographic views in addition to the default Mercator projection.

# North polar stereographic
plot = gy.plt_lat_lon(datasets, 'TN', mtime=[360, 0, 0, 0], level=4.0, projection='north_polar')

# South polar stereographic
plot = gy.plt_lat_lon(datasets, 'TN', mtime=[360, 0, 0, 0], level=4.0, projection='south_polar')

# Both hemispheres side by side
plot = gy.plt_lat_lon(datasets, 'TN', mtime=[360, 0, 0, 0], level=4.0, projection='polar')

Polar perimeter labels are controlled by polar_label:

# Solar local time labels (default — the tgcmproc look)
plot = gy.plt_lat_lon(datasets, 'TN', time='2003-03-20T00:00:00', level=4.0,
                      projection='north_polar', polar_label='lt')

# Geographic longitude labels
plot = gy.plt_lat_lon(datasets, 'TN', time='2003-03-20T00:00:00', level=4.0,
                      projection='north_polar', polar_label='lon')

# Disable ring labels (fall back to inline gridline labels)
plot = gy.plt_lat_lon(datasets, 'TN', time='2003-03-20T00:00:00', level=4.0,
                      projection='north_polar', polar_label=None)

Orthographic and Mollweide Projections:

# Orthographic (satellite view) with coastlines
plot = gy.plt_lat_lon(datasets, 'TN', mtime=[360, 0, 0, 0], level=4.0,
                      projection='orthographic', coastlines=True)

# Mollweide (equal-area) with coastlines
plot = gy.plt_lat_lon(datasets, 'TN', mtime=[360, 0, 0, 0], level=4.0,
                      projection='mollweide', coastlines=True)

Wind Vector Overlays:

Set wind=True to overlay wind vectors. Variable names are automatically selected based on model type (TIE-GCM: UN/VN, WACCM-X: U/V).

# Mercator with wind vectors
plot = gy.plt_lat_lon(datasets, 'TN', mtime=[360, 0, 0, 0], level=4.0, wind=True)

# Orthographic with wind vectors and coastlines
plot = gy.plt_lat_lon(datasets, 'TN', mtime=[360, 0, 0, 0], level=4.0,
                      projection='orthographic', wind=True, wind_density=3, coastlines=True)

# Customize wind arrow appearance
plot = gy.plt_lat_lon(datasets, 'TN', mtime=[360, 0, 0, 0], level=4.0,
                      wind=True, wind_density=5, wind_color='red', wind_scale=500)

Coastlines:

Add coastline outlines to any projection.

# Mercator with coastlines
plot = gy.plt_lat_lon(datasets, 'TN', mtime=[360, 0, 0, 0], level=4.0, coastlines=True)

# Polar with coastlines
plot = gy.plt_lat_lon(datasets, 'TN', mtime=[360, 0, 0, 0], level=4.0,
                      projection='polar', coastlines=True)

Pressure Level / Height vs Variable Line Plot

This function generates a line plot of a variable at a specific latitude and optional longitude, time, and local time.

gcmprocpy.plot_gen.plt_lev_var(datasets, variable_name, latitude, time=None, mtime=None, longitude=None, log_level=True, variable_unit=None, level_minimum=None, level_maximum=None, y_axis='pressure', localtime=None, grid=False, clean_plot=False, verbose=False)[source]

Generates a Level vs Variable line plot for a given latitude.

Parameters:

datasets (xarray.Dataset) – The loaded dataset/s using xarray.
variable_name (str) – The name of the variable with latitude, longitude, and lev/ilev dimensions.
latitude (float) – The specific latitude value for the plot.
time (np.datetime64, optional) – The selected time, e.g., ‘2022-01-01T12:00:00’.
mtime (list[int], optional) – The selected time as a list, e.g., [1, 12, 0] for 1st day, 12 hours, 0 mins.
longitude (float, optional) – The specific longitude value for the plot.
localtime (float or str, optional) – Solar local time (hours, 0-24) to select instead of longitude; converted UT-aware to the geographic longitude at that local time for the slice. Use ‘mean’ for the zonal mean. Overrides longitude when set. Defaults to None.
log_level (bool) – A flag indicating whether to display level in log values. Default is True.
variable_unit (str, optional) – The desired unit of the variable.
level_minimum (float, optional) – Minimum level value for the plot. Defaults to None.
level_maximum (float, optional) – Maximum level value for the plot. Defaults to None.
grid (bool, optional) – Overlay coordinate grid lines on the plot (cartopy gridlines on maps, axis grid elsewhere). Defaults to False.
clean_plot (bool, optional) – A flag indicating whether to display the subtext. Defaults to False.
verbose (bool, optional) – A flag indicating whether to print execution data. Defaults to False.

Returns:

Line plot.

Return type:

matplotlib.figure.Figure

Example:

Load datasets and generate a Pressure Level / Height vs Variable Line plot.

datasets = gy.load_datasets(directory, dataset_filter)
variable_name = 'TN'
latitude = 30.0
time_value = '2022-01-01T12:00:00'
longitude_value = 45.0
unit_of_variable = 'K'
plot = gy.plt_lev_var(datasets, variable_name, latitude, time=time_value, longitude=longitude_value, variable_unit=unit_of_variable)

Variable vs Latitude Line Plot (Meridional)

This function generates a 1D meridional line plot of a variable along latitude at a fixed longitude and pressure level (or height). Pass longitude='mean' for a zonal-mean profile.

gcmprocpy.plot_gen.plt_var_lat(datasets, variable_name, level, time=None, mtime=None, longitude=None, level_type='pressure', variable_unit=None, latitude_minimum=None, latitude_maximum=None, localtime=None, grid=False, clean_plot=False, verbose=False)[source]

Generates a meridional 1D line plot (variable vs latitude) at a fixed longitude and level.

Parameters:

datasets (xarray.Dataset) – The loaded dataset/s using xarray.
variable_name (str) – The name of the variable with latitude, longitude, and lev/ilev dimensions.
level (float) – The selected lev/ilev value (or ‘mean’).
time (np.datetime64, optional) – The selected time, e.g., ‘2022-01-01T12:00:00’.
mtime (list[int], optional) – The selected time as a list, e.g., [1, 12, 0].
longitude (Union[float, str], optional) – The specific longitude, or ‘mean’ for zonal mean.
localtime (float or str, optional) – Solar local time (hours, 0-24) to select instead of longitude; converted UT-aware to the geographic longitude at that local time for the slice. Use ‘mean’ for the zonal mean. Overrides longitude when set. Defaults to None.
level_type (str, optional) – ‘pressure’ (default) or ‘height’.
variable_unit (str, optional) – The desired unit of the variable.
latitude_minimum (float, optional) – Minimum latitude on the x-axis.
latitude_maximum (float, optional) – Maximum latitude on the x-axis.
grid (bool, optional) – Overlay coordinate grid lines on the plot (cartopy gridlines on maps, axis grid elsewhere). Defaults to False.
clean_plot (bool, optional) – If True, hide subtext. Defaults to False.
verbose (bool, optional) – If True, log execution data. Defaults to False.

Returns:

Line plot.

Return type:

matplotlib.figure.Figure

Example:

datasets = gy.load_datasets(directory, dataset_filter)
plot = gy.plt_var_lat(datasets, 'TN', level=4.0,
                      time='2022-01-01T12:00:00', longitude=45.0)
# Zonal mean
plot = gy.plt_var_lat(datasets, 'TN', level=4.0,
                      time='2022-01-01T12:00:00', longitude='mean')

Variable vs Longitude Line Plot (Zonal)

This function generates a 1D zonal line plot of a variable along longitude at a fixed latitude and pressure level (or height). Pass latitude='mean' for a meridional-mean profile, or latitude='wmean' for a cos(lat) area-weighted meridional mean (the unweighted 'mean' over-weights the poles).

gcmprocpy.plot_gen.plt_var_lon(datasets, variable_name, level, time=None, mtime=None, latitude=None, level_type='pressure', variable_unit=None, longitude_minimum=None, longitude_maximum=None, grid=False, clean_plot=False, verbose=False)[source]

Generates a zonal 1D line plot (variable vs longitude) at a fixed latitude and level.

Parameters:

datasets (xarray.Dataset) – The loaded dataset/s using xarray.
variable_name (str) – The name of the variable with latitude, longitude, and lev/ilev dimensions.
level (float) – The selected lev/ilev value (or ‘mean’).
time (np.datetime64, optional) – The selected time, e.g., ‘2022-01-01T12:00:00’.
mtime (list[int], optional) – The selected time as a list, e.g., [1, 12, 0].
latitude (Union[float, str], optional) – The specific latitude, or ‘mean’ for meridional mean.
level_type (str, optional) – ‘pressure’ (default) or ‘height’.
variable_unit (str, optional) – The desired unit of the variable.
longitude_minimum (float, optional) – Minimum longitude on the x-axis.
longitude_maximum (float, optional) – Maximum longitude on the x-axis.
grid (bool, optional) – Overlay coordinate grid lines on the plot (cartopy gridlines on maps, axis grid elsewhere). Defaults to False.
clean_plot (bool, optional) – If True, hide subtext. Defaults to False.
verbose (bool, optional) – If True, log execution data. Defaults to False.

Returns:

Line plot.

Return type:

matplotlib.figure.Figure

Example:

datasets = gy.load_datasets(directory, dataset_filter)
plot = gy.plt_var_lon(datasets, 'TN', level=4.0,
                      time='2022-01-01T12:00:00', latitude=30.0)

Pressure Level / Height vs Longitude Contour Plot

This function generates a contour plot of a variable at a specific latitude against longitude, with optional time and local time.

gcmprocpy.plot_gen.plt_lev_lon(datasets, variable_name, latitude, time=None, mtime=None, log_level=True, variable_unit=None, contour_intervals=20, contour_value=None, symmetric_interval=False, cmap_color=None, cmap_lim_min=None, cmap_lim_max=None, line_color='white', level_minimum=None, level_maximum=None, longitude_minimum=None, longitude_maximum=None, y_axis='pressure', wind=False, wind_density=5, wind_scale=None, wind_color='black', grid=False, clean_plot=False, verbose=False)[source]

Generates a Level vs Longitude contour plot for a given latitude.

Parameters:

datasets (xarray.Dataset) – The loaded dataset/s using xarray.
variable_name (str) – The name of the variable with latitude, longitude, and lev/ilev dimensions.
latitude (float) – The specific latitude value for the plot.
time (np.datetime64, optional) – The selected time, e.g., ‘2022-01-01T12:00:00’.
mtime (list[int], optional) – The selected time as a list, e.g., [1, 12, 0] for 1st day, 12 hours, 0 mins.
log_level (bool) – A flag indicating whether to display level in log values. Default is True.
variable_unit (str, optional) – The desired unit of the variable.
contour_intervals (int, optional) – The number of contour intervals. Defaults to 20. Ignored if contour_value is provided.
contour_value (int, optional) – The value between each contour interval.
symmetric_interval (bool, optional) – If True, the contour intervals will be symmetric around zero. Defaults to False.
cmap_color (str, optional) – The color map of the contour. Defaults to ‘viridis’ for Density, ‘inferno’ for Temp, ‘bwr’ for Wind, ‘viridis’ for undefined.
cmap_lim_min (float, optional) – Minimum limit for the color map. Defaults to the minimum value of the variable.
cmap_lim_max (float, optional) – Maximum limit for the color map. Defaults to the maximum value of the variable.
line_color (str, optional) – The color for all lines in the plot. Defaults to ‘white’.
level_minimum (float, optional) – Minimum level value for the plot. Defaults to None.
level_maximum (float, optional) – Maximum level value for the plot. Defaults to None.
longitude_minimum (float, optional) – Minimum longitude value for the plot. Defaults to -180.
longitude_maximum (float, optional) – Maximum longitude value for the plot. Defaults to 175.
wind (bool, optional) – Overlay (U, W) wind vectors on the cross-section. Uses model-specific defaults (TIE-GCM: UN/WN, WACCM-X: U/OMEGA). Defaults to False.
wind_density (int, optional) – Stride for thinning wind vectors (every Nth point). Defaults to 5.
wind_scale (float, optional) – Scale factor for quiver arrows. Larger values make arrows shorter. Defaults to None (auto-scaled).
wind_color (str, optional) – Color of the wind vectors. Defaults to ‘black’.
grid (bool, optional) – Overlay coordinate grid lines on the plot (cartopy gridlines on maps, axis grid elsewhere). Defaults to False.
clean_plot (bool, optional) – A flag indicating whether to display the subtext. Defaults to False.
verbose (bool, optional) – A flag indicating whether to print execution data. Defaults to False.

Returns:

Contour plot.

Return type:

matplotlib.figure.Figure

Example:

datasets = gy.load_datasets(directory, dataset_filter)
variable_name = 'TN'
latitude = 30.0
time_value = '2022-01-01T12:00:00'
unit_of_variable = 'K'
contour_intervals = 20
plot = gy.plt_lev_lon(datasets, variable_name, latitude, time=time_value, variable_unit=unit_of_variable, contour_intervals=contour_intervals)

Overlay (U, W) wind vectors on the cross-section:

plot = gy.plt_lev_lon(datasets, 'TN', latitude=2.5,
                      time='2003-03-20T00:00:00',
                      wind=True, wind_density=3)

Pressure Level / Height vs Latitude Contour Plot

This function generates a contour plot of a variable against pressure level / height and latitude.

gcmprocpy.plot_gen.plt_lev_lat(datasets, variable_name, time=None, mtime=None, longitude=None, log_level=True, variable_unit=None, contour_intervals=20, contour_value=None, symmetric_interval=False, cmap_color=None, cmap_lim_min=None, cmap_lim_max=None, line_color='white', level_minimum=None, level_maximum=None, latitude_minimum=None, latitude_maximum=None, y_axis='pressure', wind=False, epflux=False, wind_density=5, wind_scale=None, wind_color='black', localtime=None, grid=False, clean_plot=False, verbose=False)[source]

Generates a Level vs Latitude contour plot for a specified time and/or longitude.

Parameters:

datasets (xarray.Dataset) – The loaded dataset/s using xarray.
variable_name (str) – The name of the variable with latitude, longitude, and lev/ilev dimensions.
time (np.datetime64, optional) – The selected time, e.g., ‘2022-01-01T12:00:00’.
mtime (list[int], optional) – The selected time as a list, e.g., [1, 12, 0] for 1st day, 12 hours, 0 mins.
longitude (float, optional) – The specific longitude value for the plot.
localtime (float or str, optional) – Solar local time (hours, 0-24) to select instead of longitude; converted UT-aware to the geographic longitude at that local time for the slice. Use ‘mean’ for the zonal mean. Overrides longitude when set. Defaults to None.
log_level (bool) – A flag indicating whether to display level in log values. Default is True.
variable_unit (str, optional) – The desired unit of the variable.
contour_intervals (int, optional) – The number of contour intervals. Defaults to 20. Ignored if contour_value is provided.
contour_value (int, optional) – The value between each contour interval.
symmetric_interval (bool, optional) – If True, the contour intervals will be symmetric around zero. Defaults to False.
cmap_color (str, optional) – The color map of the contour. Defaults to ‘viridis’ for Density, ‘inferno’ for Temp, ‘bwr’ for Wind, ‘viridis’ for undefined.
cmap_lim_min (float, optional) – Minimum limit for the color map. Defaults to the minimum value of the variable.
cmap_lim_max (float, optional) – Maximum limit for the color map. Defaults to the maximum value of the variable.
line_color (str, optional) – The color for all lines in the plot. Defaults to ‘white’.
level_minimum (float, optional) – Minimum level value for the plot. Defaults to None.
level_maximum (float, optional) – Maximum level value for the plot. Defaults to None.
latitude_minimum (float, optional) – Minimum latitude value for the plot. Defaults to -87.5.
latitude_maximum (float, optional) – Maximum latitude value for the plot. Defaults to 87.5.
wind (bool, optional) – Overlay (V, W) wind vectors on the cross-section. Uses model-specific defaults (TIE-GCM: VN/WN, WACCM-X: V/OMEGA). Defaults to False.
epflux (bool, optional) – Overlay (EPVY, EPVZ) Eliassen-Palm flux vectors instead of winds. Mutually exclusive with wind. Defaults to False.
wind_density (int, optional) – Stride for thinning overlay vectors (every Nth point). Defaults to 5.
wind_scale (float, optional) – Scale factor for quiver arrows. Larger values make arrows shorter. Defaults to None (auto-scaled).
wind_color (str, optional) – Color of the overlay vectors. Defaults to ‘black’.
grid (bool, optional) – Overlay coordinate grid lines on the plot (cartopy gridlines on maps, axis grid elsewhere). Defaults to False.
clean_plot (bool, optional) – A flag indicating whether to display the subtext. Defaults to False.
verbose (bool, optional) – A flag indicating whether to print execution data. Defaults to False.

Returns:

Contour plot.

Return type:

matplotlib.figure.Figure

Example:

Load datasets and generate a Pressure Level / Height vs Latitude contour plot.

datasets = gy.load_datasets(directory, dataset_filter)
variable_name = 'TN'
longitude_value = 45.0
time_value = '2022-01-01T12:00:00'
unit_of_variable = 'K'
plot = gy.plt_lev_lat(datasets, variable_name, longitude=longitude_value, time=time_value, variable_unit=unit_of_variable)

Overlay (V, W) wind vectors on the meridional cross-section:

plot = gy.plt_lev_lat(datasets, 'TN', longitude=30.0,
                      time='2003-03-20T00:00:00',
                      wind=True, wind_density=3)

Or overlay Eliassen-Palm flux vectors (EPVY, EPVZ) instead — useful for diagnosing planetary-wave forcing of the zonal mean flow:

plot = gy.plt_lev_lat(datasets, 'TN', longitude='mean',
                      time='2003-03-20T00:00:00',
                      epflux=True, wind_density=3)

Pressure Level / Height vs Time Contour Plot

This function creates a contour plot of a variable against pressure level / height and time.

gcmprocpy.plot_gen.plt_lev_time(datasets, variable_name, latitude, longitude=None, log_level=True, variable_unit=None, contour_intervals=10, contour_value=None, symmetric_interval=False, cmap_color=None, cmap_lim_min=None, cmap_lim_max=None, line_color='white', level_minimum=None, level_maximum=None, mtime_minimum=None, mtime_maximum=None, y_axis='pressure', grid=False, clean_plot=False, verbose=False)[source]

Generates a Level vs Time contour plot for a specified latitude and/or longitude.

Parameters:

datasets (xarray.Dataset) – The loaded dataset/s using xarray.
variable_name (str) – The name of the variable with latitude, longitude, time, and ilev dimensions.
latitude (float) – The specific latitude value for the plot.
longitude (float, optional) – The specific longitude value for the plot.
log_level (bool) – A flag indicating whether to display level in log values. Default is True.
variable_unit (str, optional) – The desired unit of the variable.
contour_intervals (int, optional) – The number of contour intervals. Defaults to 10. Ignored if contour_value is provided.
contour_value (int, optional) – The value between each contour interval.
symmetric_interval (bool, optional) – If True, the contour intervals will be symmetric around zero. Defaults to False.
cmap_color (str, optional) – The color map of the contour. Defaults to ‘viridis’ for Density, ‘inferno’ for Temp, ‘bwr’ for Wind, ‘viridis’ for undefined.
cmap_lim_min (float, optional) – Minimum limit for the color map. Defaults to the minimum value of the variable.
cmap_lim_max (float, optional) – Maximum limit for the color map. Defaults to the maximum value of the variable.
line_color (str, optional) – The color for all lines in the plot. Defaults to ‘white’.
level_minimum (float, optional) – Minimum level value for the plot. Defaults to None.
level_maximum (float, optional) – Maximum level value for the plot. Defaults to None.
mtime_minimum (float, optional) – Minimum time value for the plot. Defaults to None.
mtime_maximum (float, optional) – Maximum time value for the plot. Defaults to None.
grid (bool, optional) – Overlay coordinate grid lines on the plot (cartopy gridlines on maps, axis grid elsewhere). Defaults to False.
clean_plot (bool, optional) – A flag indicating whether to display the subtext. Defaults to False.
verbose (bool, optional) – A flag indicating whether to print execution data. Defaults to False.

Returns:

Contour plot.

Return type:

matplotlib.figure.Figure

Example:

Load datasets and generate a Pressure Level / Height vs Time contour plot.

datasets = gy.load_datasets(directory, dataset_filter)
variable_name = 'TN'
latitude_value = 30.0
time_min = '2022-01-01T00:00:00'
time_max = '2022-01-02T00:00:00'
unit_of_variable = 'K'
plot = gy.plt_lev_time(datasets, variable_name, latitude=latitude_value, time_minimum=time_min, time_maximum=time_max, variable_unit=unit_of_variable)

Latitude vs Time Contour Plot

This function creates a contour plot of a variable against latitude and time.

gcmprocpy.plot_gen.plt_lat_time(datasets, variable_name, level=None, level_type='pressure', longitude=None, variable_unit=None, contour_intervals=10, contour_value=None, symmetric_interval=False, cmap_color=None, cmap_lim_min=None, cmap_lim_max=None, line_color='white', latitude_minimum=None, latitude_maximum=None, mtime_minimum=None, mtime_maximum=None, grid=False, clean_plot=False, verbose=False)[source]

Generates a Latitude vs Time contour plot for a specified level and/or longitude.

Parameters:

datasets (xarray.Dataset) – The loaded dataset/s using xarray.
variable_name (str) – The name of the variable with latitude, longitude, time, and ilev dimensions.
level (float) – The specific level value for the plot.
longitude (float, optional) – The specific longitude value for the plot.
variable_unit (str, optional) – The desired unit of the variable.
contour_intervals (int, optional) – The number of contour intervals. Defaults to 10. Ignored if contour_value is provided.
contour_value (int, optional) – The value between each contour interval.
symmetric_interval (bool, optional) – If True, the contour intervals will be symmetric around zero. Defaults to False.
cmap_color (str, optional) – The color map of the contour. Defaults to ‘viridis’ for Density, ‘inferno’ for Temp, ‘bwr’ for Wind, ‘viridis’ for undefined.
cmap_lim_min (float, optional) – Minimum limit for the color map. Defaults to the minimum value of the variable.
cmap_lim_max (float, optional) – Maximum limit for the color map. Defaults to the maximum value of the variable.
line_color (str, optional) – The color for all lines in the plot. Defaults to ‘white’.
latitude_minimum (float, optional) – Minimum latitude value for the plot. Defaults to -87.5.
latitude_maximum (float, optional) – Maximum latitude value for the plot. Defaults to 87.5.
mtime_minimum (float, optional) – Minimum time value for the plot. Defaults to None.
mtime_maximum (float, optional) – Maximum time value for the plot. Defaults to None.
grid (bool, optional) – Overlay coordinate grid lines on the plot (cartopy gridlines on maps, axis grid elsewhere). Defaults to False.
clean_plot (bool, optional) – A flag indicating whether to display the subtext. Defaults to False.
verbose (bool, optional) – A flag indicating whether to print execution data. Defaults to False.

Returns:

Contour plot.

Return type:

matplotlib.figure.Figure

Example:

Load datasets and generate a Latitude vs Time contour plot.

datasets = gy.load_datasets(directory, dataset_filter)
variable_name = 'TN'
pressure_level = 4.0
time_min = '2022-01-01T00:00:00'
time_max = '2022-01-02T00:00:00'
unit_of_variable = 'K'
plot = gy.plt_lat_time(datasets, variable_name, level=pressure_level, time_minimum=time_min, time_maximum=time_max, variable_unit=unit_of_variable)

Longitude vs Time Contour Plot

This function creates a contour plot of a variable against longitude and time.

gcmprocpy.plot_gen.plt_lon_time(datasets, variable_name, latitude, level=None, level_type='pressure', variable_unit=None, contour_intervals=10, contour_value=None, symmetric_interval=False, cmap_color=None, cmap_lim_min=None, cmap_lim_max=None, line_color='white', longitude_minimum=None, longitude_maximum=None, mtime_minimum=None, mtime_maximum=None, grid=False, clean_plot=False, verbose=False)[source]

Generates a Longitude vs Time contour plot for a specified latitude and/or level.

Parameters:

datasets (xarray.Dataset) – The loaded dataset/s using xarray.
variable_name (str) – The name of the variable with latitude, longitude, time, and lev/ilev dimensions.
latitude (float) – The specific latitude value for the plot.
level (float, optional) – The specific level value for the plot.
variable_unit (str, optional) – The desired unit of the variable.
contour_intervals (int, optional) – The number of contour intervals. Defaults to 10. Ignored if contour_value is provided.
contour_value (int, optional) – The value between each contour interval.
symmetric_interval (bool, optional) – If True, the contour intervals will be symmetric around zero. Defaults to False.
cmap_color (str, optional) – The color map of the contour.
cmap_lim_min (float, optional) – Minimum limit for the color map.
cmap_lim_max (float, optional) – Maximum limit for the color map.
line_color (str, optional) – The color for all lines in the plot. Defaults to ‘white’.
longitude_minimum (float, optional) – Minimum longitude value for the plot.
longitude_maximum (float, optional) – Maximum longitude value for the plot.
mtime_minimum (list, optional) – Minimum time value as [day, hour, min, sec].
mtime_maximum (list, optional) – Maximum time value as [day, hour, min, sec].
grid (bool, optional) – Overlay coordinate grid lines on the plot (cartopy gridlines on maps, axis grid elsewhere). Defaults to False.
clean_plot (bool, optional) – A flag indicating whether to display the subtext. Defaults to False.
verbose (bool, optional) – A flag indicating whether to print execution data. Defaults to False.

Returns:

Contour plot.

Return type:

matplotlib.figure.Figure

Example:

Load datasets and generate a Longitude vs Time contour plot.

datasets = gy.load_datasets(directory, dataset_filter)
plot = gy.plt_lon_time(datasets, 'TN', latitude=0.0, level=4.0)

Variable vs Time Line Plot

This function creates a line plot of a variable against time at a specific latitude, longitude, and optional level.

gcmprocpy.plot_gen.plt_var_time(datasets, variable_name, latitude, longitude, level=None, level_type='pressure', variable_unit=None, mtime_minimum=None, mtime_maximum=None, grid=False, clean_plot=False, verbose=False)[source]

Generates a Variable vs Time line plot at a specific lat/lon/level location.

Parameters:

datasets (xarray.Dataset) – The loaded dataset/s using xarray.
variable_name (str) – The name of the variable with latitude, longitude, time, and lev/ilev dimensions.
latitude (float) – The specific latitude value for the plot.
longitude (float) – The specific longitude value for the plot.
level (float, optional) – The specific level value for the plot.
variable_unit (str, optional) – The desired unit of the variable.
mtime_minimum (list, optional) – Minimum time value as [day, hour, min, sec].
mtime_maximum (list, optional) – Maximum time value as [day, hour, min, sec].
grid (bool, optional) – Overlay coordinate grid lines on the plot (cartopy gridlines on maps, axis grid elsewhere). Defaults to False.
clean_plot (bool, optional) – A flag indicating whether to display the subtext. Defaults to False.
verbose (bool, optional) – A flag indicating whether to print execution data. Defaults to False.

Returns:

Line plot.

Return type:

matplotlib.figure.Figure

Example:

Load datasets and generate a Variable vs Time line plot.

datasets = gy.load_datasets(directory, dataset_filter)
plot = gy.plt_var_time(datasets, 'TN', latitude=0.0, longitude=45.0, level=4.0)

Satellite Track Interpolation Plot

This function interpolates model data along a satellite trajectory and plots the result. With a level specified, it produces a 1D line plot along the track. Without a level, it produces a 2D contour plot of all levels vs along-track points.

gcmprocpy.plot_gen.plt_sat_track(datasets, variable_name, sat_time, sat_lat, sat_lon, level=None, variable_unit=None, contour_intervals=10, contour_value=None, symmetric_interval=False, cmap_color=None, cmap_lim_min=None, cmap_lim_max=None, line_color='white', grid=False, clean_plot=False, verbose=False)[source]

Plots model data interpolated along a satellite trajectory.

If a level is specified, produces a 1D line plot of the variable vs time along the track. If no level is given, produces a 2D contour plot of the variable (levels vs along-track time).

Parameters:

datasets (list[ModelDataset]) – Loaded model datasets.
variable_name (str) – The variable to plot.
sat_time (array-like) – Satellite timestamps (numpy datetime64).
sat_lat (array-like) – Satellite latitudes (degrees).
sat_lon (array-like) – Satellite longitudes (degrees).
level (float, optional) – Level/ilev to extract at. If None, plots all levels vs time.
variable_unit (str, optional) – Desired unit of the variable.
contour_intervals (int, optional) – Number of contour intervals (2D mode). Defaults to 10.
contour_value (float, optional) – Value between each contour interval.
symmetric_interval (bool, optional) – Symmetric contour intervals around zero. Defaults to False.
cmap_color (str, optional) – Colormap name.
cmap_lim_min (float, optional) – Minimum colormap limit.
cmap_lim_max (float, optional) – Maximum colormap limit.
line_color (str, optional) – Contour line color. Defaults to ‘white’.
grid (bool, optional) – Overlay coordinate grid lines on the plot (cartopy gridlines on maps, axis grid elsewhere). Defaults to False.
clean_plot (bool, optional) – If True, hides subtext. Defaults to False.
verbose (bool, optional) – Enable debug logging. Defaults to False.

Returns:

The generated plot.

Return type:

matplotlib.figure.Figure

Example:

Interpolate and plot model temperature along a simulated satellite pass.

import numpy as np
datasets = gy.load_datasets(directory, dataset_filter)
times = gy.time_list(datasets)

# Satellite trajectory: arrays of time, lat, lon (one entry per point)
sat_time = np.array([times[0] + np.timedelta64(i * 6, 'm') for i in range(20)])
sat_lat = np.linspace(-60, 60, 20)
sat_lon = np.linspace(-120, 120, 20)

# Line plot at a fixed level
plot = gy.plt_sat_track(datasets, 'TN', sat_time, sat_lat, sat_lon, level=5.0)

# Contour plot across all levels
plot = gy.plt_sat_track(datasets, 'TN', sat_time, sat_lat, sat_lon)

Magnetic Latitude vs Magnetic Longitude Plot

Plots a field on the magnetic (Quasi-Dipole) grid. Variables the model already stores on mlat / mlon (e.g. TIE-GCM ZMAG or the WACCM-X dynamo fields) are plotted directly; geographic variables are reprojected onto the magnetic grid using apexpy – an optional dependency needed only for that geographic->magnetic conversion (pip install 'gcmprocpy[magnetic]').

gcmprocpy.plot_gen.plt_mag_lat_lon(datasets, variable_name, time=None, mtime=None, level=None, level_type='pressure', variable_unit=None, contour_intervals=20, contour_value=None, symmetric_interval=False, cmap_color=None, cmap_lim_min=None, cmap_lim_max=None, line_color='white', mlat_minimum=None, mlat_maximum=None, mlon_minimum=None, mlon_maximum=None, grid=False, clean_plot=False, verbose=False)[source]

Generates a Magnetic Latitude vs Magnetic Longitude contour plot (Quasi-Dipole).

Variables already stored on the model’s magnetic grid (dimensions mlat / mlon – e.g. TIE-GCM ZMAG or the WACCM-X dynamo fields) are plotted directly. Geographic variables (on lat / lon) are reprojected onto a regular Quasi-Dipole mlat / mlon grid using apexpy (an optional dependency, needed only for this geographic->magnetic conversion). The axes are magnetic; no geographic map features (coastlines, projections) are drawn because they are meaningless in magnetic coordinates.

Parameters:

datasets (xarray.Dataset) – The loaded dataset/s using xarray.
variable_name (str) – The name of the variable to plot.
time (np.datetime64, optional) – The selected time.
mtime (list[int], optional) – The selected time as [day, hour, minute].
level (float, optional) – The vertical level. Required for geographic variables (used as the height of the geographic->magnetic conversion); for native-magnetic variables it selects the magnetic vertical level ('mean' or None averages over it).
level_type (str, optional) – ‘pressure’ or ‘height’. Defaults to ‘pressure’.
variable_unit (str, optional) – The desired unit of the variable.
contour_intervals (int, optional) – Number of contour levels. Defaults to 20.
contour_value (float, optional) – Spacing between contour levels.
symmetric_interval (bool, optional) – Center the color scale on zero.
cmap_color (str, optional) – Colormap. Defaults to a variable-based scheme.
cmap_lim_min (float, optional) – Minimum color-scale value.
cmap_lim_max (float, optional) – Maximum color-scale value.
line_color (str, optional) – Contour line color. Defaults to ‘white’.
mlat_minimum (float, optional) – Minimum magnetic latitude for the plot.
mlat_maximum (float, optional) – Maximum magnetic latitude for the plot.
mlon_minimum (float, optional) – Minimum magnetic longitude for the plot.
mlon_maximum (float, optional) – Maximum magnetic longitude for the plot.
grid (bool, optional) – Overlay coordinate grid lines on the plot. Defaults to False.
clean_plot (bool, optional) – A flag indicating whether to display the subtext. Defaults to False.
verbose (bool, optional) – A flag indicating whether to print execution data. Defaults to False.

Returns:

Contour plot.

Return type:

matplotlib.figure.Figure

Example:

Reproject a geographic field onto the magnetic grid, and plot a native magnetic-grid field directly.

datasets = gy.load_datasets(directory, dataset_filter)
# geographic field -> quasi-dipole grid (needs apexpy + a level for height)
plot = gy.plt_mag_lat_lon(datasets, 'TN', mtime=[360, 0, 0], level=-4.0)
# a field already on the magnetic grid plots directly (no apexpy needed)
plot = gy.plt_mag_lat_lon(datasets, 'ZMAG', mtime=[360, 0, 0], level='mean')

Mode: CLI

Latitude vs Longitude Contour Plots

This command generates a contour plot of a variable against latitude and longitude.

lat_lon

Parser for loading, plotting, and saving

usage: lat_lon [-h] [-dir DIRECTORY] [-dsf DATASET_FILTER]
               [-o_dir OUTPUT_DIRECTORY] -o_file FILENAME
               [-o_format OUTPUT_FORMAT] -var VARIABLE_NAME [-t TIME]
               [-mt MTIME [MTIME ...]] [-lvl LEVEL] [-unit VARIABLE_UNIT]
               [-ci CONTOUR_INTERVALS] [-cv CONTOUR_VALUE] [-si]
               [-cmc CMAP_COLOR] [-lc LINE_COLOR] [-cst] [-nsh] [-gm]
               [-lat_min LATITUDE_MINIMUM] [-lat_max LATITUDE_MAXIMUM]
               [-lon_min LONGITUDE_MINIMUM] [-lon_max LONGITUDE_MAXIMUM]
               [-proj PROJECTION] [-clon CENTER_LONGITUDE]
               [-clat CENTRAL_LATITUDE] [-wind] [-wd WIND_DENSITY]
               [-ws WIND_SCALE] [-wc WIND_COLOR] [-lt {pressure,height}]
               [-clean] [-grid]

-h, --help: show this help message and exit

-dir <directory>, --directory <directory>: Path to the directory containing the datasets

-dsf <dataset_filter>, --dataset_filter <dataset_filter>: Filter for the dataset file names

-o_dir <output_directory>, --output_directory <output_directory>: Directory where the plot will be saved.

-o_file <filename>, --filename <filename>: Filename for the saved plot.

-o_format <output_format>, --output_format <output_format>: Format of the output plot, e.g., “png”, “pdf”.

-var <variable_name>, --variable_name <variable_name>: The name of the variable with latitude, longitude, and lev/ilev dimensions.

-t <time>, --time <time>: The selected time, e.g., “2022-01-01T12:00:00”.

-mt <mtime>, --mtime <mtime>: The selected time as a list, e.g., [1, 12, 0] for 1st day, 12 hours, 0 mins.

-lvl <level>, --level <level>: The selected lev/ilev value.

-unit <variable_unit>, --variable_unit <variable_unit>: The desired unit of the variable.

-ci <contour_intervals>, --contour_intervals <contour_intervals>: The number of contour intervals. Defaults to 20.

-cv <contour_value>, --contour_value <contour_value>: The value between each contour interval.

-si, --symmetric_interval: If True, the contour intervals will be symmetric around zero. Defaults to False.

-cmc <cmap_color>, --cmap_color <cmap_color>: The color map of the contour. Defaults to “viridis” for Density, “inferno” for Temp, “bwr” for Wind, “viridis” for undefined.

-lc <line_color>, --line_color <line_color>: The color for all lines in the plot. Defaults to “white”.

-cst, --coastlines: Shows coastlines on the plot. Defaults to False.

-nsh, --nightshade: Shows nightshade on the plot. Defaults to False.

-gm, --gm_equator: Shows geomagnetic equator on the plot. Defaults to False.

-lat_min <latitude_minimum>, --latitude_minimum <latitude_minimum>: Minimum latitude to slice plots. Defaults to -87.5.

-lat_max <latitude_maximum>, --latitude_maximum <latitude_maximum>: Maximum latitude to slice plots. Defaults to 87.5.

-lon_min <longitude_minimum>, --longitude_minimum <longitude_minimum>: Minimum longitude to slice plots. Defaults to -180.

-lon_max <longitude_maximum>, --longitude_maximum <longitude_maximum>: Maximum longitude to slice plots. Defaults to 175.

-proj <projection>, --projection <projection>: Map projection: mercator, orthographic, mollweide, north_polar, south_polar, polar. Defaults to mercator.

-clon <center_longitude>, --center_longitude <center_longitude>: Center longitude for orthographic/mollweide projections. Defaults to 0.

-clat <central_latitude>, --central_latitude <central_latitude>: Central latitude for orthographic projection. Defaults to 0.

-wind, --wind: Overlay wind vectors on the plot. Defaults to False.

-wd <wind_density>, --wind_density <wind_density>: Density of wind vectors (stride). Defaults to 15.

-ws <wind_scale>, --wind_scale <wind_scale>: Scale factor for wind arrows. Defaults to None (auto).

-wc <wind_color>, --wind_color <wind_color>: Color of wind arrows. Defaults to black.

-lt {pressure,height}, --level_type {pressure,height}: Whether level is specified as pressure or height (km). Defaults to pressure.

-clean, --clean_plot: Generate a clean plot without title/colorbar. Defaults to False.

-grid, --grid: Overlay coordinate grid lines on the plot.

Pressure Level / Height vs Variable Line Plot

This command generates a line plot of a variable at a specific latitude and optional longitude, time, and local time.

lev_var

Parser for loading, plotting, and saving

usage: lev_var [-h] [-dir DIRECTORY] [-dsf DATASET_FILTER]
               [-o_dir OUTPUT_DIRECTORY] -o_file FILENAME -o_format
               OUTPUT_FORMAT [-var VARIABLE_NAME] [-lat LATITUDE] [-t TIME]
               [-mt MTIME MTIME MTIME] [-lon LONGITUDE] [-unit VARIABLE_UNIT]
               [-lvl_min LEVEL_MINIMUM] [-lvl_max LEVEL_MAXIMUM]
               [-ya {pressure,height}] [-grid] [-slt LOCALTIME]

-h, --help: show this help message and exit

-dir <directory>, --directory <directory>: Path to the directory containing the datasets

-dsf <dataset_filter>, --dataset_filter <dataset_filter>: Filter for the dataset file names

-o_dir <output_directory>, --output_directory <output_directory>: Directory where the plot will be saved.

-o_file <filename>, --filename <filename>: Filename for the saved plot.

-o_format <output_format>, --output_format <output_format>: Format of the output plot, e.g., “png”, “pdf”.

-var <variable_name>, --variable_name <variable_name>: The name of the variable with latitude, longitude, and lev/ilev dimensions

-lat <latitude>, --latitude <latitude>: The specific latitude value for the plot

-t <time>, --time <time>: The selected time, e.g., “2022-01-01T12:00:00”

-mt <mtime>, --mtime <mtime>: The selected time as a list, e.g., [1, 12, 0] for 1st day, 12 hours, 0 mins

-lon <longitude>, --longitude <longitude>: The specific longitude value for the plot

-unit <variable_unit>, --variable_unit <variable_unit>: The desired unit of the variable

-lvl_min <level_minimum>, --level_minimum <level_minimum>: Minimum level value for the plot

-lvl_max <level_maximum>, --level_maximum <level_maximum>: Maximum level value for the plot

-ya {pressure,height}, --y_axis {pressure,height}: Y-axis type: pressure or height (km). Defaults to pressure.

-grid, --grid: Overlay coordinate grid lines on the plot.

-slt <localtime>, --localtime <localtime>: Solar local time in hours (0-24) to select instead of longitude; UT-aware. Use ‘mean’ for the zonal mean.

Pressure Level / Height vs Longitude Contour Plot

This command generates a contour plot of a variable at a specific latitude against longitude, with optional time and local time.

lev_lon

Parser for loading, plotting, and saving

usage: lev_lon [-h] [-dir DIRECTORY] [-dsf DATASET_FILTER]
               [-o_dir OUTPUT_DIRECTORY] -o_file FILENAME -o_format
               OUTPUT_FORMAT [-var VARIABLE_NAME] [-lat LATITUDE] [-t TIME]
               [-mt MTIME MTIME MTIME] [-unit VARIABLE_UNIT]
               [-ci CONTOUR_INTERVALS] [-cv CONTOUR_VALUE] [-si]
               [-cmc CMAP_COLOR] [-lc LINE_COLOR] [-lvl_min LEVEL_MINIMUM]
               [-lvl_max LEVEL_MAXIMUM] [-lon_min LONGITUDE_MINIMUM]
               [-lon_max LONGITUDE_MAXIMUM] [-ya {pressure,height}] [-grid]

-h, --help: show this help message and exit

-dir <directory>, --directory <directory>: Path to the directory containing the datasets

-dsf <dataset_filter>, --dataset_filter <dataset_filter>: Filter for the dataset file names

-o_dir <output_directory>, --output_directory <output_directory>: Directory where the plot will be saved.

-o_file <filename>, --filename <filename>: Filename for the saved plot.

-o_format <output_format>, --output_format <output_format>: Format of the output plot, e.g., “png”, “pdf”.

-var <variable_name>, --variable_name <variable_name>: The name of the variable with latitude, longitude, and lev/ilev dimensions.

-lat <latitude>, --latitude <latitude>: The specific latitude value for the plot.

-t <time>, --time <time>: The selected time, e.g., ‘2022-01-01T12:00:00’.

-mt <mtime>, --mtime <mtime>: The selected time as a list, e.g., [1, 12, 0] for 1st day, 12 hours, 0 mins.

-unit <variable_unit>, --variable_unit <variable_unit>: The desired unit of the variable.

-ci <contour_intervals>, --contour_intervals <contour_intervals>: The number of contour intervals. Defaults to 20.

-cv <contour_value>, --contour_value <contour_value>: The value between each contour interval.

-si, --symmetric_interval: If True, the contour intervals will be symmetric around zero. Defaults to False.

-cmc <cmap_color>, --cmap_color <cmap_color>: The color map of the contour. Defaults to ‘viridis’ for Density, ‘inferno’ for Temp, ‘bwr’ for Wind, ‘viridis’ for undefined.

-lc <line_color>, --line_color <line_color>: The color for all lines in the plot. Defaults to ‘white’.

-lvl_min <level_minimum>, --level_minimum <level_minimum>: Minimum level value for the plot. Defaults to None.

-lvl_max <level_maximum>, --level_maximum <level_maximum>: Maximum level value for the plot. Defaults to None.

-lon_min <longitude_minimum>, --longitude_minimum <longitude_minimum>: Minimum longitude value for the plot. Defaults to -180.

-lon_max <longitude_maximum>, --longitude_maximum <longitude_maximum>: Maximum longitude value for the plot. Defaults to 175.

-ya {pressure,height}, --y_axis {pressure,height}: Y-axis type: pressure or height (km). Defaults to pressure.

-grid, --grid: Overlay coordinate grid lines on the plot.

Pressure Level / Height vs Latitude Contour Plot

This command generates a contour plot of a variable against pressure level / height and latitude.

lev_lat

Parser for loading, plotting, and saving

usage: lev_lat [-h] [-dir DIRECTORY] [-dsf DATASET_FILTER]
               [-o_dir OUTPUT_DIRECTORY] -o_file FILENAME -o_format
               OUTPUT_FORMAT [-var VARIABLE_NAME] [-t TIME]
               [-mt MTIME MTIME MTIME] [-lon LONGITUDE] [-unit VARIABLE_UNIT]
               [-ci CONTOUR_INTERVALS] [-cv CONTOUR_VALUE] [-si]
               [-cmc CMAP_COLOR] [-lc LINE_COLOR] [-lvl_min LEVEL_MINIMUM]
               [-lvl_max LEVEL_MAXIMUM] [-lat_min LATITUDE_MINIMUM]
               [-lat_max LATITUDE_MAXIMUM] [-ya {pressure,height}] [-grid]
               [-slt LOCALTIME]

-h, --help: show this help message and exit

-dir <directory>, --directory <directory>: Path to the directory containing the datasets

-dsf <dataset_filter>, --dataset_filter <dataset_filter>: Filter for the dataset file names

-o_dir <output_directory>, --output_directory <output_directory>: Directory where the plot will be saved.

-o_file <filename>, --filename <filename>: Filename for the saved plot.

-o_format <output_format>, --output_format <output_format>: Format of the output plot, e.g., “png”, “pdf”.

-var <variable_name>, --variable_name <variable_name>: The name of the variable with latitude, longitude, and lev/ilev dimensions.

-t <time>, --time <time>: The selected time, e.g., ‘2022-01-01T12:00:00’.

-mt <mtime>, --mtime <mtime>: The selected time as a list, e.g., [1, 12, 0] for 1st day, 12 hours, 0 mins.

-lon <longitude>, --longitude <longitude>: The specific longitude value for the plot.

-unit <variable_unit>, --variable_unit <variable_unit>: The desired unit of the variable.

-ci <contour_intervals>, --contour_intervals <contour_intervals>: The number of contour intervals. Defaults to 20.

-cv <contour_value>, --contour_value <contour_value>: The value between each contour interval.

-si, --symmetric_interval: If True, the contour intervals will be symmetric around zero. Defaults to False.

-cmc <cmap_color>, --cmap_color <cmap_color>: The color map of the contour. Defaults to ‘viridis’ for Density, ‘inferno’ for Temp, ‘bwr’ for Wind, ‘viridis’ for undefined.

-lc <line_color>, --line_color <line_color>: The color for all lines in the plot. Defaults to ‘white’.

-lvl_min <level_minimum>, --level_minimum <level_minimum>: Minimum level value for the plot. Defaults to None.

-lvl_max <level_maximum>, --level_maximum <level_maximum>: Maximum level value for the plot. Defaults to None.

-lat_min <latitude_minimum>, --latitude_minimum <latitude_minimum>: Minimum latitude value for the plot. Defaults to -87.5.

-lat_max <latitude_maximum>, --latitude_maximum <latitude_maximum>: Maximum latitude value for the plot. Defaults to 87.5.

-ya {pressure,height}, --y_axis {pressure,height}: Y-axis type: pressure or height (km). Defaults to pressure.

-grid, --grid: Overlay coordinate grid lines on the plot.

-slt <localtime>, --localtime <localtime>: Solar local time in hours (0-24) to select instead of longitude; UT-aware. Use ‘mean’ for the zonal mean.

Pressure Level / Height vs Time Contour Plot

This command creates a contour plot of a variable against pressure level / height and time.

lev_time

Parser for loading, plotting, and saving

usage: lev_time [-h] [-dir DIRECTORY] [-dsf DATASET_FILTER]
                [-o_dir OUTPUT_DIRECTORY] -o_file FILENAME -o_format
                OUTPUT_FORMAT [-var VARIABLE_NAME] [-lat LATITUDE]
                [-lon LONGITUDE] [-unit VARIABLE_UNIT] [-ci CONTOUR_INTERVALS]
                [-cv CONTOUR_VALUE] [-si] [-cmc CMAP_COLOR] [-lc LINE_COLOR]
                [-lvl_min LEVEL_MINIMUM] [-lvl_max LEVEL_MAXIMUM]
                [--mtime_minimum MTIME_MINIMUM]
                [--mtime_maximum MTIME_MAXIMUM] [-ya {pressure,height}]
                [-grid]

-h, --help: show this help message and exit

-dir <directory>, --directory <directory>: Path to the directory containing the datasets

-dsf <dataset_filter>, --dataset_filter <dataset_filter>: Filter for the dataset file names

-o_dir <output_directory>, --output_directory <output_directory>: Directory where the plot will be saved.

-o_file <filename>, --filename <filename>: Filename for the saved plot.

-o_format <output_format>, --output_format <output_format>: Format of the output plot, e.g., “png”, “pdf”.

-var <variable_name>, --variable_name <variable_name>: The name of the variable with latitude, longitude, time, and ilev dimensions.

-lat <latitude>, --latitude <latitude>: The specific latitude value for the plot.

-lon <longitude>, --longitude <longitude>: The specific longitude value for the plot.

-unit <variable_unit>, --variable_unit <variable_unit>: The desired unit of the variable.

-ci <contour_intervals>, --contour_intervals <contour_intervals>: The number of contour intervals. Defaults to 10.

-cv <contour_value>, --contour_value <contour_value>: The value between each contour interval.

-si, --symmetric_interval: If True, the contour intervals will be symmetric around zero. Defaults to False.

-cmc <cmap_color>, --cmap_color <cmap_color>: The color map of the contour. Defaults to ‘viridis’ for Density, ‘inferno’ for Temp, ‘bwr’ for Wind, ‘viridis’ for undefined.

-lc <line_color>, --line_color <line_color>: The color for all lines in the plot. Defaults to ‘white’.

-lvl_min <level_minimum>, --level_minimum <level_minimum>: Minimum level value for the plot. Defaults to None.

-lvl_max <level_maximum>, --level_maximum <level_maximum>: Maximum level value for the plot. Defaults to None.

--mtime_minimum <mtime_minimum>: Minimum time value for the plot. Defaults to None.

--mtime_maximum <mtime_maximum>: Maximum time value for the plot. Defaults to None.

-ya {pressure,height}, --y_axis {pressure,height}: Y-axis type: pressure or height (km). Defaults to pressure.

-grid, --grid: Overlay coordinate grid lines on the plot.

Latitude vs Time Contour Plot

This command creates a contour plot of a variable against latitude and time.

lat_time

Parser for loading, plotting, and saving

usage: lat_time [-h] [-dir DIRECTORY] [-dsf DATASET_FILTER]
                [-o_dir OUTPUT_DIRECTORY] -o_file FILENAME -o_format
                OUTPUT_FORMAT [-var VARIABLE_NAME] [-lvl LEVEL]
                [-lon LONGITUDE] [-unit VARIABLE_UNIT] [-ci CONTOUR_INTERVALS]
                [-cv CONTOUR_VALUE] [-si] [-cmc CMAP_COLOR] [-lc LINE_COLOR]
                [-lat_min LATITUDE_MINIMUM] [-lat_max LATITUDE_MAXIMUM]
                [--mtime_minimum MTIME_MINIMUM]
                [--mtime_maximum MTIME_MAXIMUM] [-lt {pressure,height}]
                [-grid]

-h, --help: show this help message and exit

-dir <directory>, --directory <directory>: Path to the directory containing the datasets

-dsf <dataset_filter>, --dataset_filter <dataset_filter>: Filter for the dataset file names

-o_dir <output_directory>, --output_directory <output_directory>: Directory where the plot will be saved.

-o_file <filename>, --filename <filename>: Filename for the saved plot.

-o_format <output_format>, --output_format <output_format>: Format of the output plot, e.g., “png”, “pdf”.

-var <variable_name>, --variable_name <variable_name>: The name of the variable with latitude, longitude, time, and ilev dimensions.

-lvl <level>, --level <level>: The specific level value for the plot.

-lon <longitude>, --longitude <longitude>: The specific longitude value for the plot.

-unit <variable_unit>, --variable_unit <variable_unit>: The desired unit of the variable.

-ci <contour_intervals>, --contour_intervals <contour_intervals>: The number of contour intervals. Defaults to 10.

-cv <contour_value>, --contour_value <contour_value>: The value between each contour interval.

-si, --symmetric_interval: If True, the contour intervals will be symmetric around zero. Defaults to False.

-cmc <cmap_color>, --cmap_color <cmap_color>: The color map of the contour. Defaults to ‘viridis’ for Density, ‘inferno’ for Temp, ‘bwr’ for Wind, ‘viridis’ for undefined.

-lc <line_color>, --line_color <line_color>: The color for all lines in the plot. Defaults to ‘white’.

-lat_min <latitude_minimum>, --latitude_minimum <latitude_minimum>: Minimum latitude value for the plot. Defaults to -87.5.

-lat_max <latitude_maximum>, --latitude_maximum <latitude_maximum>: Maximum latitude value for the plot. Defaults to 87.5.

--mtime_minimum <mtime_minimum>: Minimum time value for the plot. Defaults to None.

--mtime_maximum <mtime_maximum>: Maximum time value for the plot. Defaults to None.

-lt {pressure,height}, --level_type {pressure,height}: Whether level is specified as pressure or height (km). Defaults to pressure.

-grid, --grid: Overlay coordinate grid lines on the plot.

Longitude vs Time Contour Plot

This command creates a contour plot of a variable against longitude and time.

lon_time

Parser for loading, plotting, and saving

usage: lon_time [-h] [-dir DIRECTORY] [-dsf DATASET_FILTER]
                [-o_dir OUTPUT_DIRECTORY] -o_file FILENAME
                [-o_format OUTPUT_FORMAT] -var VARIABLE_NAME -lat LATITUDE
                [-lvl LEVEL] [-unit VARIABLE_UNIT] [-ci CONTOUR_INTERVALS]
                [-cv CONTOUR_VALUE] [-si] [-cmc CMAP_COLOR] [-lc LINE_COLOR]
                [-lon_min LONGITUDE_MINIMUM] [-lon_max LONGITUDE_MAXIMUM]
                [--mtime_minimum MTIME_MINIMUM]
                [--mtime_maximum MTIME_MAXIMUM] [-clean]
                [-lt {pressure,height}] [-grid]

-h, --help: show this help message and exit

-dir <directory>, --directory <directory>: Path to the directory containing the datasets

-dsf <dataset_filter>, --dataset_filter <dataset_filter>: Filter for the dataset file names

-o_dir <output_directory>, --output_directory <output_directory>: Directory where the plot will be saved.

-o_file <filename>, --filename <filename>: Filename for the saved plot.

-o_format <output_format>, --output_format <output_format>: Format of the output plot, e.g., “png”, “pdf”.

-var <variable_name>, --variable_name <variable_name>: The name of the variable to plot.

-lat <latitude>, --latitude <latitude>: The specific latitude value for the plot.

-lvl <level>, --level <level>: The specific level value for the plot.

-unit <variable_unit>, --variable_unit <variable_unit>: The desired unit of the variable.

-ci <contour_intervals>, --contour_intervals <contour_intervals>: The number of contour intervals. Defaults to 10.

-cv <contour_value>, --contour_value <contour_value>: The value between each contour interval.

-si, --symmetric_interval: If True, contour intervals symmetric around zero. Defaults to False.

-cmc <cmap_color>, --cmap_color <cmap_color>: The color map of the contour.

-lc <line_color>, --line_color <line_color>: The color for all lines in the plot. Defaults to white.

-lon_min <longitude_minimum>, --longitude_minimum <longitude_minimum>: Minimum longitude value for the plot.

-lon_max <longitude_maximum>, --longitude_maximum <longitude_maximum>: Maximum longitude value for the plot.

--mtime_minimum <mtime_minimum>: Minimum time value for the plot.

--mtime_maximum <mtime_maximum>: Maximum time value for the plot.

-clean, --clean_plot: Generate a clean plot without title/colorbar. Defaults to False.

-lt {pressure,height}, --level_type {pressure,height}: Whether level is specified as pressure or height (km). Defaults to pressure.

-grid, --grid: Overlay coordinate grid lines on the plot.

Variable vs Time Line Plot

This command creates a line plot of a variable against time at a specific latitude, longitude, and optional level.

var_time

Parser for loading, plotting, and saving

usage: var_time [-h] [-dir DIRECTORY] [-dsf DATASET_FILTER]
                [-o_dir OUTPUT_DIRECTORY] -o_file FILENAME
                [-o_format OUTPUT_FORMAT] -var VARIABLE_NAME -lat LATITUDE
                -lon LONGITUDE [-lvl LEVEL] [-unit VARIABLE_UNIT]
                [--mtime_minimum MTIME_MINIMUM]
                [--mtime_maximum MTIME_MAXIMUM] [-clean]
                [-lt {pressure,height}] [-grid]

-h, --help: show this help message and exit

-dir <directory>, --directory <directory>: Path to the directory containing the datasets

-dsf <dataset_filter>, --dataset_filter <dataset_filter>: Filter for the dataset file names

-o_dir <output_directory>, --output_directory <output_directory>: Directory where the plot will be saved.

-o_file <filename>, --filename <filename>: Filename for the saved plot.

-o_format <output_format>, --output_format <output_format>: Format of the output plot, e.g., “png”, “pdf”.

-var <variable_name>, --variable_name <variable_name>: The name of the variable to plot.

-lat <latitude>, --latitude <latitude>: The specific latitude value for the plot.

-lon <longitude>, --longitude <longitude>: The specific longitude value for the plot.

-lvl <level>, --level <level>: The specific level value for the plot.

-unit <variable_unit>, --variable_unit <variable_unit>: The desired unit of the variable.

--mtime_minimum <mtime_minimum>: Minimum time value for the plot.

--mtime_maximum <mtime_maximum>: Maximum time value for the plot.

-clean, --clean_plot: Generate a clean plot without title/colorbar. Defaults to False.

-lt {pressure,height}, --level_type {pressure,height}: Whether level is specified as pressure or height (km). Defaults to pressure.

-grid, --grid: Overlay coordinate grid lines on the plot.

Satellite Track Interpolation Plot

This command interpolates model data along a satellite trajectory and plots the result. Requires a CSV file with columns: time, lat, lon.

sat_track

Parser for loading, plotting, and saving satellite track interpolation plots

usage: sat_track [-h] [-dir DIRECTORY] [-dsf DATASET_FILTER]
                 [-o_dir OUTPUT_DIRECTORY] -o_file FILENAME
                 [-o_format OUTPUT_FORMAT] -var VARIABLE_NAME -sat_file
                 SATELLITE_FILE [-lvl LEVEL] [-unit VARIABLE_UNIT]
                 [-ci CONTOUR_INTERVALS] [-cv CONTOUR_VALUE] [-si]
                 [-cmc CMAP_COLOR] [-lc LINE_COLOR] [-clean] [-grid]

-h, --help: show this help message and exit

-dir <directory>, --directory <directory>: Path to the directory containing the datasets

-dsf <dataset_filter>, --dataset_filter <dataset_filter>: Filter for the dataset file names

-o_dir <output_directory>, --output_directory <output_directory>: Directory where the plot will be saved.

-o_file <filename>, --filename <filename>: Filename for the saved plot.

-o_format <output_format>, --output_format <output_format>: Format of the output plot, e.g., “png”, “pdf”.

-var <variable_name>, --variable_name <variable_name>: The name of the variable to plot.

-sat_file <satellite_file>, --satellite_file <satellite_file>: Path to CSV file with satellite track data (columns: time, lat, lon).

-lvl <level>, --level <level>: The specific level value. If omitted, plots all levels as contour.

-unit <variable_unit>, --variable_unit <variable_unit>: The desired unit of the variable.

-ci <contour_intervals>, --contour_intervals <contour_intervals>: The number of contour intervals. Defaults to 10.

-cv <contour_value>, --contour_value <contour_value>: The value between each contour interval.

-si, --symmetric_interval: If True, contour intervals symmetric around zero. Defaults to False.

-cmc <cmap_color>, --cmap_color <cmap_color>: The color map of the contour.

-lc <line_color>, --line_color <line_color>: The color for all lines in the plot. Defaults to white.

-clean, --clean_plot: Generate a clean plot without title/colorbar. Defaults to False.

-grid, --grid: Overlay coordinate grid lines on the plot.