DASH v4.2.2

Summary

This release links DASH to Zenodo to provide the repository with a DOI.

DASH v4.2.1

Summary

This patch fixes a bug that could cause gridfile.load to crash when loading data with a single dimension. It also adds citation information to the docs.

Details

1. Citation information
   Is now provided in the README, and as a resource in the docs.

2. gridfile.loadInternal
   Updated to add handling for permuting/reshaping loaded source data with a single dimension.

3. dash.stateVectorVariable.loadMembers
   Updated to add handling when reshaping raw data with a single dimension.

DASH v4.2.0

Summary

This release provides fixes for a few minor bugs. It also adds a showcase to the documentation and improves the convenience of calculating Gaspari-Cohn localization weights.

Details

Additions

1. Showcase
   Added a showcase to the documentation. This includes citations and summaries of published papers that rely on DASH. It also links to the DOIs/preprints/codebases of those papers when available.

Improvements

1. dash.localize.gc1d, dash.localize.gc2d
   Changed the Gaspari-Cohn localization weight functions so that they return a weight of 1 (i.e. no localization) for sites with NaN coordinates. NaN coordinates are common when implementing spatial means, and this update removes the need for users to explicitly assign weights to state vector variables implementing such mean.

Fixes

1. svv.buildMembers
   Fixed an indexing bug that would occur when ALL the following conditions were met: (A) Multiple variables derived from the same gridfile, (B) data pre-loaded from source, (C) a sequence, mean, or total over an ensemble dimension, and (D) the minimum mean/sequence/total index not equal to 0. We believe this bug was unlikely to affect most users. It was most likely to occur when designing explicit state vector variables for each forward model, setting time as an ensemble dimension, and then implementing different seasonal windows for the forward model variables. If this describes your setup, consider re-running the code.

2. ensembleMetadata dimension typing
   Fixed a bug wherein ensembleMetadata would sometimes tag a spatial mean as a standard spatial variable. This could cause ensembleMetadata.latlon to sometimes return coordinates for spatial means (rather than NaN placeholders).

3. kalmanFilter.index('delete')
   Fixed a bug that would cause the kalmanFilter.index command to crash when attempting to remove an index from a kalmanFilter object.

DASH v4.1.0

Notice

If you are using the v4-beta-4 or v4.0.0 release, then you should update your code immediately. This update fixes a critical error in the calculation of covariance localization weights for those two releases. See "Fix 1" below for additional details.

Summary

This release includes:

• A fix for a recent error in the calculation of covariance localization weights
• A license
• Improvements to the BayMAG and BayFOX PSMs,
• Support for dimensionless scalar variables (such as climate model parameters)

as well as several other minor improvements.

Details

Fixes

1. Gaspari-Cohn localization weights
   On October 17, 2022 an error was introduced into the code for the Gaspari-Cohn polynomial (dash.math.gaspariCohn) that caused covariance localization weights to be calculated incorrectly. This error affects the v4.0.0-Beta-4 and v4.0.0 releases, but all previous releases calculated localization weights correctly. This new release corrects the error and returns the code to its original (correct) state. Users of the two affected releases should update their code immediately.

2. ensembleMetadata.remove
   The previous code did not remove variables from the stateType array, which could cause the latlon, closestLatLon, and regrid functions to crash in some cases.

Improvements

1. Added a License
   The toolbox now has a license (the MIT license). This can be found in the repository itself, as well as within the documentation resources.

2. Improved PSM.baymag
   Added options to allow the use of constant SST, SSS, omega, and/or pH values. Also updated the supported commit. The new commit includes functionality for calculating the seasonality of proxy sites.

3. Improved PSM.bayfox
   Added options to allow the use of constant d18Osw and/or SST values.

4. Support for dimensionless scalars
   Users may wish to assimilate dimensionless scalar variables (such as climate model parameters), but these can interact poorly with some native MATLAB functions (which assume all arrays have at least 2 dimensions). Added code to allow these variables within DASH. This includes the following changes when a dimensionless scalar is detected:

   • Removing start/count/stride inputs to ncread in dash.dataSource.nc
   • Skipping calls to permute and reshape in gridfile.loadInternal, and
   • Skipping a call to reshape in dash.stateVectorVariable.buildMembers

5. Infinite Localization Radii
   Updated dash.localize.gc1d and dash.localize.gc2d to allow infinite localization radii (i.e. the case of no localization). Users may find this helpful for conducting parameter sweeps.

6. ensembleMetadata.variableIndices
   The previous code used variable names (rather than indices) to test for duplicates. In some cases, this would require users to use double-quote input strings (single-quote strings would fail). The updated function permits both single-quote and double-quote strings.

Acknowledgements

Huge thanks to @mattosman for noting the two bugs and the lack of support for dimensionless scalars.

DASH v4.0.0

Woohoo! 🎉 😎

Summary

This release adds

• A tutorial,
• A number of new PSMs,
• The ability to implement totals (sums) across state vector dimensions,
• 1D covariance localization, and
• Improvements to the PSM interface

The release also includes a number of minor improvements and bug fixes.

Details

Major Additions

1. Tutorial
   The HTML pages in the DASH docs now include a tutorial and introduction to DASH.

2. PSM.identity
   Added an identity PSM. This built-in PSM returns input values directly as outputs without running any forward model.

3. PSM.pdsi
   Added a PSM that estimates the Palmer Drought-Severity Index.

4. PRYSM PSMs
   Added PSMs to implement several of the sensor modules from the PRYSM python package. Specifically, these are the cellulose, coral, and icecore sensor modules. (See PSM.prysm.cellulose, PSM.prysm.coral, and PSM.prysm.icecore). Also added instructions for setting up PRYSM to run within Matlab (See help PSM.prysm).

