QuantileOnQuantile: Quantile-on-Quantile Regression Analysis

Description

Implements the Quantile-on-Quantile (QQ) regression methodology developed by Sim and Zhou (2015). This approach extends standard quantile regression by estimates the effect that quantiles of one variable have on quantiles of another, capturing the full dependence structure between their distributions.

Details

The main functions are:

• qq_regression - Perform QQ regression analysis

• plot_qq_3d - Create 3D surface plots (MATLAB-style)

• plot_qq_heatmap - Create heatmap visualizations

• plot_qq_contour - Create contour plots

• plot_qq_correlation - Create quantile correlation heatmaps

The package provides multiple color scales:

• Jet - MATLAB-style rainbow

• BlueRed - Diverging scale

• Viridis - Colorblind-friendly

• Plasma - High contrast

Methodology

The QQ approach combines quantile regression with local linear regression. For each quantile tau of the independent variable and each quantile theta of the dependent variable, the method estimates coefficients that capture how the relationship varies across the distributions.

This is particularly useful for financial applications where the relationship between variables may differ during extreme market conditions.

Author(s)

Maintainer: Merwan Roudane merwanroudane920@gmail.com [copyright holder]

Other contributors:

• Nicholas Sim (Original methodology developer) [contributor]

• Hongtao Zhou (Original methodology developer) [contributor]

References

Sim, N. and Zhou, H. (2015). Oil Prices, US Stock Return, and the Dependence Between Their Quantiles. Journal of Banking & Finance, 55, 1-12. doi:10.1016/j.jbankfin.2015.01.013

See Also

rq for the underlying quantile regression function.

Plot Method for qq_regression Objects

Description

Creates a 3D surface plot of qq_regression results.

Usage

## S3 method for class 'qq_regression'
plot(x, type = "coefficient", colorscale = "Jet", ...)

Arguments

Value

A plotly object. This function is called for its side effect of creating an interactive 3D visualization.

3D Surface Plot for QQ Regression

Description

Creates an interactive 3D surface plot of QQ regression results using plotly. Supports multiple color scales including MATLAB-style Jet.

Usage

plot_qq_3d(
  qq_result,
  type = c("coefficient", "rsquared", "pvalue"),
  colorscale = c("Jet", "BlueRed", "Viridis", "Plasma"),
  show_contour = TRUE,
  x_label = "X Quantile (tau)",
  y_label = "Y Quantile (theta)",
  title = NULL,
  aspect_ratio = c(1, 1, 0.7),
  camera = list(eye = list(x = 1.4, y = 1.7, z = 1.2))
)

Arguments

Details

The function creates an interactive 3D surface plot where:

• X-axis: Quantiles of the independent variable (tau)

• Y-axis: Quantiles of the dependent variable (theta)

• Z-axis: Estimated coefficients, R-squared, or p-values

The Jet colorscale mimics MATLAB's default color scheme for surface plots, transitioning from blue through cyan, green, yellow to red.

Value

A plotly object representing the 3D surface plot.

Examples

# Generate example data
set.seed(42)
n <- 200
x <- rnorm(n)
y <- 0.5 * x + rnorm(n, sd = 0.5)

# Run QQ regression
result <- qq_regression(y, x, verbose = FALSE)


# Create 3D surface plot of coefficients
plot_qq_3d(result, type = "coefficient", colorscale = "Jet")

# Create plot of R-squared values
plot_qq_3d(result, type = "rsquared", colorscale = "Viridis")

Contour Plot for QQ Regression

Description

Creates an interactive contour plot of QQ regression coefficients using plotly.

Usage

plot_qq_contour(
  qq_result,
  type = c("coefficient", "rsquared", "pvalue"),
  colorscale = "Jet",
  show_labels = TRUE,
  x_label = "X Variable Quantiles",
  y_label = "Y Variable Quantiles",
  title = NULL
)

Arguments

Value

A plotly object representing the contour plot.

