#' sfc: A package for substance flow computation.
#'
#' The sfc package provides an important functions sfc() to compute
#' the substance flow with the input files --- "data" and "model".
#' If sample.size is set more than 1, uncertainty analysis will be
#' executed while the distributions and parameters are supplied in
#' the file "data".
#'
#' @docType package
#' @import dplyr
#' @import tidyr
#' @importFrom stats median quantile sd
#' @importFrom utils read.csv
#' @importFrom triangle rtriangle
#' @name sfc-package
NULL
#' Substance Flow Computation
#'
#' \code{sfc} is the function for computing the substance flow with
#' the input file "data" and "model", and furtherly analyzing the
#' uncertainty of the computing results which are propagated from
#' the activity data and parameters.
#'
#' @param data a path for a ".csv" file or a data frame which contains
#' the basic data for substance flow computation. The details of
#' \code{data} are given under "Details".
#' @param model a path for a text file or a string vector which contains
#' the formulas for substance flow computation. The details of \code{model}
#' specification are given under "Details".
#' @param sample.size a single value, interpreted as an integer. The
#' details of \code{sample.size} are given under "Details".
#' @param rand.seed a single value, interpreted as an integer or NULL,
#' which is the same with \code{seed} in \code{\link{set.seed}}.
#' @param check logical. If FALSE, the summary of uncertainty analysis
#' will use all the samples. IF TRUE, they only use the valid samples.
#' The details of \code{check} are given under "Details".
#' @param inner logical. IF TRUE, the intermediate results will be returnd,
#' such as the input samples and the results for each sample.
#' @param ... Further arguments to be passed to both \code{\link{read.csv}}
#' and \code{\link{scan}}.
#'
#' @details There are two important inputs in \code{sfc} function: \code{data}
#' and \code{model}. "data" is a table in the form of ".csv" which includes
#' a line of the header and the other lines of the specific data. The header
#' can be divided into two categories: special fields and general fields.
#' Special fields represent the fields which are meaningful for computation,
#' while general fields only describe each row in details which will not be
#' used in computation, such as the description of the concept or unit of a
#' variable. So general fields are not as necessary as special fields. Special
#' fields can also be divided into two parts: fixed fields and flexible fields.
#' Fixed fields contains: NAME, DATA, TIME, SITE and DIST. Flexible fields
#' contains: P1, P2, P3, ... and C1, C2, C3, ... NAME means the variable name.
#' DATA means the variable value. TIME means the specific time while SITE means
#' the specific place where the variable observed. DIST is a character of
#' distribution in \code{\link{Distributions}}, such as "norm", "unif", etc.
#' P1, P2, P3, ... are the distribution parameters which are flexible because
#' different distribution has different number or meaning of parameters.
#' C1, C2, C3, ... are supplementary fields for other distinguished information
#' like TIME and SITE. All the letters of field names are in the capital form
#' to distinguish with the normal R variables or functions.
#'
#' "model" is a special R code fragment which only contains flow computation
#' expressions, like "PF[i, j, ] = DX * PX" or "PF[i, j, ] <- DX * PX". Here,
#' "i" is the start node and "j" is the end node. "DX" and "PX" represent
#' activity data and parameters, respectively. They also correspond to the
#' "NAME" field in the "data" file. "PF[i, j, ]" is an array which means the
#' flow from "i" to "j", while "PF" is the default flow name. If you do not
#' like coding, this package provides another alternative: to write model as
#' into a ".csv" file. This file contains four critical fields: NAME, START,
#' END and FUN. They are required fields while you can add other optional fields
#' to make the model more readable freely. The NAME field is used to define
#' flow label, e.g. "PF_01" labels "PF[i, j, ]". The START and END field are
#' used to define the start node "i" and the end node "j" in "PF[i, j, ]".
#' The last one, "FUN" is used to define the formula to calculate the flow,
#' such as the righthand expression "DX * PX". To keep the code easy and simple,
#' some auxiliary functions are supplied: \code{p}, \code{comp0}, \code{suma}
#' and \code{rnone}. \code{p} is used to keep flow positive while the negative
#' value will be set zero. \code{comp0} is used to change the value near zero
#' to be zero. \code{suma} is used to sum an array at the margin \code{m}.
#' \code{rnone} is used to sample the same value.
#'
#' If \code{sample.size} are greater than 1, the uncertainty of substance flow
#' computation result, i.e. "PF[i, j, ]", will be evaluated. However, we
#' will still compute the scenario when \code{sample.size} = 1, which
#' represent the expected scenario (or most valid scenario), to compare with
#' each result of each sample. If the sign of each flow are the same, the
#' sample are valid, otherwise are invalid. So the \code{sample.size} in
#' the result list is the valid sample size. To trigger the above comparation,
#' \code{check} should be set TRUE.
#'
#' @return \code{sfc} returns a list which contains four objects: \code{result},
#' \code{sample.size}, \code{sample} and \code{inner.result}. \code{result}
#' is a data frame of substance flow computation result. \code{sample.size}
#' is the sample size of valid samples. \code{sample} is the data frame of
#' the input samples. \code{inner.result} is the data frame of substance flow
#' computation result for each sample.
#'
#' @examples
#' library(sfc)
#'
#' ## model as txt
#' data <- system.file("extdata", "data_utf8.csv", package = "sfc")
#' model <- system.file("extdata", "model_utf8.txt", package = "sfc")
#' sfc(data, model, sample.size = 100, fileEncoding = "UTF-8")
#'
#' ## model as csv
#' data <- system.file("extdata", "data_utf8.csv", package = "sfc")
#' model <- system.file("extdata", "model_utf8.csv", package = "sfc")
#' sfc(data, model, fileEncoding = "UTF-8")
#' @export
sfc <- function(data,
model,
sample.size = 1,
rand.seed = NULL,
check = TRUE,
inner = FALSE,
...) {
if (is.character(data)) {
data <- read.csv(data, stringsAsFactors = FALSE, ...)
}
if (is.character(model)) {
if (any(grepl("*.csv$", model))) {
model <- read.csv(model, stringsAsFactors = FALSE, ...)
} else if (!any(grepl("(=|<-)", model))) {
model <- scan(model,
character(),
comment.char = "#",
skipNul = TRUE,
...)
}
}
if (is.data.frame(model)) {
model <- model_csv2txt(model)
}
data <- impute_data(data)
model <- model[order(flow_order(model))]
if (sample.size > 1) {
r <- mcs_flow(data, model, sample.size, rand.seed, check)
if (inner) {
list(
result = r$result,
sample.size = r$sample.size,
data.sample = r$data.sample,
inner.result = r$inner.result
)
} else {
list(result = r$result,
sample.size = r$sample.size)
}
} else {
list(result = run_flow(data, model),
sample.size = sample.size)
}
}
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.