API reference

This page provides an auto-generated summary of the MPAS-Analysis API. For more details and examples, refer to the relevant chapters in the main part of the documentation.

Top-level script: mpas_analysis

main()	Entry point for the main script mpas_analysis
build_analysis_list(config, controlConfig)	Build a list of analysis tasks.
determine_analyses_to_generate(analyses, verbose)	Build a list of analysis tasks to run based on the 'generate' config option (or command-line flag) and prerequisites and subtasks of each requested task.
add_task_and_subtasks(analysisTask, ...[, ...])	If a task has been requested through the generate config option or if it is a prerequisite of a requested task, add it to the dictionary of tasks to generate.
update_generate(config, generate)	Update the 'generate' config option using a string from the command line.
run_analysis(config, analyses)	Run all the tasks, either in serial or in parallel
wait_for_task(runningTasks[, timeout])	Build a list of analysis modules based on the 'generate' config option.

Downloading data

download_analysis_data()

Entry point for downloading the input data set from public repository for MPAS-Analysis to work.

Analysis tasks

Base Class

AnalysisTask(config, taskName, componentName)	The base class for analysis tasks.
AnalysisTask.setup_and_check()	Perform steps to set up the analysis (e.g. reading namelists and streams files).
AnalysisTask.run_task()	Run the analysis.
AnalysisTask.run_after(task)	Only run this task after the given task has completed.
AnalysisTask.add_subtask(subtask)	Add a subtask to this tasks.
AnalysisTask.run([writeLogFile])	Sets up logging and then runs the analysis task.
AnalysisTask.check_generate()	Determines if this analysis should be generated, based on the generate config option and taskName, componentName and tags.
AnalysisTask.check_analysis_enabled(...[, ...])	Check to make sure a given analysis is turned on, issuing a warning or raising an exception if not.
AnalysisTask.set_start_end_date(section)	Set the start and end dates in the config correspond to the start and end years in a given category of analysis

Ocean tasks

ConservationTask(config, controlConfig)	This task generates time series plots from output from the conservation analysis member.
ClimatologyMapSST(config, mpasClimatologyTask)	An analysis task for comparison of sea surface temperature (sst) against observations
ClimatologyMapSSS(config, mpasClimatologyTask)	An analysis task for comparison of sea surface salinity (sss) against observations
ClimatologyMapMLD(config, mpasClimatologyTask)	An analysis task for comparison of mixed layer depth (mld) against observations
ClimatologyMapMLDMinMax(config, ...[, ...])	An analysis task for comparison of mixed layer depth (mld) against observations
ClimatologyMapSSH(config, mpasClimatologyTask)	An analysis task for comparison of sea surface height (ssh) against observations
ClimatologyMapEKE(config, mpasClimatologyTask)	An analysis task for comparison of eddy kinetic energy (eke) against observations
ClimatologyMapFluxes(config, mpasClimatologyTask)	An analysis task for plotting sea surface fluxes.
ClimatologyMapOHCAnomaly(config, ...[, ...])	An analysis task for comparison of the anomaly from a reference year (typically the start of the simulation) of ocean heat content (OHC)
ClimatologyMapAntarcticMelt(config, ...)	An analysis task for comparison of Antarctic melt rates against observations
ClimatologyMapSose(config, mpasClimatologyTask)	An analysis task for comparison of antarctic field against the Southern Ocean State Estimate
ClimatologyMapVel(config, mpasClimatologyTask)	An analysis task for plotting climatologies of velocity components and magnitude
ClimatologyMapWoa(config, mpasClimatologyTask)	An analysis task for comparison of polar and global temperature and salinity against WOA23 climatology fields
ClimatologyMapArgoTemperature(config, ...[, ...])	An analysis task for comparison of potential temperature against Argo observations
ClimatologyMapArgoSalinity(config, ...[, ...])	An analysis task for comparison of global salinity against Argo observations
ClimatologyMapWaves(config, ...)	An analysis task for the computation of wave climatologies
ClimatologyMapCustom(config, mpasClimatologyTask)	A flexible analysis task for plotting climatologies of any MPAS-Ocean field on cells from timeSeriesStatsMonthly at various depths (if the field has vertical levels) and for various seasons.
ClimatologyMapWindStressCurl(config, ...[, ...])	An analysis task for computing and plotting maps of the wind stress curl.
GeojsonNetcdfTransects(config, ...[, ...])	Plot model output at transects defined by lat/lon points in a geojson or NetCDF file
IndexNino34(config, mpasTimeSeriesTask[, ...])	A task for computing and plotting time series and spectra of the El Nino 3.4 climate index
MeridionalHeatTransport(config, ...[, ...])	Plot meridional heat transport from the analysis member output.
OceanHistogram(config, mpasClimatologyTask, ...)	Plots a histogram of a 2-d ocean variable.
OceanRegionalProfiles(config, regionMasksTask)	Compute and plot vertical profiles of regionally analyzed data.
RegionalTSDiagrams(config, ...[, controlConfig])	Create T-S Diagrams of the climatology within a given ocean region
SoseTransects(config, mpasClimatologyTask[, ...])	Plot model output at transects and various longitudes around Antarctica, compared against SOSE
StreamfunctionMOC(config, mpasClimatologyTask)	Computation and plotting of model meridional overturning circulation.
TimeSeriesOHCAnomaly(config, mpasTimeSeriesTask)	Performs analysis of ocean heat content (OHC) from time-series output.
TimeSeriesTemperatureAnomaly(config, ...)	Performs analysis of time series of potential temperature anomalies from a reference simulation year as a function of depth.
TimeSeriesSalinityAnomaly(config, ...)	Performs analysis of time series of salinity anomalies from the first simulation year as a function of depth.
TimeSeriesSST(config, mpasTimeSeriesTask[, ...])	Performs analysis of the time-series output of sea-surface temperature (SST).
TimeSeriesAntarcticMelt(config, ...[, ...])	Performs analysis of the time-series output of Antarctic sub-ice-shelf melt rates.
TimeSeriesOceanRegions(config, regionMasksTask)	Performs analysis of the time-series output of regionoal mean temperature, salinity, etc.
TimeSeriesTransport(config[, controlConfig])	Extract and plot time series of transport through transects on the MPAS mesh.
WoaTransects(config, mpasClimatologyTask[, ...])	Plot model output at transects and various longitudes around Antarctica, compared against the WOA23 climatology
WoceTransects(config, mpasClimatologyTask[, ...])	Plot model output at WOCE transects and compare it against WOCE observations

