Skip to content

Commit

Permalink
Update bfast_gpu.rst
Browse files Browse the repository at this point in the history
Proofreading complete.
  • Loading branch information
alexryangregor authored Nov 22, 2023
1 parent 9176c97 commit 79e8c67
Showing 1 changed file with 31 additions and 23 deletions.
54 changes: 31 additions & 23 deletions docs/source/modules/dwn/bfast_gpu.rst
Original file line number Diff line number Diff line change
@@ -1,18 +1,22 @@
BFAST GPU
=========

This document provides usage instructions for the GPU implementation of BFAST, implemented here as a Jupyter dashboard on SEPAL.
This article provides usage instructions for the GPU implementation of Breaks for Additive Seasonal and Trend (BFAST), implemented here as a Jupyter dashboard on SEPAL.

Introduction
------------

Large amounts of satellite data are now becoming available, which, in combination with appropriate change detection methods, offer the opportunity to derive accurate information on timing and location of disturbances (e.g. deforestation events across the Earth's surface). Typical scenarios require the analysis of billions of image patches/pixels, which can become very expensive from a computational point of view. The `BFAST package <https://pypi.org/project/bfast/>`_ provides efficient, massively parallel implementation for one of the state-of-the-art change detection methods called `Breaks For Additive Season and Trend (BFASTmonitor) <http://bfast.r-forge.r-project.org>`, as proposed by Verbesselt *et al.*
Large amounts of satellite data are now becoming available, which, in combination with appropriate change detection methods, offer the opportunity to derive accurate information on timing and location of disturbances (e.g. deforestation events across the Earth's surface).

Typical scenarios require the analysis of billions of image patches/pixels, which can become very expensive from a computational point of view.

The `BFAST package <https://pypi.org/project/bfast/>`_ provides efficient, massively parallel implementation for one of the state-of-the-art change detection methods called `BFASTmonitor <http://bfast.r-forge.r-project.org>`, as proposed by Verbesselt *et al.*

.. figure:: https://raw.githubusercontent.com/12rambau/bfast_gpu/master/doc/img/bfastmonitor_1.png

The analysis perfomed pixel-wise

The implementation is based on `OpenCL <https://www.khronos.org/opencl/>`_. It allows the processing of large-scale change detection scenarios given satellite time-series data. The optimizations made are tailored to the specific requirements of modern, massively parallel devices, such as graphics processing units (GPUs).
The implementation is based on `OpenCL <https://www.khronos.org/opencl/>`_. It allows the processing of large-scale change detection scenarios given satellite time series data. The optimizations made are tailored to the specific requirements of modern, massively parallel devices, such as graphics processing units (GPUs).

The full documentation of the :code:`bfast` package can be found `on this page <https://bfast.readthedocs.io/en/latest/>`_.

Expand All @@ -21,7 +25,7 @@ Usage

.. important::

Before launching the BFAST module, you need to have at least one time series in your SEPAL folders.
Before launching the **BFAST** module, you need to have at least one time series in your **SEPAL folders**.

.. attention::

Expand All @@ -32,9 +36,13 @@ Set up

To launch the app, follow the `steps to register for SEPAL <https://docs.sepal.io/en/latest/setup/register.html>`_.

Open a GPU instance in your terminal (:code:`g4` or :code:`g8`). Then move to the SEPAL **Apps** dashboard (purple wrench icon on the left side panel). Finally, search for and select **bfast GPU**.
Open a **GPU instance** in your terminal (:code:`g4` or :code:`g8`).

Then move to the SEPAL **Apps** dashboard (purple wrench icon on the left side pane).

Finally, search for and select **bfast GPU**.

The application should launch itself in the **BFAST process** section. On the left side, the **navdrawer** will help you navigate between the different pages of the app. If you click on :code:`wiki`, :code:`bug report` or :code:`code source`, you will be redirected to the corresponding webpage.
The application should launch itself in the **BFAST process** section. On the left side, the **navdrawer** will help you navigate between the different pages of the app. If you select :code:`wiki`, :code:`bug report` or :code:`code source`, you will be redirected to the corresponding webpage.

.. note::

Expand All @@ -47,18 +55,20 @@ The application should launch itself in the **BFAST process** section. On the le
Select folder
^^^^^^^^^^^^^

Select a folder in the first widget. Navigate through your folders to find the time series folder you want to analyse. Click outside the pop-up window to exit the selection. Your folder should only contain folders with numbered names (corresponding to each tile of the TS).
Select a folder in the first widget.

By selecting an appropriate folder, a widget will be automatically filled out and enabled, as described below:
Navigate through your folders to find the time series folder you want to analyse. Click outside the pop-up window to exit the selection. Your folder should only contain folders with numbered names (corresponding to each tile of the TS).

- :code:`output directory name`: Filled out with the basename of your TS folder.
- :code:`select tiles to use`: Preselect all of the available tiles.
- :code:`monitoring dates`: The slider is enabled and filled with the date list included in the TS folder. The values default to the full range of dates.
- :code:`historical period`: The slider is enabled and filled with the date list included in the TS folder. The value defaults to the first date of the TS.
By selecting an appropriate folder, a widget will be automatically completed and enabled, as described below:

- :code:`output directory name`: Completed with the basename of your TS folder.
- :code:`select tiles to use`: Preselect all available tiles.
- :code:`monitoring dates`: The slider is enabled and completed with the date list included in the TS folder (the values default to the full range of dates).
- :code:`historical period`: The slider is enabled and completed with the date list included in the TS folder (the value defaults to the first date of the TS).

.. figure:: https://raw.githubusercontent.com/12rambau/bfast_gpu/master/doc/img/correct_folder.png

Select a folder and preload all of the information.
Select a folder and preload all information.

.. attention::

Expand All @@ -73,7 +83,7 @@ Parameters

Now you can change the parameters to fit the requirements of your analysis:

- :code:`output directory name`: This name will be used to store all of your analysis. While it is completed automatically with the base name of your TS folder, you can still change it.
- :code:`output directory name`: This name will be used to store all of your analysis. While it is completed automatically with the base name of your TS folder, you can change it.

.. note::

Expand All @@ -100,10 +110,10 @@ Advanced parameters

These parameters are for advanced users only. The default value provides accurate results in many situations.

Select :code:`Advanced parameters` and a new panel of options will be available:
Select :code:`Advanced parameters` and a new pane of options will be available:

- :code:`bandwith relative to sample size`: Float in the interval (0,1), specifying the bandwidth relative to the sample size in the MOSUM/ME monitoring processes.
- :code:`Significance level of the monitoring`: Significance level of the monitoring procedure (and ROC, if selected), i.e. probability of Type I error.
- :code:`Significance level of the monitoring`: Significance level of the monitoring procedure and ROC, if selected (i.e. probability of Type I error).
- :code:`backend`: Specifies the implementation that shall be used: **Python** resorts to the non-optimized Python version; **OpenCL** resorts to the optimized, massively parallel OpenCL implementation.

.. note::
Expand All @@ -119,7 +129,7 @@ Run process

You can now select :code:`LAUNCH BFAST ANALYSIS` to start the process.

The process will start shortly, notifying you of it's advancement tile by tile in the info banner, as shown in the following figure.
The process will start shortly, notifying you of it's advancement tile by tile in the **Info banner**, as shown in the following figure.

.. figure:: https://raw.githubusercontent.com/12rambau/bfast_gpu/master/doc/img/advancement.png

Expand All @@ -133,20 +143,18 @@ The process will start shortly, notifying you of it's advancement tile by tile i

If your connection to SEPAL is lost and the application stops, use the exact same parameters as your previous analysis. The application will find the already computed tiles and images, and start from where it stopped instead of restarting from scratch.


.. figure:: https://raw.githubusercontent.com/12rambau/bfast_gpu/master/doc/img/computation_end.png

End of computation screen


The module provided the following :code:`.vrt` outputs:
- :code:`~/module_results/bfast/[name_of_input]/[bfast_params]/bfast_outputs.vrt`

It is a three-band raster:

- band 1, the breakpoints in decimal year format
- band 2, the magnitude of change
- band 3, the validity of the pixel model
- **Band 1**: the breakpoints in decimal year format
- **Band 2**: the magnitude of change
- **Band 3**: the validity of the pixel model

This raster has the exact same dimensions as the input raster.

Expand All @@ -161,6 +169,6 @@ Here you'll find an example of two bands over the Juaboso Region in Ghana with a

.. figure:: https://raw.githubusercontent.com/12rambau/bfast_gpu/master/utils/breaks.png

Breaks masked in the center of the region, displayed with a viridis colormap, values in [2017.26, 2019.98]
Breaks masked in the centre of the region, displayed with a viridis colormap, values in [2017.26, 2019.98]

.. custom-edit:: https://raw.githubusercontent.com/sepal-contrib/bfast_gpu/release/doc/en.rst

0 comments on commit 79e8c67

Please sign in to comment.