Package {tidydann}

Check arguments of a model specification.

Description

Errors when main arguments are set that the selected engine cannot use. Called by parsnip during fit().

Usage

## S3 method for class 'nearest_neighbor_adaptive'
check_args(object, call = rlang::caller_env())

Arguments

Value

The model specification, invisibly.

Softening

Description

Scales the identity matrix added to the between class covariance, which keeps the neighborhood from collapsing onto the class boundary.

Usage

matrix_diagonal(range = c(0, 2), trans = NULL)

Arguments

Details

A value of 1 matches the publication. Of the tuning parameters, this one usually has the smallest effect on performance.

Value

An S3 class of type quant_param from the dials package.

Examples

library(tidydann)

matrix_diagonal()

Discriminant Adaptive Nearest Neighbor Classification

Description

Defines a nearest neighbor model where the shape of the neighborhood is learned from the data. This is a parsnip specification for the models in the dann package.

Usage

nearest_neighbor_adaptive(
  mode = "classification",
  neighbors = NULL,
  neighborhood = NULL,
  matrix_diagonal = NULL,
  weighted = NULL,
  sphere = NULL,
  num_comp = NULL
)

Arguments

Details

Discriminant Adaptive Nearest Neighbor (dann) is a variation of k nearest neighbors where the shape of the neighborhood is data driven. The neighborhood is elongated along class boundaries and shrunk in the orthogonal direction.

Two engines are available. The dann engine fits dann::dann() and uses neighbors, neighborhood, and matrix_diagonal. The sub_dann engine fits dann::sub_dann(), which first projects the predictors onto a lower dimensional subspace and then fits dann there. It uses every argument. Setting weighted, sphere, or num_comp with the dann engine is an error.

Prediction is parallelized. See tidydann_set_threads() to control how many threads are used.

Value

An S3 class of type nearest_neighbor_adaptive.

Examples

library(parsnip)
library(tidydann)

data("two_class_dat", package = "modeldata")

previous <- tidydann_set_threads(2)

model <- nearest_neighbor_adaptive(neighbors = 2) |>
  set_engine("dann") |>
  fit(formula = Class ~ A + B, data = two_class_dat)

model |>
  predict(new_data = two_class_dat)

tidydann_set_threads(previous)

Neighborhood size

Description

The number of nearest neighbors used to estimate the between and within class covariance matrices that shape the neighborhood.

Usage

neighborhood(range = c(2L, dials::unknown()), trans = NULL)

Arguments

Details

The upper end of the range depends on the size of the training data, so it is unknown until the data are seen. Use get_n() or finalize() from dials to fill it in.

When tuning with cross validation, each model only sees part of the training data. Use get_n_frac() with frac set to 1/V. See the README for a worked example.

Value

An S3 class of type quant_param from the dials package.

Examples

library(dials)
library(tidydann)

data("taxi", package = "modeldata")
neighborhood() |> finalize(taxi)

neighborhood() |> get_n(taxi)

Sphering method

Description

Type of covariance matrix used to sphere the data. Only used by the sub_dann engine.

Usage

sphere(values = c("mcd", "mve", "classical", "none"))

Arguments

Details

Passed to the sphere argument of fpc::ncoord().

Value

An S3 class of type qual_param from the dials package.

Examples

library(tidydann)

sphere()

Control the number of threads tidydann uses

Description

Get and set the number of threads the dann and sub_dann engines use when predicting. These are thin wrappers around dann::dann_set_threads(), dann::dann_get_threads(), and dann::dann_has_openmp().

Usage

tidydann_set_threads(n = NULL)

tidydann_get_threads()

tidydann_has_openmp()

Arguments

Details

On Linux and Windows, the prediction loop inside the dann package is parallelized with OpenMP. By default it uses every core the OpenMP runtime makes available. These functions change that count for the dann package alone, so no other package that uses OpenMP is affected. The setting lasts for the R session and is not stored on model objects.

This allows the user to move threading from a single model's predict to tidy model's tune or other logic. Thread usage can be changed without refitting.

n is clamped to the number of threads the OpenMP runtime makes available, with a message. Without OpenMP support, prediction runs on a single thread, tidydann_get_threads returns 1 no matter what was set, and tidydann_has_openmp returns FALSE.

Value

tidydann_set_threads returns the previous setting invisibly: a positive whole number, or NULL if dann was using the default. tidydann_get_threads returns the number of threads the next prediction will use. tidydann_has_openmp returns TRUE if dann was compiled with OpenMP.

Examples

library(tidydann)

# Limit dann to two threads.
previous <- tidydann_set_threads(2)
tidydann_get_threads()

# Put it back.
tidydann_set_threads(previous)

tidydann_has_openmp()

Declare tunable parameters

Description

Returns information on potential hyper-parameters that can be optimized.

Usage

## S3 method for class 'nearest_neighbor_adaptive'
tunable(x, ...)

Arguments

Details

The result depends on the engine. The dann engine does not use weighted, sphere, or num_comp, so those are omitted for it. When no engine has been set, every parameter is returned.

Value

A tibble with a column for the parameter name, information on the default method for generating a corresponding parameter object, the source of the parameter (e.g. "recipe", etc.), and the component within the source.

Update a model specification

Description

If parameters of a model specification need to be modified, update() can be used in lieu of recreating the object from scratch.

Usage

## S3 method for class 'nearest_neighbor_adaptive'
update(
  object,
  parameters = NULL,
  neighbors = NULL,
  neighborhood = NULL,
  matrix_diagonal = NULL,
  weighted = NULL,
  sphere = NULL,
  num_comp = NULL,
  fresh = FALSE,
  ...
)

Arguments

Value

An updated S3 class of type nearest_neighbor_adaptive.

Examples

library(parsnip)
library(tidydann)

model <- nearest_neighbor_adaptive(neighbors = 2)

model |> update(neighbors = 5)

Weighted between class covariance

Description

Should the between class covariance matrices be weighted? FALSE matches the publication. Only used by the sub_dann engine.

Usage

weighted(values = c(FALSE, TRUE))

Arguments

Details

Passed to the weighted argument of fpc::ncoord().

Value

An S3 class of type qual_param from the dials package.

Examples

library(tidydann)

weighted()