Package 'supraHex'

Description

Human embryo dataset contains gene expression levels (5441 genes and 18 embryo samples) from Fang et al. (2010).

Usage

data(Fang)

Value

• Fang: a gene expression matrix of 5441 genes x 18 samples, involving six successive stages, each with three replicates.

• Fang.sampleinfo: a matrix containing the information of the 18 samples for the expression matrix Fang. The three columns correspond to the sample information: "Name", "Stage" and "Replicate".

• Fang.geneinfo: a matrix containing the information of the 5441 genes for the expression matrix Fang. The three columns correspond to the gene information: "AffyID", "EntrezGene" and "Symbol".

References

Fang et al. (2010). Transcriptome analysis of early organogenesis in human embryos. Developmental Cell, 19(1):174-84.

Description

Leukemia dataset (learning set) contains gene expression levels (3051 genes and 38 patient samples) from Golub et al. (1999). This dataset has been pre-processed: capping into floor of 100 and ceiling of 16000; filtering by exclusion of genes with $max/min<=5$ or $max-min<=500$, where max and min refer respectively to the maximum and minimum intensities for a particular gene across mRNA samples; 2-base logarithmic transformation.

Usage

data(Golub)

Value

• Golub: a gene expression matrix of 3051 genes x 38 samples. These samples include 11 acute myeloid leukemia (AML) and 27 acute lymphoblastic leukemia (ALL) which can be further subtyped into 19 B-cell ALL and 8 T-cell ALL.

References

Golub et al. (1999). Molecular classification of cancer: class discovery and class prediction by gene expression monitoring, Science, Vol. 286:531-537.

Description

sBMH is supposed to identify the best-matching hexagons/rectangles (BMH) for the input data.

Usage

sBMH(sMap, data, which_bmh = c("best", "worst", "all"))

Arguments

Value

a list with following components:

• bmh: the requested BMH matrix of dlen x length(which_bmh), where dlen is the total number of rows of the input data

• qerr: the corresponding matrix of quantization errors (i.e., the distance between the input data and their BMH), with the same dimensions as "bmh" above

• mqe: the mean quantization error for the "best" BMH

• call: the call that produced this result

Note

"which_bmh" upon request can be a vector consisting of any integer values from [1, nHex]

See Also

sPipeline

Examples

# 1) generate an iid normal random matrix of 100x10 
data <- matrix( rnorm(100*10,mean=0,sd=1), nrow=100, ncol=10)

# 2) from this input matrix, determine nHex=5*sqrt(nrow(data))=50, 
# but it returns nHex=61, via "sHexGrid(nHex=50)", to make sure a supra-hexagonal grid
sTopol <- sTopology(data=data, lattice="hexa", shape="suprahex")

# 3) initialise the codebook matrix using "uniform" method
sI <- sInitial(data=data, sTopol=sTopol, init="uniform")

# 4) define trainology at "rough" stage
sT_rough <- sTrainology(sMap=sI, data=data, stage="rough")

# 5) training at "rough" stage
sM_rough <- sTrainBatch(sMap=sI, data=data, sTrain=sT_rough)

# 6) define trainology at "finetune" stage
sT_finetune <- sTrainology(sMap=sI, data=data, stage="finetune")

# 7) training at "finetune" stage
sM_finetune <- sTrainBatch(sMap=sM_rough, data=data, sTrain=sT_rough)

# 8) find the best-matching hexagons/rectangles for the input data
response <- sBMH(sMap=sM_finetune, data=data, which_bmh="best")

Description

sCompReorder is supposed to reorder component planes for the input map/data. It returns an object of class "sReorder". It is realized by using a new map grid (with sheet shape consisting of a rectangular lattice) to train component plane vectors (either column-wise vectors of codebook/data matrix or the covariance matrix thereof). As a result, similar component planes are placed closer to each other. It is highly recommend to use trained map (i.e. codebook matrix) as input if data matrix is hugely big to save computational costs.

Usage

sCompReorder(
sMap,
xdim = NULL,
ydim = NULL,
amplifier = NULL,
metric = c("none", "pearson", "spearman", "kendall", "euclidean",
"manhattan", "cos",
"mi"),
init = c("linear", "uniform", "sample"),
seed = 825,
algorithm = c("sequential", "batch"),
alphaType = c("invert", "linear", "power"),
neighKernel = c("gaussian", "bubble", "cutgaussian", "ep", "gamma"),
finetuneSustain = TRUE
)

Arguments

Value

an object of class "sReorder", a list with following components:

• nHex: the total number of rectanges in the grid

• xdim: x-dimension of the grid

• ydim: y-dimension of the grid

• uOrder: the unique order/placement for each component plane that is reordered to the "sheet"-shape grid with rectangular lattice

• coord: a matrix of nHex x 2, with each row corresponding to the coordinates of each "uOrder" rectangle in the 2D map grid

• call: the call that produced this result

Note

All component planes are uniquely placed within a "sheet"-shape rectangle grid:

• Each component plane mapped to the "sheet"-shape grid with rectangular lattice is determinied iteratively in an order from the best matched to the next compromised one.

• If multiple compoments are hit in the same rectangular lattice, the worse one is always sacrificed by moving to the next best one till all components are placed somewhere exclusively on their own.

The size of "sheet"-shape rectangle grid depends on the input arguments:

• How the input parameters are used to determine nHex is taken priority in the following order: "xdim & ydim" > "nHex" > "data".

• If both of xdim and ydim are given, $nHex=xdim*ydim$.

• If only data is input, $nHex=5*sqrt(dlen)$, where dlen is the number of rows of the input data.

• After nHex is determined, xy-dimensions of rectangle grid are then determined according to the square root of the two biggest eigenvalues of the input data.

See Also

sTopology, sPipeline, sBMH, sDistance, visCompReorder

Examples

# 1) generate an iid normal random matrix of 100x10 
data <- matrix( rnorm(100*10,mean=0,sd=1), nrow=100, ncol=10)
colnames(data) <- paste(rep('S',10), seq(1:10), sep="")

# 2) get trained using by default setup
sMap <- sPipeline(data=data)

# 3) reorder component planes in different ways
# 3a) directly using column-wise vectors of codebook matrix
sReorder <- sCompReorder(sMap=sMap, amplifier=2, metric="none")
# 3b) according to covariance matrix of pearson correlation of codebook matrix
sReorder <- sCompReorder(sMap=sMap, amplifier=2, metric="pearson")
# 3c) according to covariance matrix of pearson correlation of input matrix
sReorder <- sCompReorder(sMap=data, amplifier=2, metric="pearson")

Description

sDistance is supposed to compute and return the distance matrix between the rows of a data matrix using a specified distance metric

Usage

sDistance(
data,
metric = c("pearson", "spearman", "kendall", "euclidean", "manhattan",
"cos", "mi",
"binary")
)

Arguments

Value

• dist: a symmetric distance matrix of nRow x nRow, where nRow is the number of rows of input data matrix

Note

The distance metrics are supported:

• "pearson": Pearson correlation. Note that two curves that have identical shape, but different magnitude will still have a correlation of 1

• "spearman": Spearman rank correlation. As a nonparametric version of the pearson correlation, it calculates the correlation between the ranks of the data values in the two vectors (more robust against outliers)

• "kendall": Kendall tau rank correlation. Compared to spearman rank correlation, it goes a step further by using only the relative ordering to calculate the correlation. For all pairs of data points $(x_i, y_i)$ and $(x_j, y_j)$, it calls a pair of points either as concordant ($Nc$ in total) if $(x_i - x_j)*(y_i - y_j)>0$, or as discordant ($Nd$ in total) if $(x_i - x_j)*(y_i - y_j)<0$. Finally, it calculates gamma coefficient $(Nc-Nd)/(Nc+Nd)$ as a measure of association which is highly resistant to tied data

