Tutorial Examples: Complete Workflow Progression

Welcome to the Hazelbean tutorial series! This comprehensive learning journey takes you through the entire geospatial processing workflow, from initial project setup to professional result organization.

Learning Path Overview

Progressive Learning

Each step builds on the previous ones. Complete them in order for the best learning experience.

Step	Topic	Learning Time	Key Concepts
1	Project Setup	5 minutes	ProjectFlow, Directory Structure
2	Data Loading	10 minutes	get_path(), File Discovery, Raster Info
3	Processing	15 minutes	Array Operations, Transformations
4	Analysis	20 minutes	Spatial Analysis, Multi-raster Operations
5	Export Results	15 minutes	Professional Organization, Documentation

Total Learning Time: ~65 minutes

Step 1: Project Setup

Learning Time: 5 minutes
Prerequisites: Basic Python knowledge
Difficulty: Beginner

Learning Objectives

By completing this step, you will:

Initialize a Hazelbean ProjectFlow for organized geospatial workflows
Understand the intelligent directory structure that Hazelbean creates
Master the data discovery hierarchy and how get_path() searches for files
Build the foundation for all subsequent Hazelbean projects

Key Takeaway

ProjectFlow is the foundation of every Hazelbean workflow. It creates an organized directory structure and provides intelligent file path resolution that makes your analysis reproducible and professional. Think of it as your “project manager” that keeps everything organized automatically.

Real-World Application

In research and professional work, you’ll often work with multiple datasets across different projects. ProjectFlow ensures that your analysis remains organized and reproducible, whether you’re analyzing land cover changes, environmental impact assessments, or climate modeling.

Example Code

"""
Step 1: Project Setup and Directory Management
Learn how to initialize a Hazelbean ProjectFlow for organized geospatial workflows.
"""

import os
import hazelbean as hb

def main():
    """
    Demonstrates ProjectFlow initialization and basic project organization.
    """
    
    # Create a new project with automatic directory structure
    project_name = 'hazelbean_tutorial'
    # Keyword, not positional: the first positional argument is project_dir, so
    # hb.ProjectFlow(project_name) would create a bare relative directory here.
    p = hb.ProjectFlow(project_name=project_name)
    
    print("=== Hazelbean Project Setup Demo ===")
    print(f"Project name: {project_name}")
    print(f"Project directory: {p.project_dir}")
    
    # ProjectFlow automatically creates these standard directories:
    print("=== Standard Project Directories ===")
    print(f"Input directory: {p.input_dir}")
    print(f"Intermediate directory: {p.intermediate_dir}")
    print(f"Output directory: {p.output_dir}")
    
    # Show data discovery paths
    print("=== Data Discovery Hierarchy ===")
    print("When you use p.get_path(), Hazelbean searches in this order:")
    print(f"1. Base data directory: {p.base_data_dir}")
    print(f"2. Model base data directory: {p.model_base_data_dir}")
    print(f"3. Project base data directory: {p.project_base_data_dir}")
    print(f"4. Current directory: {p.project_dir}")
    
    print("Project setup complete!")
    print("Next: Run step_2_data_loading.py")

if __name__ == "__main__":
    main()

Step 2: Data Loading

Learning Time: 10 minutes
Prerequisites: Completed Step 1 (Project Setup)
Difficulty: Intermediate

Learning Objectives

By completing this step, you will:

Master Hazelbean’s intelligent file discovery system with get_path()
Load and examine geospatial raster data efficiently
Understand raster metadata and properties for analysis planning
Handle missing data scenarios gracefully with fallback patterns

Pro Insight

get_path() is Hazelbean’s “smart search engine” for your files. It searches through multiple data directories automatically, following an intelligent hierarchy:

Project-specific directories first
Base data directories
Model-wide data repositories
Current working directory as fallback

This means your code works whether data is local to your project, shared across projects, or in a centralized data repository.

Example Code

Note

Run the step_2_data_loading.py script from the examples/ directory to explore data loading capabilities. The script demonstrates intelligent file discovery and raster metadata extraction.

Step 3: Processing

Learning Time: 15 minutes
Prerequisites: Completed Steps 1-2 (Setup & Data Loading)
Difficulty: Intermediate

Learning Objectives

By completing this step, you will:

Apply mathematical operations to raster data efficiently
Perform coordinate transformations between spatial reference systems
Create derived datasets through raster calculations
Handle different data types and scaling factors appropriately

Critical Concept

Spatial Reference Systems (CRS) are fundamental to geospatial analysis:

Always verify your coordinate reference systems when combining datasets
Different CRS can make data appear misaligned even when geographically correct
Hazelbean helps with transformations, but understanding your data’s spatial properties prevents analysis errors
Rule of thumb: Match all datasets to the same CRS before analysis

Technical Deep Dive

Raster processing involves working with multi-dimensional arrays where each cell represents a geographic location. Understanding data types (float32 vs int16), no-data values, and scaling factors ensures your mathematical operations produce meaningful results.

Example Code

Note

Run the step_3_basic_processing.py script from the examples/ directory to learn about raster processing operations and coordinate transformations.

Step 4: Analysis

Learning Time: 20 minutes
Prerequisites: Completed Steps 1-3 (Setup, Data Loading, Basic Processing)
Difficulty: Advanced

Learning Objectives

By completing this step, you will:

Combine multiple raster datasets in sophisticated spatial analysis
Perform zonal statistics and regional summaries for insights
Create classification maps and derived analytical products
Handle complex analytical workflows efficiently and reproducibly

Real-World Applications

This step demonstrates patterns you’ll use for:

Land Cover Analysis: Classify land use types and track changes over time
Change Detection: Compare datasets across different time periods
Environmental Impact: Assess how human activities affect natural systems
Regional Planning: Analyze patterns within administrative or ecological boundaries
Resource Management: Quantify natural resources within specific regions

Analysis Philosophy

Multi-raster operations represent the core of spatial analysis. You’re not just processing individual datasets, but discovering relationships and patterns that emerge when data sources are combined intelligently.

Example Code

Note

Run the step_4_analysis.py script from the examples/ directory to explore advanced spatial analysis techniques including zonal statistics and multi-raster operations.

Step 5: Export Results

Learning Time: 15 minutes
Prerequisites: Completed Steps 1-4 (Complete analysis workflow)
Difficulty: Beginner (concepts) / Advanced (best practices)

Learning Objectives

By completing this step, you will:

Organize analysis outputs in professional directory structures
Create comprehensive documentation and metadata for reproducibility
Generate detailed analysis reports with clear summaries and insights
Establish reproducible workflows for sharing and collaboration

Professional Best Practice

Documentation and organization are just as important as the analysis itself. Well-organized results with clear documentation:

Enable collaboration with colleagues and stakeholders
Ensure reproducibility for future research and validation
Facilitate peer review and publication processes
Save time when you return to a project months later
Build credibility in professional and academic settings

Career Impact

Professional result organization distinguishes expert practitioners:

Junior level: Focuses on getting the analysis to work
Intermediate level: Produces clean code and basic documentation
Expert level: Creates comprehensive, self-documenting workflows that others can build upon

This step teaches expert-level practices that make your work valuable beyond the immediate analysis.

Example Code

Note

Run the step_5_export_results.py script from the examples/ directory to learn best practices for organizing and documenting your analysis results.

Quick Start Guide

Ready to Begin?

Prerequisites:

Python environment with Hazelbean installed
Basic familiarity with Python programming
Understanding of geospatial data concepts (helpful but not required)

Setup Instructions:

# Activate your environment
conda activate <your_env>

# Navigate to examples directory
cd hazelbean_dev/examples/

# Run the first tutorial
python step_1_project_setup.py

# Alternative: Run from anywhere with full path
python ~/path/to/hazelbean_dev/examples/step_1_project_setup.py

REM Activate your environment
conda activate <your_env>

REM Navigate to examples directory
cd hazelbean_dev\examples\

REM Run the first tutorial  
python step_1_project_setup.py

REM Alternative: Run from anywhere with full path
python C:\path\to\hazelbean_dev\examples\step_1_project_setup.py

# Activate your environment
conda activate <your_env>

# Navigate to examples directory
cd hazelbean_dev/examples/

# Run the first tutorial
python step_1_project_setup.py

# Alternative: Make executable and run directly
chmod +x step_1_project_setup.py
./step_1_project_setup.py

Learning Support

Need Help?

Got stuck? Each example includes error handling and fallback options
Want more detail? Check the comprehensive docstrings in each function
Ready for more? Explore the Test Documentation for advanced patterns
Have questions? Review the source code directly in the examples/ directory

Next Steps

After completing this tutorial series, you’ll be ready to:

Build your own geospatial analysis workflows
Integrate Hazelbean with other geospatial libraries
Contribute to the Hazelbean project
Explore advanced features in the full documentation

This educational content is maintained in sync with the latest example code to ensure accuracy and currency.