5. State vector totals
   Added the stateVector.total and stateVector.weightedTotal commands. These commands are similar to the stateVector.mean and stateVector.weightedMean commands, but they implement a sum total (rather than a mean) over the indicated dimensions. For example, these new commands can be used to compute total precipitation over a spatial field.

6. Covariance localization in 1D
   Added the dash.localize.gc1d function. This function allows users to calculate localization weights over a single dimension (such as height or depth). The outputs of this function can also be combined with 2D localization weights to implement localization over a 3D spatial array.

7. PSM.download
   Added an option for PSM.download to download the latest commit of an external code. Previously, users could only download the officially supported commit.

8. PSM memory
   Added PSM memory to the informational properties in the PSM interface. Users can now see whether a PSM maintains memory of previous time steps (and should thus use a time-ordered ensemble) when using the PSM.info method.

Minor changes

1. gridfile.new
   Users can now use strings (in addition to logicals) to select overwriting options.

2. dash.parse.nameValue
   Flag parsing is now case-insensitive.

3. PSM descriptions
   Fixed some minor typos in the PSM descriptions. (i.e. "Baysian" -> "Bayesian")

4. sv.variable
   Fixed a bug in the console display of detailed variable dimensions wherein weighted means were reported as standard means.

Acknowledgements

Many thanks to:

@kanchukaitis For the suggestion of state vector totals
@amrhein For suggesting the identity PSM, and 1D covariance localization
@PaleoLipidRR For noting the typos in the PSM descriptions, and
@sylvia-dee For providing validation data for the PRYSM PSMs

DASH v4.0.0 Beta 4

Summary

Various small improvements and fixes in preparation for the final beta testing.

Details

Improvements

1. Update BaySPLINE commit
   Updated the commit hash in PSM.bayspline. The updated forward model code (external of DASH) includes functionality to test proxy seasonality.

2. Improve linear PSM
   Update PSM.linear to implement the model using matrix algebra, rather than element-wise multiplication.

3. dash.doc
   Updated to accept single-quote input strings (in addition to double-quote strings).

4. dash.ensembleFilter.Rcovariance
   Updated to accept logical indices (in addition to linear indices).

5. stateVector.variableIndices
   The previous code used variable names (rather than indices) to test for duplicates. In some cases, this would require users to use double-quote input strings (single-quote strings would fail). The updated function permits both single-quote and double-quote strings.

Fixes

1. ensembleMetadata constructor
   Fixed a bug in the ensembleMetadata constructor that could prevent metadata from building when reference indices had a spacing larger than 1.

2. PSM.download cleanup
   Fixed a bug in PSM.download that could sometimes cause a successfully downloaded PSM to be deleted.

3. Calibration ratio for empty proxy networks
   Fixed a bug in kalmanFilter.run that could cause it to crash when attempting to calculate calibration ratios for an empty proxy network.

4. dash.math.gaspariCohn2D
   Fixed a typo in a variable name that would cause the function to crash.

5. ensembleMetadata.rows
   Updated the method to return NaN metadata when a user requests an allowed dimension, but none of the input variables have the dimension. Previously, the function would crash for this (admittedly rare) case.

DASH v4.0.0 Beta 3

Summary

This release provides a complete HTML documentation reference guide for the toolbox.

Details

1. This release includes a complete HTML reference guide for the toolbox. This reference guide is packaged directly with the toolbox, and is available offline. The HTML pages can be found in the doc folder of the toolbox.

2. The reference guide can be accessed using the dash.doc command. Enter dash.doc in the Matlab console to open the front page of the documentation. Alternatively, enter dash.doc("<item name>") to open the documentation for a specific class, function, method, or package in the toolbox. For example: dash.doc("gridfile") or dash.doc("stateVector.build")

3. The "Documentation Page" links in the help text are now fully functional. As an alternative to dash.doc, users can open the HTML documentation page for any item in the toolbox by entering: help <item name> in the console, and then clicking the "Documentation Page" link that appears at the end of the help text.

4. Updated the documentation builders (in doc_source/reST parsers) from a prototype to fully functional tool. Improvements include:
   A. Restructured and simplified the layout of the functions
   B. Checks that help text is correctly formatted
   C. Informative errors that link to the problem file
   D. Documented all functions
   E. Added support for struct outputs and multiple struct fields

Next Steps

This reference guide is the essential core of the DASH toolbox's documentation and represents a complete (albeit basic) documentation set. Future updates should work to make the toolbox more approachable to first time users. In particular, future updates should add:

1. Usage examples for all functions and methods, and
2. Tutorials / Demos / FAQ pages

to the documentation.

DASH v4.0.0 Beta 2

Summary

This update provides several bug fixes for the initial beta release. It is also the first release to provide a DASH.mltbx installation file.

Details

1. Fixed a bug that caused stateVector.build to fail when multiple variables were sourced from the same gridfile.
2. Fixed a bug wherein ensembleMetadata.closestLatLon would swap latitude and longitude coordinates.
3. Updated dash.math.haversine to account for numerical rounding errors that could cause the central angle to be slightly larger than 1.
4. This release includes the binary file: DASH-v4.0.0-beta-2.mltbx
   This binary file can be used to automatically install the DASH toolbox in a user's Matlab environment, and we recommend users download this installation file, rather than the raw source code.

Credits

Many thanks to Emily Judd for identifying the bugs.

DASH v4.0.0 Beta 1

This is the first beta release of DASH v4.0
The toolbox has been completely overhauled and is ready for initial user testing.

DASH v4.0.0 Alpha Test 5.0.6

Continued work on useVariables bug from 5.0.5. Fixed by requiring ensemble to load variables in a fixed order.