• "euclidean": Euclidean distance. Unlike the correlation-based distance measures, it takes the magnitude into account (input data should be suitably normalized

• "manhattan": Cityblock distance. The distance between two vectors is the sum of absolute value of their differences along any coordinate dimension

• "cos": Cosine similarity. As an uncentered version of pearson correlation, it is a measure of similarity between two vectors of an inner product space, i.e., measuring the cosine of the angle between them (using a dot product and magnitude)

• "mi": Mutual information (MI). $MI$ provides a general measure of dependencies between variables, in particular, positive, negative and nonlinear correlations. The caclulation of $MI$ is implemented via applying adaptive partitioning method for deriving equal-probability bins (i.e., each bin contains approximately the same number of data points). The number of bins is heuristically determined (the lower bound): $1+log2(n)$, where n is the length of the vector. Because $MI$ increases with entropy, we normalize it to allow comparison of different pairwise clone similarities: $2*MI/[H(x)+H(y)]$, where $H(x)$ and $H(y)$ stand for the entropy for the vector $x$ and $y$, respectively

• "binary": asymmetric binary (Jaccard distance index). the proportion of bits in which the only one divided by the at least one

See Also

sDmatCluster

Examples

# 1) generate an iid normal random matrix of 100x10 
data <- matrix( rnorm(100*10,mean=0,sd=1), nrow=100, ncol=10)

# 2) calculate distance matrix using different metric
sMap <- sPipeline(data=data)
# 2a) using "pearson" metric
dist <- sDistance(data=data, metric="pearson")
# 2b) using "cos" metric
# dist <- sDistance(data=data, metric="cos")
# 2c) using "spearman" metric
# dist <- sDistance(data=data, metric="spearman")
# 2d) using "kendall" metric
# dist <- sDistance(data=data, metric="kendall")
# 2e) using "euclidean" metric
# dist <- sDistance(data=data, metric="euclidean")
# 2f) using "manhattan" metric
# dist <- sDistance(data=data, metric="manhattan")
# 2g) using "mi" metric
# dist <- sDistance(data=data, metric="mi")
# 2h) using "binary" metric
# dist <- sDistance(data=data, metric="binary")

Description

sDmat is supposed to calculate distance (measured in high-dimensional input space) to neighbors (defined by based on 2D output space) for each of hexagons/rectangles

Usage

sDmat(sMap, which_neigh = 1, distMeasure = c("median", "mean", "min",
"max"))

Arguments

Value

• dMat: a vector with the length of nHex. It stores the distance a hexaon/rectangle is away from its output-space-defined neighbors in high-dimensional input space

Note

"which_neigh" is defined in output 2D space, but "distMeasure" is defined in high-dimensional input space

See Also

sNeighAny

Examples

# 1) generate an iid normal random matrix of 100x10 
data <- matrix( rnorm(100*10,mean=0,sd=1), nrow=100, ncol=10)

# 2) get trained using by default setup
sMap <- sPipeline(data=data)

# 3) calculate "median" distances in INPUT space to different neighbors in 2D OUTPUT space
# 3a) using direct neighbors in 2D OUTPUT space
dMat <- sDmat(sMap=sMap, which_neigh=1, distMeasure="median")
# 3b) using no more than 2-topological neighbors in 2D OUTPUT space
# dMat <- sDmat(sMap=sMap, which_neigh=2, distMeasure="median")

Description

sDmatCluster is supposed to obtain clusters from a grid map. It returns an object of class "sBase".

Usage

sDmatCluster(
sMap,
which_neigh = 1,
distMeasure = c("mean", "median", "min", "max"),
constraint = TRUE,
clusterLinkage = c("average", "complete", "single", "bmh"),
reindexSeed = c("hclust", "svd", "none")
)

Arguments

Value

an object of class "sBase", a list with following components:

• seeds: the vector to store cluster seeds, i.e., a list of local minima (in 2D output space) of distance matrix (in input space). They are represented by the indexes of hexagons/rectangles

• bases: the vector with the length of nHex to store the cluster memberships/bases, where nHex is the total number of hexagons/rectanges in the grid

• ig: an igraph object storing neighbor relations between bases, with node attributes 'name' (base), 'index', 'xcoord' and 'ycoord' (based on seeds)

• hclust: a hclust object storing tree-like relations between bases (based on seed model vectors)

• call: the call that produced this result

Note

The first item in the return "seeds" is the first cluster, whose memberships are those in the return "bases" that equals 1. The same relationship is held for the second item, and so on

See Also

sPipeline, sDmatMinima, sBMH, sNeighDirect, sDistance, visDmatCluster

Examples

# 1) generate an iid normal random matrix of 100x10 
data <- matrix( rnorm(100*10,mean=0,sd=1), nrow=100, ncol=10)

# 2) get trained using by default setup
sMap <- sPipeline(data=data)

# 3) partition the grid map into clusters based on different criteria
# 3a) based on "bmh" criterion
# sBase <- sDmatCluster(sMap=sMap, which_neigh=1, distMeasure="median", clusterLinkage="bmh")
# 3b) using region-growing algorithm with linkage "average"
sBase <- sDmatCluster(sMap=sMap, which_neigh=1, distMeasure="median",
clusterLinkage="average")

# 4) visualise clusters/bases partitioned from the sMap
visDmatCluster(sMap,sBase)

Description

sDmatMinima is supposed to identify local minima of distance matrix (resulting from sDmat). The criterion of being local minima is that the distance associated with a hexagon/rectangle is always smaller than its direct neighbors (i.e., 1-neighborhood)

Usage

sDmatMinima(
sMap,
which_neigh = 1,
distMeasure = c("median", "mean", "min", "max"),
constraint = TRUE
)

Arguments

Value

• minima: a vector to store a list of local minima (represented by the indexes of hexogans/rectangles

Note

Do not get confused by "which_neigh" and the criteria of being local minima. Both of them deal with 2D output space. However, "which_neigh" is used to assist in the calculation of distance matrix (so can be 1-neighborhood or more); instead, the criterion of being local minima is only 1-neighborhood in the strictest sense

See Also

sDmat, sNeighAny

Examples

# 1) generate an iid normal random matrix of 100x10 
data <- matrix( rnorm(100*10,mean=0,sd=1), nrow=100, ncol=10)

# 2) get trained using by default setup
sMap <- sPipeline(data=data)

# 3) identify local minima of distance matrix based on "median" distances and direct neighbors
minima <- sDmatMinima(sMap=sMap, which_neigh=1, distMeasure="median")

Description

sHexDist is supposed to calculate euclidian distances between each pair of hexagons/rectangles in a 2D grid of input "sTopol" or "sMap" object. It returns a symmetric matrix containing pairwise distances.

Usage

sHexDist(sObj)

Arguments

Value

• dist: a symmetric matrix of nHex x nHex, containing pairwise distances, where nHex is the total number of hexagons/rectanges in the grid

Note

The return matrix has rows/columns ordered in the same order as the "coord" matrix of the input object does.

See Also

sTopology, sInitial

Examples

# 1) generate an iid normal random matrix of 100x10 
data <- matrix( rnorm(100*10,mean=0,sd=1), nrow=100, ncol=10)

# 2) from this input matrix, determine nHex=5*sqrt(nrow(data))=50, 
# but it returns nHex=61, via "sHexGrid(nHex=50)", to make sure a supra-hexagonal grid
sTopol <- sTopology(data=data, lattice="hexa", shape="suprahex")

# 3) initialise the codebook matrix using "uniform" method
sI <- sInitial(data=data, sTopol=sTopol, init="uniform")

# 4) calculate distances between hexagons/rectangles in a 2D grid based on different objects
# 4a) based on an object of class "sTopol"
dist <- sHexDist(sObj=sTopol)
# 4b) based on an object of class "sMap"
dist <- sHexDist(sObj=sI)

Description

sHexGrid is supposed to define a supra-hexagonal map grid. A supra-hexagon is a giant hexagon, which seamlessly consists of smaller hexagons. Due to the symmetric nature, it can be uniquely determined by specifying the radius away from the grid centroid. This function takes input the grid radius (or the number of hexagons in the grid, but will be adjusted to meet the definition of supra-hexagon), and returns a list (see 'Value' below) containing: the grid radius, the total number of hexagons in the grid, the 2D coordinates of the grid centroid, the step for each hexogan away from the grid centroid, and the 2D coordinates of all hexagons in the grid.

Usage

sHexGrid(r = NULL, nHex = NULL)

Arguments

Value

an object of class "sHex", a list with following components:

• r: the grid radius

• nHex: the total number of hexagons in the grid. It may differ from the input value; actually it is always no less than the input one to ensure a supra-hexagonal grid exactly formed

• centroid: the 2D coordinates of the grid centroid

• stepCentroid: a vector with the length of nHex. It stores how many steps a hexagon is awawy from the grid centroid ('1' for the centroid itself). Starting with the centroid, it orders outward. Also, for those hexagons of the same step, it orders from the rightmost in an anti-clock wise

• angleCentroid: a vector with the length of nHex. It stores the angle a hexagon is in terms of the grid centroid ('0' for the centroid itself). For those hexagons of the same step, it orders from the rightmost in an anti-clock wise

• coord: a matrix of nHex x 2 with each row specifying the 2D coordinates of a hexagon in the grid. The order of rows is the same as 'centroid' above

• call: the call that produced this result

Note

The relationships among return values:

• $nHex = 1+6*r*(r-1)/2$

• $centroid = coord[1,]$

• $stepCentroid[1] = 1$

• $stepCentroid[2:nHex] = unlist(sapply(2:r, function(x) (c( (1+6*x*(x-1)/2-6*(x-1)+1) : (1+6*x*(x-1)/2) )>=1)*x ))$

See Also

sPipeline

Examples

# The supra-hexagonal grid is exactly determined by specifying the radius.
sHex <- sHexGrid(r=2)

# The grid is determined according to the number of input hexagons (after being adjusted).
# The return res$nHex is always no less than the input one.
# It ensures a supra-hexagonal grid is exactly formed.
sHex <- sHexGrid(nHex=12)

# Ignore input nHex if r is also given
sHex <- sHexGrid(r=3, nHex=100)

# By default, r=3 if no parameters are specified
sHex <- sHexGrid()

Description

sHexGridVariant is supposed to define a variant of a supra-hexagonal map grid. In essence, it is the subset of the supra-hexagon.

Usage

sHexGridVariant(
r = NULL,
nHex = NULL,
shape = c("suprahex", "triangle", "diamond", "hourglass", "trefoil",
"ladder",
"butterfly", "ring", "bridge")
)

Arguments

Value

an object of class "sHex", a list with following components:

• r: the grid radius

• nHex: the total number of hexagons in the grid. It may differ from the input value; actually it is always no less than the input one to ensure a supra-hexagonal grid exactly formed

• centroid: the 2D coordinates of the grid centroid

• stepCentroid: a vector with the length of nHex. It stores how many steps a hexagon is awawy from the grid centroid ('1' for the centroid itself). Starting with the centroid, it orders outward. Also, for those hexagons of the same step, it orders from the rightmost in an anti-clock wise

• angleCentroid: a vector with the length of nHex. It stores the angle a hexagon is in terms of the grid centroid ('0' for the centroid itself). For those hexagons of the same step, it orders from the rightmost in an anti-clock wise

• coord: a matrix of nHex x 2 with each row specifying the 2D coordinates of a hexagon in the grid. The order of rows is the same as 'centroid' above

• call: the call that produced this result

Note

none

See Also

sHexGrid

Examples

# For "supraHex" shape itself
sHex <- sHexGridVariant(r=6, shape="suprahex")

## Not run: 
library(ggplot2)

#geom_polygon(color="black", fill=NA)

# For "supraHex" shape itself
sHex <- sHexGridVariant(r=6, shape="suprahex")
df_polygon <- sHexPolygon(sHex)
df_coord <- data.frame(sHex$coord, index=1:nrow(sHex$coord))
gp_suprahex <- ggplot(data=df_polygon, aes(x,y,group=index)) +
geom_polygon(aes(fill=factor(stepCentroid%%2))) +
coord_fixed(ratio=1) + theme_void() + theme(legend.position="none") +
geom_text(data=df_coord, aes(x,y,label=index), color="white", size=3) +
labs(title="suprahex (r=6; xdim=ydim=11)") +
theme(plot.title=element_text(hjust=0.5,size=8))

# For "triangle" shape
sHex <- sHexGridVariant(r=6, shape="triangle")
df_polygon <- sHexPolygon(sHex)
df_coord <- data.frame(sHex$coord, index=1:nrow(sHex$coord))
gp_triangle <- ggplot(data=df_polygon, aes(x,y,group=index)) +
geom_polygon(aes(fill=factor(stepCentroid%%2))) +
coord_fixed(ratio=1) + theme_void() + theme(legend.position="none") +
geom_text(data=df_coord, aes(x,y,label=index), color="white", size=3) +
labs(title="triangle (r=6; xdim=ydim=6)") +
theme(plot.title=element_text(hjust=0.5,size=8))

# For "diamond" shape
sHex <- sHexGridVariant(r=6, shape="diamond")
df_polygon <- sHexPolygon(sHex)
df_coord <- data.frame(sHex$coord, index=1:nrow(sHex$coord))
gp_diamond <- ggplot(data=df_polygon, aes(x,y,group=index)) +
geom_polygon(aes(fill=factor(stepCentroid%%2))) +
coord_fixed(ratio=1) + theme_void() + theme(legend.position="none") +
geom_text(data=df_coord, aes(x,y,label=index), color="white", size=3) +
labs(title="diamond (r=6; xdim=6, ydim=11)") +
theme(plot.title=element_text(hjust=0.5,size=8))

# For "hourglass" shape
sHex <- sHexGridVariant(r=6, shape="hourglass")
df_polygon <- sHexPolygon(sHex)
df_coord <- data.frame(sHex$coord, index=1:nrow(sHex$coord))
gp_hourglass <- ggplot(data=df_polygon, aes(x,y,group=index)) +
geom_polygon(aes(fill=factor(stepCentroid%%2))) +
coord_fixed(ratio=1) + theme_void() + theme(legend.position="none") +
geom_text(data=df_coord, aes(x,y,label=index), color="white", size=3) +
labs(title="hourglass (r=6; xdim=6, ydim=11)") +
theme(plot.title=element_text(hjust=0.5,size=8))

# For "trefoil" shape
sHex <- sHexGridVariant(r=6, shape="trefoil")
df_polygon <- sHexPolygon(sHex)
df_coord <- data.frame(sHex$coord, index=1:nrow(sHex$coord))
gp_trefoil <- ggplot(data=df_polygon, aes(x,y,group=index)) +
geom_polygon(aes(fill=factor(stepCentroid%%2))) +
coord_fixed(ratio=1) + theme_void() + theme(legend.position="none") +
geom_text(data=df_coord, aes(x,y,label=index), color="white", size=3) +
labs(title="trefoil (r=6; xdim=ydim=11)") +
theme(plot.title=element_text(hjust=0.5,size=8))

# For "ladder" shape
sHex <- sHexGridVariant(r=6, shape="ladder")
df_polygon <- sHexPolygon(sHex)
df_coord <- data.frame(sHex$coord, index=1:nrow(sHex$coord))
gp_ladder <- ggplot(data=df_polygon, aes(x,y,group=index)) +
geom_polygon(aes(fill=factor(stepCentroid%%2))) +
coord_fixed(ratio=1) + theme_void() + theme(legend.position="none") +
geom_text(data=df_coord, aes(x,y,label=index), color="white", size=3) +
labs(title="ladder (r=6; xdim=11, ydim=6)") +
theme(plot.title=element_text(hjust=0.5,size=8))

# For "butterfly" shape
sHex <- sHexGridVariant(r=6, shape="butterfly")
df_polygon <- sHexPolygon(sHex)
df_coord <- data.frame(sHex$coord, index=1:nrow(sHex$coord))
gp_butterfly <- ggplot(data=df_polygon, aes(x,y,group=index)) +
geom_polygon(aes(fill=factor(stepCentroid%%2))) +
coord_fixed(ratio=1) + theme_void() + theme(legend.position="none") +
geom_text(data=df_coord, aes(x,y,label=index), color="white", size=3) +
labs(title="butterfly (r=6; xdim=ydim=11)") +
theme(plot.title=element_text(hjust=0.5,size=8))

# For "ring" shape
sHex <- sHexGridVariant(r=6, shape="ring")
df_polygon <- sHexPolygon(sHex)
df_coord <- data.frame(sHex$coord, index=1:nrow(sHex$coord))
gp_ring <- ggplot(data=df_polygon, aes(x,y,group=index)) +
geom_polygon(aes(fill=factor(stepCentroid%%2))) +
coord_fixed(ratio=1) + theme_void() + theme(legend.position="none") +
geom_text(data=df_coord, aes(x,y,label=index), color="white", size=3) +
labs(title="ring (r=6; xdim=ydim=11)") +
theme(plot.title=element_text(hjust=0.5,size=8))

# For "bridge" shape
sHex <- sHexGridVariant(r=6, shape="bridge")
df_polygon <- sHexPolygon(sHex)
df_coord <- data.frame(sHex$coord, index=1:nrow(sHex$coord))
gp_bridge <- ggplot(data=df_polygon, aes(x,y,group=index)) +
geom_polygon(aes(fill=factor(stepCentroid%%2))) +
coord_fixed(ratio=1) + theme_void() + theme(legend.position="none") +
geom_text(data=df_coord, aes(x,y,label=index), color="white", size=3) +
labs(title="bridge (r=6; xdim=11, ydim=6)") +
theme(plot.title=element_text(hjust=0.5,size=8))

# combined visuals
library(gridExtra)
grid.arrange(grobs=list(gp_suprahex, gp_ring, gp_diamond, gp_trefoil,
gp_butterfly, gp_hourglass, gp_ladder, gp_bridge, gp_triangle),
layout_matrix=rbind(c(1,1,2,2,3),c(1,1,2,2,3),c(4,4,5,5,6),c(4,4,5,5,6),c(7,7,8,8,9)),
nrow=5, ncol=5)

## End(Not run)

Description

sHexPolygon is supposed to extract polygon location per hexagon within a supra-hexagonal grid

Usage

sHexPolygon(sObj, area.size = 1)

Arguments

Value

a tibble of 7 columns ('index','x','y','node','edge','stepCentroid','angleCentroid') storing polygon location per hexagon. 'node' for nodes (including n1,n2,n3,n4,n5,n6), and 'edge' for a list-column where each is a tibble with a single column 'edge' containing two rows (such as edges 'e12' and 'e16' for the node 'n1').

Note

None

See Also

sHexGridVariant, sPipeline

Examples

sObj <- sTopology(xdim=4, ydim=4, lattice="hexa", shape="suprahex")
df_polygon <- sHexPolygon(sObj, area.size=1)

Description

sInitial is supposed to initialise an object of class "sInit" given a topology and input data. As a matter of fact, it initialises the codebook matrix (in input high-dimensional space). The return object inherits the topology information (i.e., a "sTopol" object from sTopology), along with initialised codebook matrix and method used.

Usage

sInitial(data, sTopol, init = c("linear", "uniform", "sample"), seed =
825)

Arguments

Value

an object of class "sInit", a list with following components:

• nHex: the total number of hexagons/rectanges in the grid

• xdim: x-dimension of the grid

• ydim: y-dimension of the grid

• r: the hypothetical radius of the grid

• lattice: the grid lattice

• shape: the grid shape

• coord: a matrix of nHex x 2, with each row corresponding to the coordinates of a hexagon/rectangle in the 2D map grid

• init: an initialisation method

• codebook: a codebook matrix of nHex x ncol(data), with each row corresponding to a prototype vector in input high-dimensional space

• call: the call that produced this result

Note

The initialisation methods include:

• "uniform": the codebook matrix is uniformly initialised via randomly taking any values within the interval [min, max] of each column of input data

• "sample": the codebook matrix is initialised via randomly sampling/selecting input data

• "linear": the codebook matrix is linearly initialised along the first two greatest eigenvectors of input data

See Also

sTopology

Examples

# 1) generate an iid normal random matrix of 100x10 
data <- matrix( rnorm(100*10,mean=0,sd=1), nrow=100, ncol=10)

# 2) from this input matrix, determine nHex=5*sqrt(nrow(data))=50, 
# but it returns nHex=61, via "sHexGrid(nHex=50)", to make sure a supra-hexagonal grid
sTopol <- sTopology(data=data, lattice="hexa", shape="suprahex")

# 3) initialise the codebook matrix using different mehtods
# 3a) using "uniform" method
sI_uniform <- sInitial(data=data, sTopol=sTopol, init="uniform")
# 3b) using "sample" method
# sI_sample <- sInitial(data=data, sTopol=sTopol, init="sample") 
# 3c) using "linear" method
# sI_linear <- sInitial(data=data, sTopol=sTopol, init="linear")

Description

sMapOverlay is supposed to overlay additional data onto the trained map for viewing the distribution of that additional data. It returns an object of class "sMap". It is realised by first estimating the hit histogram weighted by the neighborhood kernel, and then calculating the distribution of the additional data over the map (similarly weighted by the neighborhood kernel). The final overlaid distribution of additional data is normalised by the hit histogram.

Usage

sMapOverlay(sMap, data = NULL, additional)

Arguments

Value

an object of class "sMap", a list with following components:

• nHex: the total number of hexagons/rectanges in the grid

• xdim: x-dimension of the grid

• ydim: y-dimension of the grid

• r: the hypothetical radius of the grid

• lattice: the grid lattice

• shape: the grid shape

• coord: a matrix of nHex x 2, with rows corresponding to the coordinates of all hexagons/rectangles in the 2D map grid

• ig: the igraph object

• polygon: a tibble of 7 columns ('x','y','index','node','edge','stepCentroid','angleCentroid') storing polygon location per hexagon

• init: an initialisation method

• neighKernel: the training neighborhood kernel

• codebook: a codebook matrix of nHex x ncol(additional), with rows corresponding to overlaid vectors

• hits: a vector of nHex, each element meaning that a hexagon/rectangle contains the number of input data vectors being hit wherein

• mqe: the mean quantization error for the "best" BMH

• data: an input data matrix

• response: a tibble of 3 columns ('did' for rownames of input data matrix, 'index', and 'qerr' (quantization error; the distance to the "best" BMH))

• call: the call that produced this result

Note

Weighting by neighbor kernel is to avoid rigid overlaying by only focusing on the best-matching map nodes as there may exist several closest best-matching nodes for an input data vector.

See Also

sPipeline, sBMH, sHexDist, visHexMulComp

Examples

# 1) generate an iid normal random matrix of 100x10 
data <- matrix( rnorm(100*10,mean=0,sd=1), nrow=100, ncol=10)
colnames(data) <- paste(rep('S',10), seq(1:10), sep="")

# 2) get trained using by default setup
sMap <- sPipeline(data=data)

# 3) overlay additional data onto the trained map
# here using the first two columns of the input "data" as "additional"
# codebook in "sOverlay" is the same as the first two columns of codebook in "sMap"
sOverlay <- sMapOverlay(sMap=sMap, data=data, additional=data[,1:2])

# 4) viewing the distribution of that additional data
visHexMulComp(sOverlay)

Description

sNeighAny is supposed to calculate any neighbors for each hexagon/rectangle in a regular 2D grid. It returns a matrix with rows for the self, and columns for its any neighbors.

Usage

sNeighAny(sObj)

Arguments

Value

• aNeigh: a matrix of nHex x nHex, containing distance info in terms of any neighbors, where nHex is the total number of hexagons/rectanges in the grid

Note

The return matrix has rows for the self, and columns for its neighbors. The non-zeros mean the distance away from its neighbors, and the zeros for the self-self. It has rows/columns ordered in the same order as the "coord" matrix of the input object does.

See Also

sNeighDirect

Examples

# 1) generate an iid normal random matrix of 100x10 
data <- matrix( rnorm(100*10,mean=0,sd=1), nrow=100, ncol=10)

# 2) from this input matrix, determine nHex=5*sqrt(nrow(data))=50, 
# but it returns nHex=61, via "sHexGrid(nHex=50)", to make sure a supra-hexagonal grid
sTopol <- sTopology(data=data, lattice="hexa", shape="suprahex")

# 3) initialise the codebook matrix using "uniform" method
sI <- sInitial(data=data, sTopol=sTopol, init="uniform")

# 4) calculate any neighbors based on different objects
# 4a) based on an object of class "sTopol"
aNeigh <- sNeighAny(sObj=sTopol)
# 4b) based on an object of class "sMap"
# aNeigh <- sNeighAny(sObj=sI)

Description

sNeighDirect is supposed to calculate direct neighbors for each hexagon/rectangle in a regular 2D grid. It returns a matrix with rows for the self, and columns for its direct neighbors.

Usage

sNeighDirect(sObj)

Arguments

Value

• dNeigh: a matrix of nHex x nHex, containing presence/absence info in terms of direct neighbors, where nHex is the total number of hexagons/rectanges in the grid

Note

The return matrix has rows for the self, and columns for its direct neighbors. The "1" means the presence of direct neighbors, "0" for the absence. It has rows/columns ordered in the same order as the "coord" matrix of the input object does.

See Also

sHexDist

Examples

# 1) generate an iid normal random matrix of 100x10 
data <- matrix( rnorm(100*10,mean=0,sd=1), nrow=100, ncol=10)

# 2) from this input matrix, determine nHex=5*sqrt(nrow(data))=50, 
# but it returns nHex=61, via "sHexGrid(nHex=50)", to make sure a supra-hexagonal grid
sTopol <- sTopology(data=data, lattice="hexa", shape="suprahex")

# 3) initialise the codebook matrix using "uniform" method
sI <- sInitial(data=data, sTopol=sTopol, init="uniform")

# 4) calculate direct neighbors based on different objects
# 4a) based on an object of class "sTopol"
dNeigh <- sNeighDirect(sObj=sTopol)
# 4b) based on an object of class "sMap"
# dNeigh <- sNeighDirect(sObj=sI)

Description

sPipeline is supposed to finish ab inito training for the input data. It returns an object of class "sMap".

Usage

sPipeline(
data,
xdim = NULL,
ydim = NULL,
nHex = NULL,
lattice = c("hexa", "rect"),
shape = c("suprahex", "sheet", "triangle", "diamond", "hourglass",
"trefoil",
"ladder", "butterfly", "ring", "bridge"),
scaling = 5,
init = c("linear", "uniform", "sample"),
seed = 825,
algorithm = c("batch", "sequential"),
alphaType = c("invert", "linear", "power"),
neighKernel = c("gaussian", "bubble", "cutgaussian", "ep", "gamma"),
finetuneSustain = FALSE,
verbose = TRUE
)

Arguments

Value

an object of class "sMap", a list with following components:

• nHex: the total number of hexagons/rectanges in the grid

• xdim: x-dimension of the grid

• ydim: y-dimension of the grid

• r: the hypothetical radius of the grid

• lattice: the grid lattice

• shape: the grid shape

• coord: a matrix of nHex x 2, with rows corresponding to the coordinates of all hexagons/rectangles in the 2D map grid

• ig: the igraph object

• polygon: a tibble of 7 columns ('x','y','index','node','edge','stepCentroid','angleCentroid') storing polygon location per hexagon

• init: an initialisation method

• neighKernel: the training neighborhood kernel

• codebook: a codebook matrix of nHex x ncol(data), with rows corresponding to prototype vectors in input high-dimensional space

• hits: a vector of nHex, each element meaning that a hexagon/rectangle contains the number of input data vectors being hit wherein

• mqe: the mean quantization error for the "best" BMH

• data: an input data matrix (with rownames and colnames added if NULL)

• response: a tibble of 3 columns ('did' for rownames of input data matrix, 'index', and 'qerr' (quantization error; the distance to the "best" BMH))

• call: the call that produced this result

Note

The pipeline sequentially consists of:

• i) sTopology used to define the topology of a grid (with "suprahex" shape by default ) according to the input data;

• ii) sInitial used to initialise the codebook matrix given the pre-defined topology and the input data (by default using "uniform" initialisation method);

