landuse-intensity-analysis 2.0.0a7
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.
Requires Python: >=3.8
Keywords: land-use-change, intensity-analysis, pontius-aldwaik, remote-sensing, gis, environmental-science, spatial-analysis, lulc, change-detection, scientific-computing, visualization, raster-analysis

# 🌍 LULC Package - Land Use Land Cover Intensity Analysis

[![PyPI version](https://badge.fury.io/py/landuse-intensity-analysis.svg)](https://badge.fury.io/py/landuse-intensity-analysis)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Downloads](https://static.pepy.tech/badge/landuse-intensity-analysis)](https://pepy.tech/project/landuse-intensity-analysis)

**The most 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**: Environmental Scientists • GIS Analysts • PhD Students • Researchers • Policy Analysts • Conservation Organizations

---

## ✨ Why Choose LULC Package?

- 🔬 **Scientifically Rigorous**: Exact implementation of peer-reviewed Pontius-Aldwaik methodology
- ⚡ **Performance Optimized**: Memory-efficient processing handles >1GB rasters in <60 seconds
- 🎨 **24+ Visualization Types**: Publication-ready plots with academic formatting standards
- 📊 **Complete Analysis**: Interval, Category, and Transition-level intensity analysis
- 🚀 **Zero Learning Curve**: Full analysis in just 3 lines of code
- 🧠 **Memory Smart**: Advanced chunking and parallel processing for large datasets
- 📚 **Automated Workflows**: Complete pipeline from raw rasters to scientific reports

---

## 🚀 Installation

```bash
pip install landuse-intensity-analysis
```

**Requirements**: Python 3.8+ • numpy • pandas • matplotlib • rasterio • plotly

---

## ⚡ Quick Start - Complete Analysis in 3 Lines

```python
import landuse_intensity as lui

# Complete analysis with auto-detection of years from filenames
analyzer = lui.ContingencyTable.from_files([
    "landuse_2000.tiff", 
    "landuse_2010.tiff", 
    "landuse_2020.tiff"
])

# Generate all 24+ visualizations and scientific report
results = analyzer.intensity_analysis()

# Export publication-ready outputs
lui.export_complete_report(results, output_dir="my_analysis/")
```

**Result**: 24+ publication-ready visualizations + comprehensive scientific report in seconds!

---

## 🎯 Real-World Tutorial - Rio de Janeiro Analysis

Experience the full power with our executable tutorial using real data:

```bash
# Navigate to examples directory  
cd example_data

# Run complete analysis (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+ Interactive Sankey diagrams
- ✅ Spatial change maps and hotspots
- ✅ HTML + PNG outputs
- ✅ Scientific interpretation and insights

---

## 🔬 Scientific Methodology

This package implements the **Pontius-Aldwaik Intensity Analysis** framework - the gold standard for LULC change analysis, providing three rigorous analytical levels:

### 📈 Interval Level Analysis

- Overall rate of change across time periods
- Temporal patterns and acceleration/deceleration detection
- Statistical significance testing

### 📊 Category Level Analysis

- Category-specific gain/loss patterns
- Systematic vs. random change detection
- Land use class vulnerability assessment

### 🔄 Transition Level Analysis

- Pairwise transition intensities
- Systematic transition identification
- Change pathway prioritization

### 🔬 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.

---

## 🎨 Comprehensive Visualization Gallery

### Core Analysis Plots

```python
import landuse_intensity as lui

# Generate all visualization types
lui.plot_sankey(data, output_dir="plots/")                    # Transition flow diagrams
lui.plot_transition_matrix_heatmap(data, save_path="matrix.png")  # Change matrices
lui.plot_intensity_analysis(results, output_dir="analysis/")      # Complete intensity plots
lui.plot_spatial_changes(data_t1, data_t2, save_path="spatial.png")  # Spatial change maps
```

### Available Plot Types (24+)

- 🌊 **Sankey Diagrams**: Single-step, multi-step, energy-style transitions
- 🔥 **Heatmaps**: Transition matrices, correlation matrices, intensity matrices  
- 📊 **Bar Charts**: Loss/gain analysis, category intensities, temporal patterns
- 🗺️ **Spatial Maps**: Change detection, persistence mapping, hotspot analysis
- 📈 **Line Plots**: Temporal trends, trajectory analysis, rate comparisons
- 🎯 **Scatter Plots**: Category relationships, transition correlations
- 📋 **Summary Tables**: Statistical summaries, validation reports, metadata

---

## 🚀 Advanced Features & Architecture

### Memory-Optimized Processing

```python
# Handles large rasters efficiently
config = lui.AnalysisConfiguration(
    max_memory_gb=4.0,           # Automatic memory management
    block_size=1000,             # Chunked processing
    use_multiprocessing=True     # Parallel computation
)

analyzer = lui.ContingencyTable.from_files(files, config=config)
```

### Clean Architecture Pattern

```python
# Factory pattern for different analyzers
factory = lui.AnalyzerFactory()
intensity_analyzer = factory.create_analyzer("intensity")
persistence_analyzer = factory.create_analyzer("persistence")
trajectory_analyzer = factory.create_analyzer("trajectory")

# Manager for complex workflows
manager = lui.AnalyzerManager()
manager.add_dataset("2000", data_2000)
manager.add_dataset("2010", data_2010) 
manager.add_dataset("2020", data_2020)
results = manager.run_comprehensive_analysis()
```

### Automated Reporting

```python
# Generate complete scientific report
lui.create_complete_analysis_report(
    results, 
    output_dir="./publication_ready/",
    include_metadata=True,
    export_formats=['html', 'pdf', 'xlsx']
)
```

---

## 🌍 Real-World Applications

### Brazilian Amazon Deforestation

```python
# Monitor deforestation patterns in the Amazon
amazon_data = lui.load_amazon_tiles(["2018", "2019", "2020", "2021"])
deforestation_analysis = lui.analyze_forest_loss(amazon_data)
```

### Urban Expansion Analysis

```python  
# Track urban growth in megacities
urban_growth = lui.analyze_urban_expansion(
    landsat_stack=["city_2000.tiff", "city_2010.tiff", "city_2020.tiff"],
    focus_classes=['urban', 'suburban', 'rural']
)
```

### Agricultural Land Use Changes

```python
# Agricultural expansion analysis
ag_analysis = lui.analyze_agricultural_transitions(
    crop_maps=crop_classification_stack,
    climate_data=precipitation_data
)
```

---

## ⚡ Performance & Benchmarks

### Memory Optimization

- **Large Datasets**: Processes 1GB+ rasters using <2GB RAM
- **Chunked Processing**: Automatic block-wise computation for unlimited dataset sizes
- **Parallel Computing**: Multi-core processing reduces analysis time by 60-80%

### Speed Benchmarks

| Dataset Size | Processing Time | Memory Usage | Outputs Generated |
|-------------|----------------|--------------|------------------|
| 500x500 px   | <10 seconds    | <500MB       | 24+ plots        |
| 2000x2000 px | <45 seconds    | <1.5GB       | Complete analysis |
| 5000x5000 px | <3 minutes     | <2GB         | Full report       |

### Automated Optimization

```python
# Auto-detection and configuration
config = lui.AnalysisConfiguration.auto_optimize(
    raster_files=['large_raster_1.tiff', 'large_raster_2.tiff'],
    available_memory_gb=8.0
)
# Automatically selects optimal chunk size, processing strategy
```

---

## 📂 Output Organization

All analyses are automatically organized into professional directory structures:

```
analysis_results/
├── plots/
│   ├── interval_analysis/          # Temporal change plots
│   ├── category_analysis/          # Class-specific analyses  
│   ├── transition_analysis/        # Pairwise transitions
│   ├── sankey_diagrams/           # Flow visualizations
│   ├── spatial_maps/              # Geographic change maps
│   └── summary_plots/             # Overview visualizations
├── tables/
│   ├── transition_matrices.xlsx   # All transition data
│   ├── intensity_analysis.xlsx    # Statistical results
│   └── summary_statistics.xlsx    # Key metrics
├── reports/
│   ├── analysis_summary.html      # Interactive report
│   ├── methodology_notes.pdf      # Scientific documentation
│   └── validation_report.json     # Quality assessment
└── data/
    ├── contingency_tables/         # Core analysis matrices
    ├── processed_rasters/          # Cleaned input data
    └── metadata.json              # Analysis configuration
```

---

## 🧪 Data Validation & Quality Control

### Built-in Validation

```python
# Comprehensive data validation
validation = lui.validate_raster_stack([
    'landuse_2000.tiff', 
    'landuse_2010.tiff', 
    'landuse_2020.tiff'
])

if validation.is_valid:
    print("✅ Data validation passed!")
else:
    print(f"❌ Issues found: {validation.issues}")
```

### Quality Checks Include

- ✅ Spatial alignment and CRS consistency
- ✅ Temporal sequence validation
- ✅ Class consistency across time periods
- ✅ NoData and missing value handling
- ✅ Statistical outlier detection
- ✅ Memory requirement estimation

---

## 📚 Example Data & Tutorials

### Rio de Janeiro Case Study (Included)

```python
# Load included example data
rio_data = lui.load_example_data("rio_de_janeiro")
print(f"Available years: {list(rio_data.keys())}")  # [2000, 2001, 2002, 2003, 2004]

# Quick analysis with real data
results = lui.run_comprehensive_analysis(
    data_stack=rio_data,
    output_dir="./rio_analysis/",
    class_names=['Water', 'Forest', 'Agriculture', 'Urban', 'Other']
)
```

### Interactive Tutorials

1. **Basic Analysis**: `example_data/tutorial_basic.py` 
2. **Advanced Processing**: `example_data/tutorial_advanced.py`
3. **Large Dataset Handling**: `example_data/tutorial_big_data.py`
4. **Custom Visualization**: `example_data/tutorial_plotting.py`

---

## 🛠️ Professional Development

### PyPI-Ready Package

This package follows all modern Python packaging standards:

```bash
# Development installation
git clone https://github.com/ils15/LandUse-Intensity-Analysis.git
cd LandUse-Intensity-Analysis
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Code quality
black landuse_intensity/
flake8 landuse_intensity/
mypy landuse_intensity/
```

### Continuous Integration

- ✅ Automated testing on Python 3.8, 3.9, 3.10, 3.11, 3.12
- ✅ Code quality checks (Black, flake8, mypy)
- ✅ Documentation building and deployment
- ✅ PyPI automated publishing

---

## 🔧 Advanced Configuration

### Custom Analysis Workflows

```python
# Create custom analysis pipeline
pipeline = lui.AnalysisPipeline([
    lui.processors.DataValidator(),
    lui.processors.SpatialAligner(), 
    lui.processors.IntensityCalculator(),
    lui.processors.VisualizationGenerator(),
    lui.processors.ReportExporter()
])

results = pipeline.run(input_data, config=custom_config)
```

### Integration with Popular Libraries

```python
# Works seamlessly with popular geospatial libraries
import geopandas as gpd
import rasterio
import xarray as xr

# Direct integration
gdf = gpd.read_file("study_area.shp")
masked_analysis = lui.analyze_within_boundaries(raster_stack, gdf)

# xarray integration  
ds = xr.open_dataset("climate_data.nc")
climate_aware_analysis = lui.analyze_with_climate(land_use_data, ds)
```

---

## 🌐 Community & Support

### Getting Help

- 📖 **Documentation**: [Complete API Reference](https://landuse-intensity-analysis.readthedocs.io/)
- 🐛 **Issues**: [GitHub Issues](https://github.com/ils15/LandUse-Intensity-Analysis/issues)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/ils15/LandUse-Intensity-Analysis/discussions)
- 📦 **PyPI**: [Package Information](https://pypi.org/project/landuse-intensity-analysis/)

### Contributing

We welcome contributions! See our [Contributing Guide](CONTRIBUTING.md) for details.

1. Fork the project
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit changes (`git commit -am 'Add amazing feature'`)
4. Push to branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

---

## 📄 Citation & License

### Citation

If you use this library in your research, please cite:

```bibtex
@software{landuse_intensity_analysis_2025,
  title = {LULC Package: Land Use Land Cover Intensity Analysis},
  author = {LULC Package Contributors},
  url = {https://github.com/ils15/LandUse-Intensity-Analysis},
  version = {2.0.0a6},
  year = {2025},
  doi = {10.5281/zenodo.XXXXXXX}
}
```

### License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## 🎯 Version History

### Latest Release: 2.0.0a6 (September 2025)

- ✅ Complete architecture redesign with Clean Architecture pattern
- ✅ 24+ visualization types with publication-ready outputs  
- ✅ Advanced memory optimization for large datasets
- ✅ Automated workflow system with factory patterns
- ✅ Comprehensive validation and quality control
- ✅ Professional PyPI packaging and CI/CD

### Previous Versions

- **2.0.0a5**: Enhanced visualization system
- **1.x.x**: Legacy implementation

---

## 🚀 Ready to Analyze Land Use Changes?

Start your analysis in minutes:

```bash
pip install landuse-intensity-analysis
```

Transform your raw raster data into actionable scientific insights today! 🌍

---

**Developed with ❤️ for the scientific community**

*Supporting environmental research, conservation efforts, and evidence-based policy making worldwide.*