# ElPrincGraph: Core function to construct a principal elestic graph In Albluca/ElPiGraph.R: Elastic principal graph construction

## Description

The core function that takes the n m-dimensional points and construct a principal elastic graph using the grammars provided.

## Usage

 ``` 1 2 3 4 5 6 7 8 9 10``` ```ElPrincGraph(X, NumNodes = 100, NumEdges = Inf, Lambda, Mu, ElasticMatrix, NodesPositions, AdjustVect, verbose = FALSE, n.cores = 1, ClusType = "Sock", MinParOP = 20, CompileReport = FALSE, ShowTimer = FALSE, ComputeMSEP = TRUE, FinalEnergy = "Base", alpha = 0, beta = 0, gamma = 0, Mode = 1, MaxNumberOfIterations = 10, MaxFailedOperations = Inf, MaxSteps = Inf, GrammarOptimization = FALSE, eps = 0.01, TrimmingRadius = Inf, GrowGrammars = list(), ShrinkGrammars = list(), GrammarOrder = c("Grow", "Shrink"), FastSolve = FALSE, AvoidSolitary = FALSE, EmbPointProb = 1, AdjustElasticMatrix = NULL, AdjustElasticMatrix.Initial = NULL, ...) ```

## Arguments

 `X` numerical 2D matrix, the n-by-m matrix with the position of n m-dimensional points `NumNodes` integer, the number of nodes of the principal graph `NumEdges` integer, the maximum nulber of edges `Lambda` real, the lambda parameter used the compute the elastic energy `Mu` real, the lambda parameter used the compute the elastic energy `ElasticMatrix` numerical 2D matrix, the k-by-k elastic matrix `NodesPositions` numerical 2D matrix, the k-by-m matrix with k m-dimensional positions of the nodes in the initial step `AdjustVect` boolean vector keeping track of the nodes for which the elasticity parameters have been adjusted. When true for a node its elasticity parameters will not be adjusted. `verbose` `n.cores` either an integer (indicating the number of cores to used for the creation of a cluster) or cluster structure returned, e.g., by makeCluster. If a cluster structure is used, all the nodes must contains X (this is done using clusterExport) `ClusType` string, the type of cluster to use. It can gbe either "Sock" or "Fork". Currently fork clustering only works in Linux `MinParOP` integer, the minimum number of operations to use parallel computation `CompileReport` boolean, should a step-by-step report with various information on the contruction of the principal graph be compiled? `ShowTimer` boolean, should the time to construct the graph be computed and reported for each step? `ComputeMSEP` boolean, should MSEP be computed when building the report? `FinalEnergy` string indicating the final elastic emergy associated with the configuration. Currently it can be "Base" or "Penalized" `alpha` positive numeric, the value of the alpha parameter of the penalized elastic energy `beta` positive numeric, the value of the beta parameter of the penalized elastic energy `gamma` `Mode` integer, the energy computation mode `MaxNumberOfIterations` integer, maximum number of steps to embed the nodes in the data `MaxFailedOperations` integer, the maximum allowed number of consecutive failed grammar operations, i.e. appplication of the single grammar operations, that did not produce any valid configuration `MaxSteps` integer, the maximum allowed number of steps of the algorithm. Each step is composed by the application of all the specified grammar operations `GrammarOptimization` boolean, should the grammar be used to optimize the graph? If true a number MaxSteps of operations will be applied. `eps` real, minimal relative change in the position of the nodes to stop embedment `TrimmingRadius` real, maximal distance of point from a node to affect its embedment `GrowGrammars` list of strings, the grammar to be used in the growth step `ShrinkGrammars` list of strings, the grammar to be used in the shrink step `GrammarOrder` vector of strings, the order of application of the grammars. Can be any combination of "Grow" and "Shrink" `FastSolve` boolean, should FastSolve be used when fitting the points to the data? `AvoidSolitary` boolean, should configurations with "solitary nodes", i.e., nodes without associted points be discarded? `EmbPointProb` numeric between 0 and 1. If less than 1 point will be sampled at each iteration. EmbPointProb indicates the probability of using each points. This is an *experimental* feature, which may helps speeding up the computation if a large number of points is present. `AdjustElasticMatrix` a penalization function to adjust the elastic matrices after a configuration has been chosen (e.g., AdjustByConstant). If NULL (the default), no penalization will be used. `AdjustElasticMatrix.Initial` a penalization function to adjust the elastic matrices of the initial configuration (e.g., AdjustByConstant). If NULL (the default), no penalization will be used.

## Value

a named list with a number of elements:

NodePositions

A numeric matrix containing the positions of the nodes

ElasticMatrix

The elastic matrix of the graph

ReportTable

The report table for the graph construction

FinalReport

The report table associated with the final graph configuration

Lambda

The lambda parameter used during the graph construction

Mu

The mu parameter used during the graph construction

FastSolve

was FastSolve being used?

## Examples

 ```1 2 3``` ```This is a low level function. See \code{\link{computeElasticPrincipalCircle}}, \code{\link{computeElasticPrincipalCurve}}, or \code{\link{computeElasticPrincipalTree}} for examples ```

Albluca/ElPiGraph.R documentation built on June 10, 2018, 5:22 p.m.