• iii) sTrainology and sTrainSeq or sTrainBatch used to get the grid map trained at both "rough" and "finetune" stages. If instructed, sustain the "finetune" training until the mean quantization error does get worse;

• iv) sBMH used to identify the best-matching hexagons/rectangles (BMH) for the input data, and these response data are appended to the resulting object of "sMap" class.

References

Hai Fang and Julian Gough. (2014) supraHex: an R/Bioconductor package for tabular omics data analysis using a supra-hexagonal map. Biochemical and Biophysical Research Communications, 443(1), 285-289.

See Also

sTopology, sInitial, sTrainology, sTrainSeq, sTrainBatch, sBMH, visHexMulComp

Examples

# 1) generate an iid normal random matrix of 100x10 
data <- matrix( rnorm(100*10,mean=0,sd=1), nrow=100, ncol=10)
colnames(data) <- paste(rep('S',10), seq(1:10), sep="")

## Not run: 
# 2) get trained using by default setup but with different neighborhood kernels
# 2a) with "gaussian" kernel
sMap <- sPipeline(data=data, neighKernel="gaussian")
# 2b) with "bubble" kernel
# sMap <- sPipeline(data=data, neighKernel="bubble")
# 2c) with "cutgaussian" kernel
# sMap <- sPipeline(data=data, neighKernel="cutgaussian")
# 2d) with "ep" kernel
# sMap <- sPipeline(data=data, neighKernel="ep")
# 2e) with "gamma" kernel
# sMap <- sPipeline(data=data, neighKernel="gamma")

