dea-tools
=========

Python functions and algorithms developed to assist in analysing Digital Earth Australia (DEA) data (e.g. loading data, plotting, spatial analysis, machine learning). This includes the following modules:

**Loading data**

-  ``dea_tools.datahandling``: Loading and handling DEA data (e.g. combining multiple products, handling CRSs, pansharpening)

**Plotting and transforming data**

-  ``dea_tools.plotting``: Plotting DEA data (e.g. RGB plots, animations, interactive maps)
-  ``dea_tools.bandindices.py``: Calculating remote sensing band indices (e.g. NDVI, NDWI)

**Spatial and temporal analysis**

-  ``dea_tools.spatial``: Spatial analysis tools (e.g. rasterising, vectorising, contour extraction, image processing)
-  ``dea_tools.temporal``: Temporal analysis tools (e.g. phenology, temporal statistics, multi-dimensional regression)

**Classification and segmentation**

-  ``dea_tools.classification.py``: Machine learning classification (e.g. training and applying machine learning models on satellite data)
-  ``dea_tools.segmentation.py``: Image segmentation tools (e.g. applying image segementation with RSGISLIB)

**Parallel processing**

-  ``dea_tools.dask``: Parallel processing with Dask (e.g. creating Dask clusters for scalable analysis)

**Domain-specific analysis**

-  ``dea_tools.land_cover``: Functions for plotting Digital Earth Australia Land Cover data.
-  ``dea_tools.coastal``: Coastal and intertidal analysis tools (e.g. tidal tagging, coastal change timeseries)
-  ``dea_tools.bom``: Loading Bureau of Meteorology water data service data (e.g. guage data, discharge data)
-  ``dea_tools.climate``: Retrieving and manipulating gridded climate data (e.g. ERA5)
-  ``dea_tools.waterbodies``: Loading and processing DEA Waterbodies data (e.g. finding and loading waterbody timeseries data)

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

Install the package from the source on any system with ``pip``:

.. code-block:: bash

    pip install dea-tools

To work with this module on the DEA Sandbox or National Computational Infrastructure environments without installing it, you can add the ``Tools`` directory to the system path from within the ``dea-notebooks`` repository:

.. code-block:: python

   import sys
   sys.path.insert(1, '../Tools/')
   import dea_tools.datahandling  # or some other submodule

You can also ``pip install`` the module directly from the local ``Tools`` directory. To do this on the DEA Sandbox, run ``pip`` from the terminal:

.. code-block:: bash

   pip install -e Tools/


Importing functions in Python
-----------------------------

To use functions from ``dea-tools``, import them using:

.. code-block:: python

   from dea_tools.datahandling import load_ard
   from dea_tools.plotting import rgb


Citing DEA Tools
----------------

If you use any of the notebooks, code or tools in this repository in your work, please reference them using the following citation:

    Krause, C., Dunn, B., Bishop-Taylor, R., Adams, C., Burton, C., Alger, M., Chua, S., Phillips, C., Newey, V., Kouzoubov, K., Leith, A., Ayers, D., Hicks, A., DEA Notebooks contributors 2021. Digital Earth Australia notebooks and tools repository. Geoscience Australia, Canberra. https://doi.org/10.26186/145234


Building and Releasing
----------------------

This section is only relevant to you if you are a developer of this package.

Building and releasing dea-tools requires that the package is built in-place. Either build with an editable pip installation or with ``pip>=21.2`` and ``--use-feature=in-tree-build``. Building will generate a file, ``dea_tools/__version__.py``, that is dynamic on release. It should not be committed. ``setup.py`` will detect if ``__version__.py`` exists and change its behaviour accordingly.

Build instructions:

.. code-block:: bash

        cd Tools
        rm dea_tools/__version__.py  # if necessary
        pip install . --use-feature=in-tree-build
        python -m build

