lcmap-tap 2.0.1
A data visualization tool for PyCCD time-series model results and Landsat ARD
License: Unlicense
Requires Python: >=3.6
Keywords: usgs eros lcmap

Timeseries Analysis and Plotting (TAP) Tool
===========================================

Abstract
--------

The Timeseries Analysis and Plotting (TAP) Tool is being developed to
provide exploratory data analysis for the Land Change Monitoring,
Assessment, and Projection
(`LCMAP <https://eros.usgs.gov/science/land-change-monitoring-assessment-and-projection-lcmap>`__)
project at `USGS EROS <https://eros.usgs.gov/>`__. TAP is an open-source
project written in python that uses PyQt5 and matplotlib for generating
interactive GUIs and plots. Currently, it provides the following
functionality:

- Plot a timeseries of Landsat Analysis Ready Data
  (`ARD <https://www.usgs.gov/land-resources/nli/landsat/us-landsat-analysis-ready-data>`__)

  - Landsat 4-7 Bands 1, 2, 3, 4, 5, 7 Surface Reflectance
  - Landsat 8 Bands 2-7 Surface Reflectance
  - Landsat 4-7 Band 6 Brightness Temperature
  - Landsat 8 Band 10 Brightness Temperature

- Plot model parameters and curve-fits from the Continuous Change
  Detection and Classification
  (`CCDC <https://www.sciencedirect.com/science/article/pii/S0034425714000248>`__)
  algorithm
- Calculate indices on the fly for plotting and visualization

  - NDVI
  - MSAVI
  - SAVI
  - EVI
  - NDMI
  - NBR
  - NBR-2

- Display RGB visualizations of Landsat ARD
- Export plotted Landsat ARD surface reflectance, brightness
  temperature, and index values to a .csv file
- Save a plot figure as a .png file
- Save a Landsat ARD RGB display as a .png file
- Save ESRI point shapefile for plotted coordinates

--------------

**The tool currently requires the following data inputs:**

- Landsat ARD (obtained via HTTP request).
- Serialized change and cover results generated by
  `PyCCD <https://eroslab.cr.usgs.gov/lcmap/pyccd>`__ (obtained via HTTP request).

Landsat ARD and the PyCCD algorithm are publicly available.

However, TAP requires access to ARD and PyCCD results via web-services
that are available to on-site personnel at USGS EROS only.

For those reasons, TAP is not intended for general public use until the
datasets become widely available at a future date.

--------------

Installation
------------

**Note on PyQt5**: It is recommended to use PyQt5==5.10.1
because of an issue in later versions in which Qtwebengineprocess does
not close on TAP exit.

--------------

Create a Virtual Environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- `Install Miniconda3 <https://docs.conda.io/en/latest/miniconda.html>`__

- Create a Conda virtual environment

  - Linux

    .. code:: bash

       conda create --name tap python=3.6.7 gdal=2.2.2 poppler=0.60.1 cython cytoolz

  - Windows

    .. code:: powershell

       conda create --name tap python=3.6.7 gdal=2.2.2 cython cytoolz

  - If you experience SSL cert errors, disable ssl verification and try to create the env again.

    .. code:: bash

       conda config --set ssl_verify false

- Activate the environment

  .. code:: bash

     conda activate tap


Install TAP
~~~~~~~~~~~~~~~~~~~~~~~

- Ensure the virtual environment is activated from previous creation steps.

- Use pip to install TAP's latest standard release and the remaining dependencies

  .. code:: bash

     pip install lcmap-tap

  - If you are having trusted host/certificate issues during pip install,
    you can explicitly trust pypi

    .. code:: bash

       pip install lcmap-tap --trusted-host pypi.org --trusted-host files.pythonhosted.org

  - To install a pre-release or another specific version instead of a standard release:

    .. code:: bash

      pip install lcmap-tap==2.0.0rc2

- Create the configuration file required by tap

  - Note: Location may differ depending on if it was installed for a single user vs system wide.

  - Linux Example

    - Create and edit as needed

      .. code:: bash

         cd $HOME/.conda/envs/tap/lib/python3.6/site-packages/lcmap_tap/
         cp config-example.yaml config.yaml

  - Windows Example

    - Create and edit as needed

      .. code:: powershell

         cd $HOME\AppData\Local\Continuum\miniconda3\envs\tap\Lib\site-packages\lcmap_tap
         cp config-example.yaml config.yaml

Run the Tool
------------

Once installed, lcmap_tap can be executed directly from the command line
if the virtual environment is activated:

- Note: Location may differ depending on if it was installed for a single user vs system wide.

- Linux

  .. code:: bash

     lcmap_tap

- Windows

  .. code:: powershell

     python.exe $HOME\AppData\Local\Continuum\miniconda3\envs\tap\Scripts\lcmap_tap.exe

Upgrades
--------

To upgrade an already installed version of tap:

- Activate the environment

  .. code:: bash

     conda activate tap

- Upgrade to the latest standard release

  .. code:: bash

    pip install --upgrade lcmap-tap

  - Alternatively, upgrade to a specific release

    .. code:: bash

      pip install --upgrade lcmap-tap==2.0.0rc2

- If configuration parameters have changed in a new release, copy the config example:

  - Note: Location may differ depending on if it was installed for a single user vs system wide.

  - Linux Example

    - Create and edit as needed

      .. code:: bash

         cd $HOME/.conda/envs/tap/lib/python3.6/site-packages/lcmap_tap/
         cp config-example.yaml config.yaml

  - Windows Example

    - Create and edit as needed

      .. code:: powershell

         cd $HOME\AppData\Local\Continuum\miniconda3\envs\tap\Lib\site-packages\lcmap_tap
         cp config-example.yaml config.yaml

Contributing
-------------
Before committing to this repository, run the following command.

.. code-block:: bash

    git config --local commit.template .gitmessage

This will add the LCMAP commit template to `git commit`.

.. code-block:: bash

   jira/lcmap-xxxx: Title
   Description

Versioning
----------
lcmap-tap follows semantic versioning: http://semver.org/