| Title: | Quantile-on-Quantile Regression Analysis |
|---|---|
| Description: | Implements the Quantile-on-Quantile (QQ) regression methodology developed by Sim and Zhou (2015) <doi:10.1016/j.jbankfin.2015.01.013>. QQ regression estimates the effect that quantiles of one variable have on quantiles of another, capturing the dependence between distributions. The package provides functions for QQ regression estimation, 3D surface visualization with 'MATLAB'-style color schemes ('Jet', 'Viridis', 'Plasma'), heatmaps, contour plots, and quantile correlation analysis. Uses 'quantreg' for quantile regression and 'plotly' for interactive visualizations. Particularly useful for examining relationships between financial variables, oil prices, and stock returns under different market conditions. |
| Authors: | Merwan Roudane [aut, cre, cph], Nicholas Sim [ctb] (Original methodology developer), Hongtao Zhou [ctb] (Original methodology developer) |
| Maintainer: | Merwan Roudane <[email protected]> |
| License: | GPL-3 |
| Version: | 1.0.3 |
| Built: | 2026-05-09 07:20:01 UTC |
| Source: | https://github.com/cran/QuantileOnQuantile |
Creates an interactive 3D surface plot of QQ regression results using plotly. Supports multiple color scales including MATLAB-style Jet.
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)) )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)) )
qq_result |
An object of class "qq_regression" or a data frame with columns: y_quantile, x_quantile, coefficient, r_squared, p_value. |
type |
Character string. Type of values to plot: "coefficient" (default), "rsquared", or "pvalue". |
colorscale |
Character string. Color scale to use. Options are:
|
show_contour |
Logical. If |
x_label |
Character string. Label for x-axis. Default is "X Quantile (tau)". |
y_label |
Character string. Label for y-axis. Default is "Y Quantile (theta)". |
title |
Character string. Plot title. If |
aspect_ratio |
Numeric vector of length 3. Aspect ratio for x, y, z axes. Default is c(1, 1, 0.7). |
camera |
List. Camera position settings for plotly. Default provides a good viewing angle. |
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.
A plotly object representing the 3D surface plot.
# 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")# 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")
Creates an interactive contour plot of QQ regression coefficients using plotly.
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 )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 )
qq_result |
An object of class "qq_regression" or a data frame with columns: y_quantile, x_quantile, coefficient. |
type |
Character string. Type of values to plot: "coefficient" (default), "rsquared", or "pvalue". |
colorscale |
Character string. Color scale to use. Default is "Jet". |
show_labels |
Logical. If |
x_label |
Character string. Label for x-axis. Default is "X Variable Quantiles". |
y_label |
Character string. Label for y-axis. Default is "Y Variable Quantiles". |
title |
Character string. Plot title. If |
A plotly object representing the contour plot.
# 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)# 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)
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.
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 )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 )
y |
Numeric vector. The first variable. |
x |
Numeric vector. The second variable. |
quantiles |
Numeric vector. Quantiles to compute correlations for.
Default is |
x_label |
Character string. Label for x-axis. Default is "X Variable Quantiles". |
y_label |
Character string. Label for y-axis. Default is "Y Variable Quantiles". |
title |
Character string. Plot title. Default is "Quantile Correlation Heatmap". |
show_annotations |
Logical. If |
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.
A plotly object representing the correlation heatmap.
# 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)# 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)
Creates an interactive heatmap of QQ regression results using plotly.
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 )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 )
qq_result |
An object of class "qq_regression" or a data frame with columns: y_quantile, x_quantile, coefficient, r_squared, p_value. |
type |
Character string. Type of values to plot: "coefficient" (default), "rsquared", or "pvalue". |
colorscale |
Character string. Color scale to use. Options are:
|
x_label |
Character string. Label for x-axis. Default is "X Variable Quantiles". |
y_label |
Character string. Label for y-axis. Default is "Y Variable Quantiles". |
title |
Character string. Plot title. If |
zmin |
Numeric. Minimum value for color scale. If |
zmax |
Numeric. Maximum value for color scale. If |
A plotly object representing the heatmap.
# 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")# 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")
Creates a 3D surface plot of qq_regression results.
## S3 method for class 'qq_regression' plot(x, type = "coefficient", colorscale = "Jet", ...)## S3 method for class 'qq_regression' plot(x, type = "coefficient", colorscale = "Jet", ...)
x |
An object of class "qq_regression". |
type |
Character string. Type of plot: "coefficient", "rsquared", or "pvalue". Default is "coefficient". |
colorscale |
Character string. Color scale to use. One of "Jet", "BlueRed", "Viridis", or "Plasma". Default is "Jet". |
... |
Additional arguments passed to |
A plotly object. This function is called for its side effect of creating an interactive 3D visualization.
Prints a summary of a qq_regression object.
## S3 method for class 'qq_regression' print(x, ...)## S3 method for class 'qq_regression' print(x, ...)
x |
An object of class "qq_regression". |
... |
Additional arguments (currently ignored). |
The input object x is returned invisibly. This function
is called for its side effect of printing the QQ regression summary
to the console.
Returns information about the available color scales for 3D surface plots and heatmaps in the QuantileOnQuantile package.
qq_colorscales(show_preview = TRUE)qq_colorscales(show_preview = TRUE)
show_preview |
Logical. If |
The following color scales are available:
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.
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).
Perceptually uniform colorscale. Designed to be colorblind-friendly and print well in grayscale.
Another perceptually uniform colorscale. Similar benefits to Viridis but with a different color palette.
A character vector of available color scale names, invisibly.
# Show available color scales qq_colorscales() # Get scales without printing scales <- qq_colorscales(show_preview = FALSE) print(scales)# Show available color scales qq_colorscales() # Get scales without printing scales <- qq_colorscales(show_preview = FALSE) print(scales)
Exports QQ regression results to a CSV file.
qq_export(qq_result, file, digits = 4)qq_export(qq_result, file, digits = 4)
qq_result |
An object of class "qq_regression". |
file |
Character string. Path to the output file. |
digits |
Integer. Number of decimal places for rounding. Default is 4. |
Invisible NULL. Called for its side effect of writing
a CSV file.
# 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"))# 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"))
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.
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 )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 )
y |
Numeric vector. The dependent variable. |
x |
Numeric vector. The independent variable. |
y_quantiles |
Numeric vector. Quantiles of the dependent variable to
estimate. Default is |
x_quantiles |
Numeric vector. Quantiles of the independent variable
to condition on. Default is |
min_obs |
Integer. Minimum number of observations required for quantile regression. Default is 10. |
se_method |
Character string. Method for computing standard errors in quantile regression. One of "boot" (bootstrap), "nid" (no i.i.d. assumption), "iid", or "ker" (kernel). Default is "boot". |
verbose |
Logical. If |
The QQ approach combines quantile regression with local linear regression
to estimate the effect of the -quantile of x on the
-quantile of y.
The method proceeds as follows:
For each x_quantile (), subset the data where
x <= quantile(x, )
For each y_quantile (), perform quantile
regression of y on x
Extract coefficients, standard errors, t-values, p-values
Compute pseudo R-squared based on check function
If the subset has fewer than min_obs observations, a correlation-based
approach is used instead.
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")
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
# 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)# 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)
Computes comprehensive summary statistics for QQ regression results.
qq_statistics(qq_result, alpha = 0.05)qq_statistics(qq_result, alpha = 0.05)
qq_result |
An object of class "qq_regression". |
alpha |
Numeric. Significance level for counting significant results. Default is 0.05. |
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
# 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)# 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)
Converts QQ regression results to a matrix format suitable for base R plotting or export.
qq_to_matrix(qq_result, type = c("coefficient", "rsquared", "pvalue"))qq_to_matrix(qq_result, type = c("coefficient", "rsquared", "pvalue"))
qq_result |
An object of class "qq_regression" or a data frame. |
type |
Character string. Type of values: "coefficient", "rsquared", or "pvalue". Default is "coefficient". |
A matrix with y_quantiles as rows and x_quantiles as columns.
# 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))# 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))
Provides a detailed summary of a qq_regression object.
## S3 method for class 'qq_regression' summary(object, ...)## S3 method for class 'qq_regression' summary(object, ...)
object |
An object of class "qq_regression". |
... |
Additional arguments (currently ignored). |
A list containing summary statistics, returned invisibly. The function is called for its side effect of printing a detailed summary to the console.