Hazelbean

Hazelbean is a collection of geospatial processing tools based on gdal, numpy, scipy, cython, pygeoprocessing, taskgraph, natcap.invest, geopandas and many others to assist in common spatial analysis tasks in sustainability science, ecosystem service assessment, global integrated modelling assessment, natural capital accounting, and/or calculable general equilibrium modelling.

Requirements

  • Python 3.10 or later (Python 3.9 support was dropped as of version 1.4.0 due to NumPy 2.0 compatibility issues)

Hazelbean started as a personal research package of scripts for Justin Johnson and is was not originally intended for broad release. However, hazelbean is transitioning towards having full-support, primarily because it underlies several important software releases, including some from the Natural Capital Project. Thus, even in this transitory state, it is available via "pip install hazelbean". Note that hazelbean only provides a Python 3+, 64 bit, Windows version, however with the exception of precompiled cython files, it should be cross-platform and cross-version. The precompiled files are only loaded as needed.

Documentation

Our integrated documentation system provides comprehensive guides and examples:

  • ** Getting Started** - Complete setup guide with current project structure
  • ** Testing Guide** - Test infrastructure overview
  • ** Examples** - Hands-on tutorials and demonstrations

Local Documentation Site

Hazelbean's user documentation is published as the Hazelbean section of the Earth-Economy Devstack site:

Those pages live in earth_economy_devstack/docs/ and are rendered by the devstack site build. The standalone docs-site/ that used to duplicate them has been removed.

Quick Start

Option 1: Complete Environment (Recommended)

# 1. Clone repository and setup complete environment
git clone https://github.com/jandrewjohnson/hazelbean_dev.git
cd hazelbean_dev

# 2. Create environment from included configuration
mamba env create -f environment.yml
mamba activate hazelbean_env

# 3. Install hazelbean package (builds Cython extensions)
pip install -e . --no-deps

# 4. Verify installation (checks Cython extensions)
python scripts/verify_installation.py

# 5. Try educational examples
cd examples && python step_1_project_setup.py

# 6. Explore documentation locally
cd ../../earth_economy_devstack/docs && quarto preview  # devstack docs, incl. the Hazelbean section

Important Notes:

  • Step 3 compiles Cython extensions for your platform (Windows/Mac/Linux)
  • Step 4 verifies everything is working correctly and provides troubleshooting guidance if needed
  • The --no-deps flag prevents pip from reinstalling conda packages (correct for conda+pip hybrid environments)

Windows Users: If Step 3 fails with compiler errors, see the Windows Setup Guide for detailed instructions on installing build tools.

Option 2: Package Only

# Basic installation for using Hazelbean in existing environment
mamba install -c conda-forge natcap.invest geopandas pygeoprocessing taskgraph cython
pip install hazelbean

Next steps: Explore the examples/ directory for guided learning.

Detailed Installation Notes

Prerequisites

Troubleshooting

Cython Compilation Errors (Windows): If you see ImportError: cannot import name 'cython_functions' or compiler errors during installation:

  1. Quick Fix (Recommended): Install conda compiler tools:

    conda activate hazelbean_env
conda install -c conda-forge m2w64-toolchain libpython
pip install -e . --no-deps --force-reinstall

  2. Alternative: Install Microsoft Visual Studio Build Tools:

  3. Verify: Run python scripts/verify_installation.py to check if Cython extensions are working

See Windows Setup Guide for detailed troubleshooting.

Numpy Compatibility Issues: If numpy throws "wrong size or changes size binary" errors, upgrade numpy after installation:

mamba update numpy

See details: https://stackoverflow.com/questions/66060487/valueerror-numpy-ndarray-size-changed-may-indicate-binary-incompatibility-exp

macOS Permissions: Your Python environment needs permissions to access and write to the base data folder. Grant necessary permissions in System Preferences if needed.

More information

See the author's personal webpage, https://justinandrewjohnson.com/ for more details about the underlying research.

Project Flow

