Help for package mpspline2

Type:

Package

Title:

Mass-Preserving Spline Functions for Soil Data

Version:

0.1.9

Date:

2025-11-20

Description:

A low-dependency implementation of GSIF::mpspline() https://r-forge.r-project.org/scm/viewvc.php/pkg/R/mpspline.R?view=markup&revision=240&root=gsif, which applies a mass-preserving spline to soil attributes. Splining soil data is a safe way to make continuous down-profile estimates of attributes measured over discrete, often discontinuous depth intervals.

License:

GPL-2 | GPL-3 [expanded from: GPL]

Encoding:

UTF-8

Imports:

stats

Suggests:

testthat, covr

RoxygenNote:

7.3.3

URL:

https://github.com/obrl-soil/mpspline2

NeedsCompilation:

Packaged:

2025-11-22 23:37:51 UTC; leobr

Author:

Lauren O'Brien

[aut, cre], Brendan Malone

[ctb], Tomislav Hengl

[ctb], Tom Bishop [ctb], David Rossiter [ctb], Dylan Beaudette [ctb], Andrew Brown

[ctb]

Maintainer:

Lauren O'Brien <obrlsoilau@gmail.com>

Repository:

CRAN

Date/Publication:

2025-11-22 23:50:02 UTC

Spline discrete soils data - multiple sites

Description

This function implements the mass-preserving spline method of Bishop et al (1999) (doi:10.1016/S0016-7061(99)00003-8) for interpolating between measured soil attributes down a soil profile, across multiple sites' worth of data.

Usage

mpspline(
  obj = NULL,
  var_name = NULL,
  lam = 0.1,
  d = c(0, 5, 15, 30, 60, 100, 200),
  vlow = 0,
  vhigh = 1000
)

Arguments

obj

data.frame or matrix. Column 1 must contain site identifiers. Columns 2 and 3 must contain upper and lower sample depths, respectively. Subsequent columns will contain measured values for those depths.

var_name

character or integer vector denoting the column(s) in obj in which target data is stored. If not supplied, the fourth column of the input object is assumed to contain the target data.

lam

number; smoothing parameter for spline. Defaults to 0.1.

d

sequential integer vector; denotes the output depth ranges in cm. Defaults to c(0, 5, 15, 30, 60, 100, 200) after the GlobalSoilMap specification, giving output predictions over intervals 0-5cm, 5-15cm, etc.

vlow

numeric; constrains the minimum predicted value to a realistic number. Defaults to 0.

vhigh

numeric; constrains the maximum predicted value to a realistic number. Defaults to 1000.

Value

A nested list of data for each input site. List elements are: Site ID, vector of predicted values over input intervals, vector of predicted values for each cm down the profile to max(d), vector of predicted values over d (output) intervals, and root mean squared error.

Examples

# single variable
dat <- data.frame("SID" = c( 1,  1,  1,  1,   2,   2,   2,   2),
                   "UD" = c( 0, 20, 40, 60,   0,  15,  45,  80),
                   "LD" = c(10, 30, 50, 70,   5,  30,  60, 100),
                  "VAL" = c( 6,  4,  3, 10, 0.1, 0.9, 2.5,   6),
                   stringsAsFactors = FALSE)
m1 <- mpspline(obj = dat, var_name = 'VAL')

# multiple variables
dat_multi <- data.frame( "SID" = c( 1,  1,  1,  1,   2,   2,   2,   2),
                          "UD" = c( 0, 20, 40, 60,   0,  15,  45,  80),
                          "LD" = c(10, 30, 50, 70,   5,  30,  60, 100),
                        "VAL1" = c( 6,  4,  3, 10, 0.1, 0.9, 2.5,   6),
                        "VAL2" = c( 5,  3,  2,  9, 0.2, 1.0, 2.0,   5),
                        stringsAsFactors = FALSE)
m_multi <- mpspline(obj = dat_multi, var_name = c('VAL1', 'VAL2'))
# access results: m_multi[['VAL1']][['1']]

