documentation.txt 7.07 KB
======================================================================
=====  DOCUMENTATION for coastal drifter quality control tool   ======
======================================================================

Oceanographic drifter GPS data collected from coastal areas can be 
messy, and heterogenous. The purpose of this tool is to efficiently 
process drifter tracks which may contain several instances of beaching,
missing pings, irregular pings and inland data, using an interactive
GUI based approach so you can see what you are doing while you work.

Upon output, several useful parameters are also calculated. The cleaned
.mat files are contain  u, v, normed speed, heading, depth bellow, sea 
level and time after high tide. The latter two are only calculated if 
bathymetric and tidal have been provided.

The software was written and tested with matlab version R2016b under the
student license. It will run into problems with earlier versions but 
should run on later ones.

Other than the very useful  m_lldist.m  function which is from Rich
Pawlowicz's m_map package and which he owns, all software is written 
by Jean-Luc Shaw in 2018. You can freely use and distribute but you can
not sell it.

Feel free to contact me if you have any questions. 

Jean-Luc Shaw, M Sc student in physical oceanography
jean-luc.shaw@uqar.ca


Repository link:

git@gitlasso.uqar.ca:shaj0004/Coastal-drifter-deployment-cleanup-utility.git



=====                       WORKFLOW                            =====

First, your directory tree should be set up as follows:

-GUI_drifter_cleanup
--data
---bathy
---gps
----clean
----raw
--lib
--log
--tools

Next copy your unprocessed gps drifter tracks to the 'raw' folder. 
Your raw files need to be structures stored in '.mat' files. The 
structure needs to be named 'data' and have the following fields:

data.lon   : longitude vector 
data.lat   : latitude  vector
data.timeM : time in matlab format (fraction of day)

Obviously they all need to be of same length. You can now copy 
bathymetric data and tide data respectively to the bathy and tide
folders. While this is optionnal certain functions of the software
will require them to run.
    The bathymetry file should be a scatteredInterpolant or
triscatteredInterp object stored in a '.mat' file and built using 
depth positive towards the sea floor and a geographical grid in 
latitude and longitude coordinates.
    The tide file should be a matlab structure stored in a '.mat'
file and contain the following fields. It may be called anything, but
assuming it would be called 'T':

T.dnum     : time in matlab format ( fraction of day )
T.nm       : local sea level (m)
T.time_AHT : time after high tide (h)


Now all the required files are in place and you may launch the utility
by running GUI_drifter_cleanup.m . You may then use the following 
sequence of operations as guidelines to quality control of your data.

1  - Select a drifter file from the popup menu
2  - Select a bathymetry file from the popup menu (optionnal)
3  - Select a tide file from the popup menu (optionnal)
4  - Adjust the indexes I0 and If to browse through the file
5  - Toggle the auxilliary data view to spot bad data
6  - Delete bad data
7  - Find a good looking section of the track
8  - Filter inland data (optionnal)
9  - Get the track time step
10 - Reinterpolate on a regular time grid
11 - Punch this cleaned section out to a mat file
12 - Repeat from step 4 until all good data has been exported
13 - Do science ... !


NOTE !! : If you have loaded bathymetry and tide files, they are still
    active when you load a new gps file! Depths are recalculated auto-
    matically for the new gps data, and tide will be updated as well,
    but if the bathymetry or tide file does not have a value for the 
    new coordinates or time values, you need to load appropriate bathy-
    metric or tidal data or else you will run into issues! You can also
    clear the bathymetry or tide file by selecting the empty string from
    the file menu.


=====                   FUNCTION DESCRIPTION                    =====

RANGE (I0 and If) : 

    The I0 and If are index values of the raw data vector. They select
which portion of the raw data will display in both the geographical
track and auxilliary data monitors as well as the portion of the raw
data vector which will be operated on. Let's call data points corres-
ponding to indexes I0 to If inclusively the 'active data'. 

DELETE :

    Removes the active data from the working data structure BUT does 
not touch the raw data file! It zooms out to full view making I0 and
If the first and last index values of the working data structure.

UNDO :

    Reloads the selected raw data file, reads the operation log, and
chronologically applies the operation history up to last operation 
exclusively. This way, only the last applied operation is undone.

FILTER z < X :

    Uses the loaded bathymetry to locate elements of the active data
which are in water shallower than X, and deletes them from the working
data structure BUT not from the raw data file.

GET TIME STEP :
    
    Computes the median time between pings from the active data. Displays
it in the adjacent field and in the interpolation step field for con-
venience.

INTERPOLATE :

    Interpolates the active data on a regular time grid, deletes the
active data from the working data structure, and replaces it with the 
interpolated data. The value of the adjacent field in seconds is used 
as the new time step. In matlab's synthax, the new time grid is :

                time_wds(I0):step:time_wds(If)

PUNCH OUT :

    Computes u, v, speed, heading, water depth*, local sea level*, and 
time after high tide*, for the active data, exports it to a '.mat' file
in the data/gps/clean directory, and removes the active data from the
working data structure. The output 'clean' matfile is named the following
way:

                    raw-input-file-name_XXX.mat

where Xs are integers. The number XXX will be 000 the first time the 
PUNCH OUT function is used and be incremented every following time,
producing a sequence of cleaned data tracks stored in independent '.mat'
files for every raw input file analysed.

    The two radio buttons adjacent to the punch out button provide with
the option to flag element I0 as the first data point after deployment,
and element If as the last recorded data point from this deployment. They
are optionnal and not mutually exclusive.

OPERATION LOG :

    Operations DELETE, FILTER Z > X, INTERPOLATE, and PUNCH OUT are 
logged to a file created automatically in the log directory. This 
file is name the same as the selected gps input file but appended with 
the extension '.log' .
    The log entries contain the name of the operation applied, the I0 and
If values, a parameter value, and the new size of the working data struc-
ture. For the different operations prameter definition varies:

    Delete      : parameter = nan
    Filter      : parameter = minimum water depth
    Interpolate : parameter = interpolation time step in seconds
    Output      : parameter = sequential number of the punch (XXX)

======================================================================