# 3) visualise multiple component planes of a supra-hexagonal grid
visHexMulComp(sMap, colormap="jet", ncolors=20, zlim=c(-1,1),
gp=grid::gpar(cex=0.8))

# 4) get trained using by default setup but using the shape "butterfly"
sMap <- sPipeline(data=data, shape="trefoil",
algorithm=c("batch","sequential")[2])
visHexMulComp(sMap, colormap="jet", ncolors=20, zlim=c(-1,1),
gp=grid::gpar(cex=0.8))


library(ggraph)
ggraph(sMap$ig, layout=sMap$coord) + geom_edge_link() +
geom_node_circle(aes(r=0.4),fill='white') + coord_fixed(ratio=1) +
geom_node_text(aes(label=name), size=2)

## End(Not run)

Description

sTopology is supposed to define the topology of a 2D map grid. The topological shape can be either a supra-hexagonal grid or a hexagonal/rectangle sheet. It returns an object of "sTopol" class, containing: the total number of hexagons/rectangles in the grid, the grid xy-dimensions, the grid lattice, the grid shape, and the 2D coordinates of all hexagons/rectangles in the grid. The 2D coordinates can be directly used to measure distances between any pair of lattice hexagons/rectangles.

Usage

sTopology(
data = NULL,
xdim = NULL,
ydim = NULL,
nHex = NULL,
lattice = c("hexa", "rect"),
shape = c("suprahex", "sheet", "triangle", "diamond", "hourglass",
"trefoil",
"ladder", "butterfly", "ring", "bridge"),
scaling = 5
)

