Collocation Analysis Package
A Python library for collocation-based error analysis of remote sensing and geophysical datasets — quantifying errors in multiple products without ground truth .
For the full architecture guide (bilingual 中/EN), see ARCHITECTURE.md
Feature Description Sklearn-style API TC().fit(data).metrics_ — uniform interface across all methodsSmart Recommender CollocationConsultant diagnoses your data and suggests the best methodInteractive Dashboard Plotly 3-panel HTML dashboard with time-series slider and stability heatmap ELI Pipeline One-click parallel ELI analysis with auto-generated HTML report
git clone https://github.com/licm13/Collocation-Analysis.git
cd Collocation-Analysis
pip install -e . # Optional: interactive dashboard# Optional: xarray support# Optional: Bayesian methods" pymc3==3.11.5" 1. Let the consultant choose your method import numpy as np from collocation import CollocationConsultant data = np .column_stack ([product1 , product2 , product3 ]) # (n, 3) report = CollocationConsultant (data , product_names = ['ERA5' , 'GLEAM' , 'GLDAS' ]).consult ()
print (report )
# ★ PRIMARY RECOMMENDATION → EIVD # Reason: High cross-correlation detected (GLEAM×GLDAS r=0.54)... 2. Fit with the sklearn-style API from collocation .estimators import TC , EIVD , IVD # Fit and inspect model = TC ().fit (data )
print (model .metrics_ ['error_std' ]) # [0.20, 0.31, 0.39] print (model .summary ())
# Compare methods in a loop results = {name : cls ().fit (data ).metrics_ for name , cls in [('TC' , TC ), ('EIVD' , EIVD )]}from collocation import InteractiveDashboard from collocation .estimators import TC , EIVD from collocation import tc metrics = {'TC' : TC ().fit (data ).metrics_ , 'EIVD' : EIVD ().fit (data ).metrics_ }
InteractiveDashboard (data , metrics , method_fn = tc ).save ('dashboard.html' )4. ELI one-click pipeline from collocation import ELIPipeline result = ELIPipeline (
water = np .column_stack ([swvl1 , gleam_sm , gldas_sm ]),
energy = np .column_stack ([swd , era5_rn , gldas_rn ]),
vegetation = et_obs ,
product_names = {
'water' : ['ERA5-SM' , 'GLEAM-SM' , 'GLDAS-SM' ],
'energy' : ['ERA5-SW' , 'ERA5-Rn' , 'GLDAS-Rn' ],
'vegetation' : ['GLEAM-ET' ],
},
).run ()
print (result .summary ()) # ELI ratio, per-method table result .save ('eli_report.html' )5. Classic functional API (unchanged) from collocation import tc , eivd , ivd , ec , btch_he2020 EeeT , SNR , rho2 , fMSE = tc (data ) # 3-way EeeT , SNR , rho2 , fMSE , L = eivd (data ) # 3-way + cross-corr EeeT , rho2 , weights = ivd (np .column_stack ([p1 , p2 ])) # 2-way variances , weights , fused = btch_he2020 (data ) # analytical BTCH Method Products Key Use Case IVD2 Active + passive sensor fusion IVS2 Two-product with bootstrap CI TC / TCH3 Standard triple collocation EIVD3 Correlated-error products EC4 Quadruple over-determination ETCC3 Correlation-optimised merging (precipitation) MTCHN≥3 Multiplicative / positive-skew data
Method Uncertainty Dependencies BTCH_He2020None (analytical) NumPy only BayesianTCHFull MCMC PyMC3 BayesianTCFull MCMC + time-varying PyMC3
collocation/
├── base.py ← CollocationEstimator ABC
├── estimators.py ← TC / EIVD / IVD / EC sklearn wrappers
├── consultant.py ← CollocationConsultant smart recommender
├── plotting.py ← plot_error_comparison, InteractiveDashboard
├── eli_pipeline.py ← ELIPipeline, ELIResult
│
├── tc.py, eivd.py, ivd.py, ivs.py, ec.py ← classical methods
├── etcc.py, mtch.py ← advanced methods
├── btch_he2020.py, bayesian_tc.py, bayesian_tch.py
│
├── utils.py, covariance.py, fuse.py, simple_average.py, eli.py
└── fusion/ ← IVW / GLS / QP weights, robust, localization
pip install pytest
pytest tests/ -v
# New v2.0 tests only# 48 tests Package Role Required? numpy ≥ 1.18 Core numerics Yes scipy ≥ 1.4 Statistics, linear algebra Yes matplotlib ≥ 3.1 Static plots Optional plotly ≥ 5.0 Interactive dashboard Optional xarray ≥ 0.18 Native DataArray/Dataset input Optional pymc3 == 3.11.5 Bayesian TC/TCH Optional
If you use this package, please cite the underlying methods relevant to your analysis. Key references:
TC : Stoffelen (1998), JGR , 103(C4)EIVD : Dong et al. (2019), J. Hydrology , 581BTCH_He2020 : He et al. (2020), HESS ETCC : Wei et al. (2023)ELI : Dong et al. (2022), Remote Sens. Environ. MIT © Original MATLAB: licm_13@163.com | Python conversion & v2.0 upgrade: Claude
