Merge pull request #37 from openearth/installation_guide

Installation guide

README.md

@@ -1,45 +1,48 @@
-# coclicodata
+# CoCliCo Data
 
 This repository contains code to maintain the CoCliCo STAC catalog. Please note that
 this is a **relative** STAC catalog for development purposes.
 
-## Usage
+## Installation instructions
 
 Given that `coclicodata` is under active development, it's recommended to clone the repository and then install it in 'editable' mode. This way, any changes made to the package are immediately available without needing a reinstall.
 
 Follow these steps for installation:
 
-1. **Clone the repository**:
+1. Install GitHub Desktop for your OS: https://desktop.github.com/ 
+2. Install the Mamba Package Manager (miniforge3) for your OS: https://github.com/conda-forge/miniforge#mambaforge 
+3. Open a miniforge prompt (by searching "miniforge" in the task bar) and run `mamba –-version` to check if the installation was complete. 
+4. Clone the `coclicodata` repo by adding ("Add" --> "clone repository" --> "URL") URL in GitHub Desktop, you can find the URL under the green "code" button in this `coclicodata` repo. Please change the local path to something like: `C:\Users\***\Documents\GitHub` (where you create the GitHub folder yourself). The repo will be cloned here. 
+5. In the miniforge prompt, change the directory to the cloned repo by running `cd C:\Users\***\Documents\GitHub\coclicodata`, where *** needs to be replaced to your system variables.
+6. This directory contains an `environment.yml` file with all the necessary packages describing the software dependencies. Create the software environment by running the following command in the miniforge prompt (note, this will take about 10 minutes to run): 
 
    ``` bash
-   git clone https://github.com/openearth/coclicodata.git
+   mamba env create -f environment.yml
    ```
 
-2. **Install the environment**:
+7. Now you can activate the environment we just created, in your miniforge prompt please run the following:
 
    ``` bash
-   mamba env create -f /path/to/coclicodata/environment.yml
+   mamba activate coclico
    ```
 
-3. **Activate the environment**:
+8. You can look which environments you have installed by running: `mamba env list`. It places a star to indicate in which environment you are situated now (also indicated in front of your command line).
+9. In principle, mamba should have installed the pip dependencies as well. If it fails to install these, you can install the ones requiring pip in the `environment.yml` file manually by running (note list might not be complete, check against the `environment.yml` file):
 
    ``` bash
-   mamba activate coclico
+   pip install stactools-geoparquet-items odc-ui odc-stac odc-algo odc-io odc-cloud[ASYNC] mapbox mapboxcli xstac
    ```
 
-4. **Install the package in editable mode**:
+10. To check if all went well you can run `mamba list` to list all installed packages and search for, for instance `mapbox`. If it is present, you can continue. 
+11. Now, this is a bit confusing, but we still need to install our `coclicodata` package. This is available in the repo you just cloned with the same name in the folder `src/coclicodata`. As this package is not published online, we cannot do pip or mamba installations, we need to install it from our clone. 
+12. Install the `coclicodata` package by running (if you are still in the `C:\Users\***\Documents\GitHub\coclicodata` directory):
 
    ``` bash
-   pip install -e /path/to/coclicodata
+   pip install -e . 
    ```
-
-After installation, you can easily import and use any module or function from the
-`coclicodata` package in your Python scripts or interactive sessions:
-
-```python
-from coclicodata.coclico_stac import utils
-# Further code utilizing the utils module...
-```
+13. For running jupyter notebooks and / or python scripts, we recommend to install VS Code editor: https://code.visualstudio.com/ as it offers flexibility in selecting environments, directories and python interpreters as well as offers various useful extensions all in one user interface.
+14. Open VS Code and select the cloned `coclicodata` folder as your working directory. As a test, you can open `01_storm_surge.ipynb` in notebooks. Select your kernel (the `coclicodata` env) in the top right corner and run cells by pressing shift-enter. You should be able to progress through the notebook without any errors in case you put the NC files present in `docs\example` in the right directory. Please change `coclico_data_dir` and `dataset_dir` accordingly. 
+15. Might you run into trouble with these installation guidelines, please reach out to [@EtienneKras](https://github.com/EtienneKras), [@mathvansoest](https://github.com/mathvansoest) or [@FlorisCalkoen](https://github.com/FlorisCalkoen) for help.  
 
 ## Use pre-commit locally
 

environment.yml

@@ -127,7 +127,6 @@ dependencies:
       - odc-algo
       - odc-io
       - odc-cloud[ASYNC]
-      - odc-dscache
       - mapbox # not sure if this is still being used
       - mapboxcli # requires monkeypatch for Python 3.10
       - xstac

notebooks/01_storm_surge.ipynb

@@ -59,18 +59,18 @@
     "root = home.root\n",
     "\n",
     "# Import custom functionality\n",
-    "from etl import p_drive\n",
-    "from etl.CF_compliancy_checker import check_compliancy, save_compliancy\n",
+    "from coclicodata.drive_config import p_drive\n",
+    "from coclicodata.etl.cf_compliancy_checker import check_compliancy, save_compliancy\n",
     "\n",
     "# Define (local and) remote drives\n",
-    "coclico_data_dir = p_drive.joinpath(\"11205479-coclico\", \"FASTTRACK_DATA\")\n",
+    "coclico_data_dir = p_drive.joinpath(\"11207608-coclico\", \"FASTTRACK_DATA\")\n",
     "\n",
     "# Workaround to the Windows OS (10) udunits error after installation of cfchecker: https://github.com/SciTools/iris/issues/404\n",
-    "os.environ[\"UDUNITS2_XML_PATH\"] = str(\n",
-    "    home.joinpath(  # change to the udunits2.xml file dir in your Python installation\n",
-    "        r\"Anaconda3\\pkgs\\udunits2-2.2.28-h892ecd3_0\\Library\\share\\udunits\\udunits2.xml\"\n",
-    "    )\n",
-    ")"
+    "# os.environ[\"UDUNITS2_XML_PATH\"] = str(\n",
+    "#     home.joinpath(  # change to the udunits2.xml file dir in your Python installation\n",
+    "#         r\"Anaconda3\\pkgs\\udunits2-2.2.28-h892ecd3_0\\Library\\share\\udunits\\udunits2.xml\"\n",
+    "#     )\n",
+    "# )"
    ]
   },
   {
@@ -511,7 +511,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.4"
+   "version": "3.12.3"
   },
   "vscode": {
    "interpreter": {