as of 11/2023
An R package to evaluate hypotheses of diel phenotypes based on empirical data and estimate the probabilitiy of activity during the twilight, daytime, and nighttime periods.
The main idea of evaluating diel phenotypes as hypotheses is that they can be expressed as inequality
statements among the probabilities of activity during twilight, daytime, and nighttime. The core modeling and estimation functions of this packages are wrapper
functions to gibbs MCMC algorithms provided by the R package
The last update to the Diel.Niche package was on
2025/06/17. This update now allows you to calculate the proportion
of time each diel period takes up during a day within the
bin.diel.times() function. See update prior to this for
details on bin.diel.times().
News and updates regarding this package can be found here.
Please see here for Common Issues or download the Rmd.
The main package vignettes can be found on Github here: Main Vignette and Additional Vignette
Case study example vignette's can be found on Github here:
-
Example 6: Diel Activity from State-Dependent Animal Movement
-
Example 7: Implementing Gomez et al. 2005 diel phenotypes in Diel.Niche
The package manual can be found on Github here: Manual PDF
To cite this package, please use
citation("Diel.Niche")Gerber BD, Devarajan K, Farris ZJ, Fidino M (2024). A model-based hypothesis framework to define and estimate the diel niche via the Diel.Niche’ R package. Journal of Animal ecology. doi:10.1111/1365-2656.14035 https://doi.org/10.1111/1365-2656.14035.
First, install Diel.Niche using the devtools package:
# Install package from GitHub via the devtools package.
devtools::install_github("diel-project/Diel-Niche-Modeling",
ref="main", dependencies = TRUE,
build_vignettes = TRUE
)For a faster build, change to dependencies = FALSE, but the below vignettes will not be part of the package (still accessible on Github).
Check out the availble vignettes:
# Load the pacakge
library(Diel.Niche)
# You can view the main or secondary additional vignette as
vignette("Diel-Niche-Vignette")
vignette("Diel-Niche-Additional")
# Or other vignettes
vignette("Example1")
vignette("Example2")
vignette("Example3")
vignette("Example4")
vignette("Example5")
vignette("Example6")
# To list all the available vignettes for the package
browseVignettes("Diel.Niche")
# Listing the packages functions and help files
help(package="Diel.Niche")There are four fundamental hypothesis sets: Maximizing, Traditional, General, and Selection. Additional hypotheses available are described in the ‘Diel-Niche-Vignette.Rmd’
This hypothesis set includes three hypotheses (Crepuscular Max, Diurnal Max, and Nocturnal Max) with the objective to evaluate which time period is used most. As such, there is no hypothesis about activity across multiple time periods (i.e., cathemeral).
triplot(hyp=hyp.sets("Maximizing"))
This hypothesis set includes four hypotheses (Crepuscular, Diurnal,
Nocturnal, Traditional Cathemeral) that aim to capture the general
interpretation of these hypotheses from the literature. Crepuscular,
Diurnal, and Nocturnal are defined based on having at least 0.80
probability (threshold probability,
triplot(hyp=hyp.sets("Traditional"))
This hypothesis set includes seven hypotheses. The Diurnal, Crepuscular,
and Nocturnal hypotheses are defined the same as in Traditional. The
main difference is the separation of the probability space of
Traditional Cathemeral into four more specific hypotheses: General
Cathemeral, Crepuscular-Nocturnal, Diurnal-Nocturnal, and
Diurnal-Crepuscular. The General Cathemeral hypothesis—which represents
a subset of the parameter space taken by the previously mentioned
Traditional Cathemeral—aims to define when an animal uses all three diel
periods (twilight, daytime, nighttime) at equal to or more than a
minimum amount (i.e.,
triplot(hyp=hyp.sets("General"))
The Selection hypothesis set includes seven diel phenotype hypotheses (Day, Day-Night, Day-Twilight, Equal, Night, Night-Twilight, and Twilight Selection) that are defined based on the inputted (i.e., not estimated) amount of proportional time available to an animal in each diel period (
triplot(hyp=hyp.sets("Selection"), diel.setup=diel.ineq(p.avail=c(0.04,0.48))
Data simulation, model fitting, and plotting are done based on a hypothesis or set of hypotheses. Users don’t need to remember hypothesis codes, but can call them as,
hyp.sets("Maximizing")## [1] "D.max" "N.max" "CR.max"
hyp.sets("Traditional")## [1] "D" "N" "CR" "C"
hyp.sets("General")## [1] "D" "N" "CR" "C2" "D.CR" "D.N" "CR.N"
hyp.sets("Selection")## [1] "D.avail" "CR.avail" "N.avail" "EQ.avail" "D.CR.avail" "N.CR.avail" "D.N.avail"
Pick a hypothesis to simulate data from and how many samples,
set.seed(45451)
hyp <- c("CR")
sim <- sim.diel(hyp=hyp,n.sample=100)
#The probability value used to simulate data
p <- sim$p
p## [,1] [,2] [,3]
## [1,] 0.935 0.025 0.04
#The simulated data
y <- sim$y
y## y_crep y_day y_night
## [1,] 96 1 3
Models are compared using Bayes factors, which are used to derive a posterior model probability
hyp.set <- hyp.sets("Traditional")
out <- diel.fit(y,hyp.set)## Data checks Complete.
## Calculating Bayes Factors...
## The most supported model is:
## Crepuscular (Traditional)
#Call the model probabilities for each hypothesis in the set
out$bf.table## Prior Posterior
## D 0.25 0
## N 0.25 0
## CR 0.25 1
## C 0.25 0
The function ‘diel.fit’ defaults to providing the model probabilities for each hypothesis set, but not the posterior samples of the parameters for each hypothesis. We can change this as well as include additional MCMC chains,
out <- diel.fit(y,hyp.set,n.chains = 2,post.fit = TRUE)## Data checks Complete.
## Calculating Bayes Factors...
## Posterior Sampling...
## The most supported model is:
## Crepuscular (Traditional)
We can look at a convergence criteria for the most supported model.
out$ms.gelm.diag## Potential scale reduction factors:
##
## Point est. Upper C.I.
## p1_1 1 1.01
## p1_2 1 1.01
We can plot the posterior samples from the most supported model to check convergence/mixing as,
plot(coda::as.mcmc(out$post.samp.ms.model))
The posterior samples for all hypotheses are available in a list.
names(out$post.samp)## [1] "D" "N" "CR" "C"
#For each of these list is a list of chains
length(out$post.samp[[1]])## [1] 2
#Here are the means of the posterior samples of all hypotheses for chain 1
lapply(out$post.samp,FUN=function(x){colMeans(x[[1]])})## $D
## p_crep_1 p_day_1 p_night_1
## 0.190235520 0.801957493 0.007806987
##
## $N
## p_crep_1 p_day_1 p_night_1
## 0.0000000 0.1254649 0.8745351
##
## $CR
## p_crep_1 p_day_1 p_night_1
## 0.94286797 0.01899454 0.03813750
##
## $C
## p_crep_1 p_day_1 p_night_1
## 0.78993613 0.06946899 0.14059487
Using the packages bayesplot and ggplot2, we can examine our posterior distributions along with the true probabilities values,
library(ggplot2)
library(bayesplot)posteriors <- coda::as.mcmc(out$post.samp.ms.model)
plot_title <- ggtitle("Posterior distributions",
"with medians and 80% intervals")
mcmc_areas(posteriors, prob = 0.8) + plot_title+
geom_vline(xintercept=p[1], linetype="dashed",color = c("red"), linewidth=1)+
geom_vline(xintercept=p[2], linetype="dashed",color = c("purple"), linewidth=1)+
geom_vline(xintercept=p[3], linetype="dashed",color = c("green"), linewidth=1)
We can also plot the posteriors in 3D using ploty.
triplot(out)
Plotting is done using the package plotly. Plotly can have issues with RStudio. If you are using RStudio and no figures are opening then: Tools–>Global Options–>Advanced–>Rendering Engine Choose Desktop OpenGL{} and then restart RStudio.
- The many data contributors that supported the evaluation of this framework.
If you are interested in contributing, see Contributor Guidelines