# CDT Contents

This page lists the contents of Climate Data Tools for Matlab. For help getting started with CDT, see CDT Getting Started.

## Contents

## Descriptive Statistics

returns statistical values of all points within a given 1D radius of each value. This is similar to taking a moving mean, but points do not have to be equally spaced, nor do x values need to be monotonically increasing.`scatstat1`returns statistical values of all points within a given radius of each value. This is similar to taking a two-dimensional moving mean, but points do not need to be equally spaced.`scatstat2`computes the weighted average or weighted mean value.`wmean`removes the mean of a variable and scales it such that its standard deviation is 1.`standardize`calculates and plots percentile bounds for ensemble data.`ensemble2bnd`calculates the linear trend of a data series by least squares.`trend`computes weighted polynomial fits.`polyfitw`performs linear least squares detrending along the third dimension of a matrix.`detrend3`calculates statistics of a variable for specified months of the year.`monthly`estimates anomalies associated with the annual cycle or of a time series.`season`removes the seasonal (aka annual) component of variability from a time series.`deseason`gives typical values of a variable as it varies throughout the year.`climatology`fits a least-squares estimate of a sinusoid to time series data that have a periodicity of 1 year.`sinefit`produces a sinusoid of specified amplitude and phase with a frequency of 1/yr.`sineval`

## Matrix Manipulation

reshapes a 3D matrix for use with standard Matlab functions.`cube2rect`is the complement of`rect2cube``cube2rect`. It reshapes and permutes a 2D matrix into a 3D cube.applies a mask to all levels of 3D matrix corresponding to a 2D mask.`mask3`creates a 3D matrix from the product of a 2D grid and a 1D vector.`expand3`returns a 1D array of values calculated from a region of interest in a 3D matrix. For example, if you have a big global 3D sea surface temperature dataset, this function makes it easy to obtain a time series of the average sst within a region of interest.`local`reshapes timeseries data to year by time-of-year grid.`reshapetimeseries`finds the linear index of the point in an array closest to a specified coordinate.`near1`finds the subscript indices of the point in a grid closest to a specified location.`near2`converts a logical mask into an outline or border.`mask2outline`concatenates elements of a cell into a NaN-separated vector.`cell2nancat`converts regularly-spaced columnated x,y,z data into gridded data.`xyz2grid`converts a contour matrix (as returned by the`C2xyz``contour`function) into x, y, and corresponding z coordinates.simply imports the x,y,z columns of a .xyz file.`xyzread`

## Georeferenced Grids

works like`demresize``imresize`, but also resizes corresponding map coordinates.rewraps a gridded dataset to be centered on a specified longitude.`recenter`uses`cdtgrid``meshgrid`to easily create a global grid of latitudes and longitudes.gives the approximate dimensions of each cell in a lat,lon grid assuming a spherical Earth of radius 6371000 meters.`cdtdim`gives the approximate area of each cell in a lat,lon grid assuming a spherical Earth of radius 6371000 meters. This function was designed to enable easy area-averaged weighting of large gridded climate datasets.`cdtarea`calculates the spatial gradient of gridded data equally spaced in geographic coordinates.`cdtgradient`calculates the divergence of gridded vectors on the ellipsoidal Earth's surface.`cdtdivergence`calculates the z component of curl for gridded vectors on an ellipsoidal Earth.`cdtcurl`determines whether geographic locations are within a given geographic region.`geomask`determines whether geographic locations correspond to land or water.`island`converts binned index values of a sinusoidal grid to geocoordinates.`binind2latlon`

## Spatial Patterns

performs a highpass, lowpass, bandpass, or bandstop 2D gaussian filter on gridded data.`filt2`returns statistical values of all points within a given radius of each value. This is similar to taking a two-dimensional moving mean, but points do not need to be equally spaced.`scatstat2`gives eigenmode maps of variability and corresponding principal component time series for spatiotemporal data analysis.`eof`reof reconstructs a time series of eof anomalies from specified EOF modes.`reof`computes linear or rank correlation for a time series and a 3D dataset.`corr3`gives a map of correlation coefficients between grid cells of a 3D spatiotemporal dataset and a reference time series.`xcorr3`gives a map of covariance between grid cells of a 3D spatiotemporal dataset and a reference time series.`xcov3`

## Time Series

applies a zero-phase butterworth filter to a time series.`filt1`returns statistical values of all points within a given 1D radius of each value. This is similar to taking a moving mean, but points do not have to be equally spaced, nor do x values need to be monotonically increasing.`scatstat1`returns the day of year.`doy`reshapes timeseries data to year by time-of-year grid.`reshapetimeseries`converts between Matlab datetimes and Climate and Forecast-formatted times`cftime`

## Uncertainty Quantification

performs a standard simple Mann-Kendall test to determine the presence of a significant trend.`mann_kendall`performs a bootstrap uncertainty analysis on a time series given an uncertainty value at each step assuming a normal probability distribution.`ts_normstrap`performs a bootstrap analysis on the parameters estimated by`sinefit_bootstrap``sinefit`.

