README.md 6.41 KB
Newer Older
Romulo Pereira Goncalves's avatar
Romulo Pereira Goncalves committed
1
2
3
4
5
6
7
8
9
# Docker image for HaSa

Scripts to build and create a Docker image.

## Build Docker image

### Operating system

The image uses `Ubuntu 20.04` OS image as base image. All the packages are install using the package management tool `apt-get`.
10
The dependency list is defined in the docker file, `context/hasa.docker`
Romulo Pereira Goncalves's avatar
Romulo Pereira Goncalves committed
11
12
13
14
15
16
17
18
19

### R

The image uses the latest version of `R` available for `Ubuntu 20.04`.

### HaSa

The `HaSa` R package depends on `velox-v0.2.0`. To install `velox-v0.2.0` it is necessary to pin the version of some R packages: `BH`, `sp`, `sf`, and `rgdal`.
All the dependencies and installation command for `HaSa` are defined in `context/install.R`.
20
21
22

## Start a docker container

23
The user can start a docker container using the script `start_docker.sh`. In case the container exists, the script will stop and remove the old container and start a new one. Before the user runs the script it is necessary to set the variables `input_dir` (path to the root directory containing the remote sensing images and reference data), `tmp_dir` ( path to the directory for the intermediate results) and `output_dir` (path to the root directory where the results will be stored). These directories are mounted inside the docker containers as `/home/hasa/input/`, `/home/hasa/tmp/`, `/home/hasa/output/`.
24

25

26
By default the use will get a bash prompt. However, it is also possible to get a `jupyter-lab` running at `localhost:8080`. For plotting proposes, it is recommended to use the `jupyter-lab`.
27
28
29

### Bash prompt

30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
Once the script is initiate, the user will see the following prompt:
```bash
Starting HaSa container, please add the input files to /home/romulo/gitlab/HabitatSampler/demo/Data and read the results from the /home/romulo/gitlab/HabitatSampler/demo/Data


#######
This is a shell were you can use HaSa.
To start the R shell run the command: R
#######
hasa@9665b07ffc08:~$
```

Once the command `R` is executed the user gets the following prompt:
```bash
hasa@9665b07ffc08:~$ R

R version 4.0.3 (2020-10-10) -- "Bunny-Wunnies Freak Out"
Copyright (C) 2020 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu (64-bit)

R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under certain conditions.
Type 'license()' or 'licence()' for distribution details.

R is a collaborative project with many contributors.
Type 'contributors()' for more information and
'citation()' on how to cite R or R packages in publications.

Type 'demo()' for some demos, 'help()' for on-line help, or
'help.start()' for an HTML browser interface to help.
Type 'q()' to quit R.

> 
``` 

To use `HaSa` the user only needs to load it:
```R
> library(HaSa)

Attaching package: 'HaSa'

The following object is masked from 'package:graphics':

    clip

> HaSa::
HaSa::clip                      HaSa::multi_Class_Sampling      HaSa::plot_results              HaSa::Example_Reference_Points  HaSa::Sentinel_Stack_2018
HaSa::iplot                     HaSa::write_Out_Samples         HaSa::.__C__Habitat             HaSa::Example_Reference_Table   
> HaSa::
```

81
The message `The following object is masked from 'package:graphics':` means that there is a package called `graphics` which has a function with the same name. A detail explanation can be found in [here](https://stackoverflow.com/questions/39137110/what-does-the-following-object-is-masked-from-packagexxx-mean).
82

83
84
85
86
#### Demo

The user can use the file `demo/HabitatSampler.r` to explore HabitatSampler. However, it is important to keep in mind that plotting is not possible. Hence, the user when calling the function `multi_Class_Sampling` needs to set the argument `plot_on_browser=FALSE`. On each iteration, when the user defines the threshold, the interactive plot to determine the correct threshold needs to be open in a browser, i.e., open `demo/Data/Results/leaflet.html` in a browser.

87
88
### Jupyter-lab

89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
To start a `jupyter-lab` the user needs to set the variable `jupyter_lab` to `TRUE` in the `start_container.sh` script. Once set, the user only needs to re-run the script.  The user will see the following output:
```bash
docker$ ./start_docker.sh 
Error: No such container: hasa
Starting HaSa container, please add the input files to /home/romulo/gitlab/HabitatSampler/demo/Data and read the results from the /home/romulo/gitlab/HabitatSampler/demo/Data
[I 2021-01-29 13:58:46.420 ServerApp] jupyterlab | extension was successfully linked.
[I 2021-01-29 13:58:46.428 ServerApp] Writing notebook server cookie secret to /root/.local/share/jupyter/runtime/jupyter_cookie_secret
[I 2021-01-29 13:58:46.621 ServerApp] nbclassic | extension was successfully linked.
[I 2021-01-29 13:58:46.651 LabApp] JupyterLab extension loaded from /usr/local/lib/python3.8/dist-packages/jupyterlab
[I 2021-01-29 13:58:46.651 LabApp] JupyterLab application directory is /usr/local/share/jupyter/lab
[I 2021-01-29 13:58:46.654 ServerApp] jupyterlab | extension was successfully loaded.
[I 2021-01-29 13:58:46.658 ServerApp] nbclassic | extension was successfully loaded.
[I 2021-01-29 13:58:46.659 ServerApp] Serving notebooks from local directory: /home/hasa/demo
[I 2021-01-29 13:58:46.659 ServerApp] Jupyter Server 1.2.2 is running at:
[I 2021-01-29 13:58:46.659 ServerApp] http://a6d306398719:8888/lab?token=b883010687291bca935a65f39f40b66fc8a5a7646e866c1e
[I 2021-01-29 13:58:46.659 ServerApp]  or http://127.0.0.1:8888/lab?token=b883010687291bca935a65f39f40b66fc8a5a7646e866c1e
[I 2021-01-29 13:58:46.659 ServerApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).
[C 2021-01-29 13:58:46.661 ServerApp] 
    
    To access the server, open this file in a browser:
        file:///root/.local/share/jupyter/runtime/jpserver-12-open.html
    Or copy and paste one of these URLs:
        http://a6d306398719:8888/lab?token=b883010687291bca935a65f39f40b66fc8a5a7646e866c1e
     or http://127.0.0.1:8888/lab?token=b883010687291bca935a65f39f40b66fc8a5a7646e866c1e

```

The user should then open one of the provided URLs in a web-browser. For more information on how to use jupyter_lab, please refer to its [manual](https://jupyterlab.readthedocs.io/en/stable/).
117

118
119
120
#### Demo

The `jupyter-lab` will open directly into the `demo/` directory of HaSa repository. The user should load the notebook `HabitatSamplerDocker.ipynb` to run the demo. The docker version only supports single thread processing due to memory constraints. Hence, the user should call `multi_Class_Sampling` function with the default value `parallel_mode = FALSE`.