Arguments

Value

an object of class "sTopol", a list with following components:

• nHex: the total number of hexagons/rectanges in the grid. It is not always the same as the input nHex (if any); see "Note" below for the explaination

• xdim: x-dimension of the grid

• ydim: y-dimension of the grid

• r: the hypothetical radius of the grid

• lattice: the grid lattice

• shape: the grid shape

• coord: a matrix of nHex x 2, with each row corresponding to the coordinates of a hexagon/rectangle in the 2D map grid

• ig: the igraph object

• call: the call that produced this result

Note

The output of nHex depends on the input arguments and grid shape:

• How the input parameters are used to determine nHex is taken priority in the following order: "xdim & ydim" > "nHex" > "data"

• If both of xdim and ydim are given, $nHex=xdim*ydim$ for the "sheet" shape, $r=(min(xdim,ydim)+1)/2$ for the "suprahex" shape

• If only data is input, $nHex=scaling*sqrt(dlen)$, where dlen is the number of rows of the input data, and scaling can be 5 (big map), 3 (median map) and 1 (normal map)

• With nHex in hand, it depends on the grid shape:

  • For "sheet" shape, xy-dimensions of sheet grid is determined according to the square root of the two biggest eigenvalues of the input data

  • For "suprahex" shape, see sHexGrid for calculating the grid radius r. The xdim (and ydim) is related to r via $xdim=2*r-1$

See Also

sHexGrid, visHexMapping

Examples

# For "suprahex" shape
sTopol <- sTopology(xdim=3, ydim=3, lattice="hexa", shape="suprahex")

# Error: "The suprahex shape grid only allows for hexagonal lattice" 
# sTopol <- sTopology(xdim=3, ydim=3, lattice="rect", shape="suprahex")

# For "sheet" shape with hexagonal lattice
sTopol <- sTopology(xdim=3, ydim=3, lattice="hexa", shape="sheet")

# For "sheet" shape with rectangle lattice
sTopol <- sTopology(xdim=3, ydim=3, lattice="rect", shape="sheet")

# By default, nHex=19 (i.e., r=3; xdim=ydim=5) for "suprahex" shape
sTopol <- sTopology(shape="suprahex")

# By default, xdim=ydim=5 (i.e., nHex=25) for "sheet" shape
sTopol <- sTopology(shape="sheet")

# Determine the topolopy of a supra-hexagonal grid based on input data
# 1) generate an iid normal random matrix of 100x10 
data <- matrix(rnorm(100*10,mean=0,sd=1), nrow=100, ncol=10)
# 2) from this input matrix, determine nHex=5*sqrt(nrow(data))=50, 
# but it returns nHex=61, via "sHexGrid(nHex=50)", to make sure a supra-hexagonal grid
sTopol <- sTopology(data=data, lattice="hexa", shape="suprahex")
# sTopol <- sTopology(data=data, lattice="hexa", shape="trefoil")

# do visualisation
visHexMapping(sTopol,mappingType="indexes")

## Not run: 
library(ggplot2)
# another way to do visualisation
df_polygon <- sHexPolygon(sTopol)
df_coord <- data.frame(sTopol$coord, index=1:nrow(sTopol$coord))
gp <- ggplot(data=df_polygon, aes(x,y,group=index)) +
geom_polygon(aes(fill=factor(stepCentroid%%2))) +
coord_fixed(ratio=1) + theme_void() + theme(legend.position="none") +
geom_text(data=df_coord, aes(x,y,label=index), color="white")

