Home > hfrc > matlab > @HFRC > radials2totals.m

radials2totals

PURPOSE ^

RADIALS2TOTALS - generates total vector maps from several radial HFRC

SYNOPSIS ^

function h = radials2totals( varargin )

DESCRIPTION ^

 RADIALS2TOTALS - generates total vector maps from several radial HFRC
 objects.

 Usage: hfrc_totals = radials2totals( hfrc_rads1, hfrc_rads2, ...
                                      hfrc_radsN, PARAM1, VAL1, ... )

 This function uses the same basic method as in the HFRadarmap toolbox
 of Mike Cook.  It produces virtually identical results, except for
 occasional grid points.  This is probably due to subtle differences in
 the use of spatial and temporal windows.  In any case, my experience is
 that the differences affect fewer than %5 of the data.

 This routine will produce Mapping Errors and fitDif, but it will also
 produce U_error, V_error and covariances as CODAR's own method does.

 Best to have a lot of memory for this function to work swiftly.  It has
 been optimized for large radial data sets, but some fiddling or data
 preparation could be useful in individual cases.  FOR EXAMPLE, consider
 removing large radial speeds previously.  Also, remove useless grid points
 (both from radials and eventual totals) and make radial HFRC objects full
 before starting function.

 As many radial HFRC objects as desired may be given.  Each one will be
 assumed to be from a different site.

 This function will return the number of radials contributed by each
 site, even for those time-space points where data did not make the cuts
 for one reason or another (not enough sites for example).

 gridflag is used in the resulting hfrc object to identify why the point
 was rejected.  Codes are as follows:

 -1 = too few sites
 -10 = too few radials
 -100 = too fast a total current
 -1e3 = too great a mapping error
 -1e4 = produced inf or nan
 -1e5 = produced an imaginary result

 Occasionally, you will see sums of these.

 Their are many possible parameter/value pairs that can be specified.
 Some are mandatory, some are not.

 MANDATORY:

 totalGrid - 2 column vector with lon-lat coords. of grid.
 matlab_time - vector of times for total vector maps in matlab units.
 spatial_window - radius in KMS of area inside of which radial vectors
                  are considered for generating total vector at grid
                  point. 
 temporal_window - number indicating window of time to use around each
                   matlab_time - radial maps inside that window are used
                   to generate total vectors for that map.  This should
                   be in fractions of a day.
 
 OPTIONAL:

 minSites - defaults to 2.
 minRadials - defaults to 3.
 rad_max - maximum radial current.  Infinite if not given.
 cur_max - max total current
 err_max - max mapping error
 site - name of site.  Defaults to 'BML' if not given.
 creator - person generating totals.  Default: 'DMK'
 institution - Default: 'UCDavis'.
 radSiteNames - If these are found in radial HFRC objects, those will be
                used.  Otherwise, they can be specified here.
 radSitePositions - Again, if in radial objects, will be used.
                    Otherwise, can be specified here.
 sparseHFRC - Boolean.  If true, will try to sparse the HFRC
              object. Default is false.
 verbosity - how often to spit out something about state of processing.
             The higher the number, the less is spit out.  -1 for nothing.
             Defaults to 24, i.e. report every 24 timesteps.

 NOTE: This function has a fundamental problem with radial vectors of zero
 velocity.  First of all, as 0's are used to indicate bad data, truly zero
 velocities will be ignored.  Therefore, zero must be replaced by something
 nearly zero.  In this case, make sure to replace zero radial velocities
 with a very small vector that points in the direction towards the radial
 site, as is done automatically in RUV2hfrc.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

     $Id: radials2totals.m,v 1.17 2006-12-05 18:09:51 dmk Exp $    

 Copyright (C) 2001 David M. Kaplan
 Licence: GPL

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:
Generated on Mon 18-Dec-2006 07:26:46 by m2html © 2003