One key component of Hazelbean is that it manages directories, base_data, etc. using a concept called ProjectFlow. ProjectFlow defines a tree of tasks that can easily be run in parallel where needed and keeping track of task-dependencies. ProjectFlow borrows heavily in concept (though not in code) from the task_graph library produced by Rich Sharp but adds a predefined file structure suited to research and exploration tasks.

Project Flow notes

Project Flow is intended to flow easily into the situation where you have coded a script that grows and grows until you think "oops, I should really make this modular." Thus, it has several modalities useful to researchers ranging from simple drop-in solution to complex scripting framework.

Notes

In run.py, initialize the project flow object. This is the only place where user supplied (possibly absolute but can be relative) path is stated. The p ProjectFlow object is the one global variable used throughout all parts of hazelbean.

import hazelbean as hb

if __name__ == '__main__':
    p = hb.ProjectFlow(r'C:\Files\Research\cge\gtap_invest\projects\feedback_policies_and_tipping_points')

In a multi-file setup, in the run.py you will need to import different scripts, such as main.py i.e.:

import visualizations.main

The script file mainpy can have whatever code, but in particular can include "task" functions. A task function, shown below, takes only p as an agrument and returns p (potentially modified). It also must have a conditional (if p.run_this:) to specify what always runs (and is assumed to run trivially fast, i.e., to specify file paths) just by nature of having it in the task tree and what is run only conditionally (based on the task.run attribute, or optionally based on satisfying a completed function.)

def example_task_function(p):
    """Fast function that creates several tiny geotiffs of gaussian-like kernels for later use in ffn_convolve."""

    if p.run_this:
        for i in computationally_intensive_loop:
            print(i)

Important Non-Obvious Note

Importing the script will define function(s) to add "tasks", which take the ProjectFlow object as an argument and returns it after potential modification.

def add_all_tasks_to_task_tree(p):
    p.generated_kernels_task = p.add_task(example_task_function)

Creating a New Release

Hazelbean uses a fully automated release pipeline that publishes to both PyPI and conda-forge. The entire process is triggered by creating a GitHub Release.

Quick Steps

  1. Create and push a git tag:

    VERSION="1.7.7"  # Your version number
git tag -a "v${VERSION}" -m "Release version ${VERSION}"
git push origin "v${VERSION}"

  2. Create a GitHub Release at https://github.com/jandrewjohnson/hazelbean_dev/releases

    • Select your tag
    • Add release notes
    • Click "Publish release"

  3. Automation takes over:

    • GitHub Actions builds wheels for all platforms (~20 minutes)
    • Automatically uploads to PyPI
    • Updates CHANGELOG.md
    • conda-forge bot detects the release (~24 hours)
    • Review and merge the conda-forge PR
    • conda-forge builds and publishes packages (~2 hours)

Complete Release Documentation

For detailed information about the release process:

No manual PyPI uploads needed! The old manual process with twine is deprecated - everything is automated through GitHub Actions.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for jandrewjohnson from gravatar.com jandrewjohnson

Credits

Author/Maintainer: Justin Andrew Johnson

License

https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode

Requires

Python >=3.10

Provides Extra

test

Tags

