Merge branch 'JOSS' into devel

Author: mnky9800n

.github/workflows/draft-pdf.yml

@@ -0,0 +1,28 @@
+name: Draft PDF
+on:
+  workflow_dispatch: {}
+  push:
+    branches:
+    - JOSS
+
+jobs:
+  paper:
+    runs-on: ubuntu-latest
+    name: Paper Draft
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Build draft PDF
+        uses: openjournals/openjournals-draft-action@master
+        with:
+          journal: joss
+          # This should be the path to the paper within your repo.
+          paper-path: man/paper.md
+      - name: Upload
+        uses: actions/upload-artifact@v3
+        with:
+          name: paper
+          # This is the output path where Pandoc will write the compiled
+          # PDF. Note, this should be the same directory as the input
+          # paper.md
+          path: man/paper.pdf

man/paper.bib

@@ -0,0 +1,156 @@
+@article{Aiken:2018,
+  author={{Aiken}, J.M. and {Aiken}, C. and {Cotton}, F.},
+  title = "{A Python Library for Teaching Computation to Seismology Students}",
+  journal = {Seismological Research Letters},
+  volume = {89},
+  number = {3},
+  pages = {1165-1171},
+  year = {2018},
+  month = {03},
+  issn = {0895-0695},
+  doi = {10.1785/0220170246},
+  url = {https://doi.org/10.1785/0220170246},
+  eprint = {https://pubs.geoscienceworld.org/ssa/srl/article-pdf/89/3/1165/4127200/srl-2017246.1.pdf}
+}
+
+@Article{Bachl:2019,
+  author = {{Bachl}, F.E. and {Lindgren}, F. and {Borchers}, D.L. and {Illian}, J.B},
+  title = {{inlabru}: an {R} package for {Bayesian} spatial modelling from ecological survey data},
+  journal = {Methods in Ecology and Evolution},
+  volume = {10},
+  number = {},
+  pages = {760--766},
+  year = {2019},
+  month = {},
+  doi = {10.1111/2041-210X.13168},
+  publisher = {British Ecological Society}
+}
+
+@Online{CORDIS:2024,
+  author = {{CORDIS}},
+  title = {Global land ice, hydrology and ocean mass trends  |  GlobalMass},
+  journal = {},
+  volume = {},
+  number = {},
+  pages = {},
+  year = {2024},
+  month = {},
+  doi = {10.3030/694188},
+  url = {https://doi.org/10.3030/694188},
+  urldate = {2024-05-17}
+}
+
+@Article{Lindgren:2024a,
+      author={{Lindgren}, F. and {Bachl}, F.E. and {Illian}, J. and {Suen} and {Rue}, H. and {Seaton}, A.E.},
+      title={inlabru: software for fitting latent Gaussian models with non-linear predictors}, 
+      year={2024},
+      eprint={2407.00791},
+      journal = {arXiv},
+      doi = {10.48550/arXiv.2407.00791},
+      url={https://arxiv.org/abs/2407.00791}, 
+}
+
+@Misc{Lindgren:2024b,
+  author = {{Lindgren}, F. and {Bachl}, F.E. and {Borchers}, D.L. and {Simpson}, D. and {Scott-Howard}, L. and {Seaton}, A.E. and {Suen}, M.H. and {Roudier}, P. and {Meehan}, T. and {Peddinenikalva}, N. and {Perepolkin}, D.},
+  title = {inlabru},
+  year = {2024},
+  month = {},
+  journal = {GitHub repository},
+  url = {https://inlabru-org.github.io/inlabru},
+  publisher = {GitHub}
+}
+
+@Article{Rue:2009,
+  author = {{Rue}, H. and {Martino}, S. and {Chopin}, N.},
+  title = {Approximate Bayesian inference for latent Gaussian models by using integrated nested Laplace approximations},
+  journal = {Journal of the Royal Statistical Society: Series B (Statistical Methodology)},
+  volume = {71},
+  number = {2},
+  pages = {319-392},
+  year = {2009},
+  month = {},
+  doi = {10.1111/j.1467-9868.2008.00700.x},
+  url = {https://doi.org/10.1111/j.1467-9868.2008.00700.x},
+}
+
+@book{Vygotsky:1978,
+  author = {{Vygotsky}, L.S.},
+  title = {Mind in Society: Development of Higher Psychological Processes},
+  year = {1978},
+  isbn = {9780674576285},
+  url = {http://www.jstor.org/stable/j.ctvjf9vz4},
+  doi = {10.2307/j.ctvjf9vz4},
+  publisher = {Harvard University Press}
+}
+
+@Article{Woods:2022,
+  author = {{Woods}, C. and {Hedges}, L. and {Edsall}, C. and {Brooks-Pollock}, E. and {Parton-Fenton}, C. and {McKinley}, T.J. and {Keeling}, M.J. and {Danon}, L.},
+  title = {MetaWards: A flexible metapopulation framework for modelling disease spread},
+  journal = {Journal of Open Source Software},
+  volume = {7},
+  number = {70},
+  pages = {3914},
+  year = {2022},
+  month = {},
+  doi = {10.21105/joss.03914},
+  url = {https://doi.org/10.21105/joss.03914},
+  publisher = {The Open Journal}
+}
+
+@Article{Yin:2023,
+  author = {{Yin}, X. and {Aiken}, J.M. and {Bamber}, J.L.},
+  title = {{4DModeller (fdmr): A Comprehensive R Package for Spatio-Temporal Modelling}},
+  journal = {Spatial Data Science Symposium 2023 Short Paper Proceedings},
+  volume = {},
+  number = {},
+  pages = {},
+  year = {2023},
+  month = {09},
+  doi = {10.25436/E27C7F},
+  url = {http://dx.doi.org/10.25436/E27C7F},
+  publisher = {UC Santa Barbara: Center for Spatial Studies}
+}
+
+@Article{Yin:2024,
+  author = {{Yin}, X. and {Aiken}, J.M. and {Harris}, R. and {Bamber}, J.L.},
+  title = {{A Bayesian spatio-temporal model of COVID-19 spread in England}},
+  journal = {Scientific Reports},
+  volume = {14},
+  number = {1},
+  pages = {},
+  year = {2024},
+  month = {05},
+  doi = {10.1038/s41598-024-60964-0},
+  url = {https://doi.org/10.1038/s41598-024-60964-0},
+  publisher = {Springer Nature}
+}
+
+@Article{Yuan:2017,
+  author = {{Yuan}, Y. and {Bachl}, F.E. and {Lindgren}, F. and {Borchers}, D.L. and {Illian}, J.B. and {Buckland}, S.T. and {Rue}, H. and {Gerrodette}, T.},
+  title = {Point process models for spatio-temporal distance sampling data from a large-scale survey of blue whales},
+  journal = {Ann. Appl. Stat.},
+  volume = {11},
+  number = {4},
+  pages = {2270--2297},
+  year = {2017},
+  month = {12},
+  doi = {10.1214/17-AOAS1078},
+  publisher = {The Institute of Mathematical Statistics},
+  fjournal = {Annals of Applied Statistics}
+}
+
+@Article{Ziegler:2022,
+  author = {{Ziegler}, Y. and {Vishwakarma}, B.D. and {Brady}, A. and {Chuter}, S. and {Royston}, S. and {Westaway}, R.M. and {Bamber}, J.L.},
+  title = {Can GPS and GRACE data be used to separate past and present-day surface loading in a data-driven approach?},
+  journal = {Geophysical Journal International},
+  volume = {232},
+  number = {2},
+  pages = {884-901},
+  year = {2022},
+  month = {09},
+  doi = {10.1093/gji/ggac365},
+  url = {https://doi.org/10.1093/gji/ggac365},
+  issn = {0956-540X},
+  eprint = {https://academic.oup.com/gji/article-pdf/232/2/884/46456258/ggac365.pdf}
+}
+

man/paper.md

@@ -0,0 +1,73 @@
+---
+title: '4DModeller: a spatio-temporal modelling package'
+tags:
+  - R
+  - spatio-temporal modelling
+  - Bayesian inference
+  - INLA
+  - inlabru
+authors:
+  - name: John M. Aiken
+    orcid: 0000-0003-2258-3836
+    affiliation: "1, 2"
+  - name: Gareth Jones
+    orcid: 0000-0003-4814-5156
+    affiliation: 3
+  - name: Xueqing Yin
+    orcid: 0000-0003-1103-8939
+    affiliation: 3
+  - name: Anrijs K. Abele
+    orcid: 0000-0002-6053-2629
+    affiliation: 3
+  - name: Christopher Woods
+    orcid: 0000-0001-6563-9903
+    affiliation: 3
+  - name: Richard M. Westaway
+    orcid: 0000-0001-6102-1540
+    affiliation: 3
+  - name: Jonathan L. Bamber
+    orcid: 0000-0002-2280-2819
+    corresponding: true
+    affiliation: "3, 4"
+affiliations:
+  - name: Expert Analytics, Norway
+    index: 1
+  - name: University of Oslo, Norway
+    index: 2
+  - name: University of Bristol, UK
+    index: 3
+  - name: Technical University of Munich, Germany
+    index: 4
+date: 12 July 2024
+bibliography: paper.bib
+---
+
+# Summary
+
+4DModeller (`fdmr`) is a spatio-temporal modelling package capable of solving a wide range of large-scale space-time (i.e. four-dimensional) problems [@Yin:2023]. It is built around the inlabru framework which is a suite of R codes for fast efficient Bayesian inference [@Yuan:2017; @Bachl:2019; @Lindgren:2024a]. The `fdmr` package expands the inlabru framework to include specific applications of latent variable modelling for 4-D geophysical problems (e.g. ocean heat content, the Earth’s magnetic field, and global sea-level rise). `fdmr` also includes shiny apps that provide tools for data visualization, finite element mesh building and Bayesian hierarchical modelling based on an R package for Bayesian inference, `inlabru`, along with model evaluation and assessment. These shiny apps are designed to make the complex INLA framework [@Rue:2009] and associated concepts accessible to a wider scientific community, including users who have little to no previous experience using R. The tools are designed with new users in mind by leveraging their expertise with their data sets while minimizing the need to develop extensive code in R [@Aiken:2018; @Vygotsky:1978]. They allow users to interact with their data first using the intuitive knowledge of the modelling process (input data, create mesh, calculate statistical model), then auto-generating code that the users can build on.
+
+This is extended through the Tutorial Driven Software Development practice [@Woods:2022]. This approach is designed to integrate subject matter experts into the code development cycle. It involves the identification of representative and instructive use cases, followed by tutorials that describe how the package could be used to solve them, and then finally code written and tested so that it behaves as described in the tutorials [@Woods:2022]. `fdmr` users have access to a set of domain-specific tutorials as vignettes in R Markdown notebooks; tutorials which are being added to as the user community grows.
+
+The current development of the `fdmr` package supports a wide range of spatially heterogeneous and areal data, including in-situ point observations and satellite data. Examples of the former are ground station air pollution observations, rain gauge data, ocean buoy measurements, or GPS ground displacements. For areal data, the domain mesh is fixed (of regular or irregular shape) and partitioned into areal units (e.g. triangles) with well-defined boundaries. Examples of areal data are attributes collected by postcode, satellite imagery, spatially gridded products such as climate re-analysis or land use classification.
+
+Future package development efforts will focus on expanding its capabilities and broadening its applicability. Moreover, our team actively seeks interdisciplinary collaborations to further expand the modelling framework and tailor it to the specific needs of diverse disciplines.
+
+# Statement of Need
+
+The objective of the `fdmr` package is to provide researchers and practitioners with a straightforward and efficient solution for handling and analyzing different types of spatio-temporal data, enabling a comprehensive analysis of the underlying patterns, processes and trends.
+
+Spatio-temporal data analysis is crucial in many research fields. However, modelling large-scale spatio-temporal data presents challenges such as high computational demands, complex correlation structures and the separation of mixed sources. Additionally, it requires expert domain knowledge to interpret model results. There are number of packages within the R ecosystem that perform various spatio-temporal functions (e.g., `spTimer`, MCMC modeling for space-time data; `spBayes`, MCMC modeling of random effects for space-time data; and `bmstdr`, a model comparison tool that uses MCMC, INLA, and other methods to fit to data and then compare between models). A critical expectation of each of these packages is a deep background in both Bayesian modeling and understanding Bayesian data. For example, users are expected to build their own fit equations, have a deep understanding of random effects, and are expected to be able to interpret predictions and uncertainties. However, none of these packages offer much if any scaffolding to do so.
+
+`fdmr` attempts to bridge this gap and reduce the computational complexity for scientific users of handling high-resolution, high-dimensional spatio-temporal data. It has been developed as a robust and user-friendly R package designed to model spatio-temporal data within a Bayesian framework (`inlabru`) but without requiring users to have an in-depth knowledge of Bayesian statistics. Users have access to different solvers through the `inlabru` framework, such as the Integrated Nested Laplace Approximation (INLA) solver for approximate Bayesian inference and the stochastic partial differential equations (SPDE) method for defining a spatial model. Furthermore, `fdmr` provides intuitive and interactive visual analytics tools that facilitate the exploration of data patterns across both space and time. The goal is that `fdmr` will allow such tools to be used for process modelling (via Gaussian and Poisson processes) and for tasks such as latent process source separation [e.g. @Ziegler:2022] which both complements – and distinguishes it – from the existing example applications of `inlabru` [@Lindgren:2024b].
+
+The work undertaken for 4DModeller extends the Bayesian hierarchical model developed as part of the ERC-funded GlobalMass grant (www.globalmass.eu) that advanced the use of space-time statistical inference to separate global sea level rise into its different sources [@CORDIS:2024]. The `fdmr` package has since been applied to several other use cases including COVID-19 transmission in England [@Yin:2024], streamflow in hydropower catchments in Norway, extreme rainfall in Nepal, changes in the Earth’s magnetic field and ocean heat content in the Pacific.
+
+# Code Availability
+
+The `fdmr` package and installation instructions are available from the 4DModeller GitHub repository (<https://4dmodeller.github.io/fdmr/index.html>) along with shiny apps and tutorials as vignettes in R Markdown notebooks.
+
+# Acknowledgements
+
+This work was supported by UK Research and Innovation grant EP/X022641/1. JLB was also supported by German Federal Ministry of Education and Research (BMBF) in the framework of the international future AI lab “AI4EO - Artificial Intelligence for Earth Observation: Reasoning, Uncertainties, Ethics, and Beyond” (grant number: 01DD20001). Code and tutorial development were aided by two hackathons (in Oslo in November 2023 and in Bristol in March 2024) which were only made possible by funding from the Research Council of Norway through the Svalbard Science Forum's funding program Svalbard Strategic Grant (project number: 344823).
+
+# References