Installation

Installation#

This guide covers how to install and configure the geodata package for local and cloud use.

Make sure that you have the following software set up:

  • Python 3

  • Package Management System (Optional but highly recommended to isolate individual projects dependent packages)

    • conda (miniconda or anaconda)

Note

The majority of the content below applies to macOS and Linux. Any possible differences for Windows users are noted. Nontheless, it is worth noting that using geodata on Windows may present some additional challenges due to its file access properties.

Thus, it is recommended to use geodata a Linux-based system. If you are using Windows, you may want to consider using the Windows Subsystem for Linux (WSL) or a virtual machine.

Downloading Geodata#

To install geodata, open a terminal/shell window and run the following:

pip install geodata-re

Advanced: Installing from Source#

If you want to install geodata from source, you can clone the repository and install it using the following commands:

git clone https://github.com/GeodataTools/geodata.git
pip install geodata/

Configuring File Storage Location#

To configure where to store downloaded and processed files, define an environment variable called GEODATA_ROOT and save in your shell configuration files, such as .bashrc or .zshrc:

export GEODATA_ROOT=<YOUR_PATH_HERE>

Note

If you are using a Windows machine, you can set the environment variable by running the following command in the command prompt:

setx GEODATA_ROOT <YOUR PATH HERE>

If you are running geodata in a Jupyter Notebook, you could define the variable by adding and running the following cell:

%setenv GEODATA_ROOT <YOUR PATH HERE>

If you do not define this variable, all datasets and cutouts will be stored under ~/.local/geodata by default.

Note

Once you run geodata, the package will several folders under the GEODATA_ROOT directory. The following folders will be created:

  • cutouts: Contains the cutouts of the datasets

  • era5: Contains the downloaded ERA5 datasets

  • merra2: Contains the downloaded MERRA2 datasets

  • masks: Contains the created masks

  • models: Contains the computed interpolated/extrapolated wind speed models

  • gebco: Contains the downloaded GEBCO datasets

Anaconda/miniconda Environment#

Anaconda/miniconda is a powerful package manager and environment manager for Windows, macOS or Linux, and it provides easy installation for all operating systems. It is especially convenient if you are building Geodata on the cloud with potential installation permission issues.

If you already have Anaconda/miniconda installed on your machine, jump straight to the conda activate step. Otherwise, you have 2 options: download Anaconda or miniconda. Installing Anaconda requires >3GB disk space and takes minutes to download, so we will choose miniconda instead because is a small, bootstrap version of Anaconda that includes only conda, Python, the packages they depend on, and a small number of other useful packages.

If you have conda 4.6 or later versions, in the terminal/shell, run the following command below to activate the conda environment.

conda create --name geodata python=3.12
conda activate <ENVIRONMENT_NAME>
pip install geodata-re

Once you activate the environment, any packages you install (including geodata) will be isolated. If you have a new project and wish to start over again, you can create a new environment and install the package again.

conda deactivate
conda env remove --name geodata