*! version 1.0.0 29may2026

Title

qqsurf3d -- MATLAB-style filled 3D surface of a QQ result β(τ,θ)

Syntax

qqsurf3d using filename [, options]

where filename is a long-format results dataset written by
qqr, mqqr or qqkrls (variables
tau theta and a value column such as coef or t).

Main
value(varname) surface to plot: coef (default), t, se, ...

variable(name) for mqqr files: which regressor's surface

band(name) select one band level when several are stacked

Colour / resolution
colormap(name) palette: jet (default), parula, viridis, plasma, hot, cool, redblue, redgreen, redwhitegreen

levels(#) number of colour bands (default 18)

fine(#) interpolation grid density (default 64; higher = smoother)

msize(size) tile marker size (default medlarge)

cbsize(size) colour-bar swatch size (default vlarge)

Viewpoint
azimuth(#) horizontal rotation in degrees (default 35)

elevation(#) vertical tilt in degrees (default 25)

zscale(#) height exaggeration of the z-axis (default 0.6)

Labels & elements
title(string) graph title

xtitle(string) θ-axis title (default {&theta})

ytitle(string) τ-axis title (default {&tau})

ztitle(string) z / colour-bar caption (default {&beta})

nowire omit the wireframe mesh

nocbar omit the side colour bar

Output
save(filename) export the graph (e.g. fig.png)

name(name) Stata graph name

scheme(name) graphics scheme

replace overwrite the exported file / graph

Description

qqsurf3d renders a quantile-on-quantile result as a filled,
MATLAB-surf-style three-dimensional surface — the look used for the
robustness figures in Sim & Zhou (2015) and Adebayo, Ozkan & Eweade (2024).
The height and colour of the surface both encode β(τ,θ): the estimated
effect of the predictor (at its θ-quantile) on the τ-quantile of the
response.

The command reads the long-format file produced by an estimation command,
builds a regular θ × τ grid, bilinearly interpolates it to a finer
fine()×fine() mesh, projects every tile with an oblique
(azimuth/elevation) projection, paints the tiles in painter's order
(far-to-near) using one colour bucket per levels() band, and overlays a
wireframe, a 3D bounding box with numbered τ/θ/β tick marks, and a vertical
colour bar. Everything is computed in a single Mata pass, so no extra
packages are required.

qqsurf3d is the 3D companion to the 2D qqheat contour
heatmap and the lightweight qqsurf pseudo-3D scatter. Use
qqheat for precise reading and significance stars; use qqsurf3d
when you want the publication-style surface.

Dependencies: none beyond base Stata. The surface, wireframe, bounding
box, axis ticks and colour bar are all built from base twoway
(scatter/pci) in a single in-line Mata pass; colormaps are
generated internally. No heatplot, colorpalette, palettes,
colrspace or other add-on is required.

Options

Main

value(varname) chooses which column of the results file to render.
coef (the slope β) is the default; t, se or p are
also useful surfaces.

variable(name) is for multivariate results from mqqr, which
stack one surface per regressor; name the regressor whose surface you want.

band(name) selects a single level when the file contains several
stacked bands.

Colour / resolution

colormap(name) sets the palette. Sequential maps (jet, parula,
viridis, plasma, hot, cool) suit one-signed surfaces; diverging maps
(redblue, redgreen, redwhitegreen) put a neutral colour at the middle of
the range and are best when β changes sign.

levels(#) is the number of discrete colour bands (default 18).
fine(#) controls how finely the surface is interpolated before
painting (default 64). Raising fine() closes the small white seams
between tiles and yields a smoother surface at the cost of a larger graph.

msize(size) and cbsize(size) size the surface tiles and the
colour-bar swatches. If you still see speckle gaps, raise fine()
first, then msize() (e.g. large).

Viewpoint

azimuth(#) rotates the surface horizontally and elevation(#)
tilts it vertically (both in degrees). zscale(#) exaggerates or
compresses the vertical (β) axis; lower it for a flatter, map-like view and
raise it to emphasise peaks.

Labels & elements

title(), xtitle(), ytitle(), ztitle() set the graph
title and the three axis captions (θ, τ, and the z/colour-bar quantity).

nowire removes the mesh lines and nocbar removes the colour bar
for a cleaner, minimal surface.

Reading the picture

o The floor axes are the two quantile grids: θ (predictor
quantile) and τ (response quantile), each running 0→1.

o Height and colour both show β(τ,θ). A rising surface
means the effect grows; a saddle or twist means the effect depends jointly on
where both variables sit in their distributions.

o The colour bar on the right is the value key; its labels
span the true data range of β (the surface is not symmetrised, so
heights are faithful).

o For formal statements about the surface (is it flat? symmetric?
zero?), pair the picture with qqtest.

Tuning the look

To approach the smooth MATLAB surf appearance:

. qqsurf3d using qq.dta, value(coef) colormap(jet) fine(80) msize(large) levels(20)

For a clean, minimal surface (no mesh, no bar) suited to slides:

. qqsurf3d using qq.dta, value(coef) nowire nocbar azim(40) ele(20)

Examples

Bivariate QQR surface

. qqr y x, tau(0.1(0.1)0.9) theta(0.1(0.1)0.9) saving(qq.dta) replace

. qqsurf3d using qq.dta, value(coef) colormap(jet) azim(35) ele(25) ///

. title("QQR 3D surface: {&beta}({&tau},{&theta})") save(qqr_surf3d.png) replace

QQ-KRLS marginal-effect surface

. qqkrls y x, tau(0.1(0.1)0.9) theta(0.1(0.1)0.9) saving(qk.dta) replace

. qqsurf3d using qk.dta, value(coef) colormap(viridis) fine(80) ///

. title("QQ-KRLS 3D surface") save(qk_surf3d.png) replace

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.

Adebayo, T.S., Ozkan, O. and Eweade, B.S. (2024). Do energy efficiency
R&D investments and ICT promote environmental sustainability in Sweden? A
QQKRLS investigation. Journal of Cleaner Production 440:140832.

Author

Merwan Roudane. merwanroudane920@gmail.com

See also

qqr, qqheat, qqsurf, qqkrls,
qqtable, qqr_package