Merge pull request #63 from Coastal-Imaging-Research-Network/version-2.0

Version 2.0

Contents.m

@@ -1,9 +1,9 @@
-% cBathy - routines to estimate k-alpha and bathy from pixel data
-%             - mostly renamed from old beachWizard
+% cBathy-Toolbox-1.3 - Estimate k-alpha and bathy from pixel data
 %
 % Batch Routines
 %   cBathyBatch         - executes cBathy for a range of days
 %   analyzeSingleBathyRun - batch analysis for a single stackName
+%   analyzeSingleBathyRunFrommBW - batch from an mBW stack in cx
 %   SETTINGS            - contains the params setting for each site
 %
 % Stack Routines: 
@@ -12,36 +12,37 @@
 % Analysis Routines:
 %   analyzeBathyCollect - single run cBathy analysis (parallel)
 %   prepBathyInput      - prepare inputs for analysis
-%   subBathyProcess     - wrapper to extract and process an analysis point
 %   csmInvertKAlpha     - main cBathy inversion routine for k-alpha
 %   bathyFromKAlpha     - nonlinear solver for bathy from k-alpha
+%   fixBathyTide        - adjust depth estimates for tide.
+%   prepareTiles        - find fs, vs, seeds for each tide
 %   predictCSM          - xspectral matrix forward model for solver
-%   findKAlphaPhiInit   - seed for nonlinear solver 
+%   findKAlphaSeed      - seed for nonlinear solver 
 %   kInvertDepthModel   - used for bathy solver
+%   bathyCI 		- modified version of nlparci for cBathy
 %
 % Kalman Filtering:
 %   makeKalmanBathySeed - initialize the first run for K-filtering
 %   runningFilterBathy  - wrapper to Kalman filter a sequence of runs
 %   KalmanFilterBathy   - core Kalman filter routine
 %   findProcessError    - compute sensible process error
 %
-% Debugging and viewing
+% Debugging and viewing cBathy components
 %   plotStacksAndPhaseMaps  - debugMode displays for whole collect
 %   listfDependentResultsForOnePoint - debugMode listing of fDependents
 %   examineSingleBathyResult- display all variables for any bathy
-%   plotBathyCollectSDS     - images of a single bathy and errors
+%   plotBathyCollect        - images of a single bathy and errors
 %   plotBathyCollectKalman  - images of a Kalman-ed bathy and error
 %   showHourlyBathyResults  - loop through a bathy sequence
 %   showHourlyKalmanResults - loop through smooth sequence
 %   plotBathyKalmanStep     - steps through runs showing all debug info
-%   findInterpMap           - calculate the map for interpolating 
-%                             from irregular spaced stack data to
-%                             regular spaced image coords, using knnsearch
-%                             and returning N neighbors and weights
-%   useInterpMap            - use the interp map from findInterpMap
+%   alterAnalysisArray 	    - allow change to the xm-ym values for debugging
+%
+% Viewing the cBathy Stack Data
 %   showcBathyTimeSeriesMovie - display a sequence of cBathy "frames"
-%   showWaveVarianceMap      - show wave information visually
-%   
+%   findInterpMap             - find mapping from pixels to regular map 
+%   useInterpMap              - use the interp map from findInterpMap
+%   showWaveVarianceMap       - show wave information visually
 
 %
 %   Copyright (C) 2017  Coastal Imaging Research Network

KalmanFilterBathy.m

@@ -15,7 +15,7 @@
 dt = (str2num(newBathy.epoch) - str2num(priorBathy.epoch)) / (24*3600);  % in days
 foo = parseFilename(priorBathy.sName);
 Q = findProcessError(foo.station, newBathy, H)*dt;
-P = nansum(cat(3, priorBathy.runningAverage.P, Q),3);
+P = sum(cat(3, priorBathy.runningAverage.P, Q),3,'omitnan');
 
 % update everywhere then fix the nan problems in prior or new
 K = P ./ (P + newBathy.fCombined.hErr.^2);

README.md

