My solution

I made such a solution, called the Leaf Area Script, which you can find on Github and try for yourself. This is actually a collection of shell and powershell scripts covering all combinations of OS and ImageJ/Fiji. They are designed to work on most operating systems, require minimal setup, and quickly process many images. I won’t get into all the details, which are explained quite well at the link, but all you need to do is to drop images in any raster format, color, grayscale or binary, in the script folder³, run the script and check the measurements stored in the FAIRest format of all: CSV.

read.csv("aremonia.csv")

read.csv("summary.csv")

Other solutions

I would be remiss if I didn’t check other solutions, even if I think relying on well known external software like ImageJ and Fiji for the image processing ensures more reliability. I didn’t or couldn’t test all of them.

1. Some people who are really into Citrus were so proud of their script that they made a paper about it. This one is the most similar to mine, and it was easy enough to test, but I have a few issues with it. You have to manually set up input and output folders and write them in the python script. Then you have to click on a ruler each time you run the script to give a reference: making a “ruler” image in the right DPI with a 1 cm line isn’t hard, but hardly necessary and clicking is error prone (clicking on a 10-cm length would be more precise). It’s picky with the input images, for example it didn’t like half of my test images. It’s not customizable, you have to trust the defaults to do a good job with your scans

2. pliman seems nice if you prefer an R package

3. Leaf Area Meter is an unmantained python script and the syntax is more complicated, since you have to input all parameters as arguments instead of working with interactive terminal prompts

4. LeafAreaCalc looks like a python script with a UI and some traces of ChatGPT. The installation is more involved, in fact I was not able to test it because the indicated list of dependencies was not available

Setup

Just the bare minimum today.

library(conflicted)
library(tidyverse)

Rao functional diversity

The example data is a snippet from the data of De Benedictis et al. (2026). This is a peculiar case, because it comes from a 1000-unit looping transect which has been resampled with overlap at several scales, so there are many sampling units, but each has few records because they come from beech forest understory. This is just one scale of one transect. For each sampling unit X, row represent observations of a species. When the sampling units are aggregates as in this case, these can be used to calculate frequencies.

# load the preprocessed data
transect <- read_rds("transect.rds")

transect <- transect |> 
  #summarise records into species frequencies
  count(X, species) |> 
  # convert frequencies to proportions
  mutate(prop = n / sum(n), .by = X) |> 
  select(!n)

# convert data to a more traditional matrix
transect_mat <- transect |> 
  pivot_wider(names_from = species, 
              values_from = prop,
              values_fill = 0) |> 
  column_to_rownames("X") |> 
  as.matrix()

transect

# A tibble: 1,601 × 3
       X species                  prop
   <int> <chr>                   <dbl>
 1   152 Rosa arvensis           1    
 2   153 Rosa arvensis           1    
 3   154 Rosa arvensis           1    
 4   155 Rosa arvensis           1    
 5   156 Rosa arvensis           1    
 6   157 Brachypodium sylvaticum 0.5  
 7   157 Rosa arvensis           0.5  
 8   158 Brachypodium sylvaticum 0.667
 9   158 Rosa arvensis           0.333
10   159 Brachypodium sylvaticum 0.75 
# ℹ 1,591 more rows

# I have already done the work of gathering traits and calculate a distance matrix
distances <- read_rds("dist.rds")

distances[1:3, 1:3]

                  Sanicula europaea Galium odoratum Melica uniflora
Sanicula europaea         0.0000000       0.4859495       0.3095512
Galium odoratum           0.4859495       0.0000000       0.3663165
Melica uniflora           0.3095512       0.3663165       0.0000000

Custom function

As the first solution, I wanted to share a function that it’s so simple it almost feels like it shouldn’t work. The actual calculation is just one line of matrix algebra, the part before is just to get props and dist to agree. In practice, I’d always specify species, because this also ensures proportions and distances are in the same order (assuming the proportions come from a dataframe with a matching species column). Credit to this gist by Jon Lefcheck, even if the idea floats around the internet.

raoq <- function(props, dist, species = NULL){
  #subset species in the distance matrix if necessary
  if(!is.null(species)){
    dist <- dist[species, species]
  }
  
  c(crossprod(props, dist %*% props))
}

Rao sums across all species pairs the distance between i and j multiplied by the proportions of i and j to calculate an average distance. Our distance matrix already has all species pairs (optionally some that are not present, which can be subset or assigned 0 proportions), so there’s no need to loop: we just apply the matrix cross-product twice.

If you want, you could add a little check at the beginning if you want to take the species from the names of props, if present, but I prefer to be explicit with this sort of things.

if(is.null(species) && !is.null(names(props))) species <- names(props)

mat <- matrix(1:9, ncol = 3, byrow = T)
ab <- 1:3

mat

     [,1] [,2] [,3]
[1,]    1    2    3
[2,]    4    5    6
[3,]    7    8    9

mat %*% ab

     [,1]
[1,]   14
[2,]   32
[3,]   50

c(crossprod(ab, mat %*% ab))

[1] 228

#same as
sum(mat %*% ab * ab)

[1] 228

# multiply each row of mat by ab
step1 <- sweep(mat, 2, ab, "*") |> 
  # sum columns together
  rowSums()

sum(step1 * ab)

[1] 228

transect_nested <- transect |> 
  # nest, one tibble for each X
  nest(.by = X)

# calculate Rao!
transect_nested <- transect_nested |> 
  mutate(Rao = map_dbl(data, \(x) raoq(x$prop, distances, x$species)))

transect_nested

# A tibble: 564 × 3
       X data               Rao
   <int> <list>           <dbl>
 1   152 <tibble [1 × 2]> 0    
 2   153 <tibble [1 × 2]> 0    
 3   154 <tibble [1 × 2]> 0    
 4   155 <tibble [1 × 2]> 0    
 5   156 <tibble [1 × 2]> 0    
 6   157 <tibble [2 × 2]> 0.384
 7   158 <tibble [2 × 2]> 0.341
 8   159 <tibble [2 × 2]> 0.288
 9   160 <tibble [2 × 2]> 0.341
10   161 <tibble [2 × 2]> 0.360
# ℹ 554 more rows

FD, ade4, and adiv

How would one do this with usual packages? FD::dbFD() can calculate Rao, alongside many other things which can’t all be disabled (and take time to compute).

# distance matrix must be dist and not contain extra species
dist_dbfd <- distances[colnames(transect_mat), colnames(transect_mat)] |> 
  as.dist()