## Climate Indices

computes the El Nino Southern Oscillation index.`enso`calculates the Southern Annular Mode index from sea-level pressures.`sam`calculates the North Atlantic Oscillation index from sea-level pressures based on the definition proposed by Hurrell, 1995. (Equivalent to the Arctic Oscillation or Northern Annular Mode).`nao`calculates the Atlantic Multidecadal Oscillation index from sea surface temperatures based on the definition proposed by Enfield et al. 2001.`amo`gives potential reference evapotranspiration following Hargreaves-Samani.`pet`computes the standardised precipitation-evapotranspiration index.`spei`

## Oceans & Atmospheres

finds the lowermost finite values of a 3D matrix such as to determine seafloor temperature from a 3D gridded dataset.`bottom`estimates wind stress on the ocean from wind speed.`windstress`estimates the classical Ekman transport and upwelling/downwelling from 10 m winds.`ekman`returns the Coriolis frequency (also known as the Coriolis parameter or the Coriolis coefficient) for any given latitude(s).`coriolisf`gives the Rossby radius of deformation for a barotropic ocean.`rossby_radius`calculate mixed layer depth following Holte and Talley, 2009.`mld`converts binned index values of a sinusoidal grid to geocoordinates.`binind2latlon`produces a color-scaled transect diagram of oceanographic data from CTD profiles collected at different locations and/or times.`transect`produces a contoured transect diagram of oceanographic data from CTD profiles collected at different locations and/or times.`transectc`

## Geophysical Attributes

gives the nominal or latitude-dependent radius of Earth.`earth_radius`computes pressure from the baromometric forumula for a US Standard Atmosphere.`air_pressure`computes density the baromometric forumula for a US Standard Atmosphere.`air_density`gives the solar azimuth and elevation for any time at any location on Earth.`sun_angle`computes modern daily total extraterrestrial solar radiation received at the top of Earth's atmosphere.`solar_radiation`computes daily average insolation as a function of day and latitude at any point during the past 5 million years.`daily_insolation`interpolates elevations at any geographic locations from ETOPO5.`topo_interp`determines whether geographic locations correspond to land or water.`island`determines the distance from any geolocation to the nearest coastline.`dist2coast`

## Graphics

provides RGB values of common and uncommon colors by name.`rgb`provides perceptually-uniform colormaps by Thyng et al., 2016.`cmocean`creates a color-scaled text that is something between a colorbar and a text legend. It does`textcolorbar`**not**hijack the current colormap.allows multiple colormaps and colorbars in the same axes.`newcolorbar`places triangle-shaped endmembers on colorbars to indicate that data values exist beyond the extents of the values shown in the colorbar.`cbarrow`formats colorbar ticks as dates strings.`cbdate`creates horizontal lines on a plot.`hline`creates vertical lines on a plot.`vline`creates horizontal filled regions on a plot.`hfill`creates vertical filled regions on a plot.`vfill`places a title within a plot instead of on top.`ntitle`easily creates .gif animations.`gif`

## Line Plots

plots line data with different colors of shading filling the area between the curve and a reference value. This is a common way of displaying anomaly time series such as sea surface temperatures or climate indices.`anomaly`plots lines with shaded error/confidence bounds.`boundedline`creates sub-axes in tiled positions.`subsubplot`plots an Ed Hawkins style spiral plot of a time series.`spiralplot`plots a power spectral density of a time series using Matlab's inbuilt periodogram function.`plotpsd`plots a polynomial fit to scattered x,y data.`polyplot`

## Maps

plots an unprojected image base map of Earth.`earthimage`is faster than`imagescn``pcolor`, plots*all*the data you give it (whereas`pcolor`deletes data near edges and`NaN`values), makes`NaN`values transparent (whereas`imagesc`assigns the same color as the lowest value in the color axis), and is slightly easier to use than`imagesc`.plots National or US state boundaries without Matlab's Mapping Toolbox.`borders`plots National or US state boundaries on maps generated with Matlab's Mapping Toolbox.`bordersm`labels borders of nations or US states.`labelborders`labels National or US state boundaries on maps generated with Matlab's Mapping Toolbox.`labelbordersm`creates a hatch filling or stippling within a grid.`stipple`creates a hatch filling or stippling within a grid, for use on maps created with Matlab's Mapping Toolbox.`stipplem`scales a dense grid of quiver arrows to comfortably fit in axes before plotting them.`quiversc`plots patch objects with face colors scaled by numeric values.`patchsc`gives an approximate center location of polygons for map labelling (usually better than centroid).`polycenter`determines whether geographic boundingboxes overlap.`isoverlapping`

## Globes

creates a "Blue Marble" 3D globe image.`globeimage`function plots georeferenced data on a globe.`globeplot`georeferenced data on a globe where color is scaled by the data value.`globepcolor`plots georeferenced data on a globe where values in matrix Z are plotted as heights above the globe.`globesurf`plots contour lines on a globe from gridded data.`globecontour`plots georeferenced data as color-scaled markers on a globe.`globescatter`plots political boundaries borders on a globe.`globeborders`plots georeferenced vectors with components (u,v) on a globe.`globequiver`creates a hatch filling or stippling over a region of a globe.`globestipple`plots a graticule globe. Optional inputs control the appearance and behavior of the graticule.`globegraticule`plots a filled globe.`globefill`

