This fork aims to consolidate all the forks of the bfast
package to have a unified, updated package that can be submitted back to CRAN eventually and become the new upstream. The features integrated into this fork so far are:
- Documentation ported to
roxygen2
to make for easier development of functions and package building (GreatEmerald/bfast) - Optimised performance by porting critical paths to C++ (appelmar/bfast)
- Making use of the
stlplus
package for handling time series with NA values, and optional use of robust regression (Martin-Jung/bfast)
Parts of the improvements rely on modifications of the strucchange package (see here). You can install both packages with:
library(devtools)
install_github("bfast2/strucchange")
install_github("bfast2/bfast")
By default, the package will not make use of any modifications. Two functions change the behaviour:
set_fast_options() # use modifications
set_default_options() # use default implementation
The example below runs the first example of the bfastmonitor()
documentation for both settings.
library(bfast)
NDVIa <- as.ts(zoo(som$NDVI.a, som$Time))
f <- function() bfastmonitor(NDVIa, start = c(2010, 13))
set_default_options()
x = f()
system.time(replicate(100, f()))
set_fast_options()
y = f()
system.time(replicate(100, f()))
par(mfrow = c(1,2))
plot(x) ; plot(y)
The package comes with R Markdown reports to evaluate the performance modifications thoroughly. The following reports can be found in inst/reports
:
report.test.Rmd
runs test cases to make sure that modifications will return equal results,report.benchmark.Rmd
evaluates the speedup of a set of functions, andreport.profiling.Rmd
profiles some test functions to identify computational bottlenecks.
To generate html
reports, run:
library(rmarkdown)
outdir = getwd()
rmarkdown::render(system.file("reports/report.test.Rmd",package = "bfast"),output_file = paste(outdir,"/report.test.html",sep=""))
rmarkdown::render(system.file("reports/report.benchmark.Rmd",package = "bfast"),output_file = paste(outdir,"/report.benchmark.html",sep=""))
rmarkdown::render(system.file("reports/report.profiling.Rmd",package = "bfast"),output_file = paste(outdir,"/report.profiling.html",sep=""))
Notice that generating the last two reports might take some time.
Most important performance modifications include:
- using RcppArmadillo for computationally intensive operations in strucchange
- avoiding expensive calls of
model.frame()
andmodel.matrix
and using the design matrix and response vector instead of a data.frame and a formula - using
lm.fit()
instead oflm()
when possible
We always welcome contributions to the package. If you would like to propose a new functionality and/or report an issue, please use GitHub's tracker called Issues.
For development we use the GitHub Flow branching model.
Key steps:
- Create a GitHub issue in this repository with description of the work that you plan to do.
- Assign yourself to the GitHub issue you are working on, to inform other developers that you are working on it.
- Create your own working fork or branch based on the
dev
branch. - Make your changes in that branch.
- Commit your changes to your working branch as long as you are not finished with your development.
- Make sure that all tests pass (e.g., in Travis or Circle CI).
- Once your work is finished, create a pull request so that another developer can review your changes before merging them with the
dev
(ormain
) branch.
Additional steps for preparing a new release:
- Update the
NEWS.Rd
file with most notable changes. - Add new contributors to the
DESCRIPTION
file if applicable. - Release the package and make it citable (add
CITATION.cff
including DOI).