/
all-generics.r
151 lines (132 loc) · 5.27 KB
/
all-generics.r
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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
#' Construct a sparse tensor
#'
#' Construct an \linkS4class{sptensor} from a matrix of subscripts for non-zero values,
#' a vector of non-zero values, and the numeric dimensions of the tensor.
#'
#' @param subs matrix with length(dims) rows and length(vals) cols. Each row
#' in the matrix corresponds to a different tensor dimension. Each column in the
#' matrix represents a vector of subscripts pointing to a non-zero value in the
#' tensor.
#' @param vals values of non-zero entries. The subscripts for the first value
#' are the first column of the \code{subs} matrix, the subscripts for the second value
#' are in the second column of the \code{subs} matrix, etc...
#' @param dims sizes of each dimension
#'
#' @examples
#' # A 2x2x2 sparse tensor
#' subs <- matrix(c(1,1,1, 1,1,2), c(3,2))
#' vals <- c(10,20)
#' dims <- c(2,2,2)
#' X <- sptensor(subs, vals, dims)
#'
#' @seealso \code{\link{sptensor-class}} for class documentation.
setGeneric("sptensor", function(subs, vals, dims) standardGeneric("sptensor"))
#' Construct a dense tensor
#'
#' Construct a \linkS4class{dtensor} from a multi-dimensional array.
#'
#' @param x n-dimensional R array
#' @examples
#' # A 2x2x2 dense tensor
#' arr <- array(data = c(1,0,0,0,1,0,0,0) , dim = c(2,2,2))
#' X <- dtensor(arr)
#'
#' @seealso \code{\link{dtensor-class}} for class documentation.
setGeneric("dtensor", function(x) standardGeneric("dtensor"))
#' Subscripts of non-zero values in a tensor
#'
#' @param x tensor
setGeneric("nzsubs", function(x) standardGeneric("nzsubs"))
#' Subscripts of zero values in a tensor
#'
#' @param x tensor
#' @keywords internal
setGeneric("zsubs", function(x) standardGeneric("zsubs"))
#' Subscripts of all values in a tensor
#'
#' @param x tensor
#' @keywords internal
setGeneric("allsubs", function(x) standardGeneric("allsubs"))
#' Non-zero values in a tensor
#'
#' @param x tensor
setGeneric("nzvals", function(x) standardGeneric("nzvals"))
#' Convert objects to sparse tensors
#'
#' @param x object
#' @param ... extra params
setGeneric("as_sptensor", function(x, ...) standardGeneric("as_sptensor"))
#' Convert objects to dense tensors
#'
#' @param x object
#' @param ... extra params
setGeneric("as_dtensor", function(x, ...) standardGeneric("as_dtensor"))
#' Construct an unfolded sparse tensor
#'
#' Construct an \linkS4class{unfolded_sptensor} from a sparse matrix,
#' mode, and dimensions of original tensor.
#'
#' @param mat sparse matrix representing unfolded tensor
#' @param mode dimension to unfold tensor along
#' @param tensor_dims original dimensions of tensor (useful for re-folding)
#'
#' @seealso \code{\link{unfolded_sptensor-class}} for class documentation.
setGeneric("unfolded_sptensor", function(mat, mode, tensor_dims) standardGeneric("unfolded_sptensor"))
#' Construct an unfolded dense tensor
#'
#' Construct an \linkS4class{unfolded_dtensor} from a dense matrix,
#' mode, and dimensions of original tensor.
#'
#' @param mat dense matrix representing unfolded tensor
#' @param mode dimension to unfold tensor along
#' @param tensor_dims original dimensions of tensor (useful for re-folding)
#'
#' @seealso \code{\link{unfolded_dtensor-class}} for class documentation.
setGeneric("unfolded_dtensor", function(mat, mode, tensor_dims) standardGeneric("unfolded_dtensor"))
#' Unfold (matricize) a tensor along a mode
#' @param x tensor
#' @param mode dimension to unfold along
setGeneric("unfold", function(x, mode) standardGeneric("unfold"))
#' Refold an unfolded tensor
#' @param x an unfolded tensor
setGeneric("refold", function(x) standardGeneric("refold"))
#' Tensor times matrix
#'
#' Calculates the n-mode product of a tensor and a matrix. Given a tensor X with
#' dimensions \eqn{I_1, I_2, ..., I_n, I_n+1, ... I_N} and a matrix U with
#' dimensions \eqn{J, I_n}, the resulting tensor after multiplication will have
#' dimension \eqn{I_1, I_2, ..., J, I_n+1, ... I_N}.
#'
#' @param x tensor
#' @param u matrix
#' @param mode mode along tensor to perform multiplication
#'
#' @references \cite{T. G. Kolda and B. W. Bader, Tensor Decompositions and
#' Applications, SIAM Review 51(3):455-500, September 2009}
setGeneric("ttm", function(x, u, mode) standardGeneric("ttm"))
#' Tensor times vector
#'
#' Calculates the n-mode product of a tensor and a vector Given a tensor X with
#' dimensions \eqn{I_1, I_2, ..., I_n, I_n+1, ... I_N} and a vector v with
#' dimensions \eqn{J, 1}, the resulting tensor after multiplication will have
#' dimension \eqn{I_1, I_2, ..., I_n-1, I_n+1, ... I_N}. Note that the dimension
#' corresponding to the \code{mode} has been dropped.
#'
#' @param x tensor
#' @param v vector
#' @param mode mode along tensor to perform multiplication
#'
#' @references \cite{T. G. Kolda and B. W. Bader, Tensor Decompositions and
#' Applications, SIAM Review 51(3):455-500, September 2009}
setGeneric("ttv", function(x, v, mode) standardGeneric("ttv"))
#' Calculate the Frobenius norm of a tensor
#' @param x tensor
setGeneric("norm", function(x) standardGeneric("norm"))
#' Calculate the inner product of a pair of tensors
#' @param x,y tensors
setGeneric("innerprod", function(x,y) standardGeneric("innerprod"))
#' Calculate the outer product of a pair of tensors
#' @param x,y tensors
setGeneric("outerprod", function(x,y) standardGeneric("outerprod"))
#' @rdname outerprod
setGeneric("ttt", function(x, y) standardGeneric("ttt"))