Ocean subtasks

ComputeAnomalySubtask(parentTask, ...[, ...])

A subtask for computing anomalies of moving averages and writing them out.

PlotDepthIntegratedTimeSeriesSubtask(...[, ...])

Plots a time series, summed or averaged over various depth ranges

PlotHovmollerSubtask(parentTask, regionName, ...)

Plots a time series vs.

Ocean utilities

add_standard_regions_and_subset(ds, config)	Add standard region names (regionNames coordinate) to a dataset and rename nOceanRegionsTmp dimension to nOceanRegions (if present).
get_standard_region_names(config, ...)	Add standard region names from the short names
compute_zmid(bottomDepth, maxLevelCell, ...)	Computes zMid given data arrays for bottomDepth, maxLevelCell and layerThickness
compute_zinterface(bottomDepth, ...)	Computes zInterface given data arrays for bottomDepth, maxLevelCell and layerThickness
vector_cell_to_edge_isotropic(ds_mesh, ...)	Compute the zonal and meridional components of a vector at edges from cell-centered components using isotropic area-weighted averaging.

Sea ice tasks

ClimatologyMapSeaIceConc(config, ...[, ...])	An analysis task for comparison of sea ice concentration against observations
ClimatologyMapSeaIceThick(config, ...[, ...])	An analysis task for comparison of sea ice thickness against observations
ClimatologyMapSeaIceSnowDepth(config, ...[, ...])	An analysis task for sea ice snow depth
ClimatologyMapSeaIceSnowiceFormation(config, ...)	An analysis task for snow-ice formation rate
ClimatologyMapSeaIceSnowMelt(config, ...[, ...])	An analysis task for snow melt rate
ClimatologyMapSeaIcePondArea(config, ...[, ...])	An analysis task for melt pond area
ClimatologyMapSeaIceAreaFractionRidge(...[, ...])	An analysis task for ridge area per unit area of sea ice
ClimatologyMapSeaIceVolumeRidge(config, ...)	An analysis task for volume per unit ice area
ClimatologyMapSeaIceAlbedo(config, ...[, ...])	An analysis task for sea ice broadband albedo
ClimatologyMapSeaIceProduction(config, ...)	An analysis task for comparison of sea ice production against observations
ClimatologyMapSeaIceMelting(config, ...[, ...])	An analysis task for comparison of sea ice melting against observations
ClimatologyMapSeaIceAreaTendencyThermo(...)	An analysis task for sea ice area tendency due to thermodynamics
ClimatologyMapSeaIceAreaTendencyTransp(...)	An analysis task for sea ice area tendency due to transport
ClimatologyMapSeaIceVolumeTendencyThermo(...)	An analysis task for sea ice volume tendency due to thermodynamics
ClimatologyMapSeaIceVolumeTendencyTransp(...)	An analysis task for sea ice volume tendency due to transport
TimeSeriesSeaIce(config, mpasTimeSeriesTask)	Performs analysis of time series of sea-ice properties.
ClimatologyMapIcebergConc(config, ...[, ...])	An analysis task for comparison of iceberg concentration against observations

Shared modules

Reading MPAS Datasets

