Skip to content

Cokriging#396

Open
n0228a wants to merge 37 commits into
GeoStat-Framework:mainfrom
n0228a:cokriging-backup
Open

Cokriging#396
n0228a wants to merge 37 commits into
GeoStat-Framework:mainfrom
n0228a:cokriging-backup

Conversation

@n0228a
Copy link
Copy Markdown

@n0228a n0228a commented Apr 17, 2026

had to move cokriging to new branch and start pull request again

n0228a added 30 commits August 26, 2025 00:41
- Implement Simple Collocated Cokriging (SCCK) extending Krige class
- Implement Intrinsic Collocated Cokriging (ICCK) with flexible secondary models
- Add comprehensive test suite with 14 test cases covering:
  - Matrix construction and dimensions
  - Cross-correlation validation
  - RHS vector structure
  - Integration with drift functions
  - Edge cases (zero/perfect correlation)
- Follow gstools patterns: property validation, error handling, documentation
- Matrix structure: (n+1) x (n+1) for n conditioning points + 1 secondary variable
- Uses Markov model assumption: C_zy(h) = ρ * √(C_zz(h) * C_yy(h))
- All tests passing with proper position handling via pre_pos method
- Clean minimal implementation extending Krige base class
- Follows existing gstools design patterns exactly
- Only adds cross_corr parameter and secondary_data requirement
- Uses (n+1)×(n+1) matrix system solved per estimation point
- Full API compatibility: return_var, chunk_size, only_mean, etc.
- Proper integration with gstools post-processing and chunking
- Zero cross-correlation equals Simple Kriging (verified)
- Located in separate cokriging module as requested
- Create CollocatedCokriging base class following kriging module pattern
- Refactor SCCK and ICCK as thin wrappers (algorithm='MM1' vs 'intrinsic')
- Eliminate ~400 lines of duplicated code
- Maintain full backward compatibility
- All tests passing (14/14)
- Cleaner architecture for future extensibility
This commit introduces a new Correlogram base class architecture that
makes collocated cokriging future-proof and extensible for different
cross-covariance models (MM1, MM2, etc.).

**New Features:**

- Added Correlogram abstract base class defining the interface for
  cross-covariance models
- Implemented MarkovModel1 as the first concrete correlogram,
  encapsulating Markov Model I assumptions
- Correlogram objects now hold all cross-covariance parameters:
  primary_model, cross_corr, secondary_var, primary_mean, secondary_mean

**API Changes:**

New (recommended) API:
  correlogram = gs.MarkovModel1(
      primary_model=model,
      cross_corr=0.8,
      secondary_var=1.5,
      primary_mean=1.0,
      secondary_mean=0.5
  )
  scck = gs.SimpleCollocated(correlogram, cond_pos, cond_val)

Backward compatibility via from_parameters() classmethod (deprecated):
  scck = gs.SimpleCollocated.from_parameters(
      model, cond_pos, cond_val,
      cross_corr=0.8, secondary_var=1.5,
      mean=1.0, secondary_mean=0.5
  )

**Refactored Classes:**

- CollocatedCokriging: Now accepts correlogram object instead of
  individual parameters (cross_corr, secondary_var, etc.)
- SimpleCollocated: Updated to use new API with backward compatibility
- IntrinsicCollocated: Updated to use new API with backward compatibility
- Both classes delegate covariance computation to correlogram

**Benefits:**

- Separation of concerns: Cross-covariance modeling separated from
  kriging algorithm
- Extensible: Easy to add MM2, Linear Model of Coregionalization, etc.
- Self-documenting: Explicit about which cross-covariance model is used
- Maintainable: Correlogram classes can be tested independently
- Future-proof: Ready for additional correlogram models

**Testing:**

- Added comprehensive test suite (test_correlogram.py)
- All tests pass with numerical equivalence between old and new API
- Updated examples to demonstrate new API

**Documentation:**

- Updated examples/05_kriging/10_simple_collocated_cokriging.py
- Updated examples/05_kriging/11_intrinsic_collocated_cokriging.py
- Added MarkovModel1 to top-level exports
- Comprehensive docstrings with usage examples

**Future Work:**

- Placeholder for MarkovModel2 implementation
- Potential for other correlogram models (intrinsic correlation, etc.)

Closes: #correlogram-architecture
- Explains new Correlogram base class design
- Provides usage examples for MarkovModel1
- Shows how to implement MarkovModel2 (future)
- Includes migration guide from old to new API
- Documents testing and file structure
…ecture

Revert "Feature/correlogram architecture"
n0228a and others added 5 commits October 30, 2025 12:33
…for cokriging

This merge introduces the new Correlogram architecture to replace the
direct-parameter API for collocated cokriging.

Key Changes:
- New Correlogram abstract base class for cross-covariance models
- MarkovModel1 implementation (Markov Model I)
- Refactored SimpleCollocated and IntrinsicCollocated to use Correlogram objects
- Updated API: correlogram parameter replaces model/cross_corr/secondary_var
- Cleaner documentation following GSTools philosophy
- Comprehensive test suite for correlogram models

All conflicts resolved in favor of the new architecture.
All tests passing (14/14).
- Add MarkovModel1 to gstools main __init__.py exports
- Update cokriging __init__.py with proper imports
- Update example files to use new Correlogram API
@LSchueler
Copy link
Copy Markdown
Member

LSchueler commented May 8, 2026

For future references, this is a follow up of PR #394

@n0228a
Copy link
Copy Markdown
Author

n0228a commented Jun 2, 2026

I let Claude ultrareview look for errors and corrected some architectural things, no algorithmic logic was touched: src/gstools/cokriging/base.py

final result — fixing self.field storing SK instead of cokriging , normalizer mixing , only_mean crash/corruption , and unnecessary variance solve
for ICCK

  • _apply_simple_collocated: removed the spurious + kλm_Z mean term (residual-space arithmetic needs no explicit mean)
  • _apply_intrinsic_collocated: computes lambda_Y0 = C_YZ0/C_Y0 locally from _compute_covariances() instead of reading fragile instance state
  • _summate: full rewrite — computes sk_weights = krige_mat @ k_vec once in NumPy, derives field and variance directly, removes duplicate Cython call; drops dead
    ndim==1 branch, write-only _secondary_at_primary, and unreachable else: raise
  • _prepare_secondary: validates secondary_data size against eval grid, raises ValueError with clear message on mismatch
  • init (intrinsic block): validates secondary_cond_pos matches cond_pos; applies isfinite mask to secondary_cond_val before super().init so NaN-filtered
    primaries don't cause broadcast crash
  • secondary_data is None guard: message now names CondSRF

src/gstools/cokriging/methods.py

  • Removed duplicate isinstance(correlogram, Correlogram) checks from SimpleCollocated and IntrinsicCollocated (base already checks); removed now-unused import

src/gstools/init.py

  • Added Correlogram and CollocatedCokriging to top-level imports and all

tests/test_cokriging.py — 11 new tests:

  • test_scck_field_matches_full_system / test_icck_field_matches_full_system — independent full-system oracles locking the math
  • test_field_stored_is_cokriging_result — self.field holds cokriging, not SK
  • test_only_mean_not_supported — raises NotImplementedError
  • test_zero_corr_with_normalizer_equals_sk — normalizer round-trip correctness
  • test_secondary_data_wrong_length / test_secondary_data_structured_mesh — shape validation
  • test_icck_nan_in_cond_val / test_icck_non_collocated_secondary_rejected — conditioning validation
  • test_condsrf_gives_clear_error — CondSRF error message
  • test_icck_summate_matches_oracle_with_chunks / test_top_level_exports — efficiency rewrite and export check

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants