.. ......................................
.. UHDAS/CODAS restructured text document
.. ......................................


.. dataviewer.py  documentation master file, copied from edit_doc 2018-09-03
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.



Dataviewer: view, edit, compare
=================================


.. NOTE:: The older Python2 (Wx) version of Gautoedit documentation is
          in the full Python2 documentation,
          `here <https://currents.soest.hawaii.edu/docs/adcp_doc2/codas_doc/edit_doc/index.html>`_

Python3 ``dataviewer.py`` is a program for displaying velocity and
other ancillary data from a codas database in panel plots, and
velocities over topography.  It uses Qt libraries for window management
Matplotlib for figures, and Basemap for projections.

This tool was designed to let the user visualize shipboard ADCP data, presenting:

- a variety of matrix data in color panels (eg. ocean *u*, ocean *v*, precent good, backscatter)
- some time-series variables with the same time axis as the panels (eg. ship speed, ship direction)
- vectors of ocean velocity over topography, colored with the transducer temperature


It has four modes, **view**, **edit**
(which is still available under its old name ``gautoedit.py``),
**compare** and **ping**.


All ``dataviewer.py`` modes are designed to let you view
ADCP variables from the CODAS database, extracted by time.  All
start with three main panels:

- Control Window (to extract data)
- Panel plots (view data as time series in panels)
- Topography (view velocity as vectors)


::

   # program to run                    # what it does
   dataviewer.py                       view only
   dataviewer.py -e                    "gautoedit.py"; edit a CODAS dataset
                                               - manual editing
                                               - threshold editing
                                               - bottom editing
   dataviewer.py -c                    compare two CODAS datasets
                                               - manual editing
   dataviewer.py -p                    view CODAS variables and single-ping
                                      (only works with freshly-processed data)

..


.. NOTE:: NEW: Dataviewer allows you to save your **settings** or your **progress**.

         - **Settings**: general settings for using dataviewer in the active mode
         - **Progress**: suitable for the particular cruise you are working on,
           (eg. thresholds, number of panels, where you were in the dataset
           when you stopped.


----

**Work Flow**


(1) Make your :term:`Project Directory` (as in the Demos) to hold

    - each :term:`Processing Directory`
    - notes and discoveries about the data

|

(2) For each sonar:

  (i)  Create the text file for your sonar (to keep notes), eg ``km1001c_os38nb.txt``
  (ii) Follow the demos to create the **processing directory**.
       You are creating or copying a directory with :term:`Preliminary Processing`:

        - you might be copying a directory from a :term:`UHDAS Data`  (for :term:`Post-Processing`)
        - you might be doing it manually (for :term:`Single-Ping processing`) to end up with :term:`CODAS averages`
        - you might be doing it through `adcp_database_maker.py <../adcp_py3demos/adcp_database_maker_demos/ADM_adcp_database_maker_intro/index.html>`_

  (iv) Do the first steps in **post-processing**, i.e. get the calibrations close

        - look for (and patch using `patch_hcorr.py <../patch_hcorr/index.html>`_) any holes in the heading correction (if there is one)
        - assess the phase and amplitude (scale factor) calibrations; apply them
        - assess the transducer-GPS offset; apply as directed

  (v) Use ``dataviewer.py -e`` to edit the data.

        - remove only obviously bad data

  (vi) Assess the calibrations again; apply correction if needed.


.. NOTE:: It is a good idea to copy a **processing directory** to another name before making a
          change:

             - if you make a mistake you don't have to start over
             - you can compare the directories to see the effect of the change

|

Now you have multiple **processing directories** with data that are almost as
good as possible.

(3) Use dataviewer  **compare mode**  to compare them and edit out more if needed.

|

(4) When finished

    - make netCDF files, matlab files, and web page for each sonar using
      `quick_adcp.py <../quickadcp_overview.html>`_, adcp_nc.py and `quick_web.py <../quick_web/index.html>`_

|

The next pages are about each ``dataviewer.py`` mode in order, as well as a few nuggets:


.. toctree::
   :maxdepth: 1

   View Mode <dataviewer_view_mode/index>
   Edit Mode <dataviewer_edit_mode/index>
   Compare Mode <dataviewer_compare_mode/index>
   Ping Mode <dataviewer_ping_mode/index>
   Reset Editing <dataviewer_reset_editing/index>
   Save your Settings <dataviewer_save_settings/index>