library(ggraph)
ggraph(sTopol$ig, layout=sTopol$coord) + geom_edge_link() +
geom_node_circle(aes(r=0.4),fill='white') + coord_fixed(ratio=1) +
geom_node_text(aes(label=name), size=2)

## End(Not run)

Description

sTrainBatch is supposed to perform batch training algorithm. It requires three inputs: a "sMap" or "sInit" object, input data, and a "sTrain" object specifying training environment. The training is implemented iteratively, but instead of choosing a single input vector, the whole input matrix is used. In each training cycle, the whole input matrix first land in the map through identifying the corresponding winner hexagon/rectangle (BMH), and then the codebook matrix is updated via updating formula (see "Note" below for details). It returns an object of class "sMap".

Usage

sTrainBatch(sMap, data, sTrain, verbose = TRUE)

Arguments

Value

an object of class "sMap", a list with following components:

• nHex: the total number of hexagons/rectanges in the grid

• xdim: x-dimension of the grid

• ydim: y-dimension of the grid

• r: the hypothetical radius of the grid

• lattice: the grid lattice

• shape: the grid shape

• coord: a matrix of nHex x 2, with each row corresponding to the coordinates of a hexagon/rectangle in the 2D map grid

• ig: the igraph object

• init: an initialisation method

• neighKernel: the training neighborhood kernel

• codebook: a codebook matrix of nHex x ncol(data), with each row corresponding to a prototype vector in input high-dimensional space

• call: the call that produced this result

Note

Updating formula is: $m_i(t+1) = \frac{\sum_{j=1}^{dlen}h_{wi}(t)x_j}{\sum_{j=1}^{dlen}h_{wi}(t)}$, where

• $t$ denotes the training time/step

• $x_j$ is an input vector $j$ from the input data matrix (with $dlen$ rows in total)

• $i$ and $w$ stand for the hexagon/rectangle $i$ and the winner BMH $w$, respectively

• $m_i(t+1)$ is the prototype vector of the hexagon $i$ at time $t+1$

• $h_{wi}(t)$ is the neighborhood kernel, a non-increasing function of i) the distance $d_{wi}$ between the hexagon/rectangle $i$ and the winner BMH $w$, and ii) the radius $\delta_t$ at time $t$. There are five kernels available:

  • For "gaussian" kernel, $h_{wi}(t)=e^{-d_{wi}^2/(2*\delta_t^2)}$

  • For "cutguassian" kernel, $h_{wi}(t)=e^{-d_{wi}^2/(2*\delta_t^2)}*(d_{wi} \le \delta_t)$

  • For "bubble" kernel, $h_{wi}(t)=(d_{wi} \le \delta_t)$

  • For "ep" kernel, $h_{wi}(t)=(1-d_{wi}^2/\delta_t^2)*(d_{wi} \le \delta_t)$

  • For "gamma" kernel, $h_{wi}(t)=1/\Gamma(d_{wi}^2/(4*\delta_t^2)+2)$

See Also

sTrainology, visKernels

Examples

# 1) generate an iid normal random matrix of 100x10 
data <- matrix( rnorm(100*10,mean=0,sd=1), nrow=100, ncol=10)

# 2) from this input matrix, determine nHex=5*sqrt(nrow(data))=50, 
# but it returns nHex=61, via "sHexGrid(nHex=50)", to make sure a supra-hexagonal grid
sTopol <- sTopology(data=data, lattice="hexa", shape="suprahex")

# 3) initialise the codebook matrix using "uniform" method
sI <- sInitial(data=data, sTopol=sTopol, init="uniform")

# 4) define trainology at "rough" stage
sT_rough <- sTrainology(sMap=sI, data=data, stage="rough")

# 5) training at "rough" stage
sM_rough <- sTrainBatch(sMap=sI, data=data, sTrain=sT_rough)

# 6) define trainology at "finetune" stage
sT_finetune <- sTrainology(sMap=sI, data=data, stage="finetune")

# 7) training at "finetune" stage
sM_finetune <- sTrainBatch(sMap=sM_rough, data=data, sTrain=sT_rough)

Description

sTrainology is supposed to define the train-ology (i.e., the training environment/parameters). The trainology here refers to the training algorithm, the training stage, the stage-specific parameters (alpha type, initial alpha, initial radius, final radius and train length), and the training neighbor kernel used. It returns an object of class "sTrain".

Usage

sTrainology(
sMap,
data,
algorithm = c("batch", "sequential"),
stage = c("rough", "finetune", "complete"),
alphaType = c("invert", "linear", "power"),
neighKernel = c("gaussian", "bubble", "cutgaussian", "ep", "gamma")
)

Arguments

Value

an object of class "sTrain", a list with following components:

• algorithm: the training algorithm

• stage: the training stage

• alphaType: the alpha type

• alphaInitial: the initial alpha

• radiusInitial: the initial radius

• radiusFinal: the final radius

• neighKernel: the neighbor kernel

• call: the call that produced this result

Note

Training stage-specific parameters:

• "radiusInitial": it depends on the grid shape and training stage

  • For "sheet" shape: it equals $max(1,ceiling(max(xdim,ydim)/8))$ at "rough" or "complete" stage, and $max(1,ceiling(max(xdim,ydim)/32))$ at "finetune" stage

  • For "suprahex" shape: it equals $max(1,ceiling(r/2))$ at "rough" or "complete" stage, and $max(1,ceiling(r/8))$ at "finetune" stage

• "radiusFinal": it depends on the training stage

  • At "rough" stage, it equals $radiusInitial/4$

  • At "finetune" or "complete" stage, it equals $1$

• "trainLength": how many times the whole input data are set for training. It depends on the training stage and training algorithm

  • At "rough" stage, it equals $max(1,10 * trainDepth)$

  • At "finetune" stage, it equals $max(1,40 * trainDepth)$

  • At "complete" stage, it equals $max(1,50 * trainDepth)$

  • When using "batch" algorithm and the trainLength equals 1 according to the above equation, the trainLength is forced to be 2 unless $radiusInitial$ equals $radiusFinal$

  • Where $trainDepth$ is the training depth, defined as $nHex/dlen$, i.e., how many hexagons/rectanges are used per the input data length (here $dlen$ refers to the number of rows)

See Also

sInitial

Examples

# 1) generate an iid normal random matrix of 100x10 
data <- matrix( rnorm(100*10,mean=0,sd=1), nrow=100, ncol=10)

# 2) from this input matrix, determine nHex=5*sqrt(nrow(data))=50, 
# but it returns nHex=61, via "sHexGrid(nHex=50)", to make sure a supra-hexagonal grid
sTopol <- sTopology(data=data, lattice="hexa", shape="suprahex")

# 3) initialise the codebook matrix using "uniform" method
sI <- sInitial(data=data, sTopol=sTopol, init="uniform")

# 4) define trainology at different stages
# 4a) define trainology at "rough" stage
sT_rough <- sTrainology(sMap=sI, data=data, stage="rough")
# 4b) define trainology at "finetune" stage
sT_finetune <- sTrainology(sMap=sI, data=data, stage="finetune")
# 4c) define trainology using "complete" stage
sT_complete <- sTrainology(sMap=sI, data=data, stage="complete")

Description

sTrainSeq is supposed to perform sequential training algorithm. It requires three inputs: a "sMap" or "sInit" object, input data, and a "sTrain" object specifying training environment. The training is implemented iteratively, each training cycle consisting of: i) randomly choose one input vector; ii) determine the winner hexagon/rectangle (BMH) according to minimum distance of codebook matrix to the input vector; ii) update the codebook matrix of the BMH and its neighbors via updating formula (see "Note" below for details). It also returns an object of class "sMap".

Usage

sTrainSeq(sMap, data, sTrain, seed = 825, verbose = TRUE)

Arguments

Value

an object of class "sMap", a list with following components:

• nHex: the total number of hexagons/rectanges in the grid

• xdim: x-dimension of the grid

• ydim: y-dimension of the grid

• r: the hypothetical radius of the grid

• lattice: the grid lattice

• shape: the grid shape

• coord: a matrix of nHex x 2, with each row corresponding to the coordinates of a hexagon/rectangle in the 2D map grid

• ig: the igraph object

• init: an initialisation method

• neighKernel: the training neighborhood kernel

