# Generated by using Rcpp::compileAttributes() -> do not edit by hand
# Generator token: 10BE3573-1514-4C36-9D1C-5A225CD40393

#' @title Compute mean value of a vector, with optional filtering for N datapoints
#' @description Compute measure of central tendency using efficient C++ code
#' @name vector_mean
#' @inheritParams vector_mode
#' @inheritParams pairscale_mode
#' @return a single numeric value representing the mean
#' @export
vector_mean <- function(x, min_value_count = 1L, na_mode = "check") {
    .Call(`_pairscale_vector_mean`, x, min_value_count, na_mode)
}

#' @title Compute median value of a vector, with optional filtering for N datapoints
#' @description Compute measure of central tendency using efficient C++ code
#' @name vector_median
#' @inheritParams vector_mode
#' @inheritParams pairscale_mode
#' @return a single numeric value representing the median
#' @export
vector_median <- function(x, min_value_count = 1L, na_mode = "check") {
    .Call(`_pairscale_vector_median`, x, min_value_count, na_mode)
}

#' @title Compute trimmed mean value of a vector, with optional filtering for N datapoints
#' @description Compute measure of central tendency using efficient C++ code
#' @name vector_trimmedmean
#' @inheritParams vector_mode
#' @inheritParams pairscale_mode
#' @inheritParams pairscale_trimmedmean
#' @return a single numeric value representing the trimmed mean
#' @export
vector_trimmedmean <- function(x, min_value_count = 1L, trim = 0.2, na_mode = "check") {
    .Call(`_pairscale_vector_trimmedmean`, x, min_value_count, trim, na_mode)
}

#' @title Compute MAD-trimmed mean value of a vector, with optional filtering for N datapoints
#' @description Compute measure of central tendency using efficient C++ code
#' @name vector_madmean
#' @inheritParams vector_mode
#' @inheritParams pairscale_mode
#' @inheritParams pairscale_madmean
#' @return a single numeric value representing the MAD-trimmed mean
#' @export
vector_madmean <- function(x, min_value_count = 1L, threshold_std = 3, na_mode = "check") {
    .Call(`_pairscale_vector_madmean`, x, min_value_count, threshold_std, na_mode)
}

#' @title Compute mode of a vector, with optional filtering for N datapoints
#' @description Compute measure of central tendency using efficient C++ code
#' @name vector_mode
#' @inheritParams pairscale_mode
#' @param x numeric input vector, may contain non-finite values (removed if `na_mode` is left to default)
#' @return a single numeric value representing the mode
#' @export
vector_mode <- function(x, min_value_count = 3L, n_bins = 512L, adjust = 1, kernel_width_in_sd = 3, bandwidth_method = "nrd", mode_frac_maxdens = 1, na_mode = "check") {
    .Call(`_pairscale_vector_mode`, x, min_value_count, n_bins, adjust, kernel_width_in_sd, bandwidth_method, mode_frac_maxdens, na_mode)
}

#' @title Distance matrix between columns of a matrix using their mean differences
#' @description Pairwise differences between all columns in a matrix
#' @name pairdiff_mean
#' @inheritParams pairscale_mode
#' @inheritParams pairdiff_mode
#' @return a N x N numeric matrix (where N is number of column in input `x`) representing the mean difference between each column
#' @export
pairdiff_mean <- function(x, cols = NULL, min_value_count = 3L, na_mode = "check") {
    .Call(`_pairscale_pairdiff_mean`, x, cols, min_value_count, na_mode)
}

#' @title Distance matrix between columns of a matrix using their trimmed median differences
#' @description Pairwise differences between all columns in a matrix
#' @name pairdiff_median
#' @inheritParams pairscale_mode
#' @inheritParams pairdiff_mode
#' @return a N x N numeric matrix (where N is number of column in input `x`) representing the median difference between each column
#' @export
pairdiff_median <- function(x, cols = NULL, min_value_count = 3L, na_mode = "check") {
    .Call(`_pairscale_pairdiff_median`, x, cols, min_value_count, na_mode)
}

#' @title Distance matrix between columns of a matrix using their trimmed mean differences
#' @description Pairwise differences between all columns in a matrix
#' @name pairdiff_trimmedmean
#' @inheritParams pairscale_mode
#' @inheritParams pairdiff_mode
#' @inheritParams pairscale_trimmedmean
#' @return a N x N numeric matrix (where N is number of column in input `x`) representing the trimmed mean difference between each column
#' @export
pairdiff_trimmedmean <- function(x, cols = NULL, min_value_count = 3L, trim = 0.2, na_mode = "check") {
    .Call(`_pairscale_pairdiff_trimmedmean`, x, cols, min_value_count, trim, na_mode)
}

