Package Numero. November 24, 2018

Transcription

1 Package Numero November 24, 2018 Type Package Title Statistical Framework to Define Subgroups in Complex Datasets Version Date Author Song Gao [aut], Stefan Mutter [aut], Aaron E. Casey [aut], Ville-Petteri Makinen [aut, cre] Maintainer Ville-Petteri Makinen High-dimensional sets that do not exhibit a clear intrinsic clustered structure pose a challenge to conventional clustering algorithms. For this reason, we developed an unsupervised framework that helps scientists to better subgroup their sets based on visual cues, please see Gao S, Mutter S, Casey A, Makinen V-P (2018) Numero: a statistical framework to define multivariable subgroups in complex population-based sets, Int J Epidemiology, dyy113, <doi: /ije/dyy113>. The framework includes the necessary functions to construct a self-organizing map of the, to evaluate the statistical significance of the observed patterns, and to visualize the results. License GPL (>= 2) Imports Rcpp (>= ) LinkingTo Rcpp VignetteBuilder knitr Suggests knitr, rmarkdown, BiocStyle NeedsCompilation yes Repository CRAN SystemRequirements C++11 Encoding UTF-8 Date/Publication :20:09 UTC 1

2 2 nroaggregate R topics documented: nroaggregate nrocolorize nrokmeans nrokohonen nrolabel nromatch nropermute nroplot nropreprocess nrosummary nrotrain Index 11 nroaggregate Regional averages on a self-organizing map Estimate district averages based on assigned map locations for each point. nroaggregate(topology, districts, = NULL) topology districts A frame with K rows and six columns that contains the district positions of a self-organizing map, please see nrokohonen for details. A vector of M best-matching districts for each row in the matrix, please see nromatch for a typical scenario. A vector of M elements or an M x N matrix of values. A frame of K rows and N columns that contains the average district values after smoothing. The frame has also the attribute histogram that contains a K x 1 vector of estimated sample counts after smoothing.

3 nrocolorize 3 nrocolorize Assign colors based on value Assign colors to map districts based on the respective district values. nrocolorize(values, amplitudes = 1, palette = "rhodo" ) values amplitudes palette A vector of K values or a K x N matrix, where K is the number of map districts and N is the number of variables. Single value or a vector of N elements to specify available proportion of color range for each variable. One of pre-defined colormap names (see details) or a sorted vector of hexadecimal color codes as strings, see rgb() for additional details. The argument amplitudes controls the part of the color range that is available for the district value range. For proportions below 1, the minimum district value is assigned to a color that is between the first and middle element in the color palette, and the maximum is assigned to a color that is between the middle and the last element. If amplitude is greater than 1, the extreme low and high values are clipped to the first and last color in the palette, respectively. Palette can also contain the name of a colormap: gray, fire, jungle, miami, rhodo or tan. Any other word will revert to a rainbow colormap. A frame with K rows and N columns that contains color definitions as character strings.

4 4 nrokohonen nrokmeans K-means clustering K-means clustering for multi-dimensional. nrokmeans(, k = 3, subsample = NULL, balance = 0) k subsample balance Numerical frame or matrix with M rows and N columns. Number of centroids. Number of randomly selected rows used during a single training cycle. If 0, the algorithm is applied with no balancing, if 1 all the clusters will be forced to be of equal size. The K centroids are determined by Lloyd s algorithm with Euclidean distances. If subsample is less than the number of rows, a random subset of rows is used for each training cycle. A list of three named elements: centroids is a k x N matrix of the main results and layout contains the M best-matching centroid labels for each sample from the original set. Finally, history is the chronological record of training errors. nrokohonen Self-organizing map Interpolates the initial district profiles of a self-organizing map based on pre-determined seed profiles. The function is named after Teuvo Kohonen, the inventor of the self-organizing map. nrokohonen(seeds, radius = 3)

5 nrolabel 5 seeds radius A matrix of K rows and N columns. Map radius. A list containing two named elements: centroids contains the N-dimensional district profiles, and topology is an H x 6 matrix that contains the 2D spatial layout for the map districts: the first two columns (X, Y) indicate the positions of districts in Cartesian coordinates, the other four columns (RADIUS1, RADIUS2, ANGLE1, ANGLE2) define the perimeter of the district areas for visualisation on a circular map. See Also Please see nrokmeans as a means to create the seed profiles. nrolabel Label pruning Optimize the selection of labels on map districts. nrolabel(topology, values, gap = 2.3) topology values gap A matrix with six columns that contain the geometric properties of map districts, please see nrokohonen for details. A vector of K elements or an K x N matrix of smoothed district values, where K is the number of map districts and N is the number of variables, please see nroaggregate for details. Minimum distance between map districts with non-empty labels. The function assigns non-empty labels for districts based on the absolute deviations from the average district value. The most extreme districts are picked first, and then the remaining districts are prioritized based on their value and distance to the other districts already labeled.

