geva.quantiles {geva} | R Documentation

## GEVA Quantiles Detection

### Description

Calculates the quantiles of a `SVTable`.

### Usage

    geva.quantiles(
      sv,
      quantile.method = options.quantiles,
      initial.thresholds = c(S = NA_real_, V = NA_real_),
      nq.s = 3L,
      nq.v = 2L,
      comb.score.fn = prod,
      ...
    )

    options.quantiles
    # c("range.slice", "proportional", "density", "k.max.sd",
    #   "custom")

### Arguments

`sv` | a `SVTable` object (usually `GEVASummary`)
`quantile.method` | `character`, method to detect the initial quantile thresholds. Ignored if `initial.thresholds` is specified with no `NA` elements
`initial.thresholds` | named `numeric` vector with the threshold that delimits the initial quantile
`nq.s` | `integer`, number of quantiles in S-axis (experimental, see ‘Note’)
`nq.v` | `integer`, number of quantiles in V-axis (experimental, see ‘Note’)
`comb.score.fn` | `function` applied to merge `S` and `V` score columns into a single column. The function must require only one argument of `numeric vector` type and return a single `numeric` value. Examples include `prod` or `mean`
`...` | additional arguments include: `qslice` : `numeric` (`0` to `1`), the axis fraction used by `"range.slice"` and `"density"` methods (see 'Details'). Default is `0.25` `k` : `integer`, neighbor points used by `"density"` and `"k.max.sd"` methods (see 'Details'). Default is `16` `verbose` : `logical`, whether to print the current progress. Default is `TRUE`

### Details

The `quantile.method` defines how the initial quantile (usually the one at the bottom center) is calculated. Each method has a specific way to estimate the first spatial delimiter, as described below:

`"range.slice"` (default)

  Separation is set at the nearest point to a fraction of the spatial range. This fraction can be specified by the `qslice` optional argument (`numeric`, default is 0.25, or 25%);

`"density"`

  Separation is set at the point with the most proportional density by k neighbor points to its current spatial fraction. This method uses the optional arguments `qslice` (`numeric`, default is 0.25, or 25%) for the desired spatial fraction, and `k` (`numeric`, default is `16`) for the number of neighbor points;

`"k.max.sd"`

  Separation is set at the point with the greatest standard deviation of distance to its k neighbor points. The number of neighbor points can be specified by the `k` optional argument (`numeric`, default is `16`);

`"proportional"`

  Separation is set at the exact axis division so that all quantiles have the size;

`"custom"`

  Uses the values specified in the `initial.thresholds` argument.

A custom initial separation point can be specified in the `initial.thresholds` as a `numeric` vector of two elements, where the first element refers to `S` axis and the second, to `V` axis. If one of the elements is `NA`, the initial quantile is calculated for that axis only. If both values are not `NA`, the quantile separation method is ignored and automatically set to `"custom"`.

The `nq.s` and `nq.v` arguments determine the number of quantiles for the `S` and `V` axes, respectively. These parameters can be used to increase the number of possible partitions in the SV space, but their applicability is currently being tested (see ‘Note’).

The `comb.score.fn` is a function applied to the partial scores for each SV point to combine them into a single value. The result value is defined as the "quantile score" for a SV point. The function is applied iteratively to two-element `numeric` vectors.

### Note

Customizing the number of quantiles by `nq.s` and `nq.v` is a experimental feature and the remaining analysis steps are mostly based on the default parameters for these arguments. Tests are being conducted to determine this feature's applicability for the next releases.

### See Also

geva.cluster

Other geva.cluster: `geva.cluster()`, `geva.dcluster()`, `geva.hcluster()`

### Examples

    ## Quantile detection from a randomly generated input

    # Preparing the data
    ginput <- geva.ideal.example()      # Generates a random input example
    gsummary <- geva.summarize(ginput)  # Summarizes with the default parameters

    # Default usage
    gquants <- geva.quantiles(gsummary) # Detects the quantiles
    plot(gquants)                       # Plots the quantiles

    # Custom initial delimiters
    gquants <- geva.quantiles(gsummary,
                              initial.thresholds = c(S=1.00, V=0.5))
    plot(gquants)                       # Plots the quantiles

    # Quantile detection using densities
    gquants <- geva.quantiles(gsummary, quantile.method = 'density')
    plot(gquants)                       # Plots the quantiles

[Package geva version 1.2.0 Index]