diff --git a/.env.example b/.env.example index 8502ad5..33713cb 100644 --- a/.env.example +++ b/.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" diff --git a/.gitignore b/.gitignore index b386629..0bec17c 100644 --- a/.gitignore +++ b/.gitignore @@ -226,4 +226,5 @@ uv.lock # Directories and files notebooks/01-TvdP-tmp.ipynb */source/* -*.tif \ No newline at end of file +*.tif # for now +..env.swp diff --git a/README.md b/README.md index 180bd29..c75c605 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ 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 @@ -31,12 +31,14 @@ 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 │ diff --git a/data/s2bms/caption_templates/v1.json b/data/s2bms/caption_templates/v1.json new file mode 100644 index 0000000..128ae6f --- /dev/null +++ b/data/s2bms/caption_templates/v1.json @@ -0,0 +1,15 @@ +[ + "Location with , and .", + "Area with and .", + "Site with and , with and .", + "Location with and , with and .", + "Area with and , with and .", + "Site with and , with and .", + "Location with and , with , and .", + "Area with , with and .", + "Site with , with and .", + "Location with , with and .", + "Area with , with and .", + "Site with , with , and ." + +]