Good documentation for all user functinos

1. File IO/Functions/metaGridfile.m

@@ -9,7 +9,7 @@
 %
 % ----- Outputs -----
 %
-% meta: The metadata structure for the girdded .mat file.
+% meta: The metadata structure for the gridded .mat file.
 %
 % dimID: The order of the dimensions of the saved gridded data.
 %

2. Design State Vector/Functions/addVariable.m

@@ -13,9 +13,7 @@
 %
 % file: The name of the gridfile containing data for the variable.
 %
-% name: A name for the variable
-%
-% couple: A flag that specifies whether to couple the variable by default.'couple','nocouple'
+% name: A name for the variable. Must be a string.
 %
 % ----- Outputs -----
 %

2. Design State Vector/Functions/copyIndices.m

@@ -9,7 +9,8 @@
 %
 % design: A state vector design
 %
-% fromVar: The template variable
+% fromVar: The template variable. The indices in the template variable will
+%       be copied into the other variables.
 %
 % toVars: The variables into which indices will be copied.
 %

3. Build Ensemble/Functions/addToEnsemble.m

@@ -1,7 +1,18 @@
 function[] = addToEnsemble( file, nNew )
-%% Adds additional ensemble members to a prior model ensemble.
+%% Adds additional ensemble members to a previously built ensemble. Will
+% only select new ensemble members -- does not allow repeat draws.
 %
 % addToEnsemble( file, nNew )
+%
+% ----- Inputs -----
+%
+% file: The name of the .ens file containing the ensemble that should be
+%       given additional ensemble members.
+%
+% nNew: The number of new ensemble members to add.
+
+% ----- Written By -----
+% Jonathan King, University of Arizona, 2019
 
 % Error check the file. Get a matfile object
 m = ensFileCheck( file, 'write' );

3. Build Ensemble/Functions/buildEnsemble.m

@@ -1,15 +1,17 @@
 function[] = buildEnsemble( design, nEns, file )
-%% Builds an ensemble from a state vector design
+%% Builds an ensemble from a state vector design and writes it to a .ens file.
 %
-% buildEnsemble( design, nEns )
-% Builds a prior model ensemble.
-% 
+% buildEnsemble( design, nEns, file )
+% Builds a model ensemble. This is the prior for data assimilation.
 %
 % ----- Inputs -----
 %
 % design: A state vector design
 %
-% nEns: The number of ensemble members
+% nEns: The number of ensemble members desired
+%
+% file: The name of the file into which the model ensemble should be written.
+%       Must end with a ".ens" extension.
 %
 % ----- Outputs -----
 %

3. Build Ensemble/Functions/loadEnsembleMeta.m

@@ -5,7 +5,21 @@
 %
 % ----- Inputs -----
 %
-% file: a .ens file (created by "buildEnsemble.m")
+% file: a .ens file containing a model ensemble.
+%
+% ----- Outputs -----
+%
+% ensMeta: Metadata for the ensemble. This is a structure with a field for
+%          each dimension. Each dimension consists of a (nState x 1) cell
+%          containing the dimensional metadata for each state element.
+%
+% design: The stateDesign object associated with the ensemble.
+%
+% ensSize: The size of the ensemble.
+
+% ----- Written By -----
+% Jonathan King, University of Arizona, 2019
+
 
 % Check for .ens file. Get matfile object.
 m = ensFileCheck(file, 'load');

5. Data Assimilation/Functions/covLocalization.m

@@ -1,16 +1,22 @@
 function[weights, yloc] = covLocalization( siteCoord, ensMeta, R, scale)
 %% Calculates the weights for covariance localization at a site.
-% 
-% weights = covLocalization( siteCoord, stateCoord, R )
-% Creates a covariance localization with a cutoff radius R. Based on a
-% Gaspari-Cohn function.
 %
-% weights = covLocalization( siteCoord, stateCoord, R, 'optimal')
-% Uses an optimal length scale of sqrt(10/3) for the localization radius
-% based on Lorenc, 2003.
+% [w, yloc] = covLocalization( siteCoord, ensMeta, R )
+% Calculates covariance localization weights based on site coordinates and
+% ensemble metadata. Does not localize spatial means.
+%
+% [w, yloc] = covLocalization( siteCoord, stateCoord, R )
+% Calculates covariance localization weights based on user-defined state
+% vector coordinates.
+%
+% covLocalization( ..., scale )
+% Specifies the length scale to use for the localization weights. This
+% adjusts how quickly localization weights decrease as they approach the
+% cutoff radius. Must be a scalar on the interval (0, 0.5]. Default is 0.5.
+%
+% covLocalization( ..., 'optimal' )
+% Uses the optimal length scale of sqrt(10/3) based on Lorenc, 2003.
 %
-% weights = covLocalization( siteCoord, stateCoord, R, scale)
-% User specified length scale. Scale must be a scalar on the interval (0, 0.5].
 %
 % ***** Explanation of length scales and R
 %
