HABIT — Hierarchical Attention-Based Inference with Transfer Learning

A pre-trained ensemble model for predicting soil water retention curves from basic soil properties.

Paper: Ghezzehei TA (2026). Interpretable Soil Water Retention Prediction Using Hierarchical Attention Networks with Uncertainty Quantification. Water Resources Research. DOI:

Web Platform: soil-habit.

What HABIT does

HABIT predicts volumetric water content (θ) at any water potential (ψ) from soil properties. Unlike parameter-based approaches (e.g., van Genuchten fitting), HABIT predicts retention curves directly — no ill-posed inverse problem.

Input → Output

Output: Volumetric water content (cm³/cm³) with ensemble uncertainty (mean ± std from 20 models).

Automatic input adaptation

HABIT uses a single model architecture trained hierarchically. Provide whatever soil properties you have — the model adapts automatically:

• Texture only → equivalent to Stage 0 (R² ≈ 0.78)
• Texture + BD → equivalent to Stage 1 (R² ≈ 0.85)
• Texture + BD + OC → equivalent to Stage 2 (R² ≈ 0.86)
• All properties → Stage 3 (R² ≈ 0.92)

More properties = better predictions, but texture alone already works.

Quick start

from habit_inference import HABITPredictor, load_ensemble

# Load the 20-member ensemble
predictor = load_ensemble(stage=3)

# Predict for a single soil
import pandas as pd
soil = pd.DataFrame({
    'soil_id': ['my_soil'],
    'sand': [0.40],
    'silt': [0.35],
    'clay': [0.25],
    'bd': [1.35],       # optional
    'oc': [0.012],      # optional
    'ksat': [25.0]      # optional, cm/day
})

predictions = predictor.predict(soil)
# Returns: soil_id, water_potential_kPa, water_content_mean, water_content_std

From CSV

predictor.predict_from_csv('input.csv', 'output.csv')

Command line

habit-predict --input soils.csv --output predictions.csv

Model architecture

HABIT uses property-specific encoders, cross-attention layers for property interactions, multi-head attention over soil properties and water potentials, and a monotonic output layer that enforces physically correct behavior (water content decreases with increasing tension).

Key design: Hierarchical transfer learning trains the model sequentially — texture first, then adding bulk density, organic carbon, and Ksat — so a single set of weights handles any combination of available inputs via masking.

Architecture parameters

Repository contents

weights/
  member_01.h5 ... member_20.h5   # Hierarchical ensemble weights (19 MB each)
model/
  habit.py                         # Model architecture
  layers.py                        # Custom layers (attention, monotonic)
config/
  model_config.json                # Architecture hyperparameters
  scaler_params.json               # Feature scaling parameters (robust scaling)

Performance

Evaluated on held-out test set (cluster bootstrap, 1000 iterations):

Training data

2,577 soil samples compiled from two international databases (Hohenbrink et al. 2023; Gupta et al. 2022), with 44,636 water retention measurements after adaptive thinning. See the Dryad repository for the full dataset and training code.

License

MIT (code and weights). Training data: CC BY 4.0.

Citation

@article{ghezzehei2025habit,
  title={Interpretable Soil Water Retention Prediction Using Hierarchical Attention Networks with Uncertainty Quantification},
  author={Ghezzehei, Teamrat A.},
  journal={Water Resources Research},
  year={2025},
  note={DOI pending}
}

Contact

Teamrat A. Ghezzehei — taghezzehei@ucmerced.edu Life and Environmental Sciences, University of California, Merced