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: run_mpas_analysis

run_mpas_analysis.build_analysis_list(…)	Build a list of analysis tasks.
run_mpas_analysis.determine_analyses_to_generate(…)	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.
run_mpas_analysis.add_task_and_subtasks(…)	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.
run_mpas_analysis.update_generate(config, …)	Update the ‘generate’ config option using a string from the command line.
run_mpas_analysis.run_analysis(config, analyses)	Run all the tasks, either in serial or in parallel
run_mpas_analysis.wait_for_task(runningTasks)	Build a list of analysis modules based on the ‘generate’ config option.

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.
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

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
ClimatologyMapSSH(config, mpasClimatologyTask)	An analysis task for comparison of sea surface height (ssh) against observations
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
ClimatologyMapSoseTemperature(config, …[, …])	An analysis task for comparison of antarctic temperature against SOSE fields
ClimatologyMapSoseSalinity(config, …[, …])	An analysis task for comparison of antarctic salinity against SOSE fields
ClimatologyMapSoseMLD(config, …[, refConfig])	An analysis task for comparison of antarctic mixed layer depth against SOSE fields
ClimatologyMapSoseZonalVel(config, …[, …])	An analysis task for comparison of zonal velociy around Antarctica against SOSE fields
ClimatologyMapSoseMeridVel(config, …[, …])	An analysis task for comparison of meridional velociy around Antarctica against SOSE fields
ClimatologyMapSoseVelMag(config, …[, …])	An analysis task for comparison of velocity magnitude around Antarctica against SOSE fields
ClimatologyMapArgoTemperature(config, …[, …])	An analysis task for comparison of antarctic temperature against SOSE fields
ClimatologyMapArgoSalinity(config, …[, …])	An analysis task for comparison of Global Temperature against Argo fields
IndexNino34(config, mpasTimeSeriesTask[, …])	A task for computing and plotting time series and spectra of the El Nino 3.4 climate index
MeridionalHeatTransport(config, …[, refConfig])	Plot meridional heat transport from the analysis member output.
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 temperature anomalies from the first 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, …[, refConfig])	Performs analysis of the time-series output of Antarctic sub-ice-shelf melt rates.

ComputeAnomalySubtask(parentTask, …[, …])

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

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.

PlotDepthIntegratedTimeSeriesSubtask(…[, …])

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

PlotHovmollerSubtask(parentTask, regionName, …)

Plots a time series vs.

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
TimeSeriesSeaIce(config, mpasTimeSeriesTask)	Performs analysis of time series of sea-ice properties.

PlotClimatologyMapSubtask(parentTask, …[, …])	An analysis task for plotting 2D model fields against observations or a reference run.
PlotClimatologyMapSubtask.set_plot_info(…)	Store attributes related to plots, plot file names and HTML output.

Configuration

MpasAnalysisConfigParser([defaults, …])
MpasAnalysisConfigParser.getWithDefault(…)	Get an option, using the supplied default value if the option is not present.
MpasAnalysisConfigParser.getExpression(…)	Get an option as an expression (typically a list, though tuples and dicts are also availabe).

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 comparisonGridName.
get_antarctic_stereographic_projection()	Get a projection for an Antarctic steregraphic comparison grid
get_remapper(config, sourceDescriptor, …)	Given config options and descriptions of the source and comparison grids, returns a 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(…)	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 member.
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.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.
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.

Interpolation

Remapper(sourceDescriptor, destinationDescriptor)

A class for remapping fields using a given mapping file.

MpasMeshDescriptor(fileName[, meshName])	A class for describing an MPAS mesh
LatLonGridDescriptor()	A class for describing a lat-lon grid
ProjectionGridDescriptor(projection)	A class for describing a general logically rectangular grid that can be defined by a pyproj projection.

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 noation, 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, …)	Returns 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(ds, fileName[, fillValues])	Write an xarray data set to a NetCDF file using finite fill values

Plotting

plotting.timeseries_analysis_plot(config, …)	Plots the list of time series data sets and stores the result in an image file.
plotting.timeseries_analysis_plot_polar(…)	Plots the list of time series data sets on a polar plot and stores the result in an image file.
plotting.plot_polar_comparison(config, Lons, …)	Plots a data set around either the north or south pole.
plotting.plot_global_comparison(config, …)	Plots a data set as a longitude/latitude map.
plotting.plot_1D(config, xArrays, …[, …])	Plots a 1D line plot with error bars if available.
plotting.plot_vertical_section(config, …)	Plots a data set as a x distance (latitude, longitude, or spherical distance) vs depth map (vertical section).
plotting.setup_colormap(config, …[, suffix])	Set up a colormap from the registry
plotting.plot_xtick_format(calendar, …[, …])	Formats tick labels and positions along the x-axis for time series / index plots

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 ‘gregorian_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.