rao_dbfd <- FD::dbFD(
  #first argument could be either traits or a dist object
  x = dist_dbfd,
  #abundance matrix
  a = transect_mat,
  w.abun = T,
  calc.FRic = F,
  calc.FDiv = F,
  calc.CWM = F,
  messages = F) |> 
  #just Rao, please
  pluck("RaoQ")

Under the hood, it calls ade4::divc(), which is a second option, just with a different data structure.

rao_ade4 <- ade4::divc(
  #abundances should be a dataframe with species as ROWS
  as.data.frame(t(transect_mat)),
  #dist object above
  dist_dbfd,
  #the default for scale is F, but since it is undocumented better be explicit
  scale = F)

Unsurprisingly, the two give the same result, but it is not the same as raoq(). Why?

all.equal(unname(rao_dbfd), rao_ade4$diversity)

[1] TRUE

all.equal(rao_ade4$diversity, transect_nested$Rao)

[1] "Mean relative difference: 2.134283"

Inspecting the source, divc() does the same cross product trick, but column by column so it’s less efficient. Then, despite referencing Rao (1982), it performs a slightly different calculation: the distance matrix is squared, and the column result is divided by two and divided again by the squared sum of abundances. Putting aside the squared sum thing (that part is just scaling the raw abundances/presences/frequencies into proportions after the fact), this is actually the “Euclidean diversity coefficient” of Champely and Chessel (2002)! The reasoning behind it is that if distance used is the Euclidean distance, this equals the variance of the trait distribution see Appendix C of my article. This has been observed by Bello et al. (2016) too.

The scaling part is not an issue, the documentation does say “abundance, presence-absence or frequencies as entries”, and if you feed proportions it’s harmless, but divc() does the distance transformation behind the scenes, only checking if the distance matrix is Euclidean, even if it’s not the Euclidean. If we take the guts of divc, remove some input checks, and change one line to remove the part to go back to the original Rao formula, we get something like this:

fakedivc <- function (df, dis = NULL, scale = FALSE) 
{
  div <- as.data.frame(rep(0, ncol(df)))
  names(div) <- "diversity"
  rownames(div) <- names(df)
  for (i in 1:ncol(df)) {
    if (sum(df[, i]) < 1e-16) 
      div[i, ] <- 0
    else div[i, ] <- (t(df[, i]) %*% (as.matrix(dis)) %*% df[, i])/(sum(df[, i])^2)
  }
  if (scale == TRUE) {
    divmax <- divcmax(dis)$value
    div <- div/divmax
  }
  return(div)
}

And, sure enough, things match now.

rao_ade4_fake <- fakedivc(as.data.frame(t(transect_mat)),
                          dist_dbfd,
                          scale = F)

all.equal(rao_ade4_fake$diversity, transect_nested$Rao)

[1] TRUE

adiv::QE() is basically the same as these two, down to the source code, but it does have the option to choose between quadratic entropy and Euclidean diversity index:

rao_adiv <- adiv::QE(transect_mat,
                     dist_dbfd,
                     "QE") |> 
  pull()

all.equal(rao_adiv, transect_nested$Rao)

[1] TRUE

fundiversity

I agree, diversity is fun. This package seems cool, and the function fd_raoq() too. It can accept either traits or distances, has a nice helper to subset it and the community if the species don’t match, and uses the cross product under the hood. The results are the same as with raoq():

rao_fun <- fundiversity::fd_raoq(sp_com = transect_mat,
                                 dist_matrix = distances) |> 
  pluck("Q")
  
all.equal(rao_fun, transect_nested$Rao)

[1] TRUE

mFD

This function is one of those that calculates generalizations of functional diversity. Being based on Hill numbers, what it returns is actually the equivalent number but you only notice this if you pay attention to the cited literature and to the phrase “is equivalent to”, which doesn’t mean “equals”. Once we retransform the values, things add up.

rao_mfd <- mFD::alpha.fd.hill(transect_mat,
                              distances,
                              q = 2,
                              tau = "max",
                              details_returned = F)

rao_mfd <- 1 - 1 / rao_mfd[, 1]

all.equal(unname(rao_mfd), transect_nested$Rao)

[1] TRUE

hillR

Another function that calculates Hill number generalizations of functional diversity. We can calculate Rao by setting q = 2. In theory, you can provide either traits, or a “symmetric distance matrix” with traits_as_is: this is a lie, it wants a dist instead. Works fine otherwise. Unlike mFD(), it provides both Rao and functional Hill numbers, so you can pick your favourite.

rao_hillr <- hillR::hill_func(transect_mat, dist_dbfd, traits_as_is = T, q = 2, fdis = F)["Q", ]

all.equal(unname(rao_hillr), transect_nested$Rao)

[1] TRUE

Melodic

What if we look outside of CRAN? Bello et al. (2016) provide an R function called melodic() It’s a bit hidden inside the supplementary materials, and I had to tweak the checks in the first two lines because something must have changed with R in the last ten years: matrices seem to always have both class "matrix" and "array", so the check gives an error. I changed it to use inherits().

##MEan DIssimilarity Components##
#samp:  community matrix; sites in lines, species in columns
#dis:   dissimilarity matrix
#type:  "both" for results with abundances weighted and non-weighted
#       "abundance" for results with abundances weighted
#       "presence" for results with abundances non-weighted
  
melodic <- function(samp,dis,type="both"){
  if(!inherits(samp, "matrix")){samp <- as.matrix(samp)}
  if(!inherits(samp, "matrix")){dis <- as.matrix(dis)}
  if(is.null(colnames(samp)) | is.null(colnames(dis)) ){
    stop("Both samp and dis must have colnames.\n")
  }
  N<-dim(samp)[1]
    melodic<-list()
    if (type=="both"){
        melodic$abundance<-list()
        melodic$abundance$mpd<-melodic$abundance$rao<-melodic$abundance$simpson<-numeric(N)
        melodic$presence<-list()
        melodic$presence$mpd<-melodic$presence$rao<-melodic$presence$simpson<-numeric(N)
    }
    if (type=="abundance"){ 
        melodic$abundance<-list()
        melodic$abundance$mpd<-melodic$abundance$rao<-melodic$abundance$simpson<-numeric(N)
    }
    if (type=="presence"){ 
        melodic$presence<-list()
        melodic$presence$mpd<-melodic$presence$rao<-melodic$presence$simpson<-numeric(N)
    }
    for (i in 1:N){
        sppInSample<-names(samp[i,samp[i, ]>0])
        melodic$richness[i]<-rowSums(samp>0)[i]
        if (length(sppInSample)>1){
            sample.dis<-dis[sppInSample,sppInSample]
            abund.w<-numeric(length(sppInSample))
            if (type=="both" | type=="abundance"){
                abund.w <- samp[i , sppInSample] / sum(samp[i , sppInSample])
                sample.weights <- outer(abund.w , abund.w)
                melodic$abundance$mpd[i] <- weighted.mean(sample.dis[lower.tri(sample.dis)] , sample.weights[lower.tri(sample.weights)])
                melodic$abundance$rao[i] <- sum(sample.weights * sample.dis)
                melodic$abundance$simpson[i] <- sum(2*sample.weights[lower.tri(sample.weights)])
            }   
            if (type=="both" | type=="presence"){
                abund.nw <- rep(1 , length(sppInSample)) / length(sppInSample)
                sample.weights <- outer(abund.nw , abund.nw)
                melodic$presence$mpd[i] <- weighted.mean(sample.dis[lower.tri(sample.dis)] , sample.weights[lower.tri(sample.weights)])
                melodic$presence$rao[i] <- sum(sample.weights * sample.dis)
                melodic$presence$simpson[i] <- sum(2*sample.weights[lower.tri(sample.weights)])
            }   
        }   else {
            if (type=="both" | type=="abundance"){
                melodic$abundance$mpd[i] <- NA
                melodic$abundance$rao[i] <- melodic$abundance$simpson[i] <-0
            }
            if (type=="both" | type=="presence"){
                melodic$presence$mpd[i] <- NA
                melodic$presence$rao[i] <- melodic$presence$simpson[i] <-0
            }
        }
    }   
    out<-melodic
    return(out) 
}

