More docs

.Rbuildignore

@@ -21,3 +21,4 @@
 ^[\.]?air\.toml$
 ^\.vscode$
 ^\.claude$
+^vignettes/articles$

DESCRIPTION

@@ -38,7 +38,7 @@ Imports:
     tibble,
     vctrs,
     withr
-Suggests: 
+Suggests:
     covr,
     dials (>= 1.2.0),
     ggplot2,

NEWS.md

@@ -1,5 +1,7 @@
 # themis (development version)
 
+* Added a new article explaining how `over_ratio` and `under_ratio` work (#141).
+
 * All upsampling steps gain an `indicator_column` argument. When set, a logical column is added to the baked data marking rows added by the step (`TRUE`) vs rows from the original data (`FALSE`). For `step_rose()`, all rows are `TRUE` since ROSE generates a fully synthetic dataset (#58).
 
 * `step_rose()` and `rose()` now have improved documentation for `minority_prop`, clarifying that it controls the proportion of synthetic observations from the minority class, and how it differs from `over_ratio` (#144).

R/adasyn.R

@@ -22,6 +22,15 @@
 #'  the variable used to sample.
 #'
 #' @details
+#' ADASYN is an extension of SMOTE that adaptively generates synthetic minority
+#' class examples based on the local distribution of each minority instance.
+#' Instead of generating the same number of synthetic examples for every
+#' minority instance, ADASYN generates more synthetic examples for instances
+#' that are harder to learn — specifically those surrounded by more majority
+#' class neighbors. This focuses synthetic data generation on the difficult
+#' boundary regions of the minority class, resulting in a more informative
+#' augmentation than standard SMOTE.
+#'
 #' All columns in the data are sampled and returned by [recipes::juice()]
 #'  and [recipes::bake()].
 #'

R/downsample.R

@@ -19,7 +19,8 @@
 #'  that all other levels are sampled down to have the same
 #'  frequency as the least occurring level. A value of 2 would mean
 #'  that the majority levels will have (at most) (approximately)
-#'  twice as many rows than the minority level.
+#'  twice as many rows than the minority level. See
+#'  `vignette("ratio", package = "themis")` for more details.
 #' @param ratio Deprecated argument; same as `under_ratio`
 #' @param target An integer that will be used to subsample. This
 #'  should not be set by the user and will be populated by `prep`.

R/nearmiss.R

@@ -2,7 +2,7 @@
 #'
 #' `step_nearmiss()` creates a *specification* of a recipe step that removes
 #' majority class instances by undersampling points in the majority class based
-#' on their distance to other points in the same class.
+#' on their distance to points in the minority class.
 #'
 #' @inheritParams recipes::step_center
 #' @inheritParams step_downsample

R/rose.R

@@ -1,8 +1,8 @@
 #' Apply ROSE Algorithm
 #'
 #' `step_rose()` creates a *specification* of a recipe step that generates
-#' sample of synthetic data by enlarging the features space of minority and
-#' majority class example. Using [ROSE::ROSE()].
+#' samples of synthetic data by enlarging the feature space of minority and
+#' majority class examples. Using [ROSE::ROSE()].
 #'
 #' @inheritParams recipes::step_center
 #' @inheritParams step_upsample
@@ -39,12 +39,11 @@
 #' The factor variable used to balance around must only have 2 levels.
 #'
 #' The ROSE algorithm works by selecting an observation belonging to class k
-#' and generates new examples  in its neighborhood is determined by some matrix
-#' H_k. Smaller values of these arguments have the effect of shrinking the
-#' entries of the corresponding smoothing matrix H_k, Shrinking would be a
-#' cautious choice if there is a concern that excessively large neighborhoods
-#' could lead to blur the boundaries between the regions of the feature space
-#' associated with each class.
+#' and generating new examples in its neighborhood, which is determined by a
+#' smoothing matrix H_k. Smaller values of `minority_smoothness` and
+#' `majority_smoothness` shrink the entries of H_k, producing tighter
+#' neighborhoods. This is a cautious choice when there is a concern that
+#' excessively large neighborhoods could blur the boundaries between classes.
 #'
 #' All columns in the data are sampled and returned by [recipes::juice()]
 #'  and [recipes::bake()].
@@ -72,7 +71,7 @@
 #' @template case-weights-not-supported
 #'
 #' @references Lunardon, N., Menardi, G., and Torelli, N. (2014). ROSE: a
-#'  Package for Binary Imbalanced Learning. R Jorunal, 6:82–92.
+#'  Package for Binary Imbalanced Learning. R Journal, 6:82–92.
 #' @references Menardi, G. and Torelli, N. (2014). Training and assessing
 #'  classification rules with imbalanced data. Data Mining and Knowledge
 #'  Discovery, 28:92–122.
@@ -358,7 +357,7 @@ required_pkgs.step_rose <- function(x, ...) {
 #' between the regions of the feature space associated with each class.
 #'
 #' @references Lunardon, N., Menardi, G., and Torelli, N. (2014). ROSE: a
-#'  Package for Binary Imbalanced Learning. R Jorunal, 6:82–92.
+#'  Package for Binary Imbalanced Learning. R Journal, 6:82–92.
 #' @references Menardi, G. and Torelli, N. (2014). Training and assessing
 #'  classification rules with imbalanced data. Data Mining and Knowledge
 #'  Discovery, 28:92–122.

R/smote.R

@@ -1,7 +1,7 @@
 #' Apply SMOTE Algorithm
 #'
 #' `step_smote()` creates a *specification* of a recipe step that generate new
-#' examples of the  minority class using nearest neighbors of these cases.
+#' examples of the minority class using nearest neighbors of these cases.
 #'
 #' @inheritParams recipes::step_center
 #' @inheritParams step_upsample

R/smotenc.R

@@ -1,7 +1,7 @@
 #' Apply SMOTENC algorithm
 #'
 #' `step_smotenc()` creates a *specification* of a recipe step that generate new
-#' examples of the  minority class using nearest neighbors of these cases.
+#' examples of the minority class using nearest neighbors of these cases.
 #' Gower's distance is used to handle mixed data types. For categorical
 #' variables, the most common category along neighbors is chosen.
 #'
@@ -24,12 +24,18 @@
 #'  the variable used to sample.
 #'
 #' @details
+#' SMOTENC extends SMOTE to handle data sets with a mix of numeric and
+#' categorical predictors. For each minority class example, new synthetic
+#' examples are generated by interpolating between the example and its nearest
+#' neighbors using Gower's distance. Numeric features are interpolated
+#' continuously; categorical features take the most common value among the
+#' neighbors.
+#'
 #' The parameter `neighbors` controls the way the new examples are created.
 #' For each currently existing minority class example X new examples will be
 #' created (this is controlled by the parameter `over_ratio` as mentioned
 #' above). These examples will be generated by using the information from the
 #' `neighbors` nearest neighbor of each example of the minority class.
-#' The parameter `neighbors` controls how many of these neighbor are used.
 #'
 #' All columns in the data are sampled and returned by [recipes::juice()]
 #'  and [recipes::bake()].

R/tomek.R

@@ -22,12 +22,18 @@
 #'  the variable used to sample.
 #'
 #' @details
+#' A Tomek link is a pair of points from different classes that are each
+#' other's nearest neighbors. Such pairs sit on or very near the decision
+#' boundary and are considered noise or borderline cases. `step_tomek()`
+#' identifies all Tomek links and removes the majority class instance from
+#' each pair, cleaning the class boundary without discarding
+#' non-boundary majority examples. Because only boundary points are removed,
+#' this step typically discards far fewer observations than other
+#' under-sampling methods.
+#'
 #' All variables selected by `distance_with` must be numeric with no missing
 #' data.
 #'
-#' A tomek link is defined as a pair of points from different classes and are
-#' each others nearest neighbors.
-#'
 #' All columns in the data are sampled and returned by [recipes::juice()]
 #'  and [recipes::bake()].
 #'
@@ -50,7 +56,7 @@
 #' @references Tomek. Two modifications of cnn. IEEE Trans. Syst. Man Cybern.,
 #'  6:769-772, 1976.
 #'
-#'@seealso [tomek()] for direct implementation
+#' @seealso [tomek()] for direct implementation
 #' @family Steps for under-sampling
 #'
 #' @export

R/upsample.R

@@ -19,7 +19,8 @@
 #'  that all other levels are sampled up to have the same
 #'  frequency as the most occurring level. A value of 0.5 would mean
 #'  that the minority levels will have (at most) (approximately)
-#'  half as many rows as the majority level.
+#'  half as many rows as the majority level. See
+#'  `vignette("ratio", package = "themis")` for more details.
 #' @param ratio Deprecated argument; same as `over_ratio`.
 #' @param target An integer that will be used to subsample. This
 #'  should not be set by the user and will be populated by `prep`.

_pkgdown.yml

@@ -17,6 +17,12 @@ template:
 development:
   mode: auto
 
+articles:
+- title: Getting started
+  navbar: ~
+  contents:
+  - articles/ratio
+
 reference:
 - title: Over-sampling
   desc: >