Usage

gcmprocpy can be run in two modes: API and Command Line Interface (CLI).

Mode: GUI

gcmprocpy can be run in GUI mode by running the following command:

gcmprocpy

This will open the GUI window where the user can select the dataset and the plot type. The plot types include the standard lat/lon, level, and time cross-sections as well as Mag Lat vs Lon (magnetic Quasi-Dipole grid; geographic variables are reprojected via the optional apexpy dependency).

Warning

The GUI mode requires an interactive ssh session. If you are using a remote server, you can use the following command to open the GUI window: ssh -X user@server.

Mode: API

gcmprocpy can be used in custom Python scripts or Jupyter notebooks.

Importing gcmprocpy

import gcmprocpy as gy

Loading Datasets

Loading a dataset/datasets:

Note

For the inbuilt plotting routines only this method can be used to load the NetCDF datasets.

gy.load_datasets(directory/file, dataset_filter)

Closing Datasets

This function closes the netCDF datasets.

gy.close_datasets(datasets)

Plot Generation

The following plots can be made with gcmprocpy:

  • Latitude vs Longitude plots

  • Pressure level / Height vs Variable Value plots

  • Variable vs Latitude line plots (meridional cut)

  • Variable vs Longitude line plots (zonal cut)

  • Pressure level / Height vs Longitude plots

  • Pressure level / Height vs Latitude plots

  • Pressure level / Height vs Time plots

  • Latitude vs Time plots

  • Longitude vs Time plots

  • Variable vs Time plots

  • Satellite Track Interpolation plots

All level-axis plots support y_axis='height' to display the vertical axis in km. All level-selection plots support level_type='height' to specify the level as a height in km instead of a pressure level. Height conversion uses the model’s geometric height field (ZG for TIE-GCM, Z3 for WACCM-X).

Examples and detailed usage can be found in the Functionality section.

Mode: CLI

GCMprocpy can also be used directly from the command line. The following plots can be made on the command line:

  • Latitude vs Longitude plots (lat_lon)

  • Pressure level / Height vs Variable Value plots (lev_var)

  • Variable vs Latitude line plots (var_lat)

  • Variable vs Longitude line plots (var_lon)

  • Pressure level / Height vs Longitude plots (lev_lon)

  • Pressure level / Height vs Latitude plots (lev_lat)

  • Pressure level / Height vs Time plots (lev_time)

  • Latitude vs Time plots (lat_time)

  • Longitude vs Time plots (lon_time)

  • Variable vs Time plots (var_time)

  • Satellite Track Interpolation plots (sat_track)

  • Magnetic Latitude vs Magnetic Longitude plots (mag_lat_lon)

Use -lt height to specify the level as height (km) or -ya height for height y-axis. For var_lat/var_lon, the default for -lon/-lat is mean (zonal/meridional mean).

Add -grid to overlay coordinate grid lines on any plot (off by default). For lev_var/var_lat/lev_lat you can select by solar local time with -slt/--localtime (hours 0-24, or mean) instead of -lon: the local time is converted UT-aware to the geographic longitude that is at that local time for the slice (longitude = (SLT - UT) * 15), snapped to the model grid.

mag_lat_lon plots a field on the magnetic (Quasi-Dipole) grid. Fields the model already stores on mlat/mlon (e.g. TIE-GCM ZMAG or WACCM-X dynamo fields) are plotted directly; geographic fields are reprojected onto the magnetic grid, which requires the optional apexpy dependency (pip install 'gcmprocpy[magnetic]', or conda install -c conda-forge apexpy).

Examples and detailed usage can be found in the plotting routines section.