This function is alright: a bit more complex than raoq() and it doesn’t use the cool cross products, opting for a loop instead. You might find the extra output it gives useful. If we focus on Rao, it works as expected:

rao_mel <- melodic(transect_mat, distances, "abundance") |> 
  pluck("abundance", "rao")

all.equal(rao_mel, transect_nested$Rao)

[1] TRUE

Performance comparison

The authors of fundiversity seem to care about performance, since they did an overview of available packages and benchmarked them together. One thing I noticed about fd_raoq() is that it calculates Rao even with pairs of abundance vectors from different communities. That could be useful as a first step to calculate the original Rao dissimilarity, but here they are just discarded. How will it perform against the others?

dist_subset <- as.matrix(dist_dbfd)

#suppressMessages is so that FD would shut up
bench <- bench::mark(
  raoq_map = map_dbl(transect_nested$data, \(x) raoq(x$prop, distances, x$species)),
  raoq_mat = apply(transect_mat, 1, function(x) raoq(x, dist_subset)),
  FD = FD::dbFD(x = dist_dbfd,
           a = transect_mat,
           w.abun = T,
           calc.FRic = F,
           calc.FDiv = F,
           calc.CWM = F,
           messages = F),
  ade4 = ade4::divc(as.data.frame(t(transect_mat)),
             dist_dbfd,
             scale = F),
  adiv = adiv::QE(transect_mat, dist_dbfd, "QE"),
  fundiversity = fundiversity::fd_raoq(sp_com = transect_mat, dist_matrix = distances),
  mFD = mFD::alpha.fd.hill(transect_mat, distances, q = 2, tau = "max", details_returned = F),
  hillR = hillR::hill_func(transect_mat, dist_dbfd, traits_as_is = T, q = 2, fdis = F),
  melodic = melodic(transect_mat, distances, "abundance"),
  check = F) |> 
  arrange(median)

bench

# A tibble: 9 × 6
  expression        min   median `itr/sec` mem_alloc `gc/sec`
  <bch:expr>   <bch:tm> <bch:tm>     <dbl> <bch:byt>    <dbl>
1 fundiversity   1.21ms   1.77ms    476.      2.68MB    37.6 
2 raoq_mat       1.88ms   2.01ms    467.     62.89KB     4.00
3 raoq_map       3.98ms   4.41ms    139.     44.14KB     3.96
4 hillR          9.26ms   9.98ms     94.8      276KB     3.95
5 mFD            22.7ms  23.19ms     42.1   451.85KB     1.91
6 adiv          24.63ms  25.52ms     37.4     3.25MB     3.94
7 melodic       37.07ms  41.47ms     23.8    14.93MB     9.92
8 ade4           63.6ms  66.31ms     15.0     3.37MB     1.87
9 FD           856.57ms 856.57ms      1.17    5.86MB     2.33

fd_raoq() still wins, with raoq() close behind! This is the power of primitve matrix operations: even when computing N² indices instead of N, this is still faster if you can do it with matrix products instead of row by row. This holds true even when the distance matrix is subset beforehand, instead of each iteration (raoq_map).

Learning from this and taking up the challenge, can we make raoq() fast? Since the trick is to use only matrix operations, we turn to the community matrix, instead of iterating over single vectors of proportions. This has the advantage that we don’t need to have a separate species argument, we can just use column names as everyone else. Turns out we don’t need to do the big N² cross product, we can do something similar to what I did when explaining the double cross product by just doing multiplication followed by summing columns. We can have our cake and eat it too, or as they say in Italy, you can have a full cask and a drunk wife (I’m not a fan of cake, wine, or sexist sayings either):

raoq_fast <- function(com, dist){
  #subset species in the distance matrix if necessary
  species <- colnames(com)
  dist <- dist[species, species]
  #it's called rowSums because it sums together columns by row
  rowSums((com %*% dist) * com)
}

rao_raoqfast <- raoq_fast(transect_mat, distances)

all.equal(unname(rao_raoqfast), rao_fun)

[1] TRUE

rebench <- bench::mark(
  raoq_fast = unname(raoq_fast(transect_mat, distances)),
  fd_raoq = fundiversity::fd_raoq(sp_com = transect_mat, dist_matrix = distances),
  check = F) |> 
  arrange(median)

rebench

# A tibble: 2 × 6
  expression      min   median `itr/sec` mem_alloc `gc/sec`
  <bch:expr> <bch:tm> <bch:tm>     <dbl> <bch:byt>    <dbl>
1 raoq_fast      41µs  44.91µs    19487.  113.94KB     47.0
2 fd_raoq       1.2ms   1.27ms      620.    2.68MB     53.2

Well well! About 40 to 50 times faster than fd_raoq()!

Conclusions

In practice, the speed differences are irrelevant, except maybe for dbFD(because it calculates a bunch of other things). Since FD, ade4 and adiv calculate their own version of Rao, I would use either my functions, adiv, fundiversity, or melodic. If you’re into Hill numbers, the mFD and hillR packages are interesting, but you can always transform Rao yourself if you stick with q = 2. Between my two functions, I would probably still use the slower one, because iterating explicitly gives me more control over the output format. Another thing of note is whether the functions require you to subset the distance matrix beforehand or they take care of it themselves, and whether they want a matrix or a dist. I consider functions that can take a matrix and can subset or rearrange it more robust, and those would be raoq()(either one), fd_raoq(), alpha.fd.hill(), and melodic().