Spline discrete soils data - multiple sites

Description

These functions implement the mass-preserving spline method of Bishop et al (1999) (doi:10.1016/S0016-7061(99)00003-8) for interpolating between measured soil attributes down a soil profile, across multiple sites' worth of data. mpspline_compact() returns results as matrices while mpspline_tidy() returns results as data frames.

Usage

mpspline_compact(
  obj = NULL,
  var_name = NULL,
  lam = 0.1,
  d = c(0, 5, 15, 30, 60, 100, 200),
  vlow = 0,
  vhigh = 1000
)

mpspline_tidy(
  obj = NULL,
  var_name = NULL,
  lam = 0.1,
  d = c(0, 5, 15, 30, 60, 100, 200),
  vlow = 0,
  vhigh = 1000
)

Arguments

obj

data.frame or matrix. Column 1 must contain site identifiers. Columns 2 and 3 must contain upper and lower sample depths, respectively, measured in centimeters. Subsequent columns will contain measured values for those depths.

var_name

character or integer vector denoting the column(s) in obj in which target data is stored. If not supplied, the fourth column of the input object is assumed to contain the target data.

lam

number; smoothing parameter for spline. Defaults to 0.1.

d

vlow

numeric; constrains the minimum predicted value to a realistic number. Defaults to 0.

vhigh

numeric; constrains the maximum predicted value to a realistic number. Defaults to 1000.

Value

mpspline_compact() returns a four-item list containing matrices: predicted values over input depth ranges, output depth ranges, 1cm predictions, and RMSE values. Site identifiers are in rownames.

mpspline_tidy() returns a four-item list of data frames with the same predictions but in tidy format, with an added VARIABLE column when processing multiple variables.

Examples

dat <- data.frame("SID" = c( 1,  1,  1,  1,   2,   2,   2,   2),
                   "UD" = c( 0, 20, 40, 60,   0,  15,  45,  80),
                   "LD" = c(10, 30, 50, 70,   5,  30,  60, 100),
                  "VAL" = c( 6,  4,  3, 10, 0.1, 0.9, 2.5,   6),
                   stringsAsFactors = FALSE)
# single variable
result <- mpspline_compact(obj = dat, var_name = 'VAL')

# multiple variables
dat_multi <- data.frame( "SID" = c( 1,  1,  1,  1,   2,   2,   2,   2),
                          "UD" = c( 0, 20, 40, 60,   0,  15,  45,  80),
                          "LD" = c(10, 30, 50, 70,   5,  30,  60, 100),
                        "VAL1" = c( 6,  4,  3, 10, 0.1, 0.9, 2.5,   6),
                        "VAL2" = c( 5,  3,  2,  9, 0.2, 1.0, 2.0,   5),
                        stringsAsFactors = FALSE)
result_multi <- mpspline_compact(obj = dat_multi, var_name = c('VAL1', 'VAL2'))

# Single variable with tidy output
result <- mpspline_tidy(obj = dat, var_name = 'VAL')

# Multiple variables
dat_multi <- data.frame( "SID" = c( 1,  1,  1,  1,   2,   2,   2,   2),
                          "UD" = c( 0, 20, 40, 60,   0,  15,  45,  80),
                          "LD" = c(10, 30, 50, 70,   5,  30,  60, 100),
                        "VAL1" = c( 6,  4,  3, 10, 0.1, 0.9, 2.5,   6),
                        "VAL2" = c( 5,  3,  2,  9, 0.2, 1.0, 2.0,   5),
                        stringsAsFactors = FALSE)
result_multi <- mpspline_tidy(obj = dat_multi, var_name = c('VAL1', 'VAL2'))
subset(result_multi$est_dcm, VARIABLE == 'VAL1')

Convert data for splining

Description

Generate a consistent input object for splining

Usage

mpspline_conv(obj = NULL)

## S3 method for class 'matrix'
mpspline_conv(obj = NULL)

## S3 method for class 'data.frame'
mpspline_conv(obj = NULL)

