Minor updates to fix test for first-time users

.env.example

@@ -1,13 +1,14 @@
 # Adjust this file for storing private and user specific environment variables, like keys or system paths.
 # rename it to ".env" (excluded from version control by default)
 
-PROJECT_ROOT="path/to/aether"
+PROJECT_ROOT="path/to/aether/"  # path to your local aether repo
 TRAINER_PROFILE="gpu" # cpu/gpu/mps/ddp
-HF_HOME="/path/to/huggingface/cache" # set or will default to './.cache/huggingface/'
-DATA_DIR="../data/" # set orwill default to './data/'
+
 #----------------------------
 # OPTIONALS
 #----------------------------
+HF_HOME="${PROJECT_ROOT}/.cache/huggingface/" # set or will default to './.cache/huggingface/'
+DATA_DIR="${PROJECT_ROOT}/data/"  # set to your local data folder (for aether), or will default to '${PROJECT_ROOT}/data/'
 
 # Working directories
 # STORAGE_MODE=# or "shared"

.gitignore

@@ -226,4 +226,5 @@ uv.lock
 # Directories and files
 notebooks/01-TvdP-tmp.ipynb
 */source/*
-*.tif
+*.tif # for now
+..env.swp

README.md

@@ -23,20 +23,22 @@ This project develops an EO embedding/language model that can be used for explai
 
 ### Virtual environment
 
-First, install dependencies in a venv using [uv](https://docs.astral.sh/uv/getting-started/installation/)
+To install the dependencies in a venv using [uv](https://docs.astral.sh/uv/getting-started/installation/), first, clone the repo:
 
 ```bash
 # clone project
 git clone https://github.com/WUR-AI/aether
 cd aether
 ```
 
+Then, create a virtual environment (or alternatively via conda):
 ```bash
 # Create venv
 python3 -m venv .venv
 source .venv/bin/activate
 ```
 
+Then, install `uv` and use this to install all packages.
 ```bash
 # install uv manager
 pip install uv
@@ -52,9 +54,16 @@ Note, running `uv sync` in the venv will always update the package to the most u
 
 ### Set paths
 
-Next, create a file in your local repo parent folder `aether/` called `.env`. Copy the contents of `aether/env.example` and adjust the paths to your local system. **Important**: `DATA_DIR` should either point to `aether/data/` OR if it points to another folder (e.g., `my/local/data/`) then copy the contents of `aether/data/` to `my/local/data/` to ensure the butterfly use case runs using the provided example data. Other data will automatically be downloaded and organised by `pooch` if possible, or should be copied manually.
+Next, create a file in your local repo parent folder `aether/` called `.env` and copy the contents of `aether/.env.example`:
 
-Data folders should follow the following directory structure:
+```bash
+cp .env.example .env
+```
+Adjust the paths in `.env` to your local system. **At a minimum, you should set PROJECT_ROOT!**. 
+
+**Important**: `DATA_DIR` should either point to `aether/data/` (default setting) OR if it points to another folder (e.g., `my/local/data/`) then copy the contents of the `aether/data/` folder to `my/local/data/` to ensure the butterfly use case runs using the provided example data. Other data will automatically be downloaded and organised by `pooch` if possible into `DATA_DIR`, or should be copied manually.
+
+Data folders should follow the following directory structure within `DATA_DIR`:
 
 ```
 ├── registry.txt                         <- Pooch config file, don't change.
@@ -73,7 +82,18 @@ Data folders should follow the following directory structure:
 ├── other_dataset/
 ```
 
-### Training
+### Verify installation:
+
+To verify whether the installation was successful, run the tests in `aether/` using:
+```bash
+pytest --use-mock -m "not slow"
+```
+which should pass all tests.
+
+
+## Training
+
+Currently, we have implemented 2 models: a prediction model (that predicts target variables from EO data) and an alignment model (that aligns EO embeddings with text embeddings).
 
 Experiment configurations (such as choosing data, encoders, hyperparameters etc.) are managed through [Hydra](https://hydra.cc/) configurations. Define your experiment configurations in `configs/experiments/experiment_name.yaml`, for example to train predictive model with GeoCLIP coordinate encoder for the Butterfly data using `configs/experiments/prediction.yaml` (copied below)
 
@@ -112,6 +132,8 @@ To execute this experiment run (inside your venv):
 python train.py experiment=prediction
 ```
 
+Please see the [Hydra](https://hydra.cc/) and [Hydra-Lightning template](https://github.com/ashleve/lightning-hydra-template) documentation for further examples of how to configure training runs.
+
 ## Directory structure
 
 We follow the directory structure from the [Hydra-Lightning template](https://github.com/ashleve/lightning-hydra-template), which looks like:
@@ -136,7 +158,7 @@ We follow the directory structure from the [Hydra-Lightning template](https://gi
 │   ├── eval.yaml             <- Main config for evaluation
 │   └── train.yaml            <- Main config for training
 │
-├── data                   <- Project data
+├── data                   <- Project data (for aether, this can also be elsewhere, see environment paths).
 │
 ├── logs                   <- Logs generated by hydra and lightning loggers
 │

data/s2bms/caption_templates/v1.json

@@ -0,0 +1,15 @@
+[
+    "Location with <aux_corine_frac_top_1>, <aux_corine_frac_top_2> and <aux_corine_frac_top_3>.",
+    "Area with <aux_corine_frac_243> and <aux_corine_frac_322>.",
+    "Site with <aux_corine_frac_top_1> and <aux_corine_frac_top_2>, with <aux_bioclim_01> and <aux_bioclim_12>.",
+    "Location with <aux_corine_frac_top_1> and <aux_corine_frac_top_2>, with <aux_bioclim_05> and <aux_bioclim_06>.",
+    "Area with <aux_corine_frac_top_1> and <aux_corine_frac_top_2>, with <aux_bioclim_01> and <aux_bioclim_07>.",
+    "Site with <aux_corine_frac_top_1> and <aux_corine_frac_top_2>, with <aux_bioclim_13> and <aux_bioclim_14>.",
+    "Location with <aux_corine_frac_top_1> and <aux_corine_frac_top_2>, with <aux_bioclim_01>, <aux_bioclim_13> and <aux_bioclim_14>.",
+    "Area with <aux_corine_frac_top_1>, with <aux_bioclim_01> and <aux_bioclim_12>.",
+    "Site with <aux_corine_frac_top_1>, with <aux_bioclim_05> and <aux_bioclim_06>.",
+    "Location with <aux_corine_frac_top_1>, with <aux_bioclim_01> and <aux_bioclim_07>.",
+    "Area with <aux_corine_frac_top_1>, with <aux_bioclim_13> and <aux_bioclim_14>.",
+    "Site with <aux_corine_frac_top_1>, with <aux_bioclim_01>, <aux_bioclim_13> and <aux_bioclim_14>."
+
+]