I hope this is useful to someone. The first thought when having to calculate an index might be “oh, I’ll just grab a package that does it”, but we have seen how things are not as simple as that in this case. This is not meant to be a comprehensive overview, but to include many popular solutions as well as providing some interesting alternatives.

Extra: decomposition

I mentioned at the beginning that the formula is just a small part of what you can do, and you can go further with a nested decomposition in the style of .

To give you a taste of that, I’ll share a function I made for De Benedictis et al. (2026) which calculates a bunch of Rao-based indices. Compared to the original, I changed the input format to the classical community matrix, raoq() with the updated version with name matching (instead of factors, ugh), and the internal data format to the convention “species on columns, samples on rows”. The indices are described in De Bello et al. (2010) and Pavoine and Ricotta (2024).

qdecomp <- function(data, distances){
  #alpha Q
  alpha <- apply(data, 1, function(x) raoq(x, distances, names(x))) |>
    mean()
  #regional relative abundances as mean of local ab.
  #this gives equal weight to each community
  P_i <- colMeans(data)
  #gamma Q
  gamma <- raoq(P_i, distances, names(P_i))
  #additive beta
  beta_add <- gamma - alpha
  #additive beta normalized by gamma
  beta_rel <- beta_add / gamma
  #equivalent alpha
  E_alpha <- 1/(1-alpha)
  #equivalent gamma
  E_gamma <- 1/(1-gamma)
  #multiplicative eq. beta
  E_beta_mult <- E_gamma / E_alpha
  #additive eq. beta
  E_beta_add <- E_gamma - E_alpha
  #proportional additive beta, normalized on sample n
  E_beta_add_prop_norm <- (E_beta_add / E_gamma) / (1 - 1 / nrow(data))
  #matrix of taxonomic distances (0/1)
  taxon <- distances
  taxon[,] <- 1
  diag(taxon) <- 0
  #taxonomic alpha
  alpha_sp <- apply(data, 1, function(x) raoq(x, taxon, names(x))) |> 
    mean()
  #taxonomic gamma
  gamma_sp <- raoq(P_i, taxon, names(P_i))
  #additive tax. beta
  beta_sp_add <- gamma_sp - alpha_sp
  #normalized tax. beta
  beta_sp_rel <- beta_sp_add / gamma_sp
  #equivalent tax. alpha
  E_alpha_sp <- 1/(1-alpha_sp)
  #equivalent tax. gamma
  E_gamma_sp <- 1/(1-gamma_sp)
  #equivalent tax. beta
  E_beta_sp <- E_gamma_sp / E_alpha_sp
  #beta Q clustering
  clustering <- beta_rel / beta_sp_rel
  #gamma Q uniqueness
  uniqueness <- gamma / gamma_sp
  #gamma E uniqueness
  U_gamma_star <- E_gamma / E_gamma_sp
  #alpha E redundancy, inverse of Ualpha_star
  redundancy_a <- E_alpha_sp / E_alpha
  
  output <- data.frame(alpha, gamma, beta_add, beta_rel,
                       E_alpha, E_gamma, E_beta_mult, E_beta_add,
                       E_beta_add_prop_norm, clustering, uniqueness,
                       alpha_sp, gamma_sp, U_gamma_star, redundancy_a,
                       beta_sp_add, E_alpha_sp, E_gamma_sp, E_beta_sp)
  return(output)
}

How does that look, applied to the data?

qdecomp(transect_mat, distances) |> 
  glimpse()

Rows: 1
Columns: 19
$ alpha                <dbl> 0.2412185
$ gamma                <dbl> 0.4228523
$ beta_add             <dbl> 0.1816339
$ beta_rel             <dbl> 0.4295444
$ E_alpha              <dbl> 1.317902
$ E_gamma              <dbl> 1.732659
$ E_beta_mult          <dbl> 1.31471
$ E_beta_add           <dbl> 0.4147564
$ E_beta_add_prop_norm <dbl> 0.2398009
$ clustering           <dbl> 0.9526582
$ uniqueness           <dbl> 0.5636274
$ alpha_sp             <dbl> 0.4119606
$ gamma_sp             <dbl> 0.7502337
$ U_gamma_star         <dbl> 0.4327597
$ redundancy_a         <dbl> 1.290358
$ beta_sp_add          <dbl> 0.3382732
$ E_alpha_sp           <dbl> 1.700566
$ E_gamma_sp           <dbl> 4.003743
$ E_beta_sp            <dbl> 2.354359

As far as I know, most of the indices above have not yet been implemented in a package. The alternative would be following the script of Pavoine and Ricotta (2024).

Setup

Just loading some packages.

library(conflicted)
library(tidyverse)
library(vegan)

Example 1: pairwise dissimilarities

The following example uses a small, cleaned-up subset of the data in Cervellini et al. (2026). Several observers have recorded species cover in the same sampling unit (this is just one sampling unit and one exercise):

training <- read_rds("tidyveg_ex1.rds")

training

# A tibble: 175 × 3
   observer species           cover
   <chr>    <chr>             <dbl>
 1 a        Ruscus aculeatus   10  
 2 a        Hedera helix        2  
 3 a        Melica uniflora     0.1
 4 a        Rubia peregrina     0.5
 5 a        Cyclamen repandum   1  
 6 a        Quercus cerris      0.1
 7 B        Lonicera etrusca    0.1
 8 B        Cyclamen repandum   0.5
 9 B        Melica uniflora     0.5
10 B        Hedera helix        1  
# ℹ 165 more rows

This long tibble is nice: you can easily calculate observer species richness, filter out rows, transform the percent cover; it’s not the format vegdist() wants to see though. You could just pivot the tibble and feed it to the function, this actually works because vegdist() silently converts it to a matrix:

plain1 <- training |> 
  pivot_wider(names_from = species, values_from = cover, values_fill = 0) |> 
  column_to_rownames("observer") |> 
  # default Bray-Curtis (Steinhaus, Motyka, Odum, percentage difference or however you want to call it) 
  vegdist()

plain1

           a          B          c          d          E          f          g
