Extensive linting and doc fixing, close #145

NEWS.md

@@ -2,7 +2,9 @@
 
 Changes in this release:
 
-* Added `as.fhx()`. This takes data frames, tibbles, and lists as input. It assumes they have "year", "series", and "rec_type" elements/columns and returns an fhx object. (Issue #120).
+* Added `as.fhx()`. This takes data frames, tibbles, and lists as input. It assumes they have "year", "series", and "rec_type" elements/columns. It returns an `fhx` object. This makes life easier for people who work with the tidyverse. It helps make life easier for users who want to work with thier own non-FHX fire-history file formats. (Issue #120)
+
+* Extensive improvement to documentation (e.g. Issue #145). This includes new "See Also" sections so users can find cool functions, fixes for spelling errors, and clarifications to dyslexic prose.
 
 * Removed deprecated `run_sea()`. Be sure to use `sea()` now.
 
@@ -14,7 +16,7 @@ Changes in this release:
 
 * Added unit tests for basic plotting function options.
 
-* Minor internal code cleanup (Issue #130, Issue #88, Issue #133, Issue #136, Issue #88).
+* Minor internal code cleanup (Issue #130, Issue #88, Issue #133, Issue #136, Issue #88) and code linting.
 
 
 # burnr v0.4.0

R/data.R

@@ -1,71 +1,86 @@
 #' Los Griegos Peak plot2 fire-history data
 #'
-#' An fhx object with fire-history data from Los Griegos Peak, New Mexico.
+#' An `fhx` object with fire-history data from Los Griegos Peak, New Mexico.
 #'
-#' @format An fhx object with 26 series from 1366 to 2012 CE. Each series is a
-#'   string with 5 characters.
+#' @format An fhx object with 26 series from 1366 to 2012 CE.
+#'
+#' @seealso [lgr2_meta] Los Griegos Peak metadata.
 "lgr2"
 
 
 #' Metadata for the Los Griegos Peak fire-history dataset
 #'
 #' @description
-#' A dataset with species information for the Los Griegos Peak plot2
-#' fire-history dataset (`lgr2`).
-#'
-#' @format A data frame with 26 rows and 2 variables:
-#' \itemize{
-#'   \item TreeID: name of tree series
-#'   \item SpeciesID: abbreviated tree species
-#' }
+#' A data frame with species information for the Los Griegos Peak plot2
+#' fire-history dataset ([lgr2]).
+#'
+#' @format A `data.frame` with 26 rows and 2 variables:
+#'   * "TreeID": Name of tree series.
+#'   * "SpeciesID": Abbreviated tree species
+#'
+#' @seealso [lgr2] Log Griegos Peak fire-history data.
 "lgr2_meta"
 
 
 #' Peggy Mesa fire-history data
 #'
 #' @description
-#' An fhx object with fire-history data from Peggy Mesa. See dataset `pgm_meta`
-#' for metadata. Data from Guiterman, Christopher H., Ellis Q. Margolis, and
+#' An `fhx` object with fire-history data from Peggy Mesa.
+#'
+#' @format An `fhx` object with 41 series from 1555 to 2013 CE.
+#'
+#' @source Guiterman, Christopher H., Ellis Q. Margolis, and
 #' Thomas W. Swetnam. 2015. "Dendroecological Methods For Reconstructing
 #' High-Severity Fire In Pine-Oak Forests." Tree-Ring Research 71 (2): 67-77.
 #' doi:10.3959/1536-1098-71.2.67.
 #'
-#' @format An fhx object with 41 series from 1555 to 2013 CE. Each series is a
-#'   string with 5 characters.
+#' @seealso
+#'   * [pgm_meta] Peggy Mesa metadata.
+#'   * [pgm_pdsi] PDSI time-series for Peggy Mesa site.
 "pgm"
 
 
 #' Metadata for the Peggy Mesa fire-history dataset
 #'
 #' @description
-#' A dataset with species and location information for the Peggy Mesa
-#' fire-history dataset (`pgm`). Data from Guiterman, Christopher H., Ellis Q.
-#' Margolis, and Thomas W. Swetnam. 2015. "Dendroecological Methods For
-#' Reconstructing High-Severity Fire In Pine-Oak Forests." Tree-Ring Research
-#' 71 (2): 67-77. doi:10.3959/1536-1098-71.2.67.
-#'
-#' @format A data frame with 41 rows and 5 variables:
-#' \itemize{
-#'   \item TreeID: name of tree series
-#'   \item SpeciesID: abbreviated tree species
-#'   \item Latitude: latitude of tree in decimal degrees
-#'   \item Longitude: longitude of tree in decimal degrees
-#'   \item Elevation: tree elevation in meters
-#' }
+#' A data frame with species and location information for the Peggy Mesa
+#' fire-history dataset ([pgm]).
+#'
+#' @format A `data.frame` with 41 rows and 5 variables:
+#'   * "TreeID": Name of tree series.
+#'   * "SpeciesID": Abbreviated tree species.
+#'   * "Latitude": latitude of tree in decimal degrees.
+#'   * "Longitude": longitude of tree in decimal degrees.
+#'   * "Elevation": tree elevation in meters.
+#'
+#' @source Guiterman, Christopher H., Ellis Q. Margolis, and
+#' Thomas W. Swetnam. 2015. "Dendroecological Methods For Reconstructing
+#' High-Severity Fire In Pine-Oak Forests." Tree-Ring Research 71 (2): 67-77.
+#' doi:10.3959/1536-1098-71.2.67.
+#'
+#' @seealso
+#'   * [pgm] Peggy Mesa fire-history data.
+#'   * [pgm_pdsi] PDSI time-series for Peggy Mesa site.
 "pgm_meta"
 
 
 #' Reconstructed PDSI time series for the Peggy Mesa fire-history dataset
 #'
 #' @description
 #' A tree-ring reconstructed Palmer Drought-Severity Index time series
-#' corresponding to the Peggy Mesa fire-history dataset (`pgm`) -- specifically,
-#' the Jemez Mountains area (gridpoint 133). The reconstruction is from The 
+#' corresponding to the Peggy Mesa fire-history dataset ([pgm]) -- specifically,
+#' the Jemez Mountains area (gridpoint 133). The reconstruction is from The
 #' North American Drought Atlas (Cook and Krusic 2004).
 #'
-#' @format A data frame with 2004 rows and 1 variables. Row names give the year
-#' for the reconstructed value:
-#' \itemize{
-#'   \item RECON: The reconstructed PDSI series.
-#' }
+#' @format A `data.frame` with 2004 rows and 1 variables. Row names give the
+#' year for the reconstructed value:
+#'   * "RECON": The reconstructed PDSI series.
+#'
+#' @source Cook, E. R., and Krusic, P. J. (2004). The North American Drought
+#' Atlas. Retrieved September 13, 2017, from
+#' http://iridl.ldeo.columbia.edu/SOURCES/.LDEO/.TRL/.NADA2004/.pdsi-atlas.html
+#'
+#' @seealso
+#'   * [pgm] Peggy Mesa fire-history data.
+#'   * [pgm_meta] Peggy Mesa metadata.
 "pgm_pdsi"

R/intervals.R

@@ -1,10 +1,32 @@
-#' Constructor for S3 intervals class.
+#' Calculate fire intervals from a `composite`
 #'
-#' @param comp A composite fhx instance. Should have only one series in it.
-#' @param densfun String giving desired distribution to fit. Suggest "weibull"
+#' @param comp A `composite` instance, usually output from [composite()].
+#'    Should contain only one series.
+#' @param densfun String giving desired distribution to fit. Either "weibull"
 #'   or "lognormal". Default is "weibull".
 #'
-#' @return An intervals instance.
+#' @return An `intervals` object. `intervals` have components:
+#'   * "intervals" an integer vector giving the actual fire intervals.
+#'   * "fitdistr" a `fitdistr` object from [MASS::fitdistr()] representing the
+#'     density function fit.
+#'   * "densfun" a string giving the name of the density function used.
+#'   * "kstest" an `htest` object from [stats::ks.test()] giving the result of a
+#'     one-sample Kolmogorov-Smirnov test.
+#'   * "shapirotest" an `htest` object from [stats::shapiro.test()] giving the
+#'     result of a Shapiro-Wilk normality test.
+#'   * "comp_name" a string giving the name of the interval's input composite.
+#'   * "event_range" an integer vector giving the year range (min, max) of
+#'     events used to create this intervals.
+#'
+#' @seealso
+#'   * [composite()] to create a `composite` object.
+#'   * [mean.intervals()] gets mean fire interval.
+#'   * [median.intervals()] gets median fire interval.
+#'   * [quantile.intervals()] get fit distribution quantiles.
+#'   * [plot_intervals_dist()] plots `intervals`.
+#'   * [min.intervals()] gives the minimum fire interval.
+#'   * [max.intervals()] gives the maximum fire interval.
+#'   * [print.intervals()] prints common fire-interval summary statistics.
 #'
 #' @examples
 #' data(pgm)
@@ -48,70 +70,118 @@ intervals <- function(comp, densfun = "weibull") {
   x
 }
 
-#' Check if object is intervals.
+
+#' Check if object is fire `intervals`
 #'
 #' @param x An R object.
 #'
-#' @return Boolean indicating whether `x` is an intervals object.
+#' @return Boolean indicating whether x is an `intervals` object.
 #'
+#' @seealso [intervals()] creates an `intervals` object.
 #' @export
 is.intervals <- function(x) inherits(x, "intervals")
 
-#' Interval arithmetic mean.
+
+#' Fire `intervals` arithmetic mean
 #'
-#' @param x An intervals object.
-#' @param ... Additional arguments passed to \code{mean}.
+#' @param x An `intervals` object.
+#' @param ... Additional arguments passed to [mean()].
 #'
 #' @return Numeric or NA.
 #'
+#' @seealso
+#'   * [intervals()] to create a fire `intervals` object.
+#'   * [median.intervals()] gets median fire interval.
+#'   * [quantile.intervals()] get fit distribution quantiles.
+#'   * [min.intervals()] gives the minimum fire interval.
+#'   * [max.intervals()] gives the maximum fire interval.
+#'   * [print.intervals()] prints common fire-interval summary statistics.
+#'
 #' @export
 mean.intervals <- function(x, ...) {
   mean(x$intervals, ...)
 }
 
-#' Interval median.
+
+#' Fire `intervals` median
 #'
-#' @param x An intervals object.
-#' @param ... Additional arguments passed to \code{stats::median}.
+#' @param x An `intervals` object.
+#' @param ... Additional arguments passed to [stats::median()].
 #'
 #' @return Numeric or NA.
 #'
+#' @seealso
+#'   * [intervals()] to create a fire `intervals` object.
+#'   * [mean.intervals()] gets mean fire interval.
+#'   * [quantile.intervals()] get fit distribution quantiles.
+#'   * [min.intervals()] gives the minimum fire interval.
+#'   * [max.intervals()] gives the maximum fire interval.
+#'   * [print.intervals()] prints common fire-interval summary statistics.
+#'
 #' @importFrom stats median
 #' @export
 median.intervals <- function(x, ...) {
   median(x$intervals, ...)
 }
 
-#' Minimum interval.
+
+#' Minimum interval in fire `intervals`
 #'
-#' @param x An intervals object.
-#' @param ... Additional arguments passed to \code{min}.
+#' @param x An `intervals` object.
+#' @param ... Additional arguments passed to [min()].
 #'
 #' @return Numeric or NA.
 #'
+#' @seealso
+#'   * [intervals()] to create a fire `intervals` object.
+#'   * [mean.intervals()] gets median fire interval.
+#'   * [median.intervals()] gets median fire interval.
+#'   * [quantile.intervals()] get fit distribution quantiles.
+#'   * [max.intervals()] gives the maximum fire interval.
+#'   * [print.intervals()] prints common fire-interval summary statistics.
+#'
 #' @export
 min.intervals <- function(x, ...) {
   min(x$intervals)
 }
 
-#' Maximum interval.
+
+#' Maximum interval in fire `intervals`
 #'
-#' @param x An intervals object.
-#' @param ... Additional arguments passed to \code{max}.
+#' @param x An `intervals` object.
+#' @param ... Additional arguments passed to [max()].
 #'
 #' @return Numeric or NA.
 #'
+#' @seealso
+#'   * [intervals()] to create a fire `intervals` object.
+#'   * [mean.intervals()] gets median fire interval.
+#'   * [median.intervals()] gets median fire interval.
+#'   * [quantile.intervals()] get fit distribution quantiles.
+#'   * [min.intervals()] gives the minimum fire interval.
+#'   * [print.intervals()] prints common fire-interval summary statistics.
+#'
 #' @export
 max.intervals <- function(x, ...) {
   max(x$intervals)
 }
 
-#' Fit distribution quantiles.
+
+#' Fit distribution quantiles to fire `intervals`
 #'
-#' @param x An intervals object.
+#' @param x An `intervals` object.
 #' @param q Vector giving the desired quantiles.
-#' @param ... Additional arguments passed to the quantile function of the fit
-#'   distribution.
+#' @param ... Additional arguments passed to the [quantile()] method for the
+#'   fit distribution.
+#'
+#' @seealso
+#'   * [intervals()] to create a fire `intervals` object.
+#'   * [mean.intervals()] gets median fire interval.
+#'   * [median.intervals()] gets median fire interval.
+#'   * [quantile.intervals()] get fit distribution quantiles.
+#'   * [min.intervals()] gives the minimum fire interval.
+#'   * [max.intervals()] gives the maximum fire interval.
+#'   * [print.intervals()] prints common fire-interval summary statistics.
 #'
 #' @examples
 #' data(pgm)
@@ -134,10 +204,11 @@ quantile.intervals <- function(x, q = c(0.125, 0.5, 0.875), ...) {
 }
 
 
-
-#' Plot an intervals object.
+#' Plot a fire `intervals` object
 #'
-#' @param ... Arguments passed on to \code{plot_intervals_dist}.
+#' @param ... Arguments passed to [plot_intervals_dist()].
+#'
+#' @seealso [plot_intervals_dist()] plot `intervals` distributions.
 #'
 #' @examples
 #' data(pgm)
@@ -150,14 +221,22 @@ plot.intervals <- function(...) {
 }
 
 
-#' Basic intervals distribution plot.
-#'
-#' @param x An intervals object.
-#' @param binwidth A sea object.
+#' Basic fire `intervals` distribution plot
 #'
+#' @param x An `intervals` object, from [intervals()].
+#' @inheritParams ggplot2::geom_histogram
 #'
 #' @return A ggplot object.
 #'
+#' @seealso
+#'   * [intervals()] to create a fire `intervals` object.
+#'   * [mean.intervals()] gets mean fire interval.
+#'   * [median.intervals()] gets median fire interval.
+#'   * [quantile.intervals()] get fit distribution quantiles.
+#'   * [min.intervals()] gives the minimum fire interval.
+#'   * [max.intervals()] gives the maximum fire interval.
+#'   * [print.intervals()] prints common fire-interval summary statistics.
+#'
 #' @export
 plot_intervals_dist <- function(x, binwidth = NULL) {
   p <- ggplot2::ggplot(
@@ -174,11 +253,21 @@ plot_intervals_dist <- function(x, binwidth = NULL) {
 }
 
 
-#' Print an intervals objects.
+#' Print a fire `intervals` object
 #'
-#' @param x An intervals object.
+#' @param x An `intervals` object.
 #' @param ...  Additional arguments that are tossed.
 #'
+#' @seealso [intervals()] to create a fire `intervals` object.
+#'
+#' @examples
+#' data(pgm)
+#' interv <- intervals(composite(pgm))
+#' print(interv)
+#'
+#' # Note, you can also catch the printed table:
+#' summary_stats <- print(interv)
+#'
 #' @export
 print.intervals <- function(x, ...) {
   wfit <- MASS::fitdistr(x$intervals, "weibull")