landuse-intensity-analysis 2.0.0a6

Comprehensive LULC change analysis with Pontius-Aldwaik intensity methodology. Generate 24 types of publication-ready scientific visualizations from raw raster data in minutes. Complete workflow automation with memory optimization for large datasets. Perfect for researchers, environmental scientists, and GIS analysts.

🌍 LULC Package - Land Use Land Cover Intensity Analysis

The first comprehensive Python library for rigorous LULC change analysis. Generate 24 types of publication-ready scientific visualizations in minutes using the peer-reviewed Pontius-Aldwaik intensity methodology.

🎯 Perfect for: Researchers • Environmental Scientists • GIS Analysts • PhD Students • Policy Analysts

---

✨ Why LULC Package?

• 📊 Complete Analysis: Interval, Category, and Transition-level intensity analysis
• 🎨 24 Plot Types: Publication-ready visualizations with academic formatting
• ⚡ Performance: Analyze complete datasets in <60 seconds
• 🧠 Memory Optimized: Handle large rasters (>1GB) efficiently
• 🔬 Scientifically Rigorous: Exact implementation of Pontius-Aldwaik methodology
• 📚 Zero Learning Curve: Complete analysis in 3 lines of code

---

🚀 Quick Start

Installation

pip install landuse-intensity-analysis

Complete Analysis in 3 Lines

import landuse_intensity as lui

# Create analyzer with your raster files
analyzer = lui.LULCAnalysis(
    raster_stack=["landuse_2000.tiff", "landuse_2010.tiff", "landuse_2020.tiff"],
    years=[2000, 2010, 2020]
)

# Generate complete analysis with all visualizations
results = analyzer.intensity_analysis()

# Export publication-ready report
lui.create_complete_analysis_report(results, output_dir="my_analysis/")

Result: 24 publication-ready visualizations + comprehensive scientific report

---

🎯 Tutorial - Complete Workflow

Run our executable tutorial with real Rio de Janeiro data:

# Navigate to examples directory
cd example_data

# Run complete tutorial (generates 29 outputs in <60 seconds)
python tutorial_executavel.py

What you get:

• ✅ 8 Interval-level intensity plots
• ✅ 8 Category-level intensity plots
• ✅ 8 Transition-level intensity plots
• ✅ 5 Sankey diagrams
• ✅ Interactive HTML + static PNG outputs
• ✅ Scientific interpretation and insights

---

AnalyzerFactory,      # Factory pattern for creating analyzers
AnalyzerManager,      # Central management of analysis workflows
# Core analysis functions
transition_matrix_calculation,
loss_gain_table,
interval_level_analysis,
category_level_analysis,
transition_level_analysis,
# Visualization functions
plot_sankey,
plot_transition_matrix_heatmap,
plot_loss_gain_bar,
plot_comprehensive_analysis,
# Statistics and utilities
calculate_statistics,
export_results

)

### Main Components

#### AnalyzerFactory

Creates different types of analyzers based on your needs:

```python
# Create an intensity analyzer
analyzer = AnalyzerFactory.create_analyzer("intensity")

# Create a multi-step analyzer
multi_analyzer = AnalyzerFactory.create_analyzer("multi_step")

# Create a change analyzer
change_analyzer = AnalyzerFactory.create_analyzer("change")

AnalyzerManager

Manages the complete analysis workflow:

# Initialize manager
manager = AnalyzerManager()

# Add multiple datasets
manager.add_dataset("2000", data_2000)
manager.add_dataset("2010", data_2010)
manager.add_dataset("2020", data_2020)

# Run comprehensive analysis
results = manager.run_analysis(output_dir="./results/")

---

🔬 Analysis Methods

Standard Intensity Analysis

# Load your raster data
from landuse_intensity.processing import read_raster

data_2000, profile_2000 = read_raster("landuse_2000.tiff")
data_2010, profile_2010 = read_raster("landuse_2010.tiff")

# Calculate transition matrix
transition_matrix = transition_matrix_calculation(data_2000, data_2010)

# Perform interval-level analysis
interval_results = interval_level_analysis(transition_matrix)

# Perform category-level analysis  
category_results = category_level_analysis(transition_matrix)

# Perform transition-level analysis
transition_results = transition_level_analysis(transition_matrix)

Multi-Period Analysis

# Analyze multiple time periods
datasets = {
    "2000": data_2000,
    "2005": data_2005, 
    "2010": data_2010,
    "2015": data_2015,
    "2020": data_2020
}

manager = AnalyzerManager()
for year, data in datasets.items():
    manager.add_dataset(year, data)

# Run analysis for all periods
results = manager.run_analysis(
    output_dir="./multi_period_results/",
    generate_plots=True,
    export_excel=True
)

Advanced Spatial Analysis

from landuse_intensity.plots.spatial_plots import (
    plot_change_map,
    plot_persistence_map,
    plot_transition_hotspots
)

# Generate spatial change maps
plot_change_map(data_2000, data_2010, save_path="change_map.png")

# Show areas of persistence vs change
plot_persistence_map(data_2000, data_2010, save_path="persistence.png")

# Identify transition hotspots
plot_transition_hotspots(data_2000, data_2010, save_path="hotspots.png")

---

🎨 Visualization Gallery

Graph Visualizations

# Sankey diagram for transition flows
plot_sankey(data_t1, data_t2, save_path="flows.png")

# Transition matrix heatmap
plot_transition_matrix_heatmap(data_t1, data_t2, save_path="matrix.png")

# Loss and gain bar chart
plot_loss_gain_bar(loss_gain_data, save_path="losses_gains.png")

# Comprehensive analysis with multiple plots
plot_comprehensive_analysis(data_t1, data_t2, save_directory="./output/")

---

📦 Output Organization

All analysis outputs are automatically organized into structured directories:

analysis_results/
├── plots/
│   ├── sankey_diagrams/
│   ├── heatmaps/
│   ├── bar_charts/
│   └── spatial_maps/
├── tables/
│   ├── transition_matrices/
│   ├── loss_gain_tables/
│   └── intensity_analysis/
├── reports/
│   ├── analysis_summary.html
│   ├── data_validation.pdf
│   └── methodology_notes.txt
└── validation/
    ├── data_quality_checks.json
    └── processing_log.txt

---

🛠️ Development and PyPI Release

PyPI Publishing Guide

This package is designed for professional PyPI distribution. See detailed guides:

• 📦 PyPI Deployment: docs/deployment/pypi-guide.md
• 🔧 Development Setup: docs/development/development-guide.md
• 📊 Data Processing: docs/GUIA_PROCESSAMENTO_DADOS.md

Quick PyPI Release

# Build package
python -m build

# Upload to PyPI
python -m twine upload dist/*

# Install from PyPI
pip install landuse-intensity-analysis

Development Setup

# Clone the repository
git clone https://github.com/ils15/LandUse-Intensity-Analysis.git
cd LandUse-Intensity-Analysis

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run code quality checks
black landuse_intensity/
flake8 landuse_intensity/
mypy landuse_intensity/

---

🧪 Testing and Validation

Built-in Data Validation

from landuse_intensity.utils import validate_raster_data

# Comprehensive data validation
validation = validate_raster_data([data_2000, data_2010])
print(f"Validation passed: {validation['status']}")
print(f"Issues found: {validation['issues']}")

Example Data for Testing

from landuse_intensity import load_example_data

# Load Rio de Janeiro example data (5 years)
rio_data = load_example_data("rio_de_janeiro")
print(f"Years available: {list(rio_data.keys())}")

# Quick analysis with example data
results = run_comprehensive_analysis(
    data_t1=rio_data["2000"],
    data_t2=rio_data["2004"],
    output_dir="./rio_analysis/"
)

---

🌍 Real-World Example: Brazilian Cerrado

import landuse_intensity as lui
import numpy as np

# Simulate Brazilian Cerrado data
print("🌍 Cerrado Biome Analysis")

# Simulated data (replace with real data)
cerrado_classes = ['Cerrado', 'Cerradão', 'Campo', 'Agriculture', 'Pasture', 'Silviculture']

# Create simulated rasters
np.random.seed(42)
raster_2000 = np.random.choice([0,1,2,3,4,5], size=(500, 500), p=[0.4, 0.2, 0.2, 0.1, 0.05, 0.05])
raster_2020 = np.random.choice([0,1,2,3,4,5], size=(500, 500), p=[0.3, 0.15, 0.15, 0.2, 0.15, 0.05])

# Analysis
ct_cerrado = lui.ContingencyTable.from_rasters(
    raster_2000, raster_2020,
    labels1=cerrado_classes,
    labels2=cerrado_classes
)

analyzer_cerrado = lui.IntensityAnalyzer(ct_cerrado)
results_cerrado = analyzer_cerrado.full_analysis()

# Report
print("\n📊 REPORT - CERRADO CHANGES (2000-2020)")
print("=" * 50)
print(f"Total analyzed area: {ct_cerrado.total_area:,} hectares")
print(f"Changed area: {ct_cerrado.total_change:,} hectares ({ct_cerrado.total_change/ct_cerrado.total_area*100:.1f}%)")
print(f"Annual change rate: {results_cerrado.interval.annual_change_rate:.2f}%")

print("\n🔄 Main Transitions:")
transitions = ct_cerrado.table.stack()
top_transitions = transitions[transitions > 0].sort_values(ascending=False).head(5)

for (from_class, to_class), area in top_transitions.items():
    if from_class != to_class:
        print(f"  {from_class} → {to_class}: {area:,} hectares")

# Generate visualizations
from landuse_intensity.sankey_visualization import plot_single_step_sankey

plot_single_step_sankey(
    ct_cerrado.table,
    output_dir="cerrado_results",
    filename="cerrado_transitions",
    title="Cerrado Biome Transitions (2000-2020)",
    export_formats=['html', 'png', 'pdf']
)

print("\n✅ Report and visualizations saved in: cerrado_results/")
print("🌐 Interactive file: cerrado_results/cerrado_transitions.html")

---

🔧 Troubleshooting

Common Issues

Error: "Module not found"

# Verify installation
import landuse_intensity as lui
print("Version:", lui.__version__)

# If not working, reinstall
pip uninstall landuse-intensity-analysis
pip install landuse-intensity-analysis

Error: "Invalid data"

# Validate data before analysis
from landuse_intensity.utils import validate_raster_data

is_valid, message = validate_raster_data(raster_t1, raster_t2)
if not is_valid:
    print(f"Data error: {message}")

Performance with Large Rasters

# For very large rasters, process in chunks
from landuse_intensity.utils import process_raster_in_chunks

results = process_raster_in_chunks(
    raster_t1, raster_t2,
    chunk_size=(1000, 1000),
    overlap=50
)

---

📚 Scientific Background

This library implements the Pontius-Aldwaik Intensity Analysis methodology, a rigorous approach for analyzing land use change patterns. The methodology provides three levels of analysis:

1. Interval Level: Overall rate of change
2. Category Level: Category-specific gain/loss patterns
3. Transition Level: Systematic vs random transitions

Key Publications

• Pontius Jr., R.G. & Aldwaik, S.Z. (2012). "Intensity analysis to unify measurements of size and stationarity of land changes." Landscape and Urban Planning, 106(1), 103-114.

• Aldwaik, S.Z. & Pontius Jr., R.G. (2012). "Map errors that could account for deviations from a uniform intensity of land change." Environmental Modelling & Software, 31, 36-49.

---

📚 References

Methodology

• Aldwaik, S. Z., & Pontius Jr, R. G. (2012). Intensity analysis to unify measurements of size and stationarity of land changes by interval, category, and transition. Landscape and Urban Planning, 106(1), 103-114.

• Pontius Jr, R. G., & Millones, M. (2011). Death to Kappa: birth of quantity disagreement and allocation disagreement for accuracy assessment. International Journal of Remote Sensing, 32(15), 4407-4429.

Implementation

• Official Documentation: Read the Docs
• GitHub Repository: Source Code
• Examples: examples/ folder in repository

---

🤝 Contributing

Contributions are welcome!

1. Fork the project
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -am 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

For major changes, please open an issue first to discuss what you would like to change.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🎯 Citation

If you use this library in your research, please cite:

@software{landuse_intensity_analysis,
  title = {LandUse Intensity Analysis},
  author = {LandUse Intensity Analysis Contributors},
  url = {https://github.com/ils15/LandUse-Intensity-Analysis},
  version = {2.0.0a3},
  year = {2025}
}

---

📞 Support

• Documentation: https://landuse-intensity-analysis.readthedocs.io/
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• PyPI: https://pypi.org/project/landuse-intensity-analysis/

---

Ready to analyze land use changes? Get started today! 🚀