B 0.37628866                                                                  
c 0.50035386 0.23443019                                                       
d 0.59124088 0.34743202 0.20819602                                            
E 0.35370685 0.16987591 0.21955096 0.34746573                                 
f 0.59479222 0.36860827 0.26540951 0.11345394 0.36791126                      
g 0.30291698 0.51232302 0.53798227 0.58219431 0.34083045 0.63436203           
h 0.42393205 0.24168773 0.21192294 0.32967522 0.12320200 0.41688501 0.42443485
i 0.43859649 0.11675741 0.16246709 0.29105047 0.15499675 0.37092432 0.47615241
l 0.49898692 0.31496423 0.17263279 0.27286082 0.30997911 0.34016393 0.55771024
m 0.63031423 0.44891717 0.39170183 0.23830963 0.46952856 0.14808081 0.67762308
n 0.44652206 0.18074160 0.07150635 0.23863131 0.20249740 0.24658331 0.52344740
o 0.31958128 0.22515953 0.25679376 0.38076152 0.08411677 0.41259199 0.34318039
p 0.40981938 0.12837705 0.24051565 0.33743067 0.16105820 0.36128273 0.47115136
q 0.32626326 0.23101703 0.29649309 0.40094181 0.13450000 0.43125309 0.36942675
           h          i          l          m          n          o          p
B                                                                             
c                                                                             
d                                                                             
E                                                                             
f                                                                             
g                                                                             
h                                                                             
i 0.17394726                                                                  
l 0.26001195 0.29563614                                                       
m 0.49541948 0.46770217 0.32832750                                            
n 0.28706864 0.19449902 0.21701493 0.36657033                                 
o 0.16958546 0.18881442 0.37072596 0.52446625 0.26178358                      
p 0.20639199 0.15928144 0.28549849 0.41123541 0.18454441 0.21694075           
q 0.21011412 0.22333722 0.39847328 0.52607014 0.26021890 0.05654281 0.21946782

There are some issues with this. First of all, vegan really likes to use row and column names to identify the pairs. There’s not much choice with matrices, but maybe in the original data you have a separate identifier column. If you want that to be transferred, you need to transform it into row names. Tibbles hate row names so much that as soon as I call that second function the data stops being a tibble and becomes a plain dataframe. The documentation in ?tibble::rownames explains this stance convincingly: row names are just a character variable, but much more volatile (you can lose it from one operation to the next) and with a special treatment. If you want a character variable, make a column for it.

The second issue is with the output format. I really think the dist class is an ugly and error-prone convention started by base R. What you get from the above looks like a matrix (more specifically, the lower triangle), but is in fact a weird dressed-up vector. The same is true even if you set diag = TRUE and upper = TRUE in vegdist(), even if the printed output looks identical to a matrix.

plain2 <- training |> 
  pivot_wider(names_from = species, values_from = cover, values_fill = 0) |> 
  column_to_rownames("observer") |> 
  vegdist(diag = T, upper = T)

plain2

           a          B          c          d          E          f          g
a 0.00000000 0.37628866 0.50035386 0.59124088 0.35370685 0.59479222 0.30291698
B 0.37628866 0.00000000 0.23443019 0.34743202 0.16987591 0.36860827 0.51232302
c 0.50035386 0.23443019 0.00000000 0.20819602 0.21955096 0.26540951 0.53798227
d 0.59124088 0.34743202 0.20819602 0.00000000 0.34746573 0.11345394 0.58219431
E 0.35370685 0.16987591 0.21955096 0.34746573 0.00000000 0.36791126 0.34083045
f 0.59479222 0.36860827 0.26540951 0.11345394 0.36791126 0.00000000 0.63436203
g 0.30291698 0.51232302 0.53798227 0.58219431 0.34083045 0.63436203 0.00000000
h 0.42393205 0.24168773 0.21192294 0.32967522 0.12320200 0.41688501 0.42443485
i 0.43859649 0.11675741 0.16246709 0.29105047 0.15499675 0.37092432 0.47615241
l 0.49898692 0.31496423 0.17263279 0.27286082 0.30997911 0.34016393 0.55771024
m 0.63031423 0.44891717 0.39170183 0.23830963 0.46952856 0.14808081 0.67762308
n 0.44652206 0.18074160 0.07150635 0.23863131 0.20249740 0.24658331 0.52344740
o 0.31958128 0.22515953 0.25679376 0.38076152 0.08411677 0.41259199 0.34318039
p 0.40981938 0.12837705 0.24051565 0.33743067 0.16105820 0.36128273 0.47115136
q 0.32626326 0.23101703 0.29649309 0.40094181 0.13450000 0.43125309 0.36942675
           h          i          l          m          n          o          p
a 0.42393205 0.43859649 0.49898692 0.63031423 0.44652206 0.31958128 0.40981938
B 0.24168773 0.11675741 0.31496423 0.44891717 0.18074160 0.22515953 0.12837705
c 0.21192294 0.16246709 0.17263279 0.39170183 0.07150635 0.25679376 0.24051565
d 0.32967522 0.29105047 0.27286082 0.23830963 0.23863131 0.38076152 0.33743067
E 0.12320200 0.15499675 0.30997911 0.46952856 0.20249740 0.08411677 0.16105820
f 0.41688501 0.37092432 0.34016393 0.14808081 0.24658331 0.41259199 0.36128273
g 0.42443485 0.47615241 0.55771024 0.67762308 0.52344740 0.34318039 0.47115136
h 0.00000000 0.17394726 0.26001195 0.49541948 0.28706864 0.16958546 0.20639199
i 0.17394726 0.00000000 0.29563614 0.46770217 0.19449902 0.18881442 0.15928144
l 0.26001195 0.29563614 0.00000000 0.32832750 0.21701493 0.37072596 0.28549849
m 0.49541948 0.46770217 0.32832750 0.00000000 0.36657033 0.52446625 0.41123541
n 0.28706864 0.19449902 0.21701493 0.36657033 0.00000000 0.26178358 0.18454441
o 0.16958546 0.18881442 0.37072596 0.52446625 0.26178358 0.00000000 0.21694075
p 0.20639199 0.15928144 0.28549849 0.41123541 0.18454441 0.21694075 0.00000000
q 0.21011412 0.22333722 0.39847328 0.52607014 0.26021890 0.05654281 0.21946782
           q
a 0.32626326
B 0.23101703
c 0.29649309
d 0.40094181
E 0.13450000
f 0.43125309
g 0.36942675
h 0.21011412
i 0.22333722
l 0.39847328
m 0.52607014
n 0.26021890
o 0.05654281
p 0.21946782
q 0.00000000

This gets especially confusing when you try to do normal matrix operations like subsetting, since the underlying object is one-dimensional:

try(plain2[1, 1])

Error in plain2[1, 1] : incorrect number of dimensions

I think it’s best to call as.matrix() right away and work with the full symmetrical matrix, then handle it as needed.

Finally, maybe I would like to let stats and vegan enjoy their matrices and look at the output in a tibble instead. Let’s say we want to use those distance values as data in a model, as we did in the paper above. To do all this behind the scenes, I made two helper functions, which I have now adapted for more general use:

