Learn R Programming

densityratio

Overview

This package provides functionality to directly estimate a density ratio $$r(x) = \frac{p_\text{nu}(x)}{p_{\text{de}}(x)},$$ without estimating the numerator and denominator density separately. Density ratio estimation serves many purposes, for example, prediction, outlier detection, change-point detection in time-series, importance weighting under domain adaptation (i.e., sample selection bias) and evaluation of synthetic data utility. The key idea is that differences between data distributions can be captured in their density ratio, which is estimated over the entire multivariate space of the data. Subsequently, the density ratio values can be used to summarize the dissimilarity between the two distributions in a discrepancy measure.

Features

  • Fast: Computationally intensive code is executed in C++ using Rcpp and RcppArmadillo.
  • Automatic: Good default hyperparameters that can be optimized in cross-validation (we do recommend understanding those parameters before using densityratio in practice).
  • Complete: Several density ratio estimation methods, such as unconstrained least-squares importance fitting (ulsif()), Kullback-Leibler importance estimation procedure (kliep()), kernel mean matching (kmm()), ratio of estimated densities (naive()), spectral density ratio estimation (spectral() and least-squares heterodistributional subspace search (lhss()).
  • User-friendly: Simple user interface, default predict(), print() and summary() functions for all density ratio estimation methods; built-in data sets for quick testing.

Installation

You can install the stable release of densityratio from CRAN with:

install.packages('densityratio')

For the development version, use:

remotes::install_github("thomvolker/densityratio")

Usage

The package contains several functions to estimate the density ratio between the numerator data and the denominator data. To illustrate the functionality, we make use of the in-built simulated data sets numerator_data and denominator_data, that both consist of the same five variables.

Minimal example

library(densityratio)

head(numerator_data)
#> # A tibble: 6 × 5
#>   x1    x2         x3     x4     x5
#>   <fct> <fct>   <dbl>  <dbl>  <dbl>
#> 1 A     G1    -0.0299  0.967 -1.26 
#> 2 C     G1     2.29   -0.475  2.40 
#> 3 A     G1     1.37    0.577 -0.172
#> 4 B     G2     1.44   -0.193 -0.708
#> 5 A     G1     1.01    2.23   2.01 
#> 6 C     G2     1.83    0.762  3.71

fit <- ulsif(
  df_numerator = numerator_data$x5,
  df_denominator = denominator_data$x5,
  nsigma = 5,
  nlambda = 5
)

class(fit)
#> [1] "ulsif"

We can ask for the summary() of the estimated density ratio object, that contains the optimal kernel weights (optimized using cross-validation) and a measure of discrepancy between the numerator and denominator densities.

summary(fit)
#> 
#> Call:
#> ulsif(df_numerator = numerator_data$x5, df_denominator = denominator_data$x5,     nsigma = 5, nlambda = 5)
#> 
#> Kernel Information:
#>   Kernel type: Gaussian with L2 norm distances
#>   Number of kernels: 200
#> 
#> Optimal sigma: 0.3726142
#> Optimal lambda: 0.03162278
#> Optimal kernel weights: num [1:201] 0.43926 0.01016 0.00407 0.01563 0.01503 ...
#>  
#> Pearson divergence between P(nu) and P(de): 0.2801
#> For a two-sample homogeneity test, use 'summary(x, test = TRUE)'.

To formally evaluate whether the numerator and denominator densities differ significantly, you can perform a two-sample homogeneity test as follows.

summary(fit, test = TRUE)
#> 
#> Call:
#> ulsif(df_numerator = numerator_data$x5, df_denominator = denominator_data$x5,     nsigma = 5, nlambda = 5)
#> 
#> Kernel Information:
#>   Kernel type: Gaussian with L2 norm distances
#>   Number of kernels: 200
#> 
#> Optimal sigma: 0.3726142
#> Optimal lambda: 0.03162278
#> Optimal kernel weights: num [1:201] 0.43926 0.01016 0.00407 0.01563 0.01503 ...
#>  
#> Pearson divergence between P(nu) and P(de): 0.2801
#> Pr(P(nu)=P(de)) < .001
#> Bonferroni-corrected for testing with r(x) = P(nu)/P(de) AND r*(x) = P(de)/P(nu).

The probability that numerator and denominator samples share a common data generating mechanism is very small.

The ulsif-object also contains the (hyper-)parameters used in estimating the density ratio, such as the centers used in constructing the Gaussian kernels (fit$centers), the different bandwidth parameters (fit$sigma) and the regularization parameters (fit$lambda). Using these variables, we can obtain the estimated density ratio using predict().

# obtain predictions for the numerator samples

newx5 <- seq(from = -3, to = 6, by = 0.05)
pred <- predict(fit, newdata = newx5)

ggplot() +
  geom_point(aes(x = newx5, y = pred, col = "ulsif estimates")) +
  stat_function(
    mapping = aes(col = "True density ratio"),
    fun = dratio,
    args = list(p = 0.4, dif = 3, mu = 3, sd = 2),
    linewidth = 1
  ) +
  theme_classic() +
  scale_color_manual(name = NULL, values = c("#de0277", "purple")) +
  theme(
    legend.position = "inside",
    legend.position.inside = c(0.8, 0.9),
    text = element_text(size = 50),
    legend.text = element_text(size = 50),
  )

Scaling

By default, all functions in the densityratio package standardize the data to the numerator means and standard deviations. This is done to ensure that the importance of each variable in the kernel estimates is not dependent on the scale of the data. By setting scale = "denominator" one can scale the data to the means and standard deviations of the denominator data, and by setting scale = FALSE the data remains on the original scale.

Categorical data

All of the functions in the densityratio package accept categorical variables types. However, note that internally, these variables are one-hot encoded, which can lead to a high-dimensional feature-space.

summary(numerator_data$x1)
#>   A   B   C 
#> 351 339 310
summary(denominator_data$x1)
#>   A   B   C 
#> 252 232 516

fit_cat <- ulsif(
  df_numerator = numerator_data$x1,
  df_denominator = denominator_data$x1
)
#> Warning in check.sigma(nsigma, sigma_quantile, sigma, dist_nu): There are duplicate values in 'sigma', only the unique values are used.

aggregate(
  predict(fit_cat) ~ numerator_data$x1,
  FUN = unique
)
#>   numerator_data$x1 predict(fit_cat)
#> 1                 A        1.3005360
#> 2                 B        1.3574809
#> 3                 C        0.6379142

table(numerator_data$x1) / table(denominator_data$x1)
#> 
#>         A         B         C 
#> 1.3928571 1.4612069 0.6007752

This transformation can give a reasonable estimate of the ratio of proportions in the different data sets (although there is some regularization applied such that the estimated odds are closer to one than seen in the real data).

Full data example

After transforming all variables to numeric variables, it is possible to calculate the density ratio over the entire multivariate space of the data.

fit_all <- ulsif(
  df_numerator = numerator_data,
  df_denominator = denominator_data
)

summary(fit_all, test = TRUE, parallel = TRUE)
#> 
#> Call:
#> ulsif(df_numerator = numerator_data, df_denominator = denominator_data)
#> 
#> Kernel Information:
#>   Kernel type: Gaussian with L2 norm distances
#>   Number of kernels: 200
#> 
#> Optimal sigma: 1.065369
#> Optimal lambda: 0.1623777
#> Optimal kernel weights: num [1:201] 0.5691 0.1511 0.0959 0.0118 0.0149 ...
#>  
#> Pearson divergence between P(nu) and P(de): 0.4629
#> Pr(P(nu)=P(de)) < .001
#> Bonferroni-corrected for testing with r(x) = P(nu)/P(de) AND r*(x) = P(de)/P(nu).

Other density ratio estimation functions

Besides ulsif(), the package contains several other functions to estimate a density ratio.

  • naive() estimates the numerator and denominator densities separately, and subsequently takes there ratio.
  • kliep() estimates the density ratio directly through the Kullback-Leibler importance estimation procedure.
  • kmm() estimates the density ratio through kernel mean matching.
  • lhss() estimates the density ratio in a subspace where the two distributions are most different using least-squares heterodistributional subspace search.
  • spectral() estimates the density ratio using a spectral series approach.

We display kliep() and naive() as examples here. The other functions are discussed in the Get Started vignette.

fit_naive <- naive(
  df_numerator = numerator_data$x5,
  df_denominator = denominator_data$x5
)

fit_kliep <- kliep(
  df_numerator = numerator_data$x5,
  df_denominator = denominator_data$x5
)


pred_naive <- predict(fit_naive, newdata = newx5)
pred_kliep <- predict(fit_kliep, newdata = newx5)


ggplot(data = NULL, aes(x = newx5)) +
  geom_point(aes(y = pred, col = "ulsif estimates")) +
  geom_point(aes(y = pred_naive, col = "naive estimates")) +
  geom_point(aes(y = pred_kliep, col = "kliep estimates")) +
  stat_function(aes(x = NULL, col = "True density ratio"),
    fun = dratio, args = list(p = 0.4, dif = 3, mu = 3, sd = 2),
    linewidth = 1
  ) +
  theme_classic() +
  scale_color_manual(name = NULL, values = c("pink", "#512970", "#de0277", "purple")) +
  theme(
    legend.position = "inside",
    legend.position.inside = c(0.8, 0.9),
    text = element_text(size = 50),
    legend.text = element_text(size = 50),
  )

The figure directly shows that ulsif() and kliep() come rather close to the true density ratio function in this example, and outperform the naive() solution.

Contributions

This package is still in development, and I’ll be happy to take feedback and suggestions. Please submit these through GitHub Issues.

Resources

Books

Papers

How to cite

Volker, T.B., Poses, C. & Van Kesteren, E.J. (2023). densityratio: Distribution comparison through density ratio estimation. https://doi.org/10.5281/zenodo.8307818

Copy Link

Version

Install

install.packages('densityratio')

Version

0.2.1

License

GPL (>= 3)

Issues

Pull Requests

Stars

Forks

Maintainer

Thom Volker

Last Published

June 18th, 2025

Functions in densityratio (0.2.1)

numerator_data

numerator_data
numerator_small

numerator_small
print.summary.lhss

Print a summary.lhss object
summary.naivedensityratio

Extract summary from naivedensityraito object, including two-sample significance test for homogeneity of the numerator and denominator samples
print.summary.naivedensityratio

Print a summary.naivedensityratio object
summary.lhss

Extract summary from lhss object, including two-sample significance test for homogeneity of the numerator and denominator samples
predict.spectral

Obtain predicted density ratio values from a spectral object
print.spectral

Print a spectral object
summary.kliep

Extract summary from kliep object, including two-sample significance test for homogeneity of the numerator and denominator samples
summary.kmm

Extract summary from kmm object, including two-sample significance test for homogeneity of the numerator and denominator samples
print.naivedensityratio

Print a naivedensityratio object
summary.spectral

Extract summary from spectral object, including two-sample significance test for homogeneity of the numerator and denominator samples
summary.ulsif

Extract summary from ulsif object, including two-sample significance test for homogeneity of the numerator and denominator samples
print.kmm

Print a kmm object
print.lhss

Print a lhss object
permute

Single permutation
plot_bivariate

Densityratio in two-dimensional plot
print.summary.kliep

Print a summary.kliep object
extract_params.ulsif

Obtain parameters from a ulsif object
print.summary.kmm

Print a summary.kmm object
insurance

insurance
print.kliep

Print a kliep object
predict.ulsif

Obtain predicted density ratio values from a ulsif object
print.summary.spectral

Print a summary.spectral object
kliep

Kullback-Leibler importance estimation procedure
print.summary.ulsif

Print a summary.ulsif object
print.ulsif

Print a ulsif object
kmm

Kernel mean matching approach to density ratio estimation
plot_univariate

Scatter plot of density ratios and individual variables
predict.kliep

Obtain predicted density ratio values from a kliep object
spectral

Spectral series based density ratio estimation
ulsif

Unconstrained least-squares importance fitting
extract_params.kmm

Obtain parameters from a kmm object
create_bivariate_plot

Bivariate plot
create_univariate_plot

Univariate plot
dr.histogram

A histogram of density ratio estimates
distance

Create a Gram matrix with squared Euclidean distances between observations in the input matrix X and the input matrix Y
kernel_gaussian

Create gaussian kernel gram matrix from distance matrix
lhss

Least-squares heterodistributional subspace search
naive

Naive density ratio estimation
denominator_data

denominator_data
extract_params.kliep

Obtain parameters from a kliep object
denominator_small

denominator_small
extract_params

Extract parameters
colon

colon
extract_params.lhss

Obtain parameters from a lhss object
extract_params.spectral

Obtain parameters from a spectral object
predict.kmm

Obtain predicted density ratio values from a kmm object
predict.lhss

Obtain predicted density ratio values from a lhss object
kidiq

kidiq
predict.naivedensityratio

Obtain predicted density ratio values from a naivedensityratio object