bfsl

Best-fit straight line of bivariate data with errors in both coordinates.

https://github.com/pasturm/bfsl

Repository

Best-fit straight line of bivariate data with errors in both coordinates.

README.Rmd

---
output: 
  github_document
  # html_document:
    # self_contained: no
---



```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```
# R package bfsl: Best-fit Straight Line

[![R build status](https://github.com/pasturm/bfsl/workflows/R-CMD-check/badge.svg)](https://github.com/pasturm/bfsl/actions)
[![codecov](https://codecov.io/gh/pasturm/bfsl/branch/master/graph/badge.svg)](https://codecov.io/gh/pasturm/bfsl)
[![CRAN version](https://www.r-pkg.org/badges/version-last-release/bfsl)](https://cran.r-project.org/package=bfsl)
[![CRAN downloads/month](https://cranlogs.r-pkg.org/badges/bfsl)](https://cran.r-project.org/package=bfsl)
[![CRAN total downloads](https://cranlogs.r-pkg.org/badges/grand-total/bfsl)](https://cran.r-project.org/package=bfsl)
[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)


### How to fit a straight line through a set of points with errors in both coordinates?

The solution for the best-fit straight line to independent points with normally distributed errors in both _x_ and _y_ is known e.g. from York ([1966](#york66), [1968](#york68), [2004](#york04)). It provides unbiased estimates of the intercept, slope and standard errors of the best-fit straight line, even when the _x_ and _y_ errors are correlated.

The bfsl package implements York's general solution and provides the best-fit straight line of bivariate data with errors in both coordinates.

Other commonly used least-squares estimation methods, such as ordinary least-squares regression, orthogonal distance regression (also called major axis regression), geometric mean regression (also called reduced major axis or standardised major axis regression) or Deming regression are all special cases of York’s solution and only valid under particular measurement conditions.


## Examples




```{r summary, out.width="75%", dpi=300}
library(bfsl)
fit = bfsl(pearson_york_data)
summary(fit)
```

```{r plot, out.width="75%", dpi=300}
plot(fit)
ols = bfsl(pearson_york_data, sd_x = 0, sd_y = 1)
abline(coef = ols$coef[,1], lty = 2)
legend("topright", c("best-fit straight line", "ordinary least squares"), lty = c(1,2))
```
```{r confidence, out.width="75%", dpi=300}
# with confidence interval
df = as.data.frame(fit$data)
newx = seq(min(df$x-df$sd_x), max(df$x+df$sd_x), length.out = 100)
preds = predict(fit, newdata = data.frame(x=newx), interval = 'confidence')

# plot
plot(y ~ x, data = df, type = 'n', xlim = c(min(x-sd_x), max(x+sd_x)),
     ylim = c(min(y-sd_y), max(y+sd_y)), las = 1)
grid()
polygon(c(rev(newx), newx), c(rev(preds[ ,3]), preds[ ,2]), col = 'grey90', border = NA)
abline(coef = fit$coef[,1], lty = 1)
points(df$x, df$y)
arrows(df$x, df$y-df$sd_y, df$x, df$y+df$sd_y, length = 0.05, angle = 90, code = 3)
arrows(df$x-df$sd_x, df$y, df$x+df$sd_x, df$y, length = 0.05, angle = 90, code = 3)
```
```{r ggplot, out.width="60%", dpi=300}
# with ggplot2
library(ggplot2)
ggplot(data = df, aes(x = x, y = y)) +
  geom_point() +
  geom_smooth(method = bfsl, method.args = list(sd_x = df$sd_x, sd_y = df$sd_y)) +
  geom_errorbar(aes(ymin = y-sd_y, ymax = y+sd_y), width = 0.05) +
  geom_errorbarh(aes(xmin = x-sd_x, xmax = x+sd_x), height = 0.05)
```

```{r broom tidier, out.width="60%", dpi=300}
# broom tidier methods
tidy(fit, conf.int = TRUE)
glance(fit)
augment(fit, newdata = data.frame(x = c(2:6)))
```

## Installation
Install bfsl from CRAN with:
```{r cran_install, eval=FALSE}
install.packages("bfsl")
```
Install the development version from GitHub with:
```{r github_install, eval=FALSE}
if (!require("remotes")) { install.packages("remotes") }
remotes::install_github("pasturm/bfsl")
```

See the [NEWS file](https://github.com/pasturm/bfsl/blob/master/NEWS.md) for latest release notes.

## References

York, D. (1966). Least-squares fitting of a straight line. _Canadian Journal of Physics_, 44(5), 1079–1086, https://doi.org/10.1139/p66-090

York, D. (1968). Least squares fitting of a straight line with correlated errors. _Earth and Planetary Science Letters_, 5, 320–324,
https://doi.org/10.1016/S0012-821X(68)80059-7

Williamson, J. H. (1968). Least-squares fitting of a straight line,
_Canadian Journal of Physics_, 46(16), 1845-1847, https://doi.org/10.1139/p68-523

York, D. et al. (2004). Unified equations for the slope, intercept, and 
standard errors of the best straight line, _American Journal of Physics_, 72, 367-375, https://doi.org/10.1119/1.1632486

Cantrell, C. A. (2008). Technical Note: Review of methods 
for linear least-squares fitting of data and application to atmospheric chemistry problems,
_Atmospheric Chemistry and Physics_, 8, 5477-5487, https://acp.copernicus.org/articles/8/5477/2008/

Wehr, R. and Saleska, S. R. (2017). The long-solved problem of the best-fit straight line: application to isotopic mixing lines, _Biogeosciences_, 14, 17-29, https://doi.org/10.5194/bg-14-17-2017

Owner

Citation (CITATION.cff)

# -----------------------------------------------------------
# CITATION file created with {cffr} R package, v0.1.1
# See also: https://docs.ropensci.org/cffr/
# -----------------------------------------------------------
 
cff-version: 1.2.0
message: 'To cite package "bfsl" in publications use:'
type: software
license: MIT
title: 'bfsl: Best-Fit Straight Line'
version: 0.2.0
abstract: How to fit a straight line through a set of points with errors in both coordinates?
  The 'bfsl' package implements the York regression (York, 2004 <doi:10.1119/1.1632486>).
  It provides unbiased estimates of the intercept, slope and standard errors for the
  best-fit straight line to independent points with (possibly correlated) normally
  distributed errors in both x and y. Other commonly used errors-in-variables methods,
  such as orthogonal distance regression, geometric mean regression or Deming regression
  are special cases of the 'bfsl' solution.
authors:
- family-names: Sturm
  given-names: Patrick
  email: sturm@tofwerk.com
preferred-citation:
  type: manual
  title: 'bfsl: Best-Fit Straight Line'
  authors:
  - family-names: Sturm
    given-names: Patrick
    email: sturm@tofwerk.com
  version: 0.2.0
  abstract: How to fit a straight line through a set of points with errors in both
    coordinates? The 'bfsl' package implements the York regression (York, 2004 <doi:10.1119/1.1632486>).
    It provides unbiased estimates of the intercept, slope and standard errors for
    the best-fit straight line to independent points with (possibly correlated) normally
    distributed errors in both x and y. Other commonly used errors-in-variables methods,
    such as orthogonal distance regression, geometric mean regression or Deming regression
    are special cases of the 'bfsl' solution.
  repository: https://CRAN.R-project.org/package=bfsl
  repository-code: https://github.com/pasturm/bfsl
  url: https://github.com/pasturm/bfsl
  date-released: '2021-09-23'
  contact:
  - family-names: Sturm
    given-names: Patrick
    email: sturm@tofwerk.com
  license: MIT
  year: '2021'
repository: https://CRAN.R-project.org/package=bfsl
repository-code: https://github.com/pasturm/bfsl
url: https://github.com/pasturm/bfsl
date-released: '2021-09-23'
contact:
- family-names: Sturm
  given-names: Patrick
  email: sturm@tofwerk.com

GitHub Events

Committers

Last synced: over 2 years ago

Issues and Pull Requests

Last synced: 8 months ago

Packages