vegan_cook <- function(x, species_col = "species", value_col = "cover", sample_name = NULL){
  
  if(is.null(sample_name)) sample_name <- setdiff(names(x), c(species_col, value_col))
  if(length(sample_name) > 1) stop("Please provide a unique identifier column for samples")
  
  x |> 
    pivot_wider(names_from = all_of(species_col), values_from = all_of(value_col), values_fill = 0) |> 
    column_to_rownames(sample_name) |> 
    as.matrix()
}

tidyvegdist <- function(x, sample_names = "sample", diag = F, tri = F, ...){
  
  if(length(sample_names) == 1) sample_names <- str_c(sample_names, 1:2, sep = "_")
  
  vegdist(x, ...) |> 
    as.matrix() |> 
    (\(m) {if (tri) m[upper.tri(m, diag = F)] <- NA; m})() |> 
    (\(m) {if (!diag) diag(m) <- NA; m})() |> 
    as_tibble(rownames = sample_names[1]) |> 
    pivot_longer(!all_of(sample_names[1]), names_to = sample_names[2]) |> 
    drop_na()
}

vegan_cook() handles the forward transformation into a vegan matrix. You can specify the names of the columns to pivot from with species_col and value_col. The row (sample) name columns is gathered automatically from the remaining column, or can be specified manually. tidyvegdist() calls vegdist() and returns a long tibble. You can choose how to call the columns with the pair names, either with an atomic string, which gets suffixes, or with a character vector. It defaults to "sample"; you can choose to include the diagonal values (usually 0) with diag, or to get a triangular matrix instead of the full symmetric matrix with tri; finally, you can pass other arguments to vegdist(), such as method.

training |> 
  vegan_cook() |>
  tidyvegdist()

# A tibble: 210 × 3
   sample_1 sample_2 value
   <chr>    <chr>    <dbl>
 1 a        B        0.376
 2 a        c        0.500
 3 a        d        0.591
 4 a        E        0.354
 5 a        f        0.595
 6 a        g        0.303
 7 a        h        0.424
 8 a        i        0.439
 9 a        l        0.499
10 a        m        0.630
# ℹ 200 more rows

Example 2: transect data

The second example is a snippet from the data of De Benedictis et al. (2026). This is a peculiar case, because it comes from a 1000-unit looping transect which has been resampled with overlap at several scales, so there are many sampling units, but each has few records because they come from beech forest understory. This is just one scale of one transect. For each sampling unit X, row represent observations of a species. When the sampling units are aggregates as in this case, these can be used to calculate frequencies.

transect <- read_rds("tidyveg_ex2.rds")

transect

# A tibble: 7,200 × 2
       X species                
   <int> <chr>                  
 1   152 Rosa arvensis          
 2   153 Rosa arvensis          
 3   154 Rosa arvensis          
 4   155 Rosa arvensis          
 5   156 Rosa arvensis          
 6   157 Rosa arvensis          
 7   157 Brachypodium sylvaticum
 8   158 Rosa arvensis          
 9   158 Brachypodium sylvaticum
10   158 Brachypodium sylvaticum
# ℹ 7,190 more rows

There are 7200 observations, and so rows. What would happen if we had this data in a wide format?

too_wide <- transect |> 
  mutate(presence = T) |> 
  pivot_wider(names_from = species, values_from = presence, values_fn = length)

glimpse(too_wide)

Rows: 564
Columns: 11
$ X                         <int> 152, 153, 154, 155, 156, 157, 158, 159, 160,…
$ `Rosa arvensis`           <int> 1, 1, 1, 1, 1, 1, 1, 1, 2, 3, 4, 4, 4, 4, 5,…
$ `Brachypodium sylvaticum` <int> NA, NA, NA, NA, NA, 1, 2, 3, 4, 5, 6, 7, 8, …
$ `Daphne laureola`         <int> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, …
$ `Festuca heterophylla`    <int> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, …
$ `Aremonia agrimonoides`   <int> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, …
$ `Clinopodium nepeta`      <int> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, …
$ `Dactylis glomerata`      <int> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, …
$ `Luzula forsteri`         <int> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, …
$ `Lactuca muralis`         <int> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, …
$ `Hieracium murorum`       <int> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, …

I warned you the data were sparse! Out of 5640 values, 4039 are NA. And we’re lucky because only the 10 species recorded in this transect are listed.

And that’s not even fair to the long format, because this has already aggregated frequency counts in the rows. We can do the same with the long tibble:

transect <- transect |> 
  count(X, species)

transect

# A tibble: 1,601 × 3
       X species                     n
   <int> <chr>                   <int>
 1   152 Rosa arvensis               1
 2   153 Rosa arvensis               1
 3   154 Rosa arvensis               1
 4   155 Rosa arvensis               1
 5   156 Rosa arvensis               1
 6   157 Brachypodium sylvaticum     1
 7   157 Rosa arvensis               1
 8   158 Brachypodium sylvaticum     2
 9   158 Rosa arvensis               1
10   159 Brachypodium sylvaticum     3
# ℹ 1,591 more rows

Aside from this cosmetic difference, what can we do with the long format? We can join some traits or other information for example, and keep it neatly along the records.

traits <- read_rds("traits.rds")

transect |> 
  left_join(traits)

# A tibble: 1,601 × 13
       X species              n leaf_area_mm2 nmass_mg_g lma_g_m2 plant_height_m
   <int> <chr>            <int>         <dbl>      <dbl>    <dbl>          <dbl>
 1   152 Rosa arvensis        1          302.       24.3     45.4          1.16 
 2   153 Rosa arvensis        1          302.       24.3     45.4          1.16 
 3   154 Rosa arvensis        1          302.       24.3     45.4          1.16 
 4   155 Rosa arvensis        1          302.       24.3     45.4          1.16 
 5   156 Rosa arvensis        1          302.       24.3     45.4          1.16 
 6   157 Brachypodium sy…     1         2195.       21.6     23.1          0.662
 7   157 Rosa arvensis        1          302.       24.3     45.4          1.16 
 8   158 Brachypodium sy…     2         2195.       21.6     23.1          0.662
 9   158 Rosa arvensis        1          302.       24.3     45.4          1.16 
10   159 Brachypodium sy…     3         2195.       21.6     23.1          0.662
# ℹ 1,591 more rows
# ℹ 6 more variables: diaspore_mass_mg <dbl>, ssd_combined_mg_mm3 <dbl>,
#   BBRsize <dbl>, persistence <dbl>, offspring <dbl>, spread <dbl>