Examples

# Generate example data
set.seed(42)
n <- 200
x <- rnorm(n)
y <- 0.5 * x + rnorm(n, sd = 0.5)

# Run QQ regression
result <- qq_regression(y, x, verbose = FALSE)


# Create contour plot
plot_qq_contour(result)

Quantile Correlation Heatmap

Description

Creates an interactive heatmap showing the correlation between quantiles of two variables. Uses a blue-red diverging color scale similar to Python's seaborn style.

Usage

plot_qq_correlation(
  y,
  x,
  quantiles = seq(0.1, 0.9, by = 0.1),
  x_label = "X Variable Quantiles",
  y_label = "Y Variable Quantiles",
  title = "Quantile Correlation Heatmap",
  show_annotations = TRUE
)

Arguments

Details

This function computes correlations between binary indicators of whether observations fall below each quantile threshold. The resulting heatmap shows how the relationship between variables varies across different parts of their distributions.

Value

A plotly object representing the correlation heatmap.

Examples

# Generate example data
set.seed(42)
n <- 200
x <- rnorm(n)
y <- 0.5 * x + rnorm(n, sd = 0.5)


# Create correlation heatmap
plot_qq_correlation(y, x)

Heatmap for QQ Regression

Description

Creates an interactive heatmap of QQ regression results using plotly.

Usage

plot_qq_heatmap(
  qq_result,
  type = c("coefficient", "rsquared", "pvalue"),
  colorscale = NULL,
  x_label = "X Variable Quantiles",
  y_label = "Y Variable Quantiles",
  title = NULL,
  zmin = NULL,
  zmax = NULL
)

Arguments

Value

A plotly object representing the heatmap.

Examples

# Generate example data
set.seed(42)
n <- 200
x <- rnorm(n)
y <- 0.5 * x + rnorm(n, sd = 0.5)

# Run QQ regression
result <- qq_regression(y, x, verbose = FALSE)


# Create coefficient heatmap
plot_qq_heatmap(result, type = "coefficient")

# Create R-squared heatmap
plot_qq_heatmap(result, type = "rsquared", colorscale = "Plasma")

# Create p-value heatmap
plot_qq_heatmap(result, type = "pvalue", colorscale = "Jet")

Print Method for qq_regression Objects

Description

Prints a summary of a qq_regression object.

Usage

## S3 method for class 'qq_regression'
print(x, ...)

Arguments

Value

The input object x is returned invisibly. This function is called for its side effect of printing the QQ regression summary to the console.

Available Color Scales for QQ Regression Plots

Description

Returns information about the available color scales for 3D surface plots and heatmaps in the QuantileOnQuantile package.

Usage

qq_colorscales(show_preview = TRUE)

Arguments

Details

The following color scales are available:

Jet

MATLAB-style rainbow colorscale. Transitions from blue through cyan, green, yellow to red. Best for general visualization where the full range of values is important.

BlueRed

Diverging colorscale from blue to red. Also known as "COVID style" in some contexts. Best for data with a meaningful center point (e.g., zero for coefficients).

Viridis

Perceptually uniform colorscale. Designed to be colorblind-friendly and print well in grayscale.

Plasma

Another perceptually uniform colorscale. Similar benefits to Viridis but with a different color palette.

Value

A character vector of available color scale names, invisibly.

Examples

# Show available color scales
qq_colorscales()

# Get scales without printing
scales <- qq_colorscales(show_preview = FALSE)
print(scales)

Export QQ Results to CSV

Description

Exports QQ regression results to a CSV file.

Usage

qq_export(qq_result, file, digits = 4)

Arguments

Value

Invisible NULL. Called for its side effect of writing a CSV file.

Examples

# Generate example data
set.seed(42)
n <- 200
x <- rnorm(n)
y <- 0.5 * x + rnorm(n, sd = 0.5)

# Run QQ regression
result <- qq_regression(y, x, verbose = FALSE)

