reldist: Inference for Relative Distributions

In reldist: Relative Distribution Methods

Inference for Relative Distributions

Description

Estimate and graph relative distribution and density functions for continuous or discrete data.

Usage

reldist(y, yo=FALSE, ywgt=FALSE,yowgt=FALSE,
  show="none", decomp="locadd",
  location="median", scale="IQR",
  rpmult=FALSE, 
  z=FALSE, zo=FALSE,
  smooth = 0.35, 
  quiet = TRUE, 
  cdfplot=FALSE,
  ci=FALSE,
  bar="no",
  add=FALSE,
  graph=TRUE, type="l",
  xlab="Reference proportion",ylab="Relative Density",yaxs="r",
  yolabs=pretty(yo), yolabslabs=NULL, 
  ylabs=pretty(y), ylabslabs=NULL,
  yolabsloc=0.6, ylabsloc=1, 
  ylim=NULL, cex=0.8, lty=1,
  binn=5000,
  aicc=seq(0.0001, 5, length=30),
  deciles=(0:10)/10,
  discrete=FALSE,
  method="Bayes",
  y0=NULL,
  control = list(samples = 4000, burnin = 1000),
  ...)

Arguments

y	Sample from comparison distribution.
yo	Sample from reference distribution.
discrete	Do y and yo refer to a discrete distribution? If TRUE a discrete estimator is used instead of the default continuous one.
smooth	Degree of smoothness required in the fit. Higher values lead to smoother curves, lower positive values lead to closer fits to the observed data. If it is not specified the value that minimizes GCV is used. If a value less than zero is specified then the value is chosen to minimize a corrected AIC. If discrete=TRUE it is the minimum number of values to pool in the reference distribution in the probability mass function estimate.
method	Method used to estimate the relative density. The default ("Bayes") uses a density estimator based on Poisson Nonparametric Regression and Bayesian inference developed by Wand and Wu (2022). The option ("bgk") uses a Gaussian kernel density estimator for bounded domain one-dimensional data developed by Botev, Grotowski and Kroese (2010). The option ("gam") uses a local likelihood approach based on smoothed Poisson regression. The option "loclik" uses log-splines. The option "quick" uses the Anscombe transformation to stabilize variances. In versions prior to 1.3 the "quick" approach was used.
graph	Graph the results on the current device.
bar	Graph the deciles on the current device. Possible values of bar are "no" (no deciles plotted), "yes" (deciles plotted with the non-parametric fit, "only"(deciles plotted without non-parametric fit).
add	Add the density to the current plot?
ylim	plotting limit for the vertical axis.
lty	Line type to be used for the density.
xlab	Horizontal label.
ylab	Vertical label.
ylabs	Locations for label to be added to the right axis.
ylabslabs	Labels indicating the original scale for the comparison distribution.
ylabsloc	Distance of labels to right of axis (in lines).
yolabs	locations for labels to be added to the tip axis.
yolabslabs	Labels indicating the original scale for the reference distribution.
yolabsloc	Distance of labels above axis (in lines).
yaxs	Style of vertical axis.
cdfplot	calculate and plot the CDF rather than the density.
quiet	Should the output be returned invisibly?
ci	Plot (pointwise) 95% confidence intervals?
ywgt	Weights on the comparison sample.
yowgt	Weights on the reference sample.
z	Covariate on the comparison sample to be used to adjust it to the reference distribution. Only used if the form of matching specified in decomp="covariate".
zo	Covariate on the reference sample to be used in the adjustment. to the reference distribution. Only used if the form of matching specified in decomp="covariate".
show	Type of relative distribution to produce. Possible values are "none" (comparisons to reference), residual (location-matched reference to reference), effect (comparison to location-matched reference).
decomp	Form of matching to the comparison sample. Possible values are locmult (multiplicatively scale the reference), locadd (additively shift the reference), lsadd (location/scale additive shift), covariate (covariate adjust the reference (requires z and zo to be specified)).
location	How to measure location. Possible values are "mean" and "median".
scale	How to measure the scale. Possible values are "standev" (standard deviation) and IQR (interquartile range).
rpmult	Only in calculation of polarization indices: multiplicatively scale the reference sample to the comparison sample before comparing the two distributions?
binn	Number of bins used in the smoother.
deciles	The percentiles used for the histogram bins. Typically deciles (i.e., 0.0, 0.1, 0.2,...,0.9, 1.0), but any set can be used (e.g., quintiles, terciles).
aicc	Values of the smoothing parameter to search over in minimizing the corrected AIC. Only used if method="gam" and smooth is less than 0.
type	Type of plot to use. See par().
cex	Character expansion to use in plots. See par().
y0	A test to see if yo was passed. If y0 is passed it prints a warning. If y0 is passed and yo is not passed then y0 is used as the sample from reference distribution.
control	list; A simple list of control options for the STAN HMC computation used when method="Bayes", the default. The two components are samples=4000, the number of samples drawn and burnin=1000, the burn-in used.
...	Additional arguments to the plot functions. See par().

Value

x	Horizontal coordinates for the density (typically percentages).
y	Density at x.
rp	95% confidence interval for the median relative polarization as lower bound, estimate, upper bound.
rpl	95% confidence interval for the lower relative polarization as lower bound, estimate, upper bound.
rpu	95% confidence interval for the upper relative polarization as lower bound, estimate, upper bound.
cdf	x coordinates for the CDF (typically percentages) and y CDF at x.

Note

Most of the code is for the plotting and tinkering. The guts of the method are forming the relative data at the top. The rest is a standard fixed interval density estimation with a few bells and whistles.

References

For more examples see the tech report

Mark S. Handcock and Eric Mark Aldrich Applying Relative Distribution Methods in R University of Washington CSSS Working Paper No. 27, Available at SSRN: doi: 10.2139/ssrn.1515775.

Z. I. Botev, J. F. Grotowski and D. P. Kroese Kernel Density Estimation Via Diffusion Annals of Statistics, 2010, Volume 38, Number 5, Pages 2916-2957.

M. Wand and J. C. F. Yu Density Estimation via Bayesian Inference Engines AStA Advances in Statistical Analysis, 2021, doi: 10.1007/s10182-021-00422-8.

Examples

#
# First load the data.
#

data(nls, package="reldist")

#
# A simple example comparing permanent wages of the original to the
# recent cohort in the NLS.  See H&M (1999) for details.

reldist(y=recent$chpermwage,yo=original$chpermwage,method="bgk")

#
# A more sophisticated version of the same.
#

reldist(y=recent$chpermwage, yo=original$chpermwage,
        yowgt=original$wgt, ywgt=recent$wgt,      
        bar=TRUE,                                   
        smooth=0.1, method="bgk",                             
        yolabs=seq(-1, 3, by=0.5),                 
        ylim=c(0, 3.0),cex=0.8,                   
        ylab="Relative Density",                 
        xlab="Proportion of the Original Cohort")

#
# A CDF version.
#

reldist(y=recent$chpermwage, yo=original$chpermwage,
    yowgt=original$wgt, ywgt=recent$wgt,      
    cdfplot=TRUE,                               
    smooth=0.4,                              
    yolabs=seq(-1,3,by=0.5),                 
    ylabs=seq(-1,3,by=0.5),                  
    cex=0.8,                                 
    method="bgk",                             
    ylab="proportion of the recent cohort",  
    xlab="proportion of the original cohort")

reldist documentation built on March 7, 2023, 8:34 p.m.