Or we can easily convert frequencies to proportions:

transect |> 
  mutate(prop = n / sum(n), .by = X)

# A tibble: 1,601 × 4
       X species                     n  prop
   <int> <chr>                   <int> <dbl>
 1   152 Rosa arvensis               1 1    
 2   153 Rosa arvensis               1 1    
 3   154 Rosa arvensis               1 1    
 4   155 Rosa arvensis               1 1    
 5   156 Rosa arvensis               1 1    
 6   157 Brachypodium sylvaticum     1 0.5  
 7   157 Rosa arvensis               1 0.5  
 8   158 Brachypodium sylvaticum     2 0.667
 9   158 Rosa arvensis               1 0.333
10   159 Brachypodium sylvaticum     3 0.75 
# ℹ 1,591 more rows

How would you do that with the wide format? Well, for the traits I’m not sure where I would fit them, but for the proportions you need a rowwise operation, which isn’t usually as easy:

too_wide <- too_wide |> 
  # you can avoid this step by using values_fill in pivot_wider, but I wanted to count the NAs
  mutate(across(everything(), \(x) replace_na(x, 0)))

# rowwise is usually a sign that you're doing something wrong. Also, this is slow
too_wide |> 
  rowwise() |> 
  mutate(across(!X, \(x) x / sum(c_across(!X))))

# A tibble: 564 × 11
       X `Rosa arvensis` `Brachypodium sylvaticum` `Daphne laureola`
   <int>           <dbl>                     <dbl>             <dbl>
 1   152           1                         0                     0
 2   153           1                         0                     0
 3   154           1                         0                     0
 4   155           1                         0                     0
 5   156           1                         0                     0
 6   157           0.5                       0.5                   0
 7   158           0.333                     0.667                 0
 8   159           0.25                      0.75                  0
 9   160           0.333                     0.667                 0
10   161           0.375                     0.625                 0
# ℹ 554 more rows
# ℹ 7 more variables: `Festuca heterophylla` <dbl>,
#   `Aremonia agrimonoides` <dbl>, `Clinopodium nepeta` <dbl>,
#   `Dactylis glomerata` <dbl>, `Luzula forsteri` <dbl>,
#   `Lactuca muralis` <dbl>, `Hieracium murorum` <dbl>

# since we're doing this, might as well give up and convert to matrix
too_wide |> 
  column_to_rownames("X") |> 
  as.matrix() |> 
  proportions(margin = 1) |> 
  head()

    Rosa arvensis Brachypodium sylvaticum Daphne laureola Festuca heterophylla
152           1.0                     0.0               0                    0
153           1.0                     0.0               0                    0
154           1.0                     0.0               0                    0
155           1.0                     0.0               0                    0
156           1.0                     0.0               0                    0
157           0.5                     0.5               0                    0
    Aremonia agrimonoides Clinopodium nepeta Dactylis glomerata Luzula forsteri
152                     0                  0                  0               0
153                     0                  0                  0               0
154                     0                  0                  0               0
155                     0                  0                  0               0
156                     0                  0                  0               0
157                     0                  0                  0               0
    Lactuca muralis Hieracium murorum
152               0                 0
153               0                 0
154               0                 0
155               0                 0
156               0                 0
157               0                 0

Or we could calculate Rao’s quadratic entropy!

What?

In some disciplines, there is a disconnect between scientific theory and use of models and current practice. In physics, for example, theory often results in an explicit functional form, this model is tested against reality, and it is provisionally kept as long as there are no obvious discrepancies with observation. If and when those arise, it’s an incentive to question the model and look for a better one. In many other scientific fields, the role of falsification seems like the opposite: nobody really believes the “null” model represents reality, and observing a lack of fit to data is the goal. Null hypothesis rejected, you discovered something new (maybe) and you win! This contrast has been highlighted several times, for example by Meehl (1967).

It doesn’t have to be like this. Even when fitting statistical models to empirical data, sometimes you’re lucky and theory provides you with a formula that you can use in place of an additive linear model. Chapter 16 of McElreath (2020) is dedicated to examples of this, including one with the Lotka-Volterra equations. Nonlinear model formulas are key to this approach, so, with the purpose of getting in some exercise with them in brms, I have developed the following contrived example:

Let’s fit Kepler’s third law in brms to find the gravitational constant G

What I mean exactly is the formula that you get by substituting Newton’s law of gravitation into Kepler’s law

What data to fit this to? I found a website that lets you freely download data about solar system bodies in a machine-readable way. For simplicity, I’m restricting this to moons orbiting around planets, since the two are easy to combine in their data format.

Setup

library(conflicted)
library(tidyverse)
library(httr)
library(brms)
library(ggdist)

conflicts_prefer(dplyr::filter,
                 brms::ar,
                 brms::dstudent_t,
                 brms::pstudent_t,
                 brms::qstudent_t,
                 brms::rstudent_t,
                 stats::lag)

#please use cmdstanr, it's so much faster
options(cores = parallel::detectCores(),
        brms.backend = "cmdstanr",
        pillar.sigfig = 6)

theme_set(theme_minimal())

Get the data

#this is my key, stored locally. You can get your own, it's free
key <- read_lines("apikey.txt")

#moon data
moons <- GET("https://api.le-systeme-solaire.net/rest/bodies/", 
           add_headers(Authorization = paste("Bearer", key)),
           query = list(`filter[]` = "bodyType,eq,Moon")) |> 
  content()

#planet data
planets <- GET("https://api.le-systeme-solaire.net/rest/bodies/", 
               add_headers(Authorization = paste("Bearer", key)),
               query = list(`filter[]` = "bodyType,eq,Planet")) |> 
  content()

useful <- c("id", "englishName", "semimajorAxis", "mass", "sideralOrbit", "aroundPlanet")

#wrangle this ugly list into a nice tibble
planets <- planets$bodies |> 
  map(\(x) x |> 
        #some elements are null, some are lists of length 2
        #as_tibble_row complains, that's why the gymnastics
        discard(is_null) |> 
        enframe() |> 
        pivot_wider()) |> 
  #bind the planet rows into a tibble
  bind_rows() |> 
  #keep only what's necessary
  select(any_of(useful)) |> 
  #mass is in scientific notation across two fields
  mutate(mass = map_dbl(mass, \(x) x$massValue * 10^x$massExponent)) |>
  #undo the list-cols created by enframe() |> pivot_wider()
  mutate(across(everything(), unlist))

