PhenoNN: Phenology Neural Networks

PhenoNN is a deep learning package that uses LSTM networks to predict Green Chromatic Coordinate (GCC) from climate data. It supports multiple plant functional types (PFTs) including Deciduous Broadleaf (DB), Evergreen Needleleaf (EN), and Grassland (GR). PhenoNN has been developed in the context of the AI4PEX project.

Key Features

• Multiple architectures: LSTM, LSTM with Attention, GRU, and Transformer models

• Flexible data formats: Per-site CSV or flat CSV (features + targets)

• Comprehensive feature engineering: GDD, CDD, and Botta onset features

• Multiple PFT support: Pre-configured for DB, EN, and GR plant types

• Easy-to-use CLI: Simple command-line interface

• Cross-validation: Leave-site-out and year-based splitting

• Hyperparameter tuning: Integration with Optuna

• GPU acceleration: CUDA support for faster training

• Rich visualizations: Built-in plotting for model evaluation

Getting Started

• Installation
  • Prerequisites
  • Installing uv Package Manager
  • Installing PhenoNN
  • Verification
  • Dependencies
  • Optional Dependencies
  • Troubleshooting
• Quickstart
  • Predicting GCC with Pre-trained Models
  • Training Your Own Models
  • Hyperparameter Tuning
  • Python API
• Overview
  • Architecture
  • Plant Functional Types
  • Feature Sets
  • Input Data Format

User Guide

• Data Preparation
  • Input Data Format
  • File Naming Convention
  • CSV Structure
  • Data Requirements
  • Directory Structure
  • Minimum GCC File
• Training
  • Training Command
  • Arguments
  • Target Variables
  • Training Parameters
  • Cross-Validation
  • Example
• Prediction
  • Using Pre-trained Models
  • Output Format
• Hyperparameter Tuning
  • Running Tuning
  • Parameters to Tune

API Reference

• Main Package
  • PhenoCamDataset
  • LAIDataset
  • add_derived_features()
  • split_sites_by_fraction()
  • split_sites_flat()
  • get_site_ids()
  • extract_pft_and_site()
  • RNN_LSTM
  • RNN_GRU
  • EncoderTorch
  • CombinedModel
  • BiTransformer
  • run_training()
  • run_training_flat()
  • run_training_big()
  • run_prediction()
  • run_prediction_flat()
  • get_version()
  • get_versions()
• Data Module
  • PhenoCamDataset
  • LAIDataset
  • load_site()
  • extract_pft_and_site()
  • get_site_ids()
  • load_lai_norms()
  • split_sites_by_fraction()
  • split_sites_flat()
  • add_derived_features()
  • BigLAIDataset
  • generate_site_ids_from_range()
  • get_pixel_index()
  • Dataset Structure
  • Feature Groups
  • Normalization
  • Main Components
  • extract_pft_and_site()
  • load_site()
  • load_lai_norms()
  • compute_norm_stats()
  • load_norm_stats()
  • PhenoCamDataset
  • split_sites_by_fraction()
  • split_by_year()
  • split_by_sites_years()
  • Files
  • get_site_ids()
  • split_sites_by_fraction()
  • compute_norm_stats()
  • load_norm_stats()
  • LAIDataset
  • Implemented Features
  • add_derived_features()
• Models Module
  • RNN_LSTM
  • RNN_GRU
  • FCN
  • EncoderTorch
  • CombinedModel
  • BiTransformer
  • LinearBaseline
  • PerDayLinearBaseline
  • Features
  • Dependencies
  • BaseRNN
  • RNN_LSTM
  • RNN_GRU
  • Features
  • Dependencies
  • EncoderTorch
  • Implemented Models
  • Supporting Components
  • Model Inputs
  • Model Outputs
  • PositionalEncoding
  • CombinedModel
  • BiTransformer
  • Features
  • FCBlock
  • FCN
  • Implemented Models
  • Input and Output Conventions
  • LinearBaseline
  • PerDayLinearBaseline
• Training Module
  • run_training()
  • run_training_flat()
  • run_training_big()
  • Supported models
  • Typical usage
  • parse_args()
  • parse_year_list()
  • train_one_epoch()
  • validate()
  • run_training()
  • Problem Formulation
  • Supported Model Architectures
  • Dataset Splitting
  • Normalization
  • Training Features
  • Evaluation Metrics
  • Data Requirements
  • parse_args()
  • parse_args_bis()
  • parse_year_list()
  • build_model()
  • train_one_epoch()
  • validate()
  • run_training_flat()
• Prediction Module
  • run_prediction()
  • run_prediction_flat()
  • Usage
  • parse_args()
  • run_prediction()
  • Output
  • Usage
  • parse_args()
  • run_prediction_flat()
• Utils Module
  • Logger
  • plot_loss_histories()
  • plot_metric_histories()
  • plot_pred_vs_obs()
  • plot_gcc_curves()
  • plot_gcc_curves_all()
  • make_history_dicts()
  • get_loss_function()
  • ModelUtils
  • load_model()
  • FileUtils
  • EasyDict
  • Every10DaysWrapper
  • permuteWrapper
  • LastNDaysWrapper
  • Logger
  • plot_loss_histories()
  • plot_metric_histories()
  • plot_pred_vs_obs()
  • plot_gcc_curves()
  • plot_gcc_curves_all()
  • plot_feature_distributions()
  • plot_feature_distributions_per_site()
  • make_history_dicts()
  • Dependencies
  • GradientAwareLoss
  • NMSELoss
  • NMAELoss
  • MetricTracker
  • get_loss_function()
  • mse_all()
  • mbe_all()
  • mae_all()
  • r2_all()
  • nmae_all()
  • nmse_all()
  • mare_all()
  • gmrae_all()
  • Design
  • Supported models
  • Wrapper logic
  • load_model()
  • Features
  • Dependencies
  • ModelUtils
  • Core Idea
  • Classes
  • Constants
  • Design Rationale
  • SingleDayWrapper
  • permuteWrapper
  • LastNDaysWrapper
  • Every10DaysWrapper
• CLI Module
  • main()
• Version Module
  • get_version()
  • get_versions()

Development

• Contributing
  • How to Contribute
  • Development Setup
• Testing
  • Running Tests
  • Test Coverage
  • Writing Tests

Indices and tables

• Index

• Module Index

• Search Page