test coverage + small readme cleanup

.Rbuildignore

@@ -6,3 +6,4 @@
 ^_pkgdown\.yml$
 ^docs$
 ^pkgdown$
+^codecov\.yml$

.github/workflows/test-coverage.yaml

@@ -0,0 +1,61 @@
+# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples
+# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+name: test-coverage
+
+permissions: read-all
+
+jobs:
+  test-coverage:
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: any::covr, any::xml2
+          needs: coverage
+
+      - name: Test coverage
+        run: |
+          cov <- covr::package_coverage(
+            quiet = FALSE,
+            clean = FALSE,
+            install_path = file.path(normalizePath(Sys.getenv("RUNNER_TEMP"), winslash = "/"), "package")
+          )
+          covr::to_cobertura(cov)
+        shell: Rscript {0}
+
+      - uses: codecov/codecov-action@v4
+        with:
+          fail_ci_if_error: ${{ github.event_name != 'pull_request' && true || false }}
+          file: ./cobertura.xml
+          plugin: noop
+          disable_search: true
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+      - name: Show testthat output
+        if: always()
+        run: |
+          ## --------------------------------------------------------------------
+          find '${{ runner.temp }}/package' -name 'testthat.Rout*' -exec cat '{}' \; || true
+        shell: bash
+
+      - name: Upload test results
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-test-failures
+          path: ${{ runner.temp }}/package

DESCRIPTION

@@ -5,10 +5,10 @@ Authors@R:
     person("Cas", "Neyens", , "[email protected]", role = c("aut", "cre"))
 Description: Analytic element modeling of steady-state single-layer
     groundwater flow under the Dupuit-Forchheimer assumption. Elements
-    such as wells, area-sinks and line-sinks can be placed arbitrarily.
-    The hydraulic head and discharge vector, as well as other state- and
-    flow-variables, can be computed at any location in the field.
-    Tracelines can be computed numerically in three dimensions.
+    such as wells, area-sinks and line-sinks can be placed at arbitrary 
+    locations. The hydraulic head and discharge vector, as well as other
+    state- and flow-variables, can be computed at any location in the
+    flow field. Tracelines can be computed numerically in three dimensions.
 License: MIT + file LICENSE
 URL: https://github.com/cneyens/raem, https://cneyens.github.io/raem/
 BugReports: https://github.com/cneyens/raem/issues

README.Rmd

