<div align="center">
  <img src="/logo_BSC.png" alt="Logo 1" height="50">
  <img src="/logo_FOCUS.png" alt="Logo 2" height="50">
</div>

<br>
<div align="center">

This project is licensed under GNU General Public License version 3 ([GPL-3](https://www.gnu.org/licenses/gpl-3.0)|[View on GitLab](https://earth.bsc.es/gitlab/focus-africa-bsc/vignette/-/blob/main/LICENSE.txt))

[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0) 

<br>

**In this READ.me, we provide the instructions necessary to run the vignette [FOCUS_calibration_t2m.ipynb](https://earth.bsc.es/gitlab/focus-africa-bsc/vignette/-/blob/main/FOCUS_calibration_t2m.ipynb) locally on a personal computer**

</div>



#### COMPUTATIONAL REQUIREMENTS
If you want to run the vignette [FOCUS_calibration_t2m.ipynb](https://earth.bsc.es/gitlab/focus-africa-bsc/vignette/-/blob/main/FOCUS_calibration_t2m.ipynb) locally on a computer you must ensure that the next computational requirements are met:

- **R - version 3.6.1**. It can be downloaded from [https://cran.r-project.org/](https://cran.r-project.org/)  
- **CDO - version 1.9.8**. It can be downloaded from [https://code.mpimet.mpg.de/projects/cdo](https://code.mpimet.mpg.de/projects/cdo) (with previous registration). Some useful information can be found on [https://code.mpimet.mpg.de/projects/cdo/embedded/cdo.pdf]() , specially on the section 1.1.
- **JupyterLab or similar**: A tool able to open a Jupyter notebook is needed. We recommend using JupyterLab. It can be installed from [https://jupyter.org/install](https://jupyter.org/install)




A relatively easy way to download and install JupyterLab and the requested versions of R and CDO may be through conda. Conda quickly installs, runs and updates packages and their dependencies (more detailed information of conda can be found here: https://docs.conda.io/en/latest/). Some details and a guide regarding the Conda download and installation are described in: https://docs.conda.io/projects/conda/en/latest/user-guide/install/. In this regard, we encourage to download Anaconda, which is a set of about a hundred packages including conda, numpy, scipy, ipython notebook, ecc,. Complementary information regarding how Anaconda works and how can be used for installing some packages (as well as installing R, CDO or Jupyter-Lab)  can be found in their user guide: https://docs.anaconda.com/anaconda/user-guide/. 

<br>
<br>
<br>
<div align="center">

#### STEPS TO INSTALL JupyterLab AND THE REQUIRED VERSIONS OF R AND CDO THROUGH ANACONDA
Next, we offer the instructions to install JupyterLab AND THE REQUIRED VERSIONS OF R AND CDO THROUGH ANACONDA for both cases LINUX and WINDOWS

</div>

### FOR LINUX 


**Only once**:

1. Go to the [repository](https://earth.bsc.es/gitlab/focus-africa-bsc/vignette) containing the FOCUS vignette and download it (we have choosen the download source code to be "tar.gz"): 

 ![first_instruction](./instructions_screenshots/instruction_screenshot_1.png)
 
2. Extract the contents in the path that you prefer within your computer. To do so, go to what you have downloaded in **Step 1**, open it and clik on "Extract":

![second_instruction](./instructions_screenshots/instruction_screenshot_2.png)

Once you have done it, you need to choose where you want to store it. As a piece of example, we have choosen a folder named "work_folder" which has the next path for our example (yours will be different): "/home/amartine/work_folder/":

![third_instruction](./instructions_screenshots/instruction_screenshot_3.png)

after selecting the folder where the repo will be stored, the last thing to do (within this step) is to click in "Extract":

![fourth_instruction](./instructions_screenshots/instruction_screenshot_4.png)

3. Once the repository has been downloaded and saved to our computer, the next step is to acquire Anaconda. This can be done by visiting the website https://www.anaconda.com/products/distribution and clicking on the "Download" option.

![fifth_instruction](./instructions_screenshots/instruction_screenshot_5.png)

4. The next step should be install Anaconda. To accomplish that:
    - open a terminal and go to the download folder. Unless you have changed your 'bash script' you should be able to access to the download folder by just typing: `cd ~/Downloads`. If you cannot access you should explore within your computer the path where the Anaconda installer was downloaded, and then you should change to that directory. If you are not familiarised with the Linux terminal we reccomend you to first read some tutorials were the basics commands are explained, as in https://linuxcommand.org/lc3_lts0020.php
    - Once you are in the directory where the installer has been downloaded, you can install it by typing `bash Anaconda-latest-Linux-x86_64.sh` (where 'latest' should be replaced by the downloaded version). Note that, the version will depend on the name of the Anaconda installer (which depends on when it was downloaded). To check the name you can go to the path where this installer was downloaded and chek it. For example, in the moment this tutorial was creted, the installer was named "Anaconda3-2022.10-Linux-x86_64.sh" and hence, we typed: `bash Anaconda3-2022.10-Linux-x86_64.sh`. Once anaconda is installed, close the terminal.  

5. The next to do is to open a terminal and execute the following commands in order to set the environment that will let us run the vignette in our computer. Please, follow the next steps:
    - `conda env create -f <repository_path>/on_computer/settings_conda.yml`
   
    **Note 1**: you should replace <repository_path> by the path where the contents of the downloaded repository were stored (**Step 2**). As a piece of example, <repository_path>= '/home/amartine/work_folder/vignette-main/'
   
    - `conda activate settings_conda`
    - `R -e "install.packages('devtools', repos='https://ftp.cixug.es/CRAN/')"`
    - `R -e "library(devtools); path_anaconda <-'/home/amartine/anaconda3/'; Sys.setenv(TAR = paste0(path_anaconda,'/envs/settings_conda/bin/tar'));install_version('Rcpp',version='1.0.8.3', quiet=T, repos='https://ftp.cixug.es/CRAN/'); install_version('uuid',version='1.1.0', quiet=T, repos='https://ftp.cixug.es/CRAN/'); install_version('pillar',version='1.8.1', quiet=T, repos='https://ftp.cixug.es/CRAN/')"`

    **Note 2**: 'path_anaconda' must specify the path where anaconda3 has been installed in your computer. 
    
    **Warning**: the last two steps may take a while.

<br>    

**Steps that need to be followed every time you want to run the vignette**:
1. Open a terminal.
2. Type `conda activate settings_conda`. If it does not work try `source activate settings_conda`. More info in https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#activating-an-environment
3. Open Jupyter Lab. You can do it by just typing in terminal: `jupyter-lab`
4. On the left you can now navigate within your computer and go to the repository path (which is the path within your computer where you have archived the [repository](https://earth.bsc.es/gitlab/focus-africa-bsc/vignette) containing the FOCUS vignette). 

![first_instruction](./instructions_screenshots/instruction_screenshot_6.png)

5. You can now select the vignette script ("FOCUS_calibration_t2m.ipynb") and run the code line by line.

<br>

### FOR WINDOWS

If you want to install JupyterLab and the required version of R and CDO through Conda, but the opertive system of your computer is Windows, you should install a virtual machine of Ubuntu. To do so, you should download and carefully read the next detailed [tutorial](https://earth.bsc.es/gitlab/focus-africa-bsc/vignette/-/blob/main/on_computer/tutorial_virtual_machine.pdf). 

**WARNING**: ALL THE NEXT STEPS SHOULD BE CARRIED OUT FROM THE INSIDE OF THE VIRTUAL MACHINE, including the lecture of this same exact READ.me. If you are reading this from the browser of your virtual machine you can skip this WARNING, if not:
  - Open the Ubuntu virtual machine as explained in [tutorial](https://earth.bsc.es/gitlab/focus-africa-bsc/vignette/-/blob/main/on_computer/tutorial_virtual_machine.pdf)
  - From the virtual machine, open a browser and paste on it: https://earth.bsc.es/gitlab/focus-africa-bsc/vignette/-/tree/main/on_computer
  - Continue the lecture in the same exact READ.me that has been opened in the virtual machine    
  


<br>

Once you have confirmed that you are currently inside your virtual machine and are accessing this README.md file using the browser within your Ubuntu virtual machine, you can proceed with the next steps. These steps are exactly the same as those outlined in the 'FOR LINUX' section.


<br>
<div align="center">

This project is licensed under GNU General Public License version 3 ([GPL-3](https://www.gnu.org/licenses/gpl-3.0)|[View on GitLab](https://earth.bsc.es/gitlab/focus-africa-bsc/vignette/-/blob/main/LICENSE.txt))

[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)    

</div>

<div align="center">
  <img src="/logo_BSC.png" alt="Logo 1" height="50">
  <img src="/logo_FOCUS.png" alt="Logo 2" height="50">
</div>

<br>
<div align="center">

    Vignette - Calibration and verification of seasonal forecasts.
    Copyright (C) 2023  Barcelona Supercomputing Center - Centro Nacional de Supercomputacion
    
</div>