#' @title Distance matrix between columns of a matrix using their MAD-trimmed mean differences
#' @description Pairwise differences between all columns in a matrix
#' @name pairdiff_madmean
#' @inheritParams pairscale_mode
#' @inheritParams pairdiff_mode
#' @inheritParams pairscale_madmean
#' @return a N x N numeric matrix (where N is number of column in input `x`) representing the MAD-trimmed mean difference between each column
#' @export
pairdiff_madmean <- function(x, cols = NULL, min_value_count = 3L, threshold_std = 3, na_mode = "check") {
    .Call(`_pairscale_pairdiff_madmean`, x, cols, min_value_count, threshold_std, na_mode)
}

#' @title Distance matrix between columns of a matrix using their mode differences
#' @description Pairwise differences between all columns in a matrix
#' @name pairdiff_mode
#' @inheritParams pairscale_mode
#' @param cols optionally, provide an integer vector with column indices (in `x`) that should be used (these should be 1-based indices as per usual in R). Or set to `NULL` or `integer()` to use all columns
#' @return a N x N numeric matrix (where N is number of column in input `x`) representing the mode difference between each column
#' @export
pairdiff_mode <- function(x, cols = NULL, min_value_count = 3L, n_bins = 512L, adjust = 1, kernel_width_in_sd = 3, bandwidth_method = "nrd", mode_frac_maxdens = 1, na_mode = "check") {
    .Call(`_pairscale_pairdiff_mode`, x, cols, min_value_count, n_bins, adjust, kernel_width_in_sd, bandwidth_method, mode_frac_maxdens, na_mode)
}

#' @title Normalize matrix columns using their mode differences
#' @description Pairwise normalization of columns in a matrix, using the mode to define pairwise distances between columns
#' @name pairscale_mode
#' @param x a numeric matrix that needs to be normalized. This variable is changed by reference! i.e. after this function, the original variable is updated
#' @param clusters an integer vector, of same length as `ncol(x)`, that describes cluster identifiers. These values must describe a continuous set of integers between 1 and the total number of unique clusters. For example, a 6 column matrix with 3 columns from some experimental condition followed by 3 columns from another condition would be `c(1,1,1, 2,2,2)`. To disable mode-between rescaling, i.e. treat the entire matrix as one cluster, provide a vector with ones.
#' @param min_value_count the minimum number of values overlapping between a pair of columns (if there are fewer overlapping values, respective rescaling is not computed)
#' @param n_bins grid size for density computation (the resolution / number of data points to use for binning column diffs)
#' @param adjust bandwidth adjust factor for density computation
#' @param kernel_width_in_sd maximum distance in standard deviations at which we'll include data points for the Gaussian kernal. Typically 3 or 4
#' @param na_mode string value that indicated how should we should deal with NA values (default). "check" = test if NA values are present and if so, remove these. "present" = you already know NA values are present so we can skip the check for NA values for efficiency. "unchecked" = you guarantee that there are no NA values in input, thus we'll use the fastest code paths that skip over any NA checks downstream; ONLY select this if you are sure there are no NA/NaN/Inf/-Inf values !
#' @param bandwidth_method method in which this function computes bandwidth and optionally trims the data prior to binning. "nrd" is the robust, safe default. "nrd_fast" is faster and yields similar results for most distributions. Use "nrd_fastest" only when all pairwise distances are known to be near gaussian (i.e. no strong outliers and sd() is a reliable metric). "nrd_subset" is an experimental option that may be removed, it is fast but heavily favors symmetric distributions and is thus biased !
#'
#'   Valid options:
#'   * `"nrd_fastest"` ; use all data points, for bandwidth don't use IQR. Sensitive to outliers !
#'   * `"nrd_fast"` ; trim to quantiles 0.05 and 0.95, then use sd over these data points to compute bandwidth. Not as robust as the original nrd method, which also considers IQR, but much faster.
#'   * `"nrd"` ; adapted version of nrd; instead of IQR and sd we use IQR and sd over data trimmed at quantiles 0.05 and 0.95. Since we already sorted the data, computing sd on trimmed subset is 'free'
#' @param mode_frac_maxdens set to 1 to return the x-coordinate where the density is highest (mode). Setting this to a value < 1 will make this function compute not the mode, but the mean (x) value of the density where the density is some fraction higher than the maximum density. Typical value; 1. Optionally, set to 0.9 or 0.8 for possibly more robust center-finding, depending in your data distribution. Must not be smaller than 0.1 but recommended to never be lower than 0.7
#' @param niter_irls number of iterations to increase robustness (set to zero to disable)
#' @return a numeric vector that represents the normalization factors that were applied to each column in x. Note that x is updated by reference.
#' @export
pairscale_mode <- function(x, clusters = NULL, min_value_count = 3L, n_bins = 512L, adjust = 1, kernel_width_in_sd = 3, bandwidth_method = "nrd", mode_frac_maxdens = 1, niter_irls = 50L, na_mode = "check") {
    .Call(`_pairscale_pairscale_mode`, x, clusters, min_value_count, n_bins, adjust, kernel_width_in_sd, bandwidth_method, mode_frac_maxdens, niter_irls, na_mode)
}