#same as above, but for moons
moons <- moons$bodies |> 
  map(\(x) x |> 
        discard(is_null) |> 
        enframe() |> 
        pivot_wider()) |> 
  bind_rows() |> 
  select(id, englishName, semimajorAxis, mass, sideralOrbit, aroundPlanet) |> 
  #some moons have missing mass
  drop_na() |> 
  mutate(mass = map_dbl(mass, \(x) x$massValue * 10^x$massExponent),
         #just need the id of the planet
         aroundPlanet = map(aroundPlanet, 1)) |> 
  mutate(across(everything(), unlist)) |> 
  #there are some bogus entries
  filter(sideralOrbit > 0)

#join planets to moons
data <- moons |> 
  inner_join(planets |> select(id, mass),
             by = join_by(aroundPlanet == id),
             suffix = c("_s", "_p")) |> 
  mutate(
    #only the sum of masses is identified in the equation
    M = mass_s + mass_p,
    #convert semi-major axis to meters
    a = semimajorAxis * 1000,
    #convert sideral orbit to seconds
    #assuming these are conventional days, not sideral seems to be the right call
    T = sideralOrbit * 24 * 3600,
    #remind the value of pi to the model
    pi = pi)

head(data)

Fit the model

Since the data is literally on astronomical scales, I thought it wise to fit the model on a log10-transformed version of the equation. While this might take some of the nonlinear charm away, since a big product is transformed in a more familiar sum, we will see that the nonlinear formula will still let us specify the model in a way that would just break with a traditional model formula.

The parameter to fit is G, but we still need some meaningful outcome on the LHS. I decided to solve for

Then, taking the log10 of both sides

This translates directly into the nonlinear formula. Unlike the usual model formulas, regression coefficients (what you multiply the sum terms with) are explicit, so any parameter must be specified with a unique name in the formula. This lets us say explicitly that the last two terms must be multiplied by 3 and 2, not with parameters estimated from the data. The parameter to estimate, logG, has its own intercept-only model.

formula <- bf(log10(M) ~ -logG + log10(4*pi^2) + 3*log10(a) - 2*log10(T),
              logG ~ 1,
              nl = T)

Since I’m not an astronomer, I’ll pretend I have no domain knowledge outside “planets are big, and moons as well” and use default priors just this once. The model fits fine in case you’re worried.

get_prior(formula, data)

Time to actually fit the model.

fit <- brm(formula, data, seed = 950, silent = 2)

fit

 Family: gaussian 
  Links: mu = identity 
Formula: log10(M) ~ -logG + log10(4 * pi^2) + 3 * log10(a) - 2 * log10(T) 
         logG ~ 1
   Data: data (Number of observations: 161) 
  Draws: 4 chains, each with iter = 2000; warmup = 1000; thin = 1;
         total post-warmup draws = 4000

Regression Coefficients:
               Estimate Est.Error l-95% CI u-95% CI Rhat Bulk_ESS Tail_ESS
logG_Intercept   -10.18      0.00   -10.18   -10.17 1.00     4166     2866

Further Distributional Parameters:
      Estimate Est.Error l-95% CI u-95% CI Rhat Bulk_ESS Tail_ESS
sigma     0.03      0.00     0.02     0.03 1.00     1447     1820

Draws were sampled using sample(hmc). For each parameter, Bulk_ESS
and Tail_ESS are effective sample size measures, and Rhat is the potential
scale reduction factor on split chains (at convergence, Rhat = 1).

pp_check(fit)

How well did that go? Not so bad, considering all potential sources of error: almost as good as what had been derived from experiments 200 years ago, albeit with larger uncertainty.

g_draws <- fit |> 
  as_draws_df(variable = "b_logG_Intercept") |> 
  mutate(G = 10^b_logG_Intercept)

g_draws |> 
  mean_qi(G) |>
  mutate(rel_uncertainty = (.upper - .lower) / G *100) |> 
  print()

# A tibble: 1 × 7
            G      .lower      .upper .width .point .interval rel_uncertainty
        <dbl>       <dbl>       <dbl>  <dbl> <chr>  <chr>               <dbl>
1 6.66682e-11 6.60650e-11 6.72526e-11   0.95 mean   qi                1.78133

The beauty of Bayesian models is in the posterior distributions, we can look at those:

g_draws |> 
  ggplot(aes(x = G)) +
  stat_slab(aes(fill_ramp = after_stat(level)),
                    .width = c(.50, .80, .95, 1),
                    fill = "mediumpurple",
            show.legend = F) +
  geom_vline(xintercept = 6.6743e-11, linetype = 2) +
  annotate("text", x = 6.7e-11, y = 1, label = "What the NIST says") +
  scale_y_continuous(name = NULL, breaks = NULL) +
  labs(caption = "Interval widths: 50%, 80%, 95%, 100%")

Generate predictions

While this is a fine demonstration of nonlinear brms models, at the beginning I mentioned facing the model with reality. To do this we can take the estimated value of G (with all its posterior distribution) and generate predictions on a separate dataset. In this case, I’ll predict the orbital period of planets around the sun using G, masses, and semi-major axes.

planets <- planets |> 
  arrange(sideralOrbit) |> 
  mutate(
    englishName = fct(englishName),
    #the mass of the sun in kg
    mass_sun = 1.988475e30,
    M = mass + mass_sun,
    #convert semi-major axis to meters
    a = semimajorAxis * 1000,
    #convert sideral orbit to seconds
    T = sideralOrbit * 24 * 3600,
    #remind the value of pi to the model
    pi = pi)

planets_pred <- planets |> 
  expand_grid(G = g_draws$G) |> 
  mutate(Tpred = sqrt((4*pi^2*a^3)/(G*M)))

planets_pred |> 
  group_by(englishName) |> 
  mean_qi(Tpred) |> 
  select(!.width:.interval) |> 
  left_join(planets |> select(englishName, T)) |> 
  mutate(perc_err = (T - Tpred) / T * 100,
         across(Tpred:T, \(x) x |> 
                  as.difftime(units = "secs") |> 
                  `units<-`("days") |> 
                  round(3)),
         abs_err = T - Tpred)

planets_pred |> 
  ggplot() +
  stat_pointinterval(aes(y = Tpred)) +
  geom_hline(aes(yintercept = T),
             linetype = 2,
             data = planets |> mutate(T = as.difftime(T, units = "secs"))) +
  facet_wrap(vars(englishName),
             scales = "free") +
  scale_y_time(labels = \(x) str_c(round(x / 3600, 1), " d")) +
  scale_x_discrete() +
  labs(x = NULL,
       y = "Orbital period",
       title = "Predicting orbital periods",
       caption = "Median, 66% and 95% quantile intervals. Dashed line represents official value") +
  theme(plot.title = element_text(hjust = 0.5))

Not too bad! Even with our humble estimation, we can still decently predict the orbit of planets.