@@ -1,83 +1,30 @@
-# cBathy-Rob
- README for cBathy
-
-When you type 'help {toolboxName}' where you insert your own toolbox
-name, will give the Contents of the toolbox.
-
-The outline below shows the order of how analysis routines are called.
-
-This toolbox has been extacted from the full CIL version and SHOULD work
-on a standalone basis.  In doing this, a number of checks have been removed
-since these depend on CIL databases and standards.
-
-Two demo files are provided as well as example data.  'democBathy' runs
-the main cBathy processing to create phase 1 and 2 results (fDependent
-and fCombined) and plots the results.  This is currently set to analyze 
-a test data set, testStack102210Duck.mat, one used in the original cBathy 
-paper in 2013.  'demoKalmanFiltering' takes an
-example day of cBathy results and performs Kalman filtering, then plots
-the results.  The set cBathy input data is constained  the folder 
-102210cBathys and is again from an example from the 2013 paper.
-NOTE that the results for the Kalman demo are stored in a
-different location, simply for demo purposes (since many people may end
-up using the toolbox).  Normally you would save the results back to the
-input file location but now with the runningAverage field filled in. 
-For comparison, the CRAB survey from three days prior is included in the 
-file 19-Oct-2010FRFGridded.mat.
-
-The first part (democBathy) needs only the stack information and the
-tide, although if the tide is not found the routine should continue but
-leave nans in the tide fields.  The Kalman stage needs a process error
-routine specific to your site (findProcessError) and this usually needs
-the wave height, H.  Adequate results can be found by guessing H, for
-instance H = 1 m in this demo.  It makes no sense to Kalman filter if you
-have not removed the tide (averaging a non-stationary signal).  The
-toolbox contains a routine doKal.m which is a CIL version, included only to
-illustrate the steps that we normally take.  Note the use of fixBathyTide
-in Kalman filtering to make sure the tide has been compensated for.  If
-tide has been fixed in a previous step, this routine will do no harm.
-
-Note that the supplied example tide routine, fixBathyTide, is a CIL
-routine that normally looks for two input arguments, the first of which
-is the station name that we extract from the stack name (to ensure that
-you can't possibly call the tide routine for an incorrect station).  If
-the stack name is not standard, the routine will assume that this is not
-a CIL station and will fall back to a single input argument version
-(time), leaving the user responsible for chosing the correct tide
-location.  
-
-Please let us know if problems arise
-[HERE](https://github.com/Coastal-Imaging-Research-Network/cBathy-Toolbox/issues)
-
-
-
-Logicial Outline for analyzeBathyCollect version 2
-
-- no tiles, each x,y done independently
-- ie., csmInvertKAlpha does one x,y at a time, returns only fDependent
-
-```
-analyzeBathyCollect
-input:  xyz, epoch, data  (data from stacks), bathy (with params)
-output: bathy  (final results)
-
-prepBathyInput( xyz, epoch, data, bathy )
-output: f, G, bathy with empty data, allx, ally
-
-parfor loop on allx, ally
-
-subBathyProcess( f, G, xyz, ax, ay, params )
-output: fDependent
-
-spatialLimitBathy( f, G, xyz, params, ax, ay )
-output: subG, subxyz
-
-csmInvertKAlpha( f, subG, subxyz, ax, ay, params )
-output: fDependent
-
-stuff fDependent back into main bathy
-
-end parfor
-
-convert bathy fDependent to final output
-```
+# cBathy-2.0
+ README for cBathy
+
+When you type 'help {toolboxName}' where you insert your own toolbox
+name, will give the Contents of the toolbox.
+
+The outline below shows the order of how analysis routines are called.
+
+Note: Version 2.0 requires Matlab 2016a or newer.
+
+This toolbox has been extracted from the full CIL version and SHOULD work on a standalone basis.  In doing this, a number of checks have been removed since these depend on CIL databases and standards.
+
+One demo file is provided along with example data.
+'democBathyVersion2p0' runs the main cBathy processing to create phase 1 and 2 results (fDependent and fCombined) and plots the bathymetry results in fCombined.  This is currently set to analyze 
+a test data set, 1447691340.Mon.Nov.16_16_29_00.GMT.2015.argus02b.cx.mBW.mat, one of the new standard testbed datat sets created by OSU.  The cBathy input data is contained the subfolder 
+DemoData along with the sample bathymetry output. The demo produces and saves the bathymetry information estimated by cBathy into a new folder.
+
+The demo needs only the single time stack file information to run, although if tide information is found the routine should propogate the tide fields.  The Kalman stage needs a process error routine specific to your site (findProcessError) and this usually needs the wave height, H. Adequate results can be found by guessing H, for  instance H = 1 m in this demo.  It makes no sense to Kalman filter if you have not removed the tide (averaging a non-stationary signal).  The toolbox contains a routine doKal.m which is a CIL version, included only to illustrate the steps that we normally take.  Note the use of fixBathyTide in Kalman filtering to make sure the tide has been compensated for.  If tide has been fixed in a previous step, this routine will do no harm.
+
+Note that the supplied example tide routine, fixBathyTide, is a CIL
+routine that normally looks for two input arguments, the first of which is the station name that we extract from the stack name (to ensure that you can't possibly call the tide routine for an incorrect station).  If the stack name is not standard, the routine will assume that this is not a CIL station and will fall back to a single input argument version (time), leaving the user responsible for chosing the correct tide location.  
+
+Please let us know if problems arise
+[HERE](https://github.com/Coastal-Imaging-Research-Network/cBathy-Toolbox/issues)
+
+
+
+Logicial Outline for analyzeBathyCollect version 2
+
+![alt text](https://github.com/Coastal-Imaging-Research-Network/cBathy-Toolbox/blob/version-2.0/manual/versionOrgCharts.png?raw=true)

SampleParametersFile.m

@@ -0,0 +1,71 @@
+%%% Sample Inputs file. This file should be used as a template for the
+%%% parameters used in cBathy.
+%%%
+%%% *** Important Note on Usage: *** 
+%%% Before using the sample parameters, copy this file to a file named
+%%% after the station. The name of this file should be the name of the
+%%% station being processed, and it will appear in some of the output
+%%% products.
+%%% When you call analyzeBathyCollect, you will need to input the name of
+%%% the parameters file which will be evaluated to load these parameters
+%%% and may appear in some of the output products in titles/axis labels and
+%%% file names. 
+
+%%% Site-specific Inputs
+params.stationStr = 'SampleParametersFile';
+params.dxm = 10;                    % analysis domain spacing in x
+params.dym = 25;                    % analysis domain spacing in y
+params.xyMinMax = [80 800 -500 1500];   % min, max of x, then y
+                                    % default to [] for cBathy to choose
+params.tideFunction = 'cBathyTide';  % tide level function for eval
+
+%%%%%%%   Power user settings from here down   %%%%%%%
+params.MINDEPTH = 0.25;             % for initialization and final QC
+params.QTOL = 0.5;                  % reject skill below this in csm
+params.minLam = 10;                 % min normalized eigenvalue to proceed
+params.Lx = 3*params.dxm;           % tomographic domain smoothing
+params.Ly = 3*params.dym;           % 
+params.kappa0 = 2;                  % increase in smoothing at outer xm
+params.DECIMATE = 1;                % decimate pixels to reduce work load.
+params.maxNPix = 80;                % max num pixels per tile (decimate excess)
+params.minValsForBathyEst = 4;      % need this many pixels to solve
+params.shortLengthNFreqs = 4;       % need this many for coherence sorting
+                                    % versus magnitude shorting
+
+% f-domain etc.
+params.fB = [1/18: 1/50: 1/4];		% frequencies for analysis (~40 dof)
+params.nKeep = 4;                   % number of frequencies to keep
+
+% debugging options
+params.debug.production = 1; % this should be ZERO in DEBUG MODE!
+params.debug.DOPLOTSTACKANDPHASEMAPS = 1;  % top level debug of phase
+params.debug.DOSHOWPROGRESS = 1;		  % show progress of tiles
+params.debug.DOPLOTPHASETILE = 1;		  % observed and EOF results per pt
+params.debug.TRANSECTX = 200;		  % for plotStacksAndPhaseMaps
+params.debug.TRANSECTY = 900;		  % for plotStacksAndPhaseMaps
+
+% default offshore wave angle.  For search seeds.
+params.offshoreRadCCWFromx = 0;
+
+params.nlinfit = 1; % flag, 0 = use LMFnlsq.m to do non-linear fitting
+
+
+%
+% Copyright by Oregon State University, 2011
+% Developed through collaborative effort of the Argus Users Group
+% For official use by the Argus Users Group or other licensed activities.
+%
+% $Id: argus02b.m,v 1.2 2016/04/11 23:06:10 stanley Exp $
+%
+% $Log: argus02b.m,v $
+% Revision 1.2  2016/04/11 23:06:10  stanley
+% Fix MAXDEPTH
+%
+% Revision 1.1  2012/09/24 23:36:32  stanley
+% Initial revision
+%
+%
+%key 
+%comment  
+%
+params.minValsForBathyEst = 4;