kernelDensity ============================================== Purpose ---------------- To compute kernel density estimate and plot. Format ---------------- .. function:: out = kernelDensity(dataset [, kernel, bw, c0]) out = kernelDensity(dataset, formula [, kernel, bw, c0]) :param dataset: Name of datafile, dataframe, or data matrix. :type dataset: String or matrix :param formula: Optional argument, formula string for loading variables from datafile. Default is to load all variables. :type dataset: String :param kernel: Optional argument, type of kernel. Default = 1. =========== ============== 1 Normal. 2 Epanechnikov. 3 Biweight. 4 Triangular 5 Rectangular. 6 Truncated normal. 7 Parzen. 8 Cosine. 9 Triweight. 10 Tricube. 11 Logistic. 12 Sigmoid. 13 Silverman. =========== ============== If kernel is scalar, the kernel is the same for all parameters. Default = Normal density. :type kernel: Scalar :param bw: Optional argument, smoothing coefficient (bandwidth). Should be ExE compatible with the dataset. If `bw` is scalar, the smoothing coefficient will be the same for every data observation. If `bw` is zero, optimal smoothing coefficient will be computed. If `bw`` is a matrix, the smoothing coefficient will be different for each observation. Default = 0. :type bw: Scalar, Vector, or Matrix :param c0: Instance of :class:`kernelDensityControl` structure containing the following members: .. list-table:: :widths: auto * - c0.varNames - String array, variable name(s). Default is dataframe headers if included, `"X1"`, `"X2"`, ... otherwise. * - c0.NumPoints - Scalar, number of points to be computed for plots. * - c0.EndPoints - Kx2 matrix, lower (in first column) and upper (in second column) endpoints of density. Default is minimum and maximum, respectively, of the parameter values. If 1x2 matrix, endpoints will be the same for all parameters. * - c0.Truncate - Kx2 matrix, lower (in first column) and upper (in second column) truncation limits for truncated normal kernel. If 1x2 matrix, truncations limits will be the same for all plots. Default is minimum and maximum, respectively. * - c0.plotFunctionPtr - Scalar, a pointer to a user-defined function used to specify format modifications to the default plot format. * - c0.plotOff - Scalar, an indicator to turn plotting off. Set to 1 to turn off plotting. Default = 0. :type c0: Structure :return out: Instance of :class:`KernelDensityResults` structure .. csv-table:: :widths: auto "out.px", "Matrix, abscissae." "out.py", "Matrix, ordinates." "out.sm", "Kx1, or Nxk, or Nx1 smoothing coefficients." :rtype out: Structure Examples ---------------- Basic usage with dataframe +++++++++++++++++++++++++++++++ :: /* ** Example One: ** Basic usage */ // Load data fname = getGAUSSHome("examples/winevolatileacidity.csv"); data = loadd(fname); // Call kernelDensity function // with default normal density struct kernelDensityResults krslt1; krslt1 = kernelDensity(data[., "volatile acidity"]); .. figure:: _static/images/kerneldensity1.jpg :scale: 50 % Basic usage with filename +++++++++++++++++++++++++++++++ :: /* ** Example Two: ** Basic usage with filename */ // Load data fname = getGAUSSHome("examples/winevolatileacidity.csv"); // Call kernelDensity function // with default normal density call kernelDensity(fname, "volatile acidity"); Basic usage with multiple kernels ++++++++++++++++++++++++++++++++++ :: /* ** Example Three: ** Multiple kernels ** on same plot */ struct kernelDensityResults krslt2; krslt2 = kernelDensity(data[., "volatile acidity"], 1|2|3); .. figure:: _static/images/kerneldensity3.jpg :scale: 50 % Basic usage with multiple series +++++++++++++++++++++++++++++++++ :: /* ** Example Four: ** Multiple series on different plots */ struct kernelDensityResults krslt3; krslt3 = kernelDensity(data, 1); .. figure:: _static/images/kerneldensity4a.jpg :scale: 50 % .. figure:: _static/images/kerneldensity4b.jpg :scale: 50 % Modifying plot with custom plotControl setting function ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ :: /* ** Example Five: ** Modifying plot */ struct kernelDensityControl kctl; kctl = kernelDensityControlCreate(); // The ampersand (&) in front of the function // name makes it a pointer to the function kctl.plotFunctionPtr = &myPlotCustomizations; // Basic example of kernel density plot customization proc (1) = myPlotCustomizations(struct plotControl myPlot); // Set size for graph canvas plotCanvasSize("px", 800|600); // Turn on and style major grid lines plotSetGridPen(&myPlot, "major", 1, "dimgray", 2); //Return modified plotControl structure retp(myPlot); endp; // Set kernel to normal kernel = 1; // Automatically compute bandwidth bw = 0; // Call kernelDensity with // control structure struct kernelDensityResults krslt4; krslt4 = kernelDensity(data[., "volatile acidity"], kernel, bw, kctl); .. figure:: _static/images/kerneldensity5.jpg :scale: 50 % Remarks ------------- #. The x axis label will be set to the name of the column of the dataframe passed to :func:`kerneldensity`. Use :func:`setcolnames` to modify the name of the variable