.. _python_pingdata_bottomtrack:

Bottom Tracking
-----------------


Part I: CODAS binaries
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use CODAS binaries to stage the data for bottom track
calibration calculation.  This has not changed since
the original Pindata demo.


(1) **lst_btrk**: Extract the bottom track velocity data within the
    specified time range(s) from a CODAS database into a text file.

    - edit ``lst_btrk.tmp`` (documented in ``lst_btrk.cnt``)

    - run  ``lst_btrk lst_btrk.tmp``
    - creates specified output file, eg. ``aship.btm``



(2) **refabsbt** Calculate ship displacement from both position data and
    bottom track velocity data in a CODAS ADCP database,
    averaged between consecutive fixes.

    - edit ``refabsbt.tmp`` (documented in  ``refabsbt.cnt``)
         + ensemble length must match database

    - run ``refabsbt refabsbt.tmp``
    - creates ``aship.ref``

Part II: Python (used to be Matlab)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Use Python to calculate bottom track calibration values
and make plots.  This replaces the Matlab program ``btcaluv.m``.

Edit the file ``Btplot_script.py``
Run the Python py typing:

::

  python Btplot_script.py

Example:

Default ``Btplot_script.py`` for pingdata demo:

::

  #!/usr/bin/env python

  ## written by quick_mplplots.py -- edit as needed:


  ## cruiseid      is 'ADCP'
  ## dbname        is 'aship'
  ## proc_yearbase is 1993
  ## printformats   is 'png'

  import matplotlib.pyplot as plt

  from pycurrents.adcp.quick_mplplots import Btplot

  ## other parameters that can be chosen:
  ##   name            default
  ##   ------        --------------
  ##   dbname           (found in ../../adcpdb)
  ##   titlestr         (uses ADCP
  ##   proc_yearbase    (first year in database)
  ##   printformats               'pdf'
  ##   dpi                        100
  ##   outfilebase               'btcal'
  ##   ddrange                    'all'
  ##   step                       1
  ##   min_speed                  2
  ##   max_sig                    2.5
  ##   max_gap                    0.1
  ##   tol_dt                     0.02
  ##   min_depth                  25                #shallower for high freq
  ##   max_depth                  1500
  ##

  BT = Btplot()
  BT(btm_filename='aship.btm',
     ref_filename='aship.ref',
     cruiseid = 'ADCP',
     printformats = 'png',
     proc_yearbase='1993')

  plt.show()

..

This appends a block of Bottom Track Calibration information
to the file ``btcaluv.out``:

::

  ADCP bottomtrack calibration

  Time range  99.29 to  99.42
     Calculation done at Tue Apr 23 02:52:40 2013
      step: 1
      min_depth:  25   max_depth: 1500
      min_speed:  2.0 m/s   max_sig:  2.5 std devs
      max_gap:  0.10 minutes   tol_dt: 0.02 (fraction)
  unedited: 31 points
  edited:   23 points, 2.0 min speed, 2.5 max dev
              median     mean      std
  amplitude   0.9989   1.0013   0.0179
  phase      -0.4306  -0.2666   0.9689

..

To change some of the calculation parameters, copy the file
``Btplot_script.py`` to another name, eg.  ``Btplot_shallower.py``
and edit.  For example, to change the following parameters ...

 - new output filename :     outfilebase = 'btcal_shallower'
 - at slower speeds:         min_speed = 1
 - allow shallower minimum depth: min_depth = 15
 - use shallower maximum depth: max_depth = 500

\... replace the call to BT (above) in ``Btplot_shallow.py``
with these additions:

::


  BT = Btplot()
  BT(btm_filename='aship.btm',
     ref_filename='aship.ref',
     cruiseid = 'ADCP',
     printformats = 'png',
     proc_yearbase='1993',
     outfilebase = 'btcal_shallower',
     min_speed = 1,
     min_depth = 15,
     max_depth = 500)


..

Do not forget to add commas after each new line.

Run again:

::

   python Btplot_shallower.py



Now the Bottom Track Calibration values have changed:


::


  ADCP bottomtrack calibration

  Time range  99.29 to  99.42
     Calculation done at Fri May 10 05:39:14 2013
      step: 1
      min_depth:  15   max_depth: 500
      min_speed:  1.0 m/s   max_sig:  2.5 std devs
      max_gap:  0.10 minutes   tol_dt: 0.02 (fraction)
  unedited: 30 points
  edited:   23 points, 1.0 min speed, 2.5 max dev
              median     mean      std
  amplitude   0.9979   1.0010   0.0180
  phase      -0.5754  -0.3598   1.0117


..

This is just a demonstration of how to make the changes.
You have to decide what to apply.


Summary:

::

  before:
  --------
  unedited: 31 points
  edited:   23 points, 2.0 min speed, 2.5 max dev
              median     mean      std
  amplitude   0.9989   1.0013   0.0179
  phase      -0.4306  -0.2666   0.9689


  after:
  -----
  unedited: 30 points
  edited:   23 points, 1.0 min speed, 2.5 max dev
              median     mean      std
  amplitude   0.9979   1.0010   0.0180
  phase      -0.5754  -0.3598   1.0117



..