gis geospatial economics land use

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hazelbean-2.0.0.tar.gz (10.6 MB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

hazelbean-2.0.0-cp313-cp313-win_amd64.whl (1.7 MB view details)

Uploaded CPython 3.13Windows x86-64

hazelbean-2.0.0-cp313-cp313-macosx_11_0_arm64.whl (1.7 MB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

hazelbean-2.0.0-cp312-cp312-win_amd64.whl (1.7 MB view details)

Uploaded CPython 3.12Windows x86-64

hazelbean-2.0.0-cp312-cp312-macosx_11_0_arm64.whl (1.7 MB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

hazelbean-2.0.0-cp311-cp311-win_amd64.whl (1.7 MB view details)

Uploaded CPython 3.11Windows x86-64

hazelbean-2.0.0-cp311-cp311-macosx_11_0_arm64.whl (1.7 MB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

hazelbean-2.0.0-cp310-cp310-win_amd64.whl (1.7 MB view details)

Uploaded CPython 3.10Windows x86-64

hazelbean-2.0.0-cp310-cp310-macosx_11_0_arm64.whl (1.7 MB view details)

Uploaded CPython 3.10macOS 11.0+ ARM64

File details

Details for the file hazelbean-2.0.0.tar.gz.

File metadata

  • Download URL: hazelbean-2.0.0.tar.gz
  • Upload date:
  • Size: 10.6 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.12.13

File hashes

Hashes for hazelbean-2.0.0.tar.gz
Algorithm Hash digest
SHA256 a65b0c6a01080278aa8d0dfacf841c4cebd9b8bacb68e7258b984f56614ce4d1
MD5 3979f40ba1e7f9acfd2911eb0b3f2058
BLAKE2b-256 8776cf2f38bd29feb232763394e689df5f6bae9b39bf82a6a0a668a666c0f1d9

See more details on using hashes here.

File details

Details for the file hazelbean-2.0.0-cp313-cp313-win_amd64.whl.

File metadata

  • Download URL: hazelbean-2.0.0-cp313-cp313-win_amd64.whl
  • Upload date:
  • Size: 1.7 MB
  • Tags: CPython 3.13, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for hazelbean-2.0.0-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 94b707eca9d517c2e4092287ec8573bd00e5fc59b41abfc25678475e68fca96f
MD5 6e804359041457a9bb6fba5004e4a3b7
BLAKE2b-256 95063c2ae3db580ea11af655671f45ae1358077e029781371505dc46fe9d1379

See more details on using hashes here.

File details

Details for the file hazelbean-2.0.0-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for hazelbean-2.0.0-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 2f432f13d53935b5fdad101da04ed75aa54abbf437834b9af81447a99195659f
MD5 79d79b39e0cb8d6cdd751c1fa217dcac
BLAKE2b-256 32e203633cb34986a82ccbd4ca36201b30aab1af14a6db3975145b2412aefcb6

See more details on using hashes here.

File details

Details for the file hazelbean-2.0.0-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: hazelbean-2.0.0-cp312-cp312-win_amd64.whl
  • Upload date:
  • Size: 1.7 MB
  • Tags: CPython 3.12, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.12.13

File hashes

Hashes for hazelbean-2.0.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 359d1c74668af415697e787cad575a61ab3c737d34f3482f02e322ba9f6aae13
MD5 cf76525293113f0373f292fc25f56468
BLAKE2b-256 fc14514a7c9714365becba12ddf3df5eac52d004bd18b6d25db5b2258b18d395

See more details on using hashes here.

File details

Details for the file hazelbean-2.0.0-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for hazelbean-2.0.0-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 e7d79a02b1fae6a73bb37aa7aaf439d1f8e0a5834a99921e8160ed6ba1382e81
MD5 340d649d798d45bae92eb071a7db138f
BLAKE2b-256 5c0e7289f2510c94d8cac6b7412535ec4c13d412875bc8ebd34317058130c33c

See more details on using hashes here.

File details

Details for the file hazelbean-2.0.0-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: hazelbean-2.0.0-cp311-cp311-win_amd64.whl
  • Upload date:
  • Size: 1.7 MB
  • Tags: CPython 3.11, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.11.15

File hashes

Hashes for hazelbean-2.0.0-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 cc0e2ecdbc1c250bfd985592ada53301a2f350fda89205eea266fd36532b9255
MD5 63b4e76f1aa8b9cb39dca9ba2518d2a8
BLAKE2b-256 33c6a053ab6f94a998eaccdd605d94808d4e09c5896189b056ac38551f600f9c

See more details on using hashes here.

File details

Details for the file hazelbean-2.0.0-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for hazelbean-2.0.0-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 086f67cc3f0235e5cb92f31b757dc967ef59b7f44285a5df8216931bec53fec2
MD5 4b786e597b58aa4e808299b89a28588a
BLAKE2b-256 3ae793b265f9336b965b25b22a38ab59b46346532cf17aad27c9ae770bb129d1

See more details on using hashes here.

File details

Details for the file hazelbean-2.0.0-cp310-cp310-win_amd64.whl.

File metadata

  • Download URL: hazelbean-2.0.0-cp310-cp310-win_amd64.whl
  • Upload date:
  • Size: 1.7 MB
  • Tags: CPython 3.10, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.10.20

File hashes

Hashes for hazelbean-2.0.0-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 abe423b4139f77ed0f87e72085440267011ec80e203ca4c42613af10c73ed058
MD5 397ede7d654259487f43bfdcc4debb63
BLAKE2b-256 7e9f15f06ab8720a5f85797fe0ad893daba95a50a495587bedf33a2516441b45

See more details on using hashes here.

File details

Details for the file hazelbean-2.0.0-cp310-cp310-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for hazelbean-2.0.0-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 b62025816e464eac5b5d27aba341a8c8495f68c71dd4443d289bd0b478b18f81
MD5 426db842cd4d751cb4fa24686682b123
BLAKE2b-256 10d23f2c04eddfa6dcbe684caceabb2bf29a62b1447bca9c9f776028a57f1d35

See more details on using hashes here.

Release history Release notifications | RSS feed

This release

2.0.0 This release

9 files

1.8.0

9 files

1.7.9

9 files

1.7.8

9 files

1.7.7

9 files

1.7.6

11 files

1.7.5

11 files

1.7.4

11 files

1.7.3

11 files

1.7.2

11 files

1.7.1

11 files

1.7.0

11 files

1.6.9

11 files

1.6.8

10 files

1.6.7

10 files

1.6.4

10 files

1.6.3

10 files

1.6.1

10 files

1.6.0

11 files

1.5.2

2 files

1.5.1

2 files

1.5.0

2 files

1.4.9

2 files

1.4.8

2 files

1.4.7

2 files

1.4.6

2 files

1.4.5

2 files

1.4.4

2 files

1.4.3

2 files

1.4.2

2 files

1.4.1

2 files

1.4.0

2 files

1.3.9

2 files

1.3.8

2 files

1.3.7

2 files

1.3.6

2 files

1.3.4

2 files

1.3.3

2 files

1.3.2

3 files

1.3.0

2 files

1.2.9

2 files

1.2.8

2 files

1.2.7

2 files

1.2.6

2 files

1.2.5

2 files

1.2.4

2 files

1.2.3

2 files

1.2.2

2 files

1.2.1

2 files

1.2.0

2 files

1.1.9

2 files

1.1.8

2 files

1.1.7

2 files

1.1.6

2 files

1.1.5

2 files

1.0.9

2 files

1.0.8

2 files

1.0.7

2 files

1.0.6

2 files

1.0.2

2 files

1.0.1

2 files

1.0.0

2 files

0.9.9

2 files

0.9.8

2 files

0.9.7

2 files

0.9.6

2 files

0.9.5

2 files

0.9.4

2 files

0.9.3

2 files

0.9.2

2 files

0.9.1

2 files

0.9.0

2 files

0.8.8

2 files

0.8.7

2 files

0.8.6

2 files

0.8.5

2 files

0.8.4

2 files

0.8.3

2 files

0.8.0

2 files

0.7.9

2 files

Pre-release

0.7.9.dev1

2 files

0.7.8

1 file

Pre-release

0.7.8.dev4

1 file

Pre-release

0.7.8.dev3

2 files

Pre-release

0.7.8.dev1

1 file

0.7.6

1 file

0.7.5

1 file

0.7.4

1 file

0.7.2

2 files

0.7.0

2 files

0.6.9

2 files

0.6.8

2 files

0.6.7

2 files

0.6.6

2 files

0.6.5

2 files

0.6.4

2 files

0.6.3

2 files

0.6.2

2 files

0.6.1

2 files

0.6.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page