6 6 nromatch A frame with K rows and N columns that contains labels for all the districts. nromatch Best-matching districts Compare the multivariate samples from a set against the district profiles of a self-organizing map (SOM). nromatch(som, ) som Either a matrix or a list with an element centroids that contains the matrix of reference profiles, such as outputs from nrokmeans and nrotrain. A matrix with identical column names to the centroid matrix. The matching error between a sample and a reference profile is defined as the Euclidean distance in N-dimensional space, where N is the number of variables. A vector of integers with elements corresponding to the rows in. Each element contains the index of the best matching centroid from som. The vector also has the attribute quality that contains three columns: RESIDUAL is the Euclidean distance in space (shorter is better), QUALITY is a scale-independent measure of the matching quality if training history is available (higher is better, 1 means equal quality to the training set), and COVERAGE shows the proportion of elements that were available for matching. Finally, the names of the columns that were used for matching are stored in the attribute features.

7 nropermute 7 nropermute Permutation analysis Estimate the dynamic range (and statistical significance) for regional patterns on a self-organizing maps using permutations. nropermute(som, districts,, n = 10000) som districts n A list that must contain the element topology, see nrokohonen for details. A numeric vector of M best matching districts, typically the output from /codenromatch. A numeric vector of M values or an M x N matrix, where M is the number of points and N is the number of variables. Maximum number of permutations. A frame with eight columns. For example, P.z is a parametric estimate for statistical significance, P.freq is the frequency-based estimate for statistical signicance, and Z is the estimated z-score of how far the observed map plane is from the average randomly generated layout. N. indicates how many values were used and N.cycles tells the number of completed permutations. AMPLITUDE is the dynamic range for colors that can be used in nrocolorize. nroplot Plot a self-organizing map Create a graphical interface for selecting subgroups from multiple map colorings simultaneusly. nroplot(elements, colors, labels = NULL, values = NULL, subplot = NULL, interactive = FALSE, file = NULL)

8 8 nropreprocess elements colors labels values subplot interactive file A frame with K rows and six columns that contains the district positions of a self-organizing map (i.e. the topology), please see nrokohonen for details. May also contain additional columns for visualization of subgroup information. A character vector with K elements or a K x N matrix of hexadecimal color codes as strings. A character vector with K elements or a K x N matrix of district labels. A vector with K elements or a K x N matrix of district values. A two-element vector that sets out the number of rows and columns for a grid layout of multiple colorings. If TRUE, an interactive version of the plot is launched. If non-empty, the figure is saved as a Scalable Vector Graphics file. Some non-alphanumeric characters are not supported and will be automatically converted to _. Too long labels or column names will be truncated. A frame with K rows that contains the topology and subgrouping information. See Also Please see nrocolorize for converting values into color codes, and nrolabel for optimizing which labels to show on the map. nropreprocess Data cleaning and standardization Convert to numerical values, remove unusable rows and columns, and standardize scale of each variable. nropreprocess(, training = NULL, strata = NULL, key = NULL)

9 nrosummary 9 training strata key A matrix or a frame. A character vector that contains the headings of feature columns that are intended for model training and point matching. The heading of the column that defines batches; each batch will be processed separately. The heading of the column that contains row identifiers. A list with three members is returned: original contains a subset of the original set were unusable rows were removed, values contains those columns that could be converted to numbers, and features contains the standardized training columns. nrosummary Estimate subgroup statistics Combine subgrouping information for districts with the points that reside in the districts, and estimate statistics for each subgroup and variable. nrosummary(, districts, regions, categlim = 8) districts regions categlim A vector of M elements or an M x N matrix of values. A vector of M best-matching districts for each row in the matrix, please see nromatch for a typical usage case. An vector of K elements that defines if a district belongs to a larger region (i.e. a subgroup). The threshold for the number of unique values before a variable is considered continuous. The region vector must have K elements where K is the total number of map districts. Accordingly, the value at element [i] indicates the region for the district [i].

10 10 nrotrain A frame of summary statistics that contains a row for every combination of subgroups and variables. nrotrain Train Self-Organizing Map Iterative algorithm to adapt a self-organizing map (SOM) to a set of multivariable. nrotrain(som,, subsample = NULL) som subsample A list of two elements: centroids and topology, see nrokohonen for additional details. A matrix with the same column names as the centroids. Number of rows used during a single training cycle. A copy of som, where the centroids list element is updated according to the patterns. In addition, the quantization errors during training is stored in the element history. See Also nrokohonen for details on the SOM

11 Index nroaggregate, 2, 5 nrocolorize, 3, 7, 8 nrokmeans, 4, 5, 6 nrokohonen, 2, 4, 5, 7, 8, 10 nrolabel, 5, 8 nromatch, 2, 6, 7, 9 nropermute, 7 nroplot, 7 nropreprocess, 8 nrosummary, 9 nrotrain, 6, 10 11