@@ -22,6 +22,8 @@ knitr::opts_knit$set(
 <!-- badges: start -->
 
 [![R-CMD-check](https://github.com/cneyens/raem/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/cneyens/raem/actions/workflows/R-CMD-check.yaml)
+[![Codecov test coverage](https://codecov.io/gh/cneyens/raem/branch/main/graph/badge.svg)](https://app.codecov.io/gh/cneyens/raem?branch=main)
+[![CRAN status](https://www.r-pkg.org/badges/version/raem)](https://CRAN.R-project.org/package=raem)
 <!-- badges: end -->
 
 `raem` is an R package for modeling steady-state single-layer groundwater flow under the Dupuit-Forchheimer assumption using analytic elements.
@@ -44,14 +46,16 @@ Specify the aquifer parameters and create elements:
 ```{r create-elements}
 library(raem)
 
-k = 10
-top = 10
-base = 0
-n = 0.2
+# aquifer parameters ----
+k = 10     # hydraulic conductivity, m/d
+top = 10   # aquifer top elevation, m
+base = 0   # aquifer base elevation, m
+n = 0.2    # aquifer porosity, -
 
-hr = 15 # head at reference point, above aquifer top
-TR = k * (top - base) # constant transmissivity of background flow
+hr = 15    # head at reference point, m
+TR = k * (top - base) # constant transmissivity of background flow, m2/d
 
+# create elements ----
 uf = uniformflow(TR, gradient = 0.001, angle = -45)
 rf = constant(xc = -1000, yc = 0, hc = hr)
 w1 = well(xw = 200, yw = 0, Q = 250)
@@ -87,7 +91,7 @@ contours(m, xg, yg, 'heads', col = 'dodgerblue', nlevels = 20)
 plot(m, add = TRUE)
 ```
 
-Compute particle traces starting along `y = 200` at 20 intervals per year for 5 years and add to plot:
+Compute particle traces starting along `y = 200` at 20 intervals per year for 5 years and add to the plot:
 
 ```{r plot-traces, dpi = 300}
 paths = tracelines(m, x0 = seq(-450, 450, 50), y0 = 200, z0 = top, times = seq(0, 5*365, 365/20))
@@ -99,3 +103,7 @@ plot(paths, add = TRUE, col = 'orange')
 # this still creates a plot in man/figures, so setting eval = FALSE
 knitr::opts_knit$set(global.device = FALSE)
 ```
+
+## Documentation
+
+The package documentation can be found at https://cneyens.github.io/raem/. 

README.md

@@ -6,6 +6,10 @@
 <!-- badges: start -->
 
 [![R-CMD-check](https://github.com/cneyens/raem/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/cneyens/raem/actions/workflows/R-CMD-check.yaml)
+[![Codecov test
+coverage](https://codecov.io/gh/cneyens/raem/branch/main/graph/badge.svg)](https://app.codecov.io/gh/cneyens/raem?branch=main)
+[![CRAN
+status](https://www.r-pkg.org/badges/version/raem)](https://CRAN.R-project.org/package=raem)
 <!-- badges: end -->
 
 `raem` is an R package for modeling steady-state single-layer
@@ -32,14 +36,16 @@ Specify the aquifer parameters and create elements:
 ``` r
 library(raem)
 
-k = 10
-top = 10
-base = 0
-n = 0.2
+# aquifer parameters ----
+k = 10     # hydraulic conductivity, m/d
+top = 10   # aquifer top elevation, m
+base = 0   # aquifer base elevation, m
+n = 0.2    # aquifer porosity, -
 
-hr = 15 # head at reference point, above aquifer top
-TR = k * (top - base) # constant transmissivity of background flow
+hr = 15    # head at reference point, m
+TR = k * (top - base) # constant transmissivity of background flow, m2/d
 
+# create elements ----
 uf = uniformflow(TR, gradient = 0.001, angle = -45)
 rf = constant(xc = -1000, yc = 0, hc = hr)
 w1 = well(xw = 200, yw = 0, Q = 250)
@@ -88,11 +94,16 @@ plot(m, add = TRUE)
 <img src="man/figures/README-plot-head-1.png" width="100%" />
 
 Compute particle traces starting along `y = 200` at 20 intervals per
-year for 5 years and add to plot:
+year for 5 years and add to the plot:
 
 ``` r
 paths = tracelines(m, x0 = seq(-450, 450, 50), y0 = 200, z0 = top, times = seq(0, 5*365, 365/20))
 plot(paths, add = TRUE, col = 'orange')
 ```
 
 <img src="man/figures/README-plot-traces-1.png" width="100%" />
+
+## Documentation
+
+The package documentation can be found at
+<https://cneyens.github.io/raem/>.

codecov.yml

@@ -0,0 +1,14 @@
+comment: false
+
+coverage:
+  status:
+    project:
+      default:
+        target: auto
+        threshold: 1%
+        informational: true
+    patch:
+      default:
+        target: auto
+        threshold: 1%
+        informational: true

vignettes/vign-01-overview.Rmd

@@ -17,7 +17,7 @@ knitr::opts_chunk$set(
 )
 ```
 
-The `raem` package provides a set of R functions to create an analytic element model of steady-state, single layer groundwater flow under the Dupuit-Forchheimer assumption. This vignette gives a short overview of the theory and basics behind analytic element modeling and how the `raem` package implements this in R.
+The `raem` package provides a set of R functions to create an analytic element model of steady-state, single-layer groundwater flow under the Dupuit-Forchheimer assumption. This vignette gives a short overview of the theory and basics behind analytic element modeling and how the `raem` package implements this in R.
 
 # Introduction to analytic element modeling