• codebook: a codebook matrix of nHex x ncol(data), with each row corresponding to a prototype vector in input high-dimensional space

• call: the call that produced this result

Note

Updating formula is: $m_i(t+1) = m_i(t) + \alpha(t)*h_{wi}(t)*[x(t)-m_i(t)]$, where

• $t$ denotes the training time/step

• $i$ and $w$ stand for the hexagon/rectangle $i$ and the winner BMH $w$, respectively

• $x(t)$ is an input vector randomly choosen (from the input data) at time $t$

• $m_i(t)$ and $m_i(t+1)$ are respectively the prototype vectors of the hexagon $i$ at time $t$ and $t+1$

• $\alpha(t)$ is the learning rate at time $t$. There are three types of learning rate functions:

  • For "linear" function, $\alpha(t)=\alpha_0*(1-t/T)$

  • For "power" function, $\alpha(t)=\alpha_0*(0.005/\alpha_0)^{t/T}$

  • For "invert" function, $\alpha(t)=\alpha_0/(1+100*t/T)$

  • Where $\alpha_0$ is the initial learing rate (typically, $\alpha_0=0.5$ at "rough" stage, $\alpha_0=0.05$ at "finetune" stage), $T$ is the length of training time/step (often being set to input data length, i.e., the total number of rows)

• $h_{wi}(t)$ is the neighborhood kernel, a non-increasing function of i) the distance $d_{wi}$ between the hexagon/rectangle $i$ and the winner BMH $w$, and ii) the radius $\delta_t$ at time $t$. There are five kernels available:

  • For "gaussian" kernel, $h_{wi}(t)=e^{-d_{wi}^2/(2*\delta_t^2)}$

  • For "cutguassian" kernel, $h_{wi}(t)=e^{-d_{wi}^2/(2*\delta_t^2)}*(d_{wi} \le \delta_t)$

  • For "bubble" kernel, $h_{wi}(t)=(d_{wi} \le \delta_t)$

  • For "ep" kernel, $h_{wi}(t)=(1-d_{wi}^2/\delta_t^2)*(d_{wi} \le \delta_t)$

  • For "gamma" kernel, $h_{wi}(t)=1/\Gamma(d_{wi}^2/(4*\delta_t^2)+2)$

See Also

sTrainology, visKernels

Examples

# 1) generate an iid normal random matrix of 100x10 
data <- matrix( rnorm(100*10,mean=0,sd=1), nrow=100, ncol=10)

# 2) from this input matrix, determine nHex=5*sqrt(nrow(data))=50, 
# but it returns nHex=61, via "sHexGrid(nHex=50)", to make sure a supra-hexagonal grid
sTopol <- sTopology(data=data, lattice="hexa", shape="suprahex")

# 3) initialise the codebook matrix using "uniform" method
sI <- sInitial(data=data, sTopol=sTopol, init="uniform")

# 4) define trainology at "rough" stage
sT_rough <- sTrainology(sMap=sI, data=data, algorithm="sequential",
stage="rough")

# 5) training at "rough" stage
sM_rough <- sTrainSeq(sMap=sI, data=data, sTrain=sT_rough)

# 6) define trainology at "finetune" stage
sT_finetune <- sTrainology(sMap=sI, data=data, algorithm="sequential",
stage="finetune")

# 7) training at "finetune" stage
sM_finetune <- sTrainSeq(sMap=sM_rough, data=data, sTrain=sT_rough)

Description

sWriteData is supposed to write out the best-matching hexagons and/or cluster bases in terms of data.

Usage

sWriteData(sMap, data, sBase = NULL, filename = NULL, keep.data =
FALSE)

Arguments

Value

a data frame with following components:

• ID: ID for data. It inherits the rownames of data (if exists). Otherwise, it is sequential integer values starting with 1 and ending with dlen, the total number of rows of the input data

• Hexagon_index: the index for best-matching hexagons

• Qerr_distance: the quantification error (distance) for best-matching hexagons

• Cluster_base: optional, it is only appended when sBase is given. It stores the cluster memberships/bases

• data: optional, it is only appended when keep.data is true

Note

If "filename" is not NULL, a tab-delimited text file will be also written out. If "sBase" is not NULL and comes from the "sMap" partition, then cluster bases are also appended. if "keep.data" is true, the data will be part of output.

See Also

sBMH

Examples

# 1) generate an iid normal random matrix of 100x10 
data <- matrix( rnorm(100*10,mean=0,sd=1), nrow=100, ncol=10)

# 2) get trained using by default setup 
sMap <- sPipeline(data=data)

# 3) write data's BMH hitting the trained map
output <- sWriteData(sMap=sMap, data=data, filename="sData_output.txt")

# 4) partition the grid map into cluster bases
sBase <- sDmatCluster(sMap=sMap, which_neigh=1,
distMeasure="median", clusterLinkage="average")

# 5) write data's BMH and cluster bases
output <- sWriteData(sMap=sMap, data=data, sBase=sBase,
filename="sData_base_output.txt")

Description

visColoralpha is supposed to add transparent (alpha) into colors.

Usage

visColoralpha(col, alpha)

Arguments

Value

a vector of colors (after transparent being added)

Note

none

See Also

visColormap

Examples

# 1) define "blue-white-red" colormap
palette.name <- visColormap(colormap="bwr")

# 2) use the return function "palette.name" to generate 10 colors spanning "bwr"
col <- palette.name(10)

# 3) add transparent (alpha=0.5)
cols <- visColoralpha(col, alpha=0.5)

Description

visColorbar is supposed to define a colorbar

Usage

visColorbar(
colormap = c("bwr", "jet", "gbr", "wyr", "br", "yr", "rainbow", "wb"),
ncolors = 40,
zlim = c(0, 1),
gp = grid::gpar()
)

Arguments

Value

invisibly

Note

none

See Also

visColormap, visHexMulComp, visCompReorder

Examples

# draw "blue-white-red" colorbar
visColorbar(colormap="bwr")

Description

visColormap is supposed to define a colormap. It returns a function, which will take an integer argument specifying how many colors interpolate the given colormap.

Usage

visColormap(
colormap = c("bwr", "jet", "gbr", "wyr", "br", "yr", "rainbow", "wb",
"heat",
"terrain", "topo", "cm")
)

Arguments

Value

• palette.name: a function that takes an integer argument for generating that number of colors interpolating the given sequence

Note

The input colormap includes:

• "jet": jet colormap

• "bwr": blue-white-red

• "gbr": green-black-red

• "wyr": white-yellow-red

• "br": black-red

• "yr": yellow-red

• "wb": white-black

• "rainbow": rainbow colormap, that is, red-yellow-green-cyan-blue-magenta

• Alternatively, any hyphen-separated HTML color names, e.g. "blue-black-yellow", "royalblue-white-sandybrown", "darkblue-lightblue-lightyellow-darkorange", "darkgreen-white-darkviolet", "darkgreen-lightgreen-lightpink-darkred". A list of standard color names can be found in http://html-color-codes.info/color-names

See Also

visColoralpha

Examples

# 1) define "blue-white-red" colormap
palette.name <- visColormap(colormap="bwr")

# 2) use the return function "palette.name" to generate 10 colors spanning "bwr"
palette.name(10)

Description

visCompReorder is supposed to visualise multiple component planes reorded within a sheet-shape rectangle grid

Usage

visCompReorder(
sMap,
sReorder,
margin = rep(0.1, 4),
height = 7,
title.rotate = 0,
title.xy = c(0.45, 1),
colormap = c("bwr", "jet", "gbr", "wyr", "br", "yr", "rainbow", "wb"),
ncolors = 40,
zlim = NULL,
border.color = "transparent",
gp = grid::gpar(),
newpage = TRUE
)

Arguments

Value

invisible

Note

none

See Also

visVp, visHexComp, visColorbar, sCompReorder

Examples

# 1) generate data with an iid matrix of 1000 x 9
data <- cbind(matrix(rnorm(1000*3,mean=0,sd=1), nrow=1000, ncol=3),
matrix(rnorm(1000*3,mean=0.5,sd=1), nrow=1000, ncol=3),
matrix(rnorm(1000*3,mean=-0.5,sd=1), nrow=1000, ncol=3))
colnames(data) <- c("S1","S1","S1","S2","S2","S2","S3","S3","S3")

# 2) sMap resulted from using by default setup
sMap <- sPipeline(data=data, shape=c("suprahex","trefoil")[2])

# 3) reorder component planes
sReorder <- sCompReorder(sMap=sMap, amplifier=2, metric="none")

