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
- scatstat1 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.
- scatstat2 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.
- wmean computes the weighted average or weighted mean value.
- standardize removes the mean of a variable and scales it such that its standard deviation is 1.
- ensemble2bnd calculates and plots percentile bounds for ensemble data.
- trend calculates the linear trend of a data series by least squares.
- polyfitw computes weighted polynomial fits.
- detrend3 performs linear least squares detrending along the third dimension of a matrix.
- monthly calculates statistics of a variable for specified months of the year.
- season estimates anomalies associated with the annual cycle or of a time series.
- deseason removes the seasonal (aka annual) component of variability from a time series.
- climatology gives typical values of a variable as it varies throughout the year.
- sinefit fits a least-squares estimate of a sinusoid to time series data that have a periodicity of 1 year.
- sineval produces a sinusoid of specified amplitude and phase with a frequency of 1/yr.
Matrix Manipulation
- cube2rect reshapes a 3D matrix for use with standard Matlab functions.
- rect2cube is the complement of cube2rect. It reshapes and permutes a 2D matrix into a 3D cube.
- mask3 applies a mask to all levels of 3D matrix corresponding to a 2D mask.
- expand3 creates a 3D matrix from the product of a 2D grid and a 1D vector.
- local 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.
- reshapetimeseries reshapes timeseries data to year by time-of-year grid.
- near1 finds the linear index of the point in an array closest to a specified coordinate.
- near2 finds the subscript indices of the point in a grid closest to a specified location.
- mask2outline converts a logical mask into an outline or border.
- cell2nancat concatenates elements of a cell into a NaN-separated vector.
- xyz2grid converts regularly-spaced columnated x,y,z data into gridded data.
- C2xyz converts a contour matrix (as returned by the contour function) into x, y, and corresponding z coordinates.
- xyzread simply imports the x,y,z columns of a .xyz file.
Georeferenced Grids
- demresize works like imresize, but also resizes corresponding map coordinates.
- recenter rewraps a gridded dataset to be centered on a specified longitude.
- cdtgrid uses meshgrid to easily create a global grid of latitudes and longitudes.
- cdtdim gives the approximate dimensions of each cell in a lat,lon grid assuming a spherical Earth of radius 6371000 meters.
- cdtarea 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.
- cdtgradient calculates the spatial gradient of gridded data equally spaced in geographic coordinates.
- cdtdivergence calculates the divergence of gridded vectors on the ellipsoidal Earth's surface.
- cdtcurl calculates the z component of curl for gridded vectors on an ellipsoidal Earth.
- geomask determines whether geographic locations are within a given geographic region.
- island determines whether geographic locations correspond to land or water.
- binind2latlon converts binned index values of a sinusoidal grid to geocoordinates.
Spatial Patterns
- filt2 performs a highpass, lowpass, bandpass, or bandstop 2D gaussian filter on gridded data.
- scatstat2 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.
- eof gives eigenmode maps of variability and corresponding principal component time series for spatiotemporal data analysis.
- reof reof reconstructs a time series of eof anomalies from specified EOF modes.
- corr3 computes linear or rank correlation for a time series and a 3D dataset.
- xcorr3 gives a map of correlation coefficients between grid cells of a 3D spatiotemporal dataset and a reference time series.
- xcov3 gives a map of covariance between grid cells of a 3D spatiotemporal dataset and a reference time series.
Time Series
- filt1 applies a zero-phase butterworth filter to a time series.
- scatstat1 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.
- doy returns the day of year.
- reshapetimeseries reshapes timeseries data to year by time-of-year grid.
- cftime converts between Matlab datetimes and Climate and Forecast-formatted times
Uncertainty Quantification
- mann_kendall performs a standard simple Mann-Kendall test to determine the presence of a significant trend.
- ts_normstrap performs a bootstrap uncertainty analysis on a time series given an uncertainty value at each step assuming a normal probability distribution.
- sinefit_bootstrap performs a bootstrap analysis on the parameters estimated by sinefit.
Climate Indices
- enso computes the El Nino Southern Oscillation index.
- sam calculates the Southern Annular Mode index from sea-level pressures.
- nao 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).
- amo calculates the Atlantic Multidecadal Oscillation index from sea surface temperatures based on the definition proposed by Enfield et al. 2001.
- pet gives potential reference evapotranspiration following Hargreaves-Samani.
- spei computes the standardised precipitation-evapotranspiration index.
Oceans & Atmospheres
- bottom finds the lowermost finite values of a 3D matrix such as to determine seafloor temperature from a 3D gridded dataset.
- windstress estimates wind stress on the ocean from wind speed.
- ekman estimates the classical Ekman transport and upwelling/downwelling from 10 m winds.
- coriolisf returns the Coriolis frequency (also known as the Coriolis parameter or the Coriolis coefficient) for any given latitude(s).
- rossby_radius gives the Rossby radius of deformation for a barotropic ocean.
- mld calculate mixed layer depth following Holte and Talley, 2009.
- binind2latlon converts binned index values of a sinusoidal grid to geocoordinates.
- transect produces a color-scaled transect diagram of oceanographic data from CTD profiles collected at different locations and/or times.
- transectc produces a contoured transect diagram of oceanographic data from CTD profiles collected at different locations and/or times.
Geophysical Attributes
- earth_radius gives the nominal or latitude-dependent radius of Earth.
- air_pressure computes pressure from the baromometric forumula for a US Standard Atmosphere.
- air_density computes density the baromometric forumula for a US Standard Atmosphere.
- sun_angle gives the solar azimuth and elevation for any time at any location on Earth.
- solar_radiation computes modern daily total extraterrestrial solar radiation received at the top of Earth's atmosphere.
- daily_insolation computes daily average insolation as a function of day and latitude at any point during the past 5 million years.
- topo_interp interpolates elevations at any geographic locations from ETOPO5.
- island determines whether geographic locations correspond to land or water.
- dist2coast determines the distance from any geolocation to the nearest coastline.
Graphics
- rgb provides RGB values of common and uncommon colors by name.
- cmocean provides perceptually-uniform colormaps by Thyng et al., 2016.
- textcolorbar creates a color-scaled text that is something between a colorbar and a text legend. It does not hijack the current colormap.
- newcolorbar allows multiple colormaps and colorbars in the same axes.
- cbarrow places triangle-shaped endmembers on colorbars to indicate that data values exist beyond the extents of the values shown in the colorbar.
- cbdate formats colorbar ticks as dates strings.
- hline creates horizontal lines on a plot.
- vline creates vertical lines on a plot.
- hfill creates horizontal filled regions on a plot.
- vfill creates vertical filled regions on a plot.
- ntitle places a title within a plot instead of on top.
- gif easily creates .gif animations.
Line Plots
- anomaly 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.
- boundedline plots lines with shaded error/confidence bounds.
- subsubplot creates sub-axes in tiled positions.
- spiralplot plots an Ed Hawkins style spiral plot of a time series.
- plotpsd plots a power spectral density of a time series using Matlab's inbuilt periodogram function.
- polyplot plots a polynomial fit to scattered x,y data.
Maps
- earthimage plots an unprojected image base map of Earth.
- imagescn is faster than 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.
- borders plots National or US state boundaries without Matlab's Mapping Toolbox.
- bordersm plots National or US state boundaries on maps generated with Matlab's Mapping Toolbox.
- labelborders labels borders of nations or US states.
- labelbordersm labels National or US state boundaries on maps generated with Matlab's Mapping Toolbox.
- stipple creates a hatch filling or stippling within a grid.
- stipplem creates a hatch filling or stippling within a grid, for use on maps created with Matlab's Mapping Toolbox.
- quiversc scales a dense grid of quiver arrows to comfortably fit in axes before plotting them.
- patchsc plots patch objects with face colors scaled by numeric values.
- polycenter gives an approximate center location of polygons for map labelling (usually better than centroid).
- isoverlapping determines whether geographic boundingboxes overlap.
Globes
- globeimage creates a "Blue Marble" 3D globe image.
- globeplot function plots georeferenced data on a globe.
- globepcolor georeferenced data on a globe where color is scaled by the data value.
- globesurf plots georeferenced data on a globe where values in matrix Z are plotted as heights above the globe.
- globecontour plots contour lines on a globe from gridded data.
- globescatter plots georeferenced data as color-scaled markers on a globe.
- globeborders plots political boundaries borders on a globe.
- globequiver plots georeferenced vectors with components (u,v) on a globe.
- globestipple creates a hatch filling or stippling over a region of a globe.
- globegraticule plots a graticule globe. Optional inputs control the appearance and behavior of the graticule.
- globefill plots a filled globe.
NetCDF and HDF5
Check out the NetCDF tutorial for help getting started with NetCDF data.
- ncstruct reads several variables from netcdf file(s).
- ncdateread reads datetimes from a netcdf time variable.
- ncdatelim reads first and last date from a netcdf file.
- ncbuild builds and writes variable data to a netcdf file.
- ncschema_ collection assists in building a netcdf file schema structure.
- ncaddhis prepends a dated string to the global history attribute of a netcdf file
- h5struct loads HDF5 data into a Matlab stucture with the same hierarchy as the original file.
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:
- altimetry_example.h5: Surface elevations from NASA's Airborne Topographic Mapper, used as an example dataset in the documentation for h5struct.
- bluemarble.png: True-color image of Earth from NASA. This image is plotted by earthimage.
- borderdata.mat: National and US state boundaries plotted by borders, bordersm, labelborders, labelbordersm, and globeborders.
- BROKE_cruise_odv.txt: contains ocean temperature, salinity, and oxygen from CTD casts taken off the coast of Antarctica.
- Curie_Depth.xyz: Gridded Antarctic Curie Depth from Martos, 2017.
- distance2coast.mat: A global grid of distances to coastlines calculated using great circle distances on the land_mask.mat dataset. Called by dist2coast.
- ERA_interim_2017.nc: 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.
- example_ctd.mat: Example oceanographic profile data used in the transect documentation.
- global_sst.mat: An 0.75 degree global grid of sea surface temperatures.
- global_topography.mat: A 5-minute (1/12 degree) global grid of topography from the World digital elevation model (ETOPO5) called by topo_interp.
- land_mask.mat: A 1/8 degree binary mask indicating areas of land or ocean. This dataset is called by the island function.
- mlo_daily_C02.mat: Atmospheric Carbon Dioxide Dry Air Mole Fractions from quasi-continuous measurements at Mauna Loa, Hawaii. From NOAA.
- nao_slp_data.mat: Observations of zonal mean sea level pressure from the Climate Research Unit, used as an example for the nao function.
- ncep-ncar.mat: Temperature and precipitation reanalysis data described in the documentation for the spei function.
- north_atlantic_sst.mat: 2 degree monthly gridded sea surface temperatures spanning the North Atlantic ocean from 1870 to 2017.
- orbit91.txt: Earth's orbital parameters from Berger A. and Loutre M.F., 1991 used as an example for daily_insolation.
- orbital_parameter_data.mat: used by the daily_insolation function written by Ian Eisenman and Peter Huybers, Harvard University, August 2006.
- pacific_sst.mat: 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 eof function documentation.
- pacific_wind.mat: 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 ekman function documentation.
- sam_slp_data.mat zonal mean surface pressure averaged from 12 stations by G. Marshall, used as example data in the documentation for the sam function.
- seaice_extent.mat: 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 spiralplot and function documentation.
- sodb_example.mat: A 3D grid of potential temperatures from the Southern Ocean Database. The dataset is described at the end of the bottom documentation.
- xkcd_rgb_data.mat: 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 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