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

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.
ClimatologyMapIcebergConc(config, …[, …])	An analysis task for comparison of iceberg concentration against observations

PlotClimatologyMapSubtask(parentTask, …[, …])	An analysis task for plotting 2D model fields against observations or a control 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 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.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.

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

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(config, xArray, …[, …])	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.

Regions

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

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