open_mpas_dataset(fileName, calendar[, ...])

Opens and returns an xarray data set given file name(s) and the MPAS calendar name.

mpas_xarray.open_multifile_dataset(...[, ...])	Opens and returns an xarray data set given file name(s) and the MPAS calendar name.
mpas_xarray.preprocess(ds, calendar, ...)	Builds correct time specification for MPAS, allowing a date offset because the time must be between 1678 and 2262 based on the xarray library.
mpas_xarray.remove_repeated_time_index(ds)	Remove repeated times from xarray dataset.
mpas_xarray.subset_variables(ds, variableList)	Given a data set and a list of variable names, returns a new data set that contains only variables with those names.

generalized_reader.open_multifile_dataset(...)

Opens and returns an xarray data set given file name(s) and the MPAS calendar name.

Climatology

get_comparison_descriptor(config, ...)	Get the comparison grid descriptor from the comparison_grid_name.
get_remapper(config, sourceDescriptor, ...)	Given config options and descriptions of the source and comparison grids, returns a pyremap.Remapper object that can be used to remap from source files or data sets to corresponding data sets on the comparison grid.
compute_monthly_climatology(ds[, calendar, ...])	Compute monthly climatologies from a data set.
compute_climatology(ds, monthValues[, ...])	Compute a monthly, seasonal or annual climatology data set from a data set.
add_years_months_days_in_month(ds[, calendar])	Add year, month and daysInMonth as data arrays in ds.
get_unmasked_mpas_climatology_directory(config)	Get the directory for an unmasked MPAS climatology produced by ncclimo, making the directory if it doesn't already exist
get_unmasked_mpas_climatology_file_name(...)	Get the file name for an unmasked MPAS climatology produced by ncclimo
get_masked_mpas_climatology_file_name(...[, op])	Get the file name for a masked MPAS climatology
get_remapped_mpas_climatology_file_name(...)	Get the file name for a masked MPAS climatology
MpasClimatologyTask(config, componentName[, ...])	An analysis tasks for computing climatologies from output from the timeSeriesStatsMonthly* analysis members.
MpasClimatologyTask.add_variables(variableList)	Add one or more variables and optionally one or more seasons for which to compute climatologies.
MpasClimatologyTask.get_file_name(season)	Returns the full path for MPAS climatology file produced by ncclimo.
RemapMpasClimatologySubtask(...[, ...])	An analysis tasks for computing climatologies from output from the timeSeriesStatsMonthly analysis member.
RemapMpasClimatologySubtask.setup_and_check()	Perform steps to set up the analysis and check for errors in the setup.
RemapMpasClimatologySubtask.run_task()	Compute the requested climatologies
RemapMpasClimatologySubtask.add_comparison_grid_descriptor(...)	Add a custom grid descriptor (something other than 'latlon', 'antarctic', 'arctic', 'north_atlantic', or 'north_pacific', or 'subpolar_north_atlantic').
RemapMpasClimatologySubtask.get_masked_file_name(season)	Given config options, the name of a field and a string identifying the months in a seasonal climatology, returns the full path for MPAS climatology files before and after remapping.
RemapMpasClimatologySubtask.get_remapped_file_name(...)	Given config options, the name of a field and a string identifying the months in a seasonal climatology, returns the full path for MPAS climatology files before and after remapping.
RemapMpasClimatologySubtask.customize_masked_climatology(...)	Override this function to customize the climatology during the masking phase (before remapping)
RemapMpasClimatologySubtask.customize_remapped_climatology(...)	Override this function to customize the climatology after remapping
RemapObservedClimatologySubtask(parentTask, ...)	An analysis task for comparison of 2D model fields against observations.
RemapObservedClimatologySubtask.get_observation_descriptor(...)	get a MeshDescriptor for the observation grid.
RemapObservedClimatologySubtask.build_observational_dataset(...)	read in the data sets for observations, and possibly rename some variables and dimensions.
RemapObservedClimatologySubtask.get_file_name(stage)	Given config options, the name of a field and a string identifying the months in a seasonal climatology, returns the full path for MPAS climatology files before and after remapping.

Time Series

cache_time_series(timesInDataSet, ...[, ...])	Create or update a NetCDF file cacheFileName containing the given time series, calculated with timeSeriesCalcFunction over the given times, start and end year, and time frequency with which results are cached.
compute_moving_avg_anomaly_from_start(...[, ...])	Compute the rolling mean of the anomaly of a quantity from the beginning of the simulation (such that the rolling mean starts at zero by definition)
compute_moving_avg(ds[, movingAveragePoints])	Compute the rolling mean of a data set
MpasTimeSeriesTask(config, componentName[, ...])	An analysis tasks for computing time series from output from the timeSeriesStatsMonthly analysis member.

Namelist and Streams Files