## NetCDF and HDF5

Check out the NetCDF tutorial for help getting started with NetCDF data.

reads several variables from netcdf file(s).`ncstruct`reads datetimes from a netcdf time variable.`ncdateread`reads first and last date from a netcdf file.`ncdatelim`builds and writes variable data to a netcdf file.`ncbuild`collection assists in building a netcdf file schema structure.`ncschema_`prepends a dated string to the global history attribute of a netcdf file`ncaddhis`loads HDF5 data into a Matlab stucture with the same hierarchy as the original file.`h5struct`

## Tutorials

CDT includes a handful of tutorials that address some common issues that we run into when analyzing climate data in Matlab.

**NetCDF data**describes how to load and analyze NetCDF data.**Dates and times**describes various Matlab date formats, and how to use them with Earth science data.**Linear trends**explains how to apply least-squares regression to climate time series.**Mapmaking**describes several different ways to make maps of climate data in Matlab.

## Sample Datasets

CDT comes with several datasets which can be used to test scripts or create examples. They are as follows:

: Surface elevations from NASA's Airborne Topographic Mapper, used as an example dataset in the documentation for`altimetry_example.h5``h5struct`.: True-color image of Earth from NASA. This image is plotted by`bluemarble.png``earthimage`.: National and US state boundaries plotted by`borderdata.mat``borders`,`bordersm`,`labelborders`,`labelbordersm`, and`globeborders`.: contains ocean temperature, salinity, and oxygen from CTD casts taken off the coast of Antarctica.`BROKE_cruise_odv.txt`: Gridded Antarctic Curie Depth from Martos, 2017.`Curie_Depth.xyz`: A global grid of distances to coastlines calculated using great circle distances on the`distance2coast.mat``land_mask.mat`dataset. Called by`dist2coast`.: ECMWF Synoptic Monthly Means of temperature, wind, surface pressure, and precipitation. See the NetCDF Tutorial for a description of how to load and plot this dataset.`ERA_interim_2017.nc`: Example oceanographic profile data used in the`example_ctd.mat``transect`documentation.: An 0.75 degree global grid of sea surface temperatures.`global_sst.mat`: A 5-minute (1/12 degree) global grid of topography from the World digital elevation model (ETOPO5) called by`global_topography.mat``topo_interp`.: A 1/8 degree binary mask indicating areas of land or ocean. This dataset is called by the`land_mask.mat``island`function.: Atmospheric Carbon Dioxide Dry Air Mole Fractions from quasi-continuous measurements at Mauna Loa, Hawaii. From NOAA.`mlo_daily_C02.mat`: Observations of zonal mean sea level pressure from the Climate Research Unit, used as an example for the`nao_slp_data.mat``nao`function.: Temperature and precipitation reanalysis data described in the documentation for the`ncep-ncar.mat``spei`function.: 2 degree monthly gridded sea surface temperatures spanning the North Atlantic ocean from 1870 to 2017.`north_atlantic_sst.mat`: Earth's orbital parameters from Berger A. and Loutre M.F., 1991 used as an example for`orbit91.txt``daily_insolation`.: used by the`orbital_parameter_data.mat``daily_insolation`function written by Ian Eisenman and Peter Huybers, Harvard University, August 2006.: A 67 year time series of gridded monthly sea surface temperatures covering part of the Pacific Ocean. This dataset is analyzed as part of the`pacific_sst.mat``eof`function documentation.: A 1/8 degree grid of sea surface temperatures and wind covering part of the Pacific Ocean. This dataset is analyzed as part of the`pacific_wind.mat``ekman`function documentation.zonal mean surface pressure averaged from 12 stations by G. Marshall, used as example data in the documentation for the`sam_slp_data.mat``sam`function.: A 38 year daily time series of sea ice extent for the northern and southern hemispheres from the NSIDC. This dataset is plotted as part of the`seaice_extent.mat``spiralplot`and function documentation.: A 3D grid of potential temperatures from the Southern Ocean Database. The dataset is described at the end of the`sodb_example.mat``bottom`documentation.: The names and RGB values of 950 colors as they appear on computer screens. This data results from an impressively thorough survey conducted by XKCD's Randall Munroe and is called by the CDT function`xkcd_rgb_data.mat``rgb`.

## Citing CDT

Please cite our paper!

Chad A. Greene, Kaustubh Thirumalai, Kelly A. Kearney, Jose Miguel Delgado, Wolfgang Schwanghart, Natalie S. Wolfenbarger, Kristen M. Thyng, David E. Gwyther, Alex S. Gardner, and Donald D. Blankenship (2019). The Climate Data Toolbox for MATLAB. *Geochemistry, Geophysics, Geosystems,* 20, 3774-3781. doi:10.1029/2019GC008392