# Export to CSV
qq_export(result, file.path(tempdir(), "qq_results.csv"))

Quantile-on-Quantile Regression

Description

Performs Quantile-on-Quantile (QQ) regression analysis as described in Sim and Zhou (2015). This approach estimates the effect that quantiles of an independent variable have on quantiles of a dependent variable, capturing the dependence between their distributions.

Usage

qq_regression(
  y,
  x,
  y_quantiles = seq(0.05, 0.95, by = 0.05),
  x_quantiles = seq(0.05, 0.95, by = 0.05),
  min_obs = 10,
  se_method = "boot",
  verbose = TRUE
)

Arguments

Details

The QQ approach combines quantile regression with local linear regression to estimate the effect of the \tau-quantile of x on the \theta-quantile of y.

The method proceeds as follows:

1. For each x_quantile (\tau), subset the data where x <= quantile(x, \tau)

2. For each y_quantile (\theta), perform quantile regression of y on x

3. Extract coefficients, standard errors, t-values, p-values

4. Compute pseudo R-squared based on check function

If the subset has fewer than min_obs observations, a correlation-based approach is used instead.

Value

An object of class "qq_regression" containing:

• results - Data frame with columns: y_quantile, x_quantile, coefficient, std_error, t_value, p_value, r_squared

• y_quantiles - Quantiles of y used

• x_quantiles - Quantiles of x used

• n_obs - Number of complete observations

• call - The matched call

• method - Method used ("quantile_regression" or "correlation")

References

Sim, N. and Zhou, H. (2015). Oil Prices, US Stock Return, and the Dependence Between Their Quantiles. Journal of Banking & Finance, 55, 1-12. doi:10.1016/j.jbankfin.2015.01.013

Examples

# Generate example data
set.seed(42)
n <- 200
x <- rnorm(n)
y <- 0.5 * x + rnorm(n, sd = 0.5)

# Run QQ regression with default quantiles
result <- qq_regression(y, x, verbose = FALSE)

# Print summary
print(result)

# View first few results
head(result$results)


# Run with custom quantiles
result2 <- qq_regression(y, x,
                         y_quantiles = seq(0.1, 0.9, by = 0.1),
                         x_quantiles = seq(0.1, 0.9, by = 0.1),
                         verbose = FALSE)

Summary Statistics for QQ Regression

Description

Computes comprehensive summary statistics for QQ regression results.

Usage

qq_statistics(qq_result, alpha = 0.05)

Arguments

Value

A data frame with summary statistics including:

• Mean, median, min, max of coefficients

• Mean, median, min, max of R-squared

• Number of significant results at specified alpha

• Total number of results

Examples

# Generate example data
set.seed(42)
n <- 200
x <- rnorm(n)
y <- 0.5 * x + rnorm(n, sd = 0.5)

# Run QQ regression
result <- qq_regression(y, x, verbose = FALSE)

# Get summary statistics
stats <- qq_statistics(result)
print(stats)

Convert QQ Results to Matrix

Description

Converts QQ regression results to a matrix format suitable for base R plotting or export.

Usage

qq_to_matrix(qq_result, type = c("coefficient", "rsquared", "pvalue"))

Arguments

Value

A matrix with y_quantiles as rows and x_quantiles as columns.

Examples

# Generate example data
set.seed(42)
n <- 200
x <- rnorm(n)
y <- 0.5 * x + rnorm(n, sd = 0.5)

# Run QQ regression
result <- qq_regression(y, x, verbose = FALSE)

# Convert to matrix
coef_matrix <- qq_to_matrix(result, type = "coefficient")
print(dim(coef_matrix))

Summary Method for qq_regression Objects

Description

Provides a detailed summary of a qq_regression object.

Usage

## S3 method for class 'qq_regression'
summary(object, ...)

Arguments

Value

A list containing summary statistics, returned invisibly. The function is called for its side effect of printing a detailed summary to the console.