convert_namelist_to_dict(fname[, readonly])	Converts a namelist file to key-value pairs in dictionary.
NameList.__init__(fname[, path])	Parse the namelist file
NameList.__getattr__(key)	Accessor for dot noation, e.g., nml.field
NameList.__getitem__(key)	Accessor for bracket notation, e.g., nml['field']
NameList.get(key)	Get the value associated with a given key
NameList.getint(key)	Get the integer value associated with a given key
NameList.getfloat(key)	Get the float value associated with a given key
NameList.getbool(key)	Get the boolean value associated with a given key
StreamsFile.__init__(fname[, streamsdir])	Parse the streams file.
StreamsFile.read(streamname, attribname)	Get the value of the given attribute in the given stream
StreamsFile.readpath(streamName[, ...])	Given the name of a stream and optionally start and end dates and a calendar type, returns a list of files that match the file template in the stream.
StreamsFile.has_stream(streamName)	Does the stream file have the given stream?
StreamsFile.find_stream(possibleStreams)	If one (or more) of the names in possibleStreams is an stream in this streams file, returns the first match.

I/O Utilities

utility.paths(*args)	Returns glob'd paths in list for arbitrary number of function arguments.
utility.make_directories(path)	Make the given path if it does not already exist.
utility.build_config_full_path(config, ...)	Get a full path from a base directory and a relative path
utility.check_path_exists(path)	Raise an exception if the given path does not exist.
write_netcdf

Plotting

timeseries_analysis_plot(config, dsvalues, ...)	Plots the list of time series data sets.
timeseries_analysis_plot_polar(config, ...)	Plots the list of time series data sets on a polar plot.
plot_polar_comparison(config, lon, lat, ...)	Plots a data set around either the north or south pole.
plot_global_comparison(config, Lons, Lats, ...)	Plots a data set as a longitude/latitude map.
plot_1D(config, xArrays, fieldArrays, errArrays)	Plots a 1D line plot with error bars if available.
plot_vertical_section_comparison(config, ...)	Plots vertical section plots in a three-panel format, comparing model data (in modelArray) to some reference dataset (in refArray), which can be either observations or an alternative model, and also presenting the difference plot of the two.
plot_vertical_section(config, field, ...[, ...])	Plots a data set as a x distance (latitude, longitude, or spherical distance) vs depth map (vertical section).
colormap.setup_colormap(config, ...[, suffix])	Set up a colormap from the registry
ticks.plot_xtick_format(calendar, minDays, ...)	Formats tick labels and positions along the x-axis for time series / index plots
add_inset(fig, fc[, latlonbuffer, ...])	Plots an inset map showing the location of a transect or polygon.
PlotClimatologyMapSubtask(parentTask, ...[, ...])	An analysis task for plotting 2D model fields against observations.
PlotClimatologyMapSubtask.set_plot_info(...)	Store attributes related to plots, plot file names and HTML output.

Projection

get_pyproj_projection(comparison_grid_name)	Get the projection from the comparison_grid_name.
get_cartopy_projection(comparison_grid_name)	Get the projection from the comparison_grid_name.

Regions

compute_region_masks.ComputeRegionMasks(...)	An analysis tasks for computing cell masks for regions defined by geojson features
compute_region_masks_subtask.ComputeRegionMasksSubtask(...)	An analysis tasks for computing cell masks for regions defined by geojson features
compute_region_masks_subtask.get_feature_list(...)	Builds a list of features found in the geojson file

Timekeeping

utility.get_simulation_start_time(streams)	Given a StreamsFile object, returns the simulation start time parsed from a restart file.
utility.string_to_datetime(dateString)	Given a date string and a calendar, returns a datetime.datetime
utility.string_to_relative_delta(dateString)	Given a date string and a calendar, returns an instance of MpasRelativeDelta
utility.string_to_days_since_date(dateString)	Given a date string or an array-like of date strings, a reference date string, and a calendar, returns the number of days (as a float or numpy.array of floats) since the reference date
utility.days_to_datetime(days[, calendar, ...])	Covert days to datetime.datetime objects given a reference date and an MPAS calendar (either 'gregorian' or 'noleap').
utility.datetime_to_days(dates[, calendar, ...])	Given date(s), a calendar and a reference date, returns the days since the reference date, either as a single float or an array of floats.
utility.date_to_days([year, month, day, ...])	Convert a date to days since the reference date.
MpasRelativeDelta.MpasRelativeDelta([dt1, ...])	MpasRelativeDelta is a subclass of dateutil.relativedelta for relative time intervals with different MPAS calendars.

Transects

compute_transect_masks_subtask.compute_mpas_transect_masks(...)	Build a transect mask file from the given MPAS mesh and geojson file defining a set of transects.
compute_transect_masks_subtask.ComputeTransectMasksSubtask(...)	An analysis tasks for computing cell masks for transects defined by geojson features