diff --git a/paper.bib b/paper.bib index d86ef6a..6a8ae93 100644 --- a/paper.bib +++ b/paper.bib @@ -28,8 +28,11 @@ @incollection{Bezerra2025BM Bezerra, Janaina Santos}, booktitle = {Dynamics of the Oceans - Variability, Hydrological Cycles, and Sea Level Change}, + editor = {Zhang, Xiaolin and Attada, Raju}, publisher = {IntechOpen}, year = {2025}, + isbn = {978-0-85014-752-0}, + doi = {10.5772/intechopen.1012210}, url = {https://www.intechopen.com/chapters/1220205} } @@ -44,13 +47,13 @@ @software{Jordahl2021 @article{Verburg2004, title = {Land use change modelling: current practice and research priorities}, - author = {Verburg, Peter H. and Schot, Paul P. and Dijst, Martin J. and Veldkamp, Tom A.}, + author = {Verburg, Peter H. and Schot, Paul P. and Dijst, Martin J. and Veldkamp, A.}, journal = {GeoJournal}, volume = {61}, number = {4}, pages = {309--324}, year = {2004}, - doi = {10.1007/s10708-004-5036-7} + doi = {10.1007/s10708-004-4946-y} } @article{Bezerra2022, @@ -150,16 +153,29 @@ @software{DisSLUCCDiscrete url = {https://github.com/DisSModel/disslucc-discrete} } -@article{Pontius2008, - author = {Pontius, Robert Gilmore and Peethambaram, Sneha and Castella, Jean-Christophe}, - title = {Comparison of Three Maps at Multiple Resolutions: a Case Study of Land Change Simulation in Cho Don District, Vietnam}, +@article{PontiusEtAl2011, + author = {Pontius Jr., Robert Gilmore and Peethambaram, Smitha and Castella, Jean-Christophe}, + title = {Comparison of Three Maps at Multiple Resolutions: a Case Study of + Land Change Simulation in Cho Don District, Vietnam}, journal = {Annals of the Association of American Geographers}, - year = {2008}, - volume = {98}, + year = {2011}, + volume = {101}, number = {1}, - pages = {28--49} + pages = {45--62}, + doi = {10.1080/00045608.2010.517742} } +@article{PontiusMillones2011, + author = {Pontius Jr., Robert Gilmore and Millones, Marco}, + title = {Death to {Kappa}: birth of quantity disagreement and allocation + disagreement for accuracy assessment}, + journal = {International Journal of Remote Sensing}, + year = {2011}, + volume = {32}, + number = {15}, + pages = {4407--4429}, + doi = {10.1080/01431161.2011.552923} +} @article{Willmott2005, author = {Willmott, Cort J. and Matsuura, Kenji}, @@ -168,17 +184,19 @@ @article{Willmott2005 journal = {Climate Research}, year = {2005}, volume = {30}, - pages = {79--82} + pages = {79--82}, + doi = {10.3354/cr030079} } - @article{Veldkamp1996, author = {Veldkamp, A. and Fresco, L. O.}, title = {{CLUE}: a conceptual model to study the conversion of land use and its effects}, journal = {Ecological Modelling}, year = {1996}, volume = {85}, - pages = {253--270} + number = {2-3}, + pages = {253--270}, + doi = {10.1016/0304-3800(94)00151-0} } @inproceedings{Costa2009, diff --git a/paper.md b/paper.md index 9e4f6a2..d73ecd6 100644 --- a/paper.md +++ b/paper.md @@ -41,8 +41,8 @@ explicit dynamic modeling, targeting the complexities of Land Use and Land Cover Change (LUCC). It translates the modeling paradigms of the TerraME framework [@Carneiro2013] into the Python ecosystem, enabling researchers to simulate complex socio-environmental systems — forest fires, epidemiological spreads, -coastal dynamics — by coupling a time-stepped simulation clock with the spatial -data structures of GeoPandas [@Jordahl2021]. +coastal dynamics — by coupling a time-stepped clock with the spatial data +structures of GeoPandas [@Jordahl2021]. The framework provides a **dual-substrate architecture**: a vector substrate backed by GeoDataFrame for spatial expressiveness, and a raster substrate backed @@ -52,31 +52,29 @@ available through the DisSModel GitHub organisation and on PyPI. ## Statement of Need Python has become the lingua franca for geospatial data science, supported by -libraries such as GeoPandas and PySAL. However, these tools are designed for -static analysis. Dynamic spatial modeling — simulating how landscapes evolve over -time — has historically required specialised platforms. In Brazil, TerraME -[@Carneiro2013] and Dinamica EGO are the most widely adopted general-purpose -frameworks, while institutions elsewhere often rely on narrower, more specific -allocation models such as CLUE and CLUE-S [@Veldkamp1996]. This fragmentation -leaves researchers choosing between a general-purpose Lua-based toolchain and -single-purpose implementations with no shared contract between them. - -While TerraME is conceptually robust, its reliance on Lua scripting — a language -with substantially smaller adoption in the data science ecosystem than Python — -creates a barrier for data scientists, and the framework itself has seen no new -release since August 2020. General-purpose simulation libraries, meanwhile, lack -native synchronisation between a time-stepped clock and the geographical state of -a GeoDataFrame. DisSModel fills this gap with a lightweight, purpose-built -scheduler coupled directly to vector and raster spatial state, providing a -Pythonic, actively maintained implementation of the TerraME paradigm — and, -through its satellite packages, of specific allocation models like CLUE and -CLUE-S as well. +libraries such as GeoPandas and PySAL — but these tools are designed for static +analysis. Dynamic spatial modeling, simulating how landscapes evolve over time, +has historically required specialised platforms. In Brazil, TerraME [@Carneiro2013] +and Dinamica EGO are the most widely adopted general-purpose frameworks, while +institutions elsewhere rely on narrower allocation models such as CLUE and CLUE-S +[@Veldkamp1996]. This fragmentation leaves researchers choosing between a +Lua-based toolchain and single-purpose implementations with no shared contract. + +While TerraME is conceptually robust, its reliance on Lua — a language with far +smaller adoption in data science than Python — creates a barrier for data +scientists, and the framework has seen no new release since August 2020. +General-purpose simulation libraries, meanwhile, lack native synchronisation +between a time-stepped clock and the geographical state of a GeoDataFrame. +DisSModel fills this gap with a lightweight scheduler coupled directly to vector +and raster spatial state, providing a Pythonic, actively maintained implementation +of the TerraME paradigm — and, through its satellite packages, of allocation +models like CLUE and CLUE-S. Reproducibility is a first-class concern: the `executor` module provides a -standardised lifecycle — `validate → load → run → save` — that captures -provenance metadata (input checksums, parameters, timing, output paths) in an -`ExperimentRecord` object generated automatically for every run, with no -additional instrumentation by the modeller. +standardised lifecycle — `validate → load → run → save` — capturing provenance +metadata (input checksums, parameters, timing, output paths) in an +`ExperimentRecord` generated automatically for every run, with no additional +instrumentation by the modeller. ## State of the Field @@ -93,17 +91,16 @@ libraries and specialised GIS simulation software: | Reproducibility | Manual | Manual | Automated (ExperimentRecord) | | Neighborhoods | GPM Support | Limited | libpysal weights (Queen, Rook, KNN, custom) | -Frameworks like NetLogo and Mesa are excellent for ABM but require boilerplate to -handle real-world spatial projections. DisSModel uses GeoPandas as its core -engine, following the discrete spatial modeling approach proposed by -@SantosJunior2025. +NetLogo and Mesa are excellent for ABM but require boilerplate to handle +real-world spatial projections. DisSModel uses GeoPandas as its core engine, +following the discrete spatial modeling approach of @SantosJunior2025. ## Software Design DisSModel is organised into five modules with strict separation of concerns, extensible through class inheritance. **Core** manages the simulation clock: the -`Environment` class orchestrates time progression, and spatial models auto-register -at instantiation, receiving clock ticks through `setup / pre_execute / execute / +`Environment` orchestrates time progression, and spatial models auto-register at +instantiation, receiving ticks through `setup / pre_execute / execute / post_execute` hooks. **Geo** provides the dual-substrate design: a vector substrate (`SpatialModel`, `CellularAutomaton`) on GeoDataFrame with libpysal neighbourhoods [@Rey2021], and a raster substrate (`RasterModel`, @@ -113,25 +110,25 @@ the `ModelExecutor` four-phase lifecycle (`validate`, `load`, `run`, `save`); subclasses self-register via `__init_subclass__`, and every run produces an `ExperimentRecord` capturing input checksum, parameters, timing, and output paths. **IO** provides a unified dataset abstraction (`load_dataset` / `save_dataset`) -across GeoDataFrame, GeoTIFF, and Xarray/Zarr, including transparent `s3://` -resolution. **Visualization** integrates Matplotlib, Streamlit-compatible input -widgets, and `RasterMap` for raster rendering. +across GeoDataFrame, GeoTIFF, and Xarray/Zarr, with transparent `s3://` +resolution. **Visualization** integrates Matplotlib, Streamlit-compatible widgets, +and `RasterMap`. This extensibility has already produced independent domain packages: `dissmodel-ca` [@DisSModelCA] (Cellular Automata patterns), `dissmodel-sysdyn` -[@DisSModelSysDyn] (System Dynamics components), and `DisSLUCC-Continuous` -[@DisSLUCCContinuous], which implements the continuous LUCC modeling components of -LUCCME — Demand, Potential, and Allocation [@Veldkamp1996; @Verburg2004] — on both -substrates and the same `ModelExecutor` contract, an explicit Python counterpart -to TerraME/LUCCME. +[@DisSModelSysDyn] (System Dynamics), and `DisSLUCC-Continuous` +[@DisSLUCCContinuous], which implements LUCCME's continuous components — Demand, +Potential, and Allocation [@Veldkamp1996; @Verburg2004] — on both substrates and +the same `ModelExecutor` contract, an explicit Python counterpart to +TerraME/LUCCME. ## Performance The vector substrate offers spatial expressiveness; the raster substrate achieves -high throughput via NumPy vectorisation. All benchmarks were run on an Intel Core -i7-7700T CPU @ 2.90GHz, 15 GB RAM (Ubuntu, Python 3.12.3, NumPy 2.4.6, GeoPandas -1.1.3); absolute timings vary by hardware, but the relative speedup pattern is the -result of interest. +high throughput via NumPy vectorisation. All benchmarks ran on an Intel Core +i7-7700T @ 2.90GHz, 15 GB RAM (Ubuntu, Python 3.12.3, NumPy 2.4.6, GeoPandas +1.1.3); absolute timings vary by hardware, but the relative speedup is the result +of interest. **Conway's Game of Life** confirms mathematical equivalence across substrates with different throughput: @@ -148,36 +145,44 @@ different throughput: **BR-MANGUE coastal dynamics.** The foundation for coupled mangrove-flood modeling was established by Bezerra et al. [@Bezerra2013] and extended in @Bezerra2025BM, co-authored by Denilson da Silva Bezerra, the submitting author, and Felipe Martins -Sousa — the same three researchers now responsible for the DisSModel -reimplementation of BR-MANGUE. The `brmangue-dissmodel` package [@BRMangue] validates the -raster implementation against TerraME over the Maranhão Island dataset (50,496 -cells, 20 steps): land use matches on 99.9% of cells, soil on 99.8%, and -elevation (1 mm tolerance) on 90.7% (MAE 0.0033 m); match percentage is the -appropriate metric for these categorical outputs [@Pontius2008]. Reproducible via -`brmangue-dissmodel/src/brmangue/executors/validation_executor.py` against the -committed TerraME golden CSV references in `tests/fixtures/golden/`, with +Sousa — the same researchers responsible for the DisSModel reimplementation. The +`brmangue-dissmodel` package [@BRMangue] +validates the raster implementation against TerraME over the Maranhão Island +dataset (50,496 cells, 19 steps): land use and soil match exactly at every +checkpoint (MAE 0, max error 0), and elevation on 97.3% of cells within 1 mm +(MAE 0.00068 m) — match percentage being the appropriate metric for categorical +outputs [@PontiusEtAl2011]. In this scenario the flood component triggers no land-use +transition and the golden files confirm TerraME behaves identically, so the +agreement above exercises mangrove migration; flooding is covered separately under +the original laboratory parameters. Reproducible via +`brmangue-dissmodel/src/brmangue/executors/validation_executor.py` (`end_time=19`) +against the committed golden CSVs in `tests/fixtures/golden/`, with `tests/test_model_invariants.py` and `tests/test_transition_rules.py` covering structural correctness. Cross-substrate equivalence (60×60 synthetic grid, 3,600 cells, 10 steps) shows -100% match for land use and soil and 100% match for elevation under tolerance -(MAE 0.000959 m, max error 0.024 m), with the raster substrate running at 2.1 -ms/step against 84.2 ms/step for vector (40.1× speedup). The residual elevation -divergence reflects floating-point rounding differences, not algorithmic -disagreement. Each run automatically produces an `ExperimentRecord` with timings, -checksums, and artifact paths. +100% match for land use, soil, and elevation under tolerance (MAE 0.000959 m, max +error 0.024 m), with raster at 2.1 ms/step against 84.2 ms/step for vector (40.1× +speedup); the residual elevation divergence is floating-point rounding, not +algorithmic disagreement. Each run automatically produces an `ExperimentRecord` +with timings, checksums, and artifact paths. **DisSLUCC-Continuous** implements the continuous CLUE-like allocation algorithm [@Veldkamp1996]; MAE is the appropriate metric for its fractional outputs -[@Pontius2008; @Willmott2005]. Over the Lab1 study area (6,574 cells, 6 steps), +[@PontiusEtAl2011; @Willmott2005]. Over the Lab1 study area (6,574 cells, 6 steps), both substrates reproduce the TerraME/LUCCME reference at MAE = 0.0036 (RMSE -0.0062, max error 0.027) in [0,1] scale, consistent with expected divergence -between independent implementations. Vector and raster are numerically identical -(MAE = 0.000), and the raster substrate is 3.9× faster (44.0 ms/step vs 172.8 -ms/step). Reproducible via -`disslucc-continuous/tests/test_benchmark_validation.py`. Full end-to-end -provenance from raw inputs to final metrics is addressed by the -`dissmodel-platform` satellite package. +0.0062, max error 0.027) in [0,1] scale. The residual is accounted for by the +original model's own convergence tolerance: the LuccME script declares +`maxDifference = 1643` area units against a 2014 demand of 21,607 — a 7.6% band, +within which the reference itself stops short of its declared demand. Consistently, +the Pontius decomposition attributes 90% of the residual to quantity and 10% to +allocation [@PontiusMillones2011]. The raster substrate is 3.9× faster (44.0 ms/step vs +172.8 ms/step). Reproducible via +`disslucc-continuous/tests/test_benchmark_validation.py`, with +`tests/test_benchmark_discriminance.py` confirming that perturbing the regression +coefficients breaks the tolerance criterion. Full end-to-end provenance from raw +inputs to final metrics is addressed by the `dissmodel-platform` satellite +package. ## Research Impact Statement @@ -190,37 +195,39 @@ was presented at INPE's Graduate Program in Applied Computing seminar series institutional community that maintains TerraME and LuccME. The framework is in active use across two UFMA research groups. Within LambdaGeo, -graduate students develop `disslucc-continuous` and `brmangue-dissmodel` as part -of their Master's research. Independently, Prof. Denilson da Silva Bezerra (UFMA, -former INPE researcher), whose doctoral work established BR-MANGUE's scientific -foundation [@Bezerra2013], actively uses the DisSModel reimplementation in his own -coastal dynamics research program (PVCBS4959-2025, PVCBS4960-2025; +graduate students develop `disslucc-continuous` and `brmangue-dissmodel` as part of +their Master's research. Independently, Prof. Denilson da Silva Bezerra (UFMA, +former INPE), whose doctoral work established BR-MANGUE's scientific foundation +[@Bezerra2013], uses the DisSModel reimplementation in his own coastal dynamics +research program (PVCBS4959-2025, PVCBS4960-2025; https://sigaa.ufma.br/sigaa/public/docente/pesquisa.jsf?siape=3104707), a collaboration predating DisSModel itself [@Bezerra2025BM]. Starting August 2026, the project receives its first PIBIC-funded undergraduate research fellows (CNPq), under approved institutional project PVCET5136-2026 at -UFMA. The concentrated 2026 development effort was deliberately oriented toward -this milestone: stabilizing the `ModelExecutor` contract so each fellow can own an -independent repository — `disslucc-continuous`, `disslucc-discrete`, -`brmangue-dissmodel`, or `disscube` (a data-cube access and spatial-derivation -layer, the Python successor to TerraME's `fillCellularSpace`) — without core -changes. +UFMA. The concentrated 2026 development effort was oriented toward this milestone: +stabilizing the `ModelExecutor` contract so each fellow can own an independent +repository — `disslucc-continuous`, `disslucc-discrete`, `brmangue-dissmodel`, or +`disscube` (a data-cube layer, the Python successor to TerraME's +`fillCellularSpace`) — without core changes. Since the original submission, development has continued with `disslucc-discrete` [@DisSLUCCDiscrete], a CLUE-S-like discrete allocation package using logistic regression — the discrete counterpart to `DisSLUCC-Continuous`. An initial version has been validated against the Lab6 case study (Moju municipality, 5,914 cells, 6 -steps) from the original TerraME/LuccME repository, achieving 100% categorical -agreement with the TerraME reference (kappa = 1.0, F1 = 1.0) at 56.8 ms/step. - -These independent domain packages — `dissmodel-ca`, `dissmodel-sysdyn`, -`DisSLUCC-Continuous`, `disslucc-discrete`, and `brmangue-dissmodel` — demonstrate -that the `ModelExecutor` contract generalizes across modeling paradigms without -core modifications. Studies such as @Bezerra2022, developed using LuccME, -represent the class of models the DisSLUCC packages are designed to reproduce. A -roadmap toward DisSModel 1.0 (May 2027) anchors a community outreach effort -including an open textbook, *Geospatial Modeling with Python* +steps) from the original TerraME/LuccME repository, reaching cell-for-cell +agreement — zero quantity and zero allocation disagreement [@PontiusMillones2011] — at +56.8 ms/step. A shipped discriminance test shows this scenario is also reproduced +by a trivial static ranking, so it validates coefficient transcription rather than +the allocation algorithm; a dynamic-covariate scenario is planned. + +These packages — `dissmodel-ca`, `dissmodel-sysdyn`, `DisSLUCC-Continuous`, +`disslucc-discrete`, and `brmangue-dissmodel` — demonstrate that the +`ModelExecutor` contract generalizes across modeling paradigms without core +modifications. Studies such as @Bezerra2022, developed using LuccME, represent the +class of models the DisSLUCC packages are designed to reproduce. A roadmap toward +DisSModel 1.0 (May 2027) anchors community outreach including an open textbook, +*Geospatial Modeling with Python* (https://lambdageo.github.io/geospatial-modeling-python/), already in progress. This positions DisSModel as the simulation layer in the Brazilian Earth Observation stack, complementary to SITS [@Simoes2021] and the Brazil Data Cube @@ -245,14 +252,14 @@ corresponding to the second author's undergraduate thesis [@SantosJunior2025], d not involve generative AI. Development resumed in February–March 2026 with Claude (chat) used mainly for documentation; from April 2026, Gemini CLI accelerated code generation and refactoring; from June 2026, Claude Code (CLI) was used on newer -satellite repositories such as `disslucc-discrete`. AI tools also assisted with -writing in English, which is not the submitting author's native language. The +satellite repositories such as `disslucc-discrete`, including the audit of the +validation routines against the original TerraME scripts. AI tools also assisted +with writing in English, not the submitting author's native language. The scientific design — the TerraME compatibility contract, executor pattern, dual-substrate architecture, and validation methodology — predates and is independent of this AI-assisted phase, tracing to the submitting author's doctoral research at INPE and the undergraduate thesis cited above. AI tools assisted with implementation velocity and language clarity, not scientific or -architectural decisions. All outputs were reviewed and validated by the human -authors. +architectural decisions. All outputs were reviewed and validated by the authors. -## References \ No newline at end of file +## References