#' @title Normalize matrix columns using their median differences
#' @description Pairwise normalization of columns in a matrix, using the median to define pairwise distances between columns
#' @name pairscale_median
#' @inheritParams pairscale_mode
#' @return a numeric vector that represents the normalization factors that were applied to each column in x. Note that x is updated by reference.
#' @export
pairscale_median <- function(x, clusters = NULL, min_value_count = 3L, niter_irls = 50L, na_mode = "check") {
    .Call(`_pairscale_pairscale_median`, x, clusters, min_value_count, niter_irls, na_mode)
}

#' @title Normalize matrix columns using their mean differences
#' @description Pairwise normalization of columns in a matrix, using the mean to define pairwise distances between columns
#' @name pairscale_mean
#' @inheritParams pairscale_mode
#' @return a numeric vector that represents the normalization factors that were applied to each column in x. Note that x is updated by reference.
#' @export
pairscale_mean <- function(x, clusters = NULL, min_value_count = 3L, niter_irls = 50L, na_mode = "check") {
    .Call(`_pairscale_pairscale_mean`, x, clusters, min_value_count, niter_irls, na_mode)
}

#' @title Normalize matrix columns using their trimmed-mean differences
#' @description Pairwise normalization of columns in a matrix, using the trimmed-mean to define pairwise distances between columns
#' @name pairscale_trimmedmean
#' @inheritParams pairscale_mode
#' @param trim amount of trim to apply to both the lower- and upper-parts of a vector before computing the mean. 0 indicates no trim, 0.5 indicates 100% trim (i.e. 50% of data on both sides) so that value is out of bounds. Typically set to 0.1-0.3
#' @return a numeric vector that represents the normalization factors that were applied to each column in x. Note that x is updated by reference.
#' @export
pairscale_trimmedmean <- function(x, clusters = NULL, min_value_count = 3L, trim = 0.2, niter_irls = 50L, na_mode = "check") {
    .Call(`_pairscale_pairscale_trimmedmean`, x, clusters, min_value_count, trim, niter_irls, na_mode)
}

#' @title Normalize matrix columns using their MAD-trimmed mean differences
#' @description Pairwise normalization of columns in a matrix, using the MAD-trimmed mean to define pairwise distances between columns
#' @name pairscale_madmean
#' @inheritParams pairscale_mode
#' @param threshold_std ratio of MAD a value has to be away from the median to be considered an outlier (and thus removed/ignored). Note that the MAD thresholds are inclusive, i.e. values at +/- threshold_std*MAD from median are included
#' @return a numeric vector that represents the normalization factors that were applied to each column in x. Note that x is updated by reference.
#' @export
pairscale_madmean <- function(x, clusters = NULL, min_value_count = 3L, threshold_std = 3, niter_irls = 50L, na_mode = "check") {
    .Call(`_pairscale_pairscale_madmean`, x, clusters, min_value_count, threshold_std, niter_irls, na_mode)
}

#' @title graph Laplacian approach to finding normalization factors
#' @description find normalization factors for a given distance matrix computed with e.g. `pairdiff_median()`. For increased robustness, this function offers iterative reweighted improvement of the initial estimate.
#' @name solve_graph_laplacian
#' @param M skew-symmetric input matrix, generated with e.g. `pairdiff_median()`
#' @param niter_irls refine the initial estimate using N additional iterative reweighted least squares loops for robust graph laplacian
#' @examples
#' # toy example
#' x = cbind(
#'   c(1,2,3,4),
#'   c(2,3,4,9),
#'   c(1,2,4,5),
#'   c(1,0,1,0)
#' )
#' # compute pairwide median difference between all columns
#' M = pairscale::pairdiff_median(x)
#' # solve matrix M to find scaling factors, without and with reweighting
#' s1 = pairscale::solve_graph_laplacian(M, niter_irls = 0)
#' s2 = pairscale::solve_graph_laplacian(M, niter_irls = 10)
#' # rescaled matrices; only the robust variant correctly aligns columns 1 and 2
#' t(t(x) - s1)
#' t(t(x) - s2)
#' @return a numeric vector of length `ncol(M)` that contains scaling factors for `M`
#' @export
solve_graph_laplacian <- function(M, niter_irls = 1L) {
    .Call(`_pairscale_solve_graph_laplacian`, M, niter_irls)
}

