hyper.convert: Parameterisation conversion functions. In hyper.fit: Generic N-Dimensional Hyperplane Fitting with Heteroscedastic Covariant Errors and Intrinsic Scatter

Description

The hyper.convert function allows the user to generically convert their current plane definition system to an alternative. The obvious use case might be when the user has an equation defined as a projection formula along a preferred axis (e.g. z=ax+by+c) and they want to find the orthogonal offset of the hyperplane to the origin, and the intrinsic scatter orthogonal to the hyperplane.

To ease use, and minimise mistakes, hyper.convert creates an object of type hyper.plane.param which can then be converted using the class specific convert function. This has the advantage of knowing how the current projection is defined, and minmises the user inputs to simply the new projection desired.

Usage

 ```1 2 3 4 5 6 7 8``` ```hyper.convert(parm, coord, beta = 0, scat = 0, in.coord.type = "alpha", out.coord.type, in.scat.type = "vert.axis", out.scat.type, in.vert.axis, out.vert.axis) #To ease usability the package also included a hyper.plane.param class specific convert #function: ## S3 method for class 'hyper.plane.param' convert(x,coord.type='alpha',scat.type='vert.axis',vert.axis,...) ```

Arguments

 `x` Argument for the class dependent convert.hyper.plane.param function. An object of class hyper.plane.param, i.e. the output of the hyper.convert function. `coord.type` Argument for the class dependent convert.hyper.plane.param function. This specifies whether the output coord vector is defined in terms of the normal vector to the hyperplane (normvec) gradients defined to produce values along the vert.axis dimension (alpha) or by the values of the angles that form the gradients (theta). If missing it takes the value of in.coord.type. `scat.type` Argument for the class dependent convert.hyper.plane.param function. This specifies whether the output beta/scat should be defined as orthogonal to the plane (orth) or along the vert.axis of interest (vert.axis). If missing it takes the value of in.scat.type. `vert.axis` Argument for the class dependent convert.hyper.plane.param function. This specifies the output/requested vertical projection axis. If missing it takes the value of in.vert.axis. `parm` Vector of all parameters. This should be a concatenation of c(coord,beta,scat). Either 'parm' or 'coord' must be specified. `coord` The current coordinate parameters using the in.coord.type coordinate system. This should be a vector of length dimensions-1 (i.e. 1 for 2D xy data and 2 for 3D xyz data). The coord argument must be explictly specified by the user. `beta` The current offset of the hyperplane defined using the in.scat.type projection system. The default is 0. `scat` The current intrinsic scatter of the hyperplane defined using the in.scat.type projection system. The default is 0. `in.coord.type` This specifies whether the input coord vector is defined in terms of the normal vector to the hyperplane (normvec) gradients defined to produce values along the vert.axis dimension (alpha, default) or by the values of the angles that form the gradients (theta). `out.coord.type` This specifies whether the output coord vector is defined in terms of the normal vector to the hyperplane (normvec) gradients defined to produce values along the vert.axis dimension (alpha) or by the values of the angles that form the gradients (theta). If missing it takes the value of in.coord.type. `in.scat.type` This specifies whether the input scat is defined as orthogonal to the plane (orth) or along the vert.axis of interest (vert.axis). `out.scat.type` This specifies whether the output scat should be defined as orthogonal to the plane (orth) or along the vert.axis of interest (vert.axis). If missing it takes the value of in.scat.type. `in.vert.axis` This specifies the input vertical projection axis. If missing it uses the maximum dimension value (i.e. y-axis for a 2d dataset). `out.vert.axis` This specifies the output/requested vertical projection axis. If missing it takes the value of in.vert.axis. `...` Additional arguments to pass to convert.hyper.plane.param, namely coord.type, scat.type, vert.axis.

Value

hyper.convert returns a multi-component list of class hyper.plane.param containing:

 `parm` parm is a concatination of the parameters that fully decribe the hyperplane with intrinsic scatter. It can be used as a direct input to other hyper.fit functions that can accept a parm type input. `coord` The output coordinate parameters using the out.coord.type coordinate system. `beta` The output offset of the hyperplane defined using the out.scat.type projection system. Potentially standardised by the abs.beta.orth argument. `scat` The output intrinsic scatter of the hyperplane defined using the out.scat.type projection system. `unitvec` The unit vector orthogonal to the hyperplane. This is always the vector pointing from the origin *to* the hyperplane. `beta.orth` The absolute distance of the hyperplane to the origin. By definition this will always be positive. `scat.orth` The intrinsic scatter orthogonal to the hyperplane. By definition this will always be positive. `coord.type` The requested out.coord.type. `scat.type` The requested out.scat.type. `vert.axis` The requested out.vert.axis (if out.vert.axis is not specified, this will be the maximum dimension value, see in.vert.axis in arguments section above).

Author(s)

Aaron Robotham and Danail Obreschkow

References

Robotham, A.S.G., & Obreschkow, D., PASA, in press

`hyper.basic`, `hyper.convert`, `hyper.data`, `hyper.fit`, `hyper.plot`, `hyper.sigcor`, `hyper.summary`
 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29``` ```#Here we are assuming our plane forula is z=2x+3y+1 plus Gaussian intrinsic scatter along #z with sd=4: excoord.alpha=c(2,3) exbeta.vert.axis=1 exscat.vert.axis=4 print(hyper.convert(coord=excoord.alpha, beta=exbeta.vert.axis, scat=exscat.vert.axis, out.coord.type='theta', out.scat.type='orth')) print(hyper.convert(coord=excoord.alpha, beta=exbeta.vert.axis, scat=exscat.vert.axis, out.vert.axis=2)) #To simplify conversions and reduce mistakes you can use the class dependent method: temp=hyper.convert(coord=excoord.alpha, beta=exbeta.vert.axis, scat=exscat.vert.axis) print(convert(temp, coord.type='normvec')\$parm) print(convert(temp, coord.type='theta')\$parm) print(convert(temp, coord.type='theta', vert.axis=2)\$parm) print(convert(temp, coord.type='theta', scat.type='orth')\$parm) #We can check the conversions by print(temp\$parm) print(convert(convert(convert(convert(temp, 'normvec'), 'theta', 'vert.axis',1), 'alpha', 'orth', 2))\$parm) #The conversions back and forth won't return *exactly* the same values: print(all(convert(convert(convert(convert(temp, 'normvec'), 'theta', 'vert.axis', 1),'alpha', 'orth', 2))\$parm==temp\$parm)) #But they will be very close for the most part: print(all(round(convert(convert(convert(convert(temp, 'normvec'), 'theta', 'vert.axis', 1), 'alpha', 'orth', 2))\$parm)==temp\$parm)) ```