# 4) visualise multiple component planes reorded within a sheet-shape rectangle grid
visCompReorder(sMap=sMap, sReorder=sReorder, margin=rep(0.1,4),
height=7,
title.rotate=0, title.xy=c(0.45, 1), colormap="gbr", ncolors=10,
zlim=c(-1,1),
border.color="transparent")

Description

visDmatCluster is supposed to visualise clusters/bases partitioned from a supra-hexagonal grid

Usage

visDmatCluster(
sMap,
sBase,
height = 7,
margin = rep(0.1, 4),
area.size = 1,
gp = grid::gpar(cex = 0.8, font = 2, col = "black"),
border.color = "transparent",
fill.color = NULL,
lty = 1,
lwd = 1,
lineend = "round",
linejoin = "round",
colormap = c("rainbow", "jet", "bwr", "gbr", "wyr", "br", "yr", "wb"),
clip = c("on", "inherit", "off"),
newpage = TRUE
)

Arguments

Value

invisible

Note

none

See Also

sDmatCluster, sDmat, visColormap, visHexGrid

Examples

# 1) generate an iid normal random matrix of 100x10 
data <- matrix( rnorm(100*10,mean=0,sd=1), nrow=100, ncol=10)

## Not run: 
# 2) get trained using by default setup
sMap <- sPipeline(data=data)

# 3) partition the grid map into clusters using region-growing algorithm
sBase <- sDmatCluster(sMap=sMap, which_neigh=1,
distMeasure="median", clusterLinkage="average")

# 4) visualise clusters/bases partitioned from the sMap
visDmatCluster(sMap,sBase)
# 4a) also, the area size is proportional to the hits
visDmatCluster(sMap,sBase, area.size=log2(sMap$hits+1))
# 4b) also, the area size is inversely proportional to the map distance
dMat <- sDmat(sMap)
visDmatCluster(sMap,sBase, area.size=-1*log2(dMat))

# 5) customise the fill color and line type
my_color <-
visColormap(colormap="PapayaWhip-pink-Tomato")(length(sBase$seeds))[sBase$bases]
my_lty <- (sBase$bases %% 2)
visDmatCluster(sMap,sBase, fill.color=my_color, lty=my_lty,
border.color="black", lwd=2, area.size=0.9)
# also, the area size is inversely proportional to the map distance
visDmatCluster(sMap,sBase, fill.color=my_color, lty=my_lty,
border.color="black", lwd=2, area.size=-1*log2(dMat))

## End(Not run)

Description

visDmatHeatmap is supposed to visualise gene clusters/bases partitioned from a supra-hexagonal grid using heatmap

Usage

visDmatHeatmap(
sMap,
data,
sBase,
base.color = "rainbow",
base.separated.arg = NULL,
base.legend.location = c("none", "bottomleft", "bottomright", "bottom",
"left",
"topleft", "top", "topright", "right", "center"),
reorderRow = c("none", "hclust", "svd"),
keep.data = FALSE,
...
)

Arguments

Value

a data frame with following components:

• ID: ID for data. It inherits the rownames of data (if exists). Otherwise, it is sequential integer values starting with 1 and ending with dlen, the total number of rows of the input data

• Hexagon_index: the index for best-matching hexagons

• Cluster_base: optional, it is only appended when sBase is given. It stores the cluster memberships/bases

• data: optional, it is only appended when keep.data is true

Note: the returned data has rows in the same order as visualised in the heatmap

Note

A list of parameters in "base.separated.arg":

• "lty": the line type. Line types can either be specified as an integer (0=blank, 1=solid (default), 2=dashed, 3=dotted, 4=dotdash, 5=longdash, 6=twodash) or as one of the character strings "blank","solid","dashed","dotted","dotdash","longdash","twodash", where "blank" uses 'invisible lines' (i.e., does not draw them)

• "lwd": the line width

• "col": the line color

See Also

sDmatCluster, visHeatmapAdv

Examples

# 1) generate an iid normal random matrix of 100x10 
data <- matrix( rnorm(100*10,mean=0,sd=1), nrow=100, ncol=10)

## Not run: 
# 2) get trained using by default setup
sMap <- sPipeline(data=data)

# 3) partition the grid map into clusters using region-growing algorithm
sBase <- sDmatCluster(sMap=sMap, which_neigh=1,
distMeasure="median", clusterLinkage="average")

# 4) heatmap visualisation
output <- visDmatHeatmap(sMap, data, sBase,
base.legend.location="bottomleft", labRow=NA)

## End(Not run)

Description

visHeatmap is supposed to visualise input data matrix using heatmap. Note: this heatmap displays matrix in a bottom-to-top direction

Usage

visHeatmap(
data,
scale = c("none", "row", "column"),
row.metric = c("none", "pearson", "spearman", "kendall", "euclidean",
"manhattan",
"cos", "mi"),
row.method = c("ward", "single", "complete", "average", "mcquitty",
"median",
"centroid"),
column.metric = c("none", "pearson", "spearman", "kendall",
"euclidean", "manhattan",
"cos", "mi"),
column.method = c("ward", "single", "complete", "average", "mcquitty",
"median",
"centroid"),
colormap = c("bwr", "jet", "gbr", "wyr", "br", "yr", "rainbow", "wb"),
ncolors = 64,
zlim = NULL,
row.cutree = NULL,
row.colormap = c("rainbow"),
column.cutree = NULL,
column.colormap = c("rainbow"),
...
)

Arguments

Value

invisible

Note

The clustering methods are provided:

• "ward": Ward's minimum variance method aims at finding compact, spherical clusters

• "single": The single linkage method (which is closely related to the minimal spanning tree) adopts a 'friends of friends' clustering strategy

• "complete": The complete linkage method finds similar clusters

• "average","mcquitty","median","centroid": These methods can be regarded as aiming for clusters with characteristics somewhere between the single and complete link methods. Two methods "median" and "centroid" are not leading to a monotone distance measure, or equivalently the resulting dendrograms can have so called inversions (which are hard to interpret)

See Also

visHeatmap

Examples

# 1) generate data with an iid matrix of 100 x 9
data <- cbind(matrix(rnorm(100*3,mean=0,sd=1), nrow=100, ncol=3),
matrix(rnorm(100*3,mean=0.5,sd=1), nrow=100, ncol=3),
matrix(rnorm(100*3,mean=-0.5,sd=1), nrow=100, ncol=3))
colnames(data) <- c("S1","S1","S1","S2","S2","S2","S3","S3","S3")

# 2) prepare colors for the column sidebar
lvs <- unique(colnames(data))
lvs_color <- visColormap(colormap="rainbow")(length(lvs))
my_ColSideColors <- sapply(colnames(data), function(x)
lvs_color[x==lvs])

# 3) heatmap with row dendrogram (with 10 color-coded groups)
visHeatmap(data, row.metric="euclidean", row.method="average",
colormap="gbr", zlim=c(-2,2),
ColSideColors=my_ColSideColors, row.cutree=10, row.colormap="jet",
labRow=NA)

Description

visHeatmapAdv is supposed to visualise input data matrix using advanced heatmap. It allows for adding multiple sidecolors in both columns and rows. Besides, the sidecolor can be automatically added via cutting histogram into groups. Note: this heatmap displays matrix in a top-to-bottom direction

Usage

visHeatmapAdv(
data,
scale = c("none", "row", "column"),
Rowv = TRUE,
Colv = TRUE,
dendrogram = c("both", "row", "column", "none"),
dist.metric = c("euclidean", "pearson", "spearman", "kendall",
"manhattan", "cos",
"mi"),
linkage.method = c("complete", "ward", "single", "average", "mcquitty",
"median",
"centroid"),
colormap = c("bwr", "jet", "gbr", "wyr", "br", "yr", "rainbow", "wb"),
ncolors = 64,
zlim = NULL,
RowSideColors = NULL,
row.cutree = NULL,
row.colormap = c("jet"),
ColSideColors = NULL,
column.cutree = NULL,
column.colormap = c("jet"),
...
)

Arguments

Value

invisible

Note

The clustering/linkage methods are provided:

• "ward": Ward's minimum variance method aims at finding compact, spherical clusters

• "single": The single linkage method (which is closely related to the minimal spanning tree) adopts a 'friends of friends' clustering strategy

• "complete": The complete linkage method finds similar clusters

• "average","mcquitty","median","centroid": These methods can be regarded as aiming for clusters with characteristics somewhere between the single and complete link methods. Two methods "median" and "centroid" are not leading to a monotone distance measure, or equivalently the resulting dendrograms can have so called inversions (which are hard to interpret)