@@ -29,11 +35,15 @@
 %
 % ----- Inputs -----
 % 
-% site: The set of site coordinates, latitude x longitude. (nObs x 2)
+% siteCoord: The set of observation site coordinates. A two-column matrix. First column
+%            is latitude, second is longitude. Supports both 0-360 and 
+%            -180 to 180 longitude coordinates. (nObs x 2)
 %
-% coords: The ensemble metadata, latitude x longitude.
-%         Non-localizable state variables (e.g. spatial means) should use NaN
-%         coordinates to prevent localization.  (nState x 2)
+% ensMeta: A set of ensemble metadata.
+% 
+% stateCoord: A set of user defined state coordinates. A two column matrix:
+%     first column is latitude, second is longitude. Supports both 0-360 and
+%     180 to -180 longitude coordinates.
 %
 % R: The cutoff radius. All covariance outside of this radius will be
 %    eliminated.
@@ -44,7 +54,10 @@
 %
 % ----- Outputs -----
 %
-% weights: The localization weights for each site. (nState x nObs)
+% w: The localization weights between each site and each state vector element. (nState x nObs)
+%
+% yloc: The localization weights between the observations sites. (Required
+%       localization with a joint update scheme. (nObs x nObs)
 
 % ----- Sources -----
 % 
@@ -60,6 +73,13 @@
 % Arizona, 08 Nov 2018.
 %
 % Modified to included variable/optimal length scales by Jonathan King.
+%
+% Y localization weights by Jonathan King
+
+% Check that the site coordinates are a 2 column matirx
+if ~ismatrix(siteCoord) || size(siteCoord,2) ~= 2
+    error('Site coordinates must be a two column matrix.');
+end
 
 % If ensemble metadata, get the lat-lon metadata
 if isstruct( ensMeta )

5. Data Assimilation/Functions/dash.m

@@ -43,28 +43,30 @@
 %
 % w: Model-estimate covariance localization weights. Applied to the Kalman
 %    numerator. Required for localization in both serial and joint update
-%    schemes. (nState x nObs)
+%    schemes. See the covLocalization.m function. (nState x nObs)
 %
 % yloc: Estimate-estimate covariance localization weights. Applied to the
 %       Kalman denominator. Only required for localization with a joint
-%       update scheme. (nObs x nObs)
+%       update scheme. See the covLocalization.m function. (nObs x nObs)
 %
 % ----- Outputs -----
 %
-% Amean: Update analysis mean. (nState x nTime).
+% Amean: Updated ensemble mean. (nState x nTime).
 %
-% Avar: Update analysis variance (nState x nTime).
+% Avar: Update ensemble variance (nState x nTime).
 %
 % Ye: Model estimates.
-%       serial DA: (nObs x nEns x nTime)
 %       joint DA: (nObs x nEns)
-% 
-% Yi: The initial model estimate for the appended Ye method. (nObs x nEns)
+%       serial DA: (nObs x nEns x nTime)
+%       *** Note that serial appended DA returns the Ye values actually
+%       used to update the ensemble, which will differ from the initial and
+%       final Ye estimates. ***
 %
-% Yu: The model estimate used to update each time step for the appended Ye
-%     method. (nObs x nEns x nTime)
+% R: The R values used to update the ensemble. Includes R values
+%    dynamically generated by PSMs. (nObs x nTime)
 %
-% Yf: The final model estimate for each time step. (nObs x nEns x nTime)
+% update: A boolean array indicating which observations were used to update
+%         each time step. (nObs x nTime)
 
 % ----- Written By -----
 % Jonathan King, University of Arizona, 2019
@@ -75,8 +77,9 @@
 [serial, append, inflate, localize, meanOnly] = parseInputs( varargin, {'serial','append','inflate','localize','meanOnly'}, ...
                                                            {false, false, 1, [], []}, {[],[],[],[],[]} );
 
-% Error check. Get w and yloc if unspecified.
-[w, yloc] = setup( M, D, R, F, inflate, localize, serial, append, meanOnly );
+% Error check. Get default inflation and covariance localization if
+% unspecified
+[inflate, w, yloc] = setup( M, D, R, F, inflate, localize, serial, append, meanOnly );
 
 % Apply the inflation factor
 M = inflateEnsemble( inflate, M );
@@ -100,7 +103,8 @@
 
 end
 
-function[w, yloc] = setup( M, D, R, F, inflate, localize, serial, append, meanOnly )
+%% Error checking and default values
+function[inflate, w, yloc] = setup( M, D, R, F, inflate, localize, serial, append, meanOnly )
 
 % Check that M is a matrix of real, numeric value without NaN or Inf
 if ~ismatrix(M) || ~isreal(M) || ~isnumeric(M) || any(isinf(M(:))) || any(isnan(M(:)))
@@ -163,7 +167,9 @@
 %% Inflation
 
 % Inflation factor
-if ~isscalar(inflate) || inflate<=0 || isinf(inflate) || isnan(inflate) || ~isnumeric(inflate)
+if isempty(inflate)
+    inflate = 1;
+elseif ~isscalar(inflate) || inflate<=0 || isinf(inflate) || isnan(inflate) || ~isnumeric(inflate)
     error('The inflation factor must be a scalar greater than 0. It must be real, numeric, finite and not NaN.');
 end
 

5. Data Assimilation/Functions/regridAnalysis.m

@@ -9,19 +9,22 @@
 %
 % ----- Inputs -----
 %
-% A: The mean or variance state vector from a particular time step of an
-%   udpate analysis. (nState x 1)
+% A: A state vector. Typically, the updated ensemble mean or variance (nState x 1).
 %
 % var: The name of a variable. Must be a string.
 %
-% ensMeta: Ensemble metadata
+% ensMeta: The ensemble metadata
 %
 % design: A state vector design.
 %
 % ----- Outputs -----
+%
 % rA: A regridded analysis for one variable.
 %
-% dimID: The dimensional ordering of the regridded variable.
+% dimID: The order of the dimensions for the regridded variable.
+
+% ----- Written By -----
+% Jonathan King, University of Arizona, 2019
 
 % Check for nosqueeze
 nosqueeze = parseInputs( varargin, {'nosqueeze'}, {false}, {'b'} );

5. Data Assimilation/Functions/regridTripolar.m

@@ -9,25 +9,26 @@
 %
 % ----- Inputs -----
 %
-% A: The mean or variance state vector from a particular time step of an
-%   udpate analysis. (nState x 1)
+% A: A state vector. Typically the updated ensemble mean or variance. (nState x 1)
 %
 % var: The name of a variable. Must be a string.
 %
 % ensMeta: Ensemble metadata
 %
-% design: A state vector design.
+% design: The state vector design for this analysis.
 %
 % ocnDex: A set of logical indices that point to non-nan indices on a
-% tripolar grid. (nTripole x 1)
+% tripolar grid. Typically, the indices of ocean grid nodes. (nTripole x 1)
 %
 % gridSize: size of the original tripolar grid. (2 x 1)
 %
 % ----- Outputs -----
 %
 % rA: A regridded analysis for one variable.
 %
-% dimID: The dimensional ordering of the regridded variable.
+% dimID: The dimensional ordering of the regridded variable. Tri1 and tri2
+%        are the first and second dimensions associated with the original
+%        tripolar grid.
 
 % ----- Written by -----
 % Jonathan King, University of Arizona, 2019

5. Data Assimilation/Utilities/Ensrf/jointENSRF.m

@@ -40,17 +40,17 @@
 Knum = jointKalman( 'Knum', Mdev, Ydev, w );
 
 % For each time step
-for t = 1:nTime
+parfor t = 1:nTime
 
     % Update using obs that are not NaN
     update(:,t) = update(:,t) & ~isnan( D(:,t) );
     obs = update(:,t);
 
     % Get the full kalman gain and kalman denominator
-    [K, Kdenom] = jointKalman( 'K', Knum(:,obs), Ydev(obs,:), yloc(obs,obs), R(obs,t) );
+    [K, Kdenom] = jointKalman( 'K', Knum(:,obs), Ydev(obs,:), yloc(obs,obs), R(obs,t) ); %#ok<PFBNS>
 
     % Update the mean
-    Amean(:,t) = Mmean + K * ( D(obs,t) - Ymean(obs) );
+    Amean(:,t) = Mmean + K * ( D(obs,t) - Ymean(obs) ); %#ok<PFBNS>
     K = [];   %#ok<NASGU>  (Free up memory)
 
     % If returning variance
@@ -60,7 +60,7 @@
         Ka = jointKalman( 'Ka', Knum(:,obs), Kdenom, R(obs,t) );
 
         % Update the deviations and get the variance
-        Avar(:,t) = var(   Mdev - Ka * Ydev(obs,:),   0, 2 ); %#ok<AGROW>
+        Avar(:,t) = var(   Mdev - Ka * Ydev(obs,:),   0, 2 );
     end
 end
 

5. Data Assimilation/Utilities/Ensrf/serialENSRF.m

@@ -22,9 +22,11 @@
 %
 % ----- Outputs -----
 %
-% A: The mean and variance of the analysis ensemble. (nState x nTime x 2)
+% Amean: Updated ensemble mean (nState x nTime)
 %
-% Y: The model estimates used for each update. (nObs x nEns x nTime)
+% Avar: Updated ensemble variance (nState x nTime)
+%
+% Ye: Proxy estimates. (nObs x nEns x nTime)
 
 % ----- Written By -----
 % Jonathan King, University of Arizona, 2019