README for gcmpy/utils
This directory contains some helpful modules for making figures from MITgcm converted netCDF output, as well as some standalone scripts to make diagnostic plots.
Helper Modules
modeldata.py
Reads the model input namelists, and returns a python object containing the data. The function getdata
takes the paths to the data
and data.pkg
files, and returns a namedtuple object with attributes corresponding to the input namelists.
Call signature:
getdata(data = 'data', datapkg = 'data.pkg', datadiagnostics = None):
Arguments:
data
: Path todata
file the model was run fromdatapkg
: Path todata.pkg
file the model was run fromdatadiagnostics
: Path todata.diagnostics
file (if used).
Returns:
- Named Tuple with attributes
dx
,dy
,dz
,nx
,ny
,nz
,startTime
,endTime
,deltaT
delX
,delY
,delZ
.
find.py
Function find.all
finds all netCDF files in a given directory, and returns a list of files sorted by iteration. It slices the list as files[start:stop:step]
, where the start
, stop
, step
arguments are optional keyword arguments.
Positional Arguments:
dir
: Directory the netCDF files are stored in
Keyword Arguments with defaults:
start = 0
: Index in the list of files to start withstop = None
: Index in the list of files to stop with. If None, goes to the end. Otherwise if it is an integer, slices until that index.step = 1
: Integer step size when slicing list of files.
Returns:
filedata
: a namedtuple with attributesfiles
anditers
.filedata.files
is a sorted list of file names (with the directory stripped), andfieldata.iters
is the corresponding sorted list of iterations.
Example:
filedata = find.all('run', start = 1, stop = 20, step = 2)
files = filedata.files
iters = filedata.iters
Searches in the directory run/
for all *.nc
files. It returns the order tuple which is assigned to filedata
, which are accessible with .files
and .iters
attributes. In this case, it will contain files and iteration numbers for the 2nd, 4th, ..., 18th files in the directory.
interface.py
Defines a common, centralized, and consistent command-line interface for most figures. The interface is defined for both "single-run" plots and "multiple-run" plots, depending on if you're looking at data from one parameter set or comparing data from multiple different model runs.
reprocess.py
Copy netCDF files and modify and 2D fields to 3D datasets, padded with 0's. When doing 3D visualization and trying to plot ice fraction/thickness and a 3D field (Temperature, desntiy, etc) you need the arrays to be the same dimension. So, this module pads the 2D array underneath with 0s for other levels. This lets you visualize both fields at once. Saves files with the same name, but ending .regird
.
Single-run interface
The single-run interface is the function interface.single()
, which takes no arguments. The command line interface specified is
python -m gcmpy.utils.[module_name] file [--start START] [--stop STOP] [--step STEP] [--time_unit T]
Where the arguments are:
- file : Where to save the created figure
- [--start START] : Starting index in list of files to plot
- [--stop STOP] : Ending index in list of files to plot
- [--step STEP] : Step size in passing through list of files
- [--time_unit T] : Unit to measure time in: one of 'day', '1e3', or (None or '')
Multiple-run -interface
The comparison interface is the function interface.multiple()
, which also takes no arguments. The command line interface specified is
python -m gcmpy.utils.[module_name] file dirs --labels LABELS [--start START] [--stop STOP] [--step STEP] [--time_unit T]
Where the arguments are:
- file : Where to save the created figure
- dirs : List of directories to plot data from
- --labels LABELS : Legend labels. Pass as many labels here as directories in dirs
- [--start START] : Starting index in list of files to plot
- [--stop STOP] : Ending index in list of files to plot
- [--step STEP] : Step size in passing through list of files
- [--time_unit T] : Unit to measure time in: one of 'day', '1e3', or (None or '')
Other interface
You can define your own argument parser with the function interface.ArgumentParser(base = 'multiple')
. Specify base as 'multiple'
or 'single'
, and it will return an argparse.ArgumentParser
object with the corresponding args already added. You can then add arguments from there. If you need fewer arguments, just start from the base argparse.ArgumentParser()
object.
humidity.py
Provides functions for converting between relative humidity and specific humidity.
Function q(T, P, RH)
returns the specific humidity corresponding to relative humidity RH
at temperature and pressure T
and P
.
Function RH(T, P, q)
returns the relative humidity corresponding to specific humidity q
at temperature and pressure T
and P
.
timeutils.py
Provide function for converting time from seconds to days, 10^3 seconds, or keep in seconds, and formatting time axis labels with the correct units.
Available plots
Most of the available plots are simple line plots, showing an average or otherwise computed quantity evolving over time. There are options for plotting quantities from a single model run, or to compare the same quantity over multiple runs. There are some additional plots, with separate descriptions given.
Single run line plots
The line plots here show the value of one parameter or computed quantity over time. The command line interface is as consistent as possible
python -m gcmpy.utils.[module] figname [--start START] [--stop STOP] [--step STEP]
Where
figname
is where to save the resulting imageSTART
,STOP
, andSTEP
specify the iterations to take. The list of all files is sliced starting at START until STOP, with a step size STEP
Some modules may take additional arguments. Available modules are listed below
Module name | Description | Extra arguments |
---|---|---|
average2d | Plot the spatial mean of an arbitrary specified field. Requires extra arguments to define which field to plot, the title, and the ylabel | field [--title TITLE] [--ylabel YLABEL] |
heat | Plot total internal energy. Computed using initial conditions as reference state | |
icehist | Total ice mass computed from effective height, grid size, and standard ice density | |
TKE | Total kinetic energy | |
tprof | Make an animated line plot showing the temperature vertical profile over time | [--still STILL] optionally save still frames with name STILL |
tsurf | Plot the mean surface temperature over time |
Comparison line plots
The idea behind the comparison plots is to compare data between model runs with slightly different parameters. The default behaviour is to overlay the data from all the model runs onto the same plot. Another panel can be optionally added to show to difference between two cases. This is especially useful if only two parameter sets are being considered.
The plots follow a uniform command line interface as much as possible. The interface is
python -m gcmpy.utils.delta[plot] figname [--dirs DIRS ...]
[--labels LABELS ... ]
[--start START] [--stop STOP]
[--step STEP] [--include_delta]
[additional options]
Where
DIRS
lists all the directories to compare (at least 1 must be given)LABELS
specifies the legend labels for the plotSTART
,STOP
, andSTEP
specify the iterations to take. The list of all files is sliced starting at START until STOP, with a step size STEP.--include_delta
is an option to include another panel with the difference between two cases. The difference is taken between the last - first directories passed. This is mostly useful when only two cases are being compared.
Some plots (specifically deltaAverage2d
) have additional options.
The following table lists available plots
Module name | Description | Extra arguments |
---|---|---|
deltaAverage2d | Compare the mean of an arbitrary specified field | [--title TITLE] [--ylabel YLABEL] |
deltaIce | Compare total ice mass, computed from effective height and density. | |
deltaQ | Compare total internal energy, using initial conditions as reference state | |
deltaTKE | Compare total kinetic energy | |
deltaHeff | Compare mean ice thickness |
Additional Plots
The plots listed here aren't line plots, but can still be useful.
tcolour
Plot a Hovmoller diagram of horizontally-averaged temperature profile over time. Z is on the y-axis, and time on the x-axis. The plot is coloured by temperature. The command line interface is consistent iwth the above interfaces
python -m gcmpy.utils.tcolour figname [--start --stop --step]
With the same definitions as usual
fluxes
Make figure with many panels (currently 9) relating energies and heat fluxes. Subfigures plotted are (left to right across rows):
- Rate of change of total internal energy of water
- Rate of change of total internal energy of water per unit area
- SIqnet: Mean total heat flux out of the water surface. For ice covered areas, flux is water to ice. For open water, flux is water to atmosphere.
- SIatmQnt: Total atmospheric heat flux. For ice covered areas, heat flux from ice to atmosphere. For open water, heat flux from ocean to atmosphere.
- Ice covered part of SIqnet. Total heat flux from water into ice, averaged over the whole domain.
- Ice covered part of SIatmQnt. Total heat flux from ice into atmosphere, averaged over the whole domain.
- Rate of change of total internal energy of water per unit area + net heat flux out of the water. This should theoretically be identically zero, but the rate of change plotted in (2) is computed numerically as an average between files. Some small numerical error is expected.
- EXFhs: Sensible heat flux into water, positive increases temperature
- EXFhl: Latent heat flux into water, positive increases temperature