Accessing DE Africa Data and Functionality via Local Environments

Directly accessing Digital Earth Africa (DE Africa) data in a local environment also provides significant advantages, including the flexibility to configure compute resources on your own machine and the ability to integrate DE Africa datasets with user-generated or third-party data. Beyond the DE Africa Sandbox, users can install Python locally and run DE Africa workflows in environments such as Jupyter Notebook, JupyterLab, or even Python IDLE. For more advanced applications, DE Africa workflows can also be integrated into Python-based web services such as Django or Flask, enabling the development of interactive dashboards, APIs, and decision-support tools. This approach gives users full control over package installation, storage, and processing while extending DE Africa capabilities into web and operational systems.

Getting Started in a Local Environment

Before you can use DE Africa Direct Access locally, make sure the necessary software is installed.

Using Anaconda is recommended because it simplifies environment management and brings most required packages into one place.

1. Install Anaconda

📥 Download Anaconda for Windows, macOS, and Linux

After installation, open your Anaconda terminal (Command Prompt on Windows, Terminal on macOS/Linux) and create a new environment:

conda create -n deafrica_env python=3.12
conda activate deafrica_env

2. Install packages into the conda environment

We will install required packages using conda in small batches to manage the memory footprint of the installation tasks and simplify environment solving. To do this, procees through the following commands in the Anaconda terminal.

2.1 Begin with core geospatial packages

conda install -c conda-forge gdal geopandas rasterio fiona pyproj shapely

2.2 Jupyter and plotting

conda install -c conda-forge ipykernel matplotlib session-info jupyterlab

2.3 ODC & STAC

conda install -c conda-forge odc-stac odc-algo pystac

2.4 OSMnx

conda install -c conda-forge osmnx

2.5 xarray

conda install -c conda-forge xarray

3. Open JupyterLab

Run the following in your Anaconda terminal:

jupyter lab

4. Start with DE Africa direct access notebooks

Navigate to DE Africa Loading Demonstration notebook and upload it into your newly created Jupyter environment to try running it. Alternatively, you could also clone the direct access repository into a local directory you’d like to use.

Once you’ve confirmed that the loading demonstration notebook is working as expected, you can experiment with other notebooks.

Selecting the Kernel in Jupyter Notebook

When you open a notebook in Jupyter Notebook, you need to make sure it is using the correct kernel (the Python environment where you installed your DE Africa packages).

Steps to Select the Kernel:

Open Jupyter Notebook by running in your terminal:
```
jupyter notebook
```
From the Jupyter interface, open the notebook you want to run.
Go to the top menu bar and select: Kernel → Change kernel → Python (deafrica_env) (or the name of the environment you created).
The notebook will now run using that environment, with access to the installed DE Africa packages.

⚠️ Tip: If you don’t see your environment listed, make sure you have installed the kernel spec with:

pip install ipykernel
python -m ipykernel install --user --name=deafrica_env --display-name "Python (deafrica_env)"

Then restart Jupyter Notebook and check again under Kernel → Change kernel

hdstats build error (Windows/macOS/Linux)

Symptom note: Failed building wheel for hdstats ERROR: Failed to build installable wheels for some pyproject.toml based projects (hdstats)

✅ Here’s how to fix it:

🔧 Step 1: Install Microsoft C++ Build Tools

Go to this link: 👉 Visual Studio

Step 2: Click Download Build Tools

Step 3: When the installer launches:

Select “C++ build tools”
Make sure “Windows 10 SDK” or “Windows 11 SDK” is also checked
Click Install
Once installed, restart your system (recommended)

Local Environment vs Cube-in-a-Box

Running DE Africa Direct Access in a local environment (e.g., installing Python and using Jupyter Notebook or JupyterLab) is different from using Cube-in-a-Box.

In a local setup, you install the necessary Python packages and run notebooks directly on your own machine. This gives you flexibility and control, but some ODC core functionalities (e.g., dc.load) may not be fully available without additional setup.
Cube-in-a-Box, on the other hand, comes prepackaged with a complete Open Data Cube (ODC) environment, fully configured inside a Docker container. This setup includes all ODC core functionality out-of-the-box and is designed for users who want a ready-to-use, fully featured data cube environment.

👉 If you want more information on Cube-in-a-Box, check it here: Cube-in-a-Box Documentation

Accessing DE Africa Tools in a Local Environment

In addition to cloud platforms, many of the tools and functions available in the DE Africa Sandbox can also be used in a local environment once the required packages are installed.
This means you can run workflows directly on your own machine using Jupyter Notebook, JupyterLab, or even Python IDLE.
For more advanced applications, DE Africa tools can also be integrated into Python web frameworks such as Django or Flask, enabling the development of interactive dashboards, APIs, and decision-support tools.

Examples of available functions include:

deafrica_display_map for interactive map visualization.
deafrica_rgb plotting functions for quick rendering of satellite imagery.
calculate_indices for computing vegetation, water, and other spectral indices.
xr_rasterize for converting vector data to raster grids.

As demonstrated in the loading notebook — and other example notebooks — these functions run effectively in local environments, making it possible to replicate Sandbox workflows while maintaining full control over your compute resources, storage, and package management.

⚠️ Note: Local environments do not come preconfigured with a full ODC core setup (unlike Cube-in-a-Box or the Sandbox).

Functions that depend on ODC (e.g., dc.load and load_ard) will not work without additional configuration.

However, most functions that rely on common Python libraries such as xarray, geopandas, and scipy are fully supported and run without issue.

Local environments are ideal for users who want full customization, offline control, and the flexibility to integrate DE Africa workflows into larger applications while still benefiting from the majority of DE Africa tools outside the Sandbox.

Conclusion

Using DE Africa Direct Access in a local environment such as Python with Jupyter Notebook, JupyterLab, or Python IDLE provides users with flexibility beyond the Sandbox. Moreover, the integration of DE Africa workflows into Python web frameworks like Django or Flask opens up opportunities to build interactive dashboards, web applications, and decision-support tools. While certain ODC-dependent workflows may require additional setup, most DE Africa tools and functions run effectively in these environments. This versatility enables researchers, developers, and institutions to create reproducible, scalable, and operational workflows, combining DE Africa datasets with other sources to support innovation and real-world decision-making.

💡 Feedback

If you have any feedback on DE Africa data and services, please contact us at:

📧 helpdesk@digitalearthafrica.org

🚀 Looking Ahead

The DE Africa team will continue to improve these tools and services to make it easier for users to flexibly access, analyze, and integrate data in the environments of their choice.