Arguments

obj

Value

data frame, sorted by site ID, upper and lower depth.

pre-spline data checks

Description

Runs a few data quality checks and makes some repairs where possible.

Usage

mpspline_datchk(s = NULL, var_name = NULL)

Arguments

s

data frame, input data for a single soil profile.

var_name

character or integer vector denoting the column(s) in site in which target data is stored. If not supplied, the fourth column of the input object is assumed to contain the target data.

Value

If data passes checks it is returned unchanged. Sites with no data to spline and sites with overlapping input depth ranges return NA.

Estimate spline parameters

Description

Estimate key parameters for building a mass-preserving spline across a single soil profile

Usage

mpspline_est1(s = NULL, var_name = NULL, lam = NULL)

Arguments

s

data.frame containing a single profile's worth of soil info

var_name

character or integer vector denoting the column(s) in site in which target data is stored. If not supplied, the fourth column of the input object is assumed to contain the target data.

lam

number; smoothing parameter for spline. Defaults to 0.1.

Value

A list of parameters used for spline fitting.

Fit spline parameters

Description

Fit spline parameters to data for a single site.

Usage

mpspline_fit1(
  s = NULL,
  p = NULL,
  var_name = NULL,
  d = NULL,
  vhigh = NULL,
  vlow = NULL
)

Arguments

s

data.frame; data for one site

p

list; estimated spline parameters for one site from mpspline_est1

var_name

character or integer vector denoting the column(s) in obj in which target data is stored. If not supplied, the fourth column of the input object is assumed to contain the target data.

d

vhigh

numeric; constrains the maximum predicted value to a realistic number. Defaults to 1000.

vlow

numeric; constrains the minimum predicted value to a realistic number. Defaults to 0.

Value

list of two vectors: fitted values at 1cm intervals and the average of same over the requested depth ranges.

Spline discrete soils data - single site

Description

This function implements the mass-preserving spline method of Bishop et al (1999) (doi:10.1016/S0016-7061(99)00003-8) for interpolating between measured soil attributes down a single soil profile.

Usage

mpspline_one(
  site = NULL,
  var_name = NULL,
  lam = 0.1,
  d = c(0, 5, 15, 30, 60, 100, 200),
  vlow = 0,
  vhigh = 1000
)

Arguments

site

data frame containing data for a single soil profile. Column 1 must contain site identifiers. Columns 2 and 3 must contain upper and lower sample depths, respectively, measured in centimeters. Subsequent columns will contain measured values for those depths.

var_name

character or integer vector denoting the column(s) in site in which target data is stored. If not supplied, the fourth column of the input object is assumed to contain the target data.

lam

number; smoothing parameter for spline. Defaults to 0.1.

d

vlow

numeric; constrains the minimum predicted value to a realistic number. Defaults to 0.

vhigh

numeric; constrains the maximum predicted value to a realistic number. Defaults to 1000.

Value

A list with the following elements: Site ID, vector of predicted values over input intervals, vector of predicted values for each cm down the profile to max(d), vector of predicted values over d (output) intervals, and root mean squared error.

Examples

dat <- data.frame("SID" = c( 1,  1,  1,  1),
                   "UD" = c( 0, 20, 40, 60),
                   "LD" = c(10, 30, 50, 70),
                  "VAL" = c( 6,  4,  3, 10),
                   stringsAsFactors = FALSE)
mpspline_one(site = dat, var_name = 'VAL')

calculate RMSE

Description

Calculates Root Mean Squared Error (RMSE) for estimates on a single site

Usage

mpspline_rmse1(s = NULL, p = NULL, var_name = NULL)

Arguments

s

data.frame; data for one site

p

list; estimated spline parameters for one site from mpspline_est1

var_name

character or integer vector denoting the column(s) in site in which target data is stored. If not supplied, the fourth column of the input object is assumed to contain the target data.

Value

length-2 named numeric - RMSE and RMSE scaled against input data's interquartile range.

Note

Useful for comparing the results of varying parameter lam.