Maintainer: | Martin Zaefferer <martin.zaefferer@gmx.de> |
License: | GPL-2 | GPL-3 [expanded from: GPL (≥ 2)] |
Title: | Slow Feature Analysis |
Type: | Package |
Author: | Wolfgang Konen <wolfgang.konen@fh-koeln.de>, Martin Zaefferer, Patrick Koch; Bug hunting and testing by Ayodele Fasika, Ashwin Kumar, Prawyn Jebakumar |
Description: | Slow Feature Analysis (SFA), ported to R based on 'matlab' implementations of SFA: 'SFA toolkit' 1.0 by Pietro Berkes and 'SFA toolkit' 2.8 by Wolfgang Konen. |
Version: | 1.5 |
Date: | 2022-03-29 |
Depends: | R (≥ 2.0.0) |
Imports: | stats, MASS, graphics, grDevices |
NeedsCompilation: | no |
Repository: | CRAN |
RoxygenNote: | 7.1.2 |
Packaged: | 2022-03-29 09:40:39 UTC; Martin |
Date/Publication: | 2022-03-29 10:00:07 UTC |
Slow Feature Analysis
Description
Slow Feature Analysis
Details
Package: | rSFA |
Type: | Package |
Version: | 1.5 |
Date: | 29.03.2022 |
Maintainer: | Martin Zaefferer martin.zaefferer@gmx.de |
License: | GPL (>= 2) |
LazyLoad: | yes |
Slow Feature Analysis (SFA), ported to R based on the matlab implementations SFA toolkit 1.0 by Pietro Berkes and SFA toolkit 2.8 by Wolfgang Konen.
Author(s)
Wolfgang Konen wolfgang.konen@fh-koeln.de, Martin Zaefferer, Patrick Koch; Bug hunting and testing by Ayodele Fasika, Ashwin Kumar, Prawyn Jebakumar
Add noisy copies for parametric bootstrap
Description
Given training data X with true labels REALCLASS, add new records to X and REALCLASS, which are noisy copies of the training data.
Usage
addNoisyCopies(realclass, x, pars)
Arguments
realclass |
true class of training data (can be vector, numerics, integers, factors) |
x |
a matrix containing the training data |
pars |
list of parameters: |
Value
list res
- res
contains two list entries: realclass and x (including added copies)
References
Custom Repeater Function
Description
Faster than customRepmat in matlab package, in certain cases.
Usage
customRep(a, n)
Arguments
a |
to be repeated |
n |
repeat by |
Value
Returns the repeated dataset
Custom repmat Function
Description
R version of the matlab function repmat, repeating a by m x n
Usage
customRepmat(a, n, m)
Arguments
a |
to be repeated |
n |
repeater parameter |
m |
repeater parameter |
Value
Returns the repeated dataset
Custom Size Function.
Description
custom R version of matlabs size function. Calls length for vectors, or else calls dim.
Usage
customSize(x, i = NULL)
Arguments
x |
object to be checked for size |
i |
1, 2 or NULL. Defines if both or which size information should be returned. |
Value
a vector if i is null, an integer if i is 1 or 2.
Computes the eta value of a signal (slowness)
Description
Computes the eta value of a signal (slowness)
Usage
etaval(x, T = length(x))
Arguments
x |
The columns of signal correspond to different input components. Must be normalized (zero mean, unit variance) |
T |
Time interval |
Value
returns the eta value of the signal in a time interval T time units long.
Classifier for SFA demos
Description
Train or apply a Gaussian classifier..
Usage
gaussClassifier(gauss, y, realC, method = "train")
Arguments
gauss |
List created by gaussCreate. Contains also the elements:
|
y |
K x M matrix where K is the total number of patterns and M is the number of variables used for classification. I.e. each row of y contains the data for one pattern. |
realC |
1 x K matrix with NCLASS distinct real class labels needed only for method='train'. In case of method="apply" realC is not used and can have any value |
method |
either "train" (default) or "apply" |
Value
list gauss
containing
gauss$predC |
1 x K matrix: the predicted class |
gauss$prob |
K x NCLASS matrix: prob(k,n) is the estimated probability that pattern k belongs to class m |
See Also
Create an Gaussian classifier object
Description
Create an Gaussian classifier object
Usage
gaussCreate(nclass, dimY)
Arguments
nclass |
number of classes |
dimY |
dimension |
Value
list of defaults for gauss classifier
See Also
Load a GAUSS object.
Description
Load a GAUSS object.
Usage
gaussLoad(filename)
Arguments
filename |
Load list |
Value
list gauss
References
Save a GAUSS object.
Description
Save a GAUSS object.
Usage
gaussSave(gauss, filename)
Arguments
gauss |
A list that contains all information about the handled gauss-structure |
filename |
Save list |
References
Create a new covariance object.
Description
Create a new covariance object.
Usage
lcovCreate(dim)
Arguments
dim |
dimension of the covariance object list to be created |
Value
list containing the COVMTX, avg and tlen
See Also
Fix a covariance object
Description
Computes the definitive covariance matrix and the average of the covariance object referenced by lcov after a series of update operations.
Usage
lcovFix(lcov)
Arguments
lcov |
A list that contains all information about the handled covariance-structure |
Value
returns the fixed covariance list structure
See Also
Principal Component Analysis on a covariance object
Description
Performs PCA _and_ whitening on the covariance object referenced by lcov. CAUTION: can be numerically instable if covariance matrix is singular, better use LCOV_PCA2 instead /W. Konen/
Usage
lcovPca(lcov, dimRange = NULL)
Arguments
lcov |
A list that contains all information about the handled covariance-structure |
dimRange |
A number or vector for dimensionality reduction: |
Value
returns a list: $W is the whitening matrix, $DW the dewhitening matrix and $D an array containing a list of the eigenvalues. $kvar contains the total variance kept in percent.
Note
lcovFix(lcov) has to be used before this function is applied
See Also
Improved Principal Component Analysis on a covariance object
Description
Performs PCA _and_ whitening
on the covariance object referenced by lcov.
Difference to LCOV_PCA: null the rows of W (columns of DW) where the
corresponding eigenvalue in D is close to zero (more precisely: if
lam/lam_max < EPS = 1e-7). This is numerically stable in the case where
the covariance matrix is singular.
- Author: Wolfgang Konen, Cologne Univ., May'2009
Usage
lcovPca2(lcov, dimRange = NULL)
Arguments
lcov |
A list that contains all information about the handled covariance-structure |
dimRange |
A number or vector for dimensionality reduction: |
Value
returns a list: $W is the whitening matrix, $DW the dewhitening matrix and $D an array containing a list of the eigenvalues. $kvar contains the total variance kept in percent.
Note
lcovFix(lcov) has to be used before this function is applied
See Also
Transform a covariance object
Description
Computes the definitive covariance matrix and the average of the covariance object referenced by lcov after a series of update operations.
Usage
lcovTransform(lcov, A)
Arguments
lcov |
A list that contains all information about the handled covariance-structure to be transformed |
A |
linear function by which covariance object is to be transformed |
Value
returns the fixed covariance list structure
Note
lcovFix(lcov) has to be used before this function is applied
See Also
Update a covariance object
Description
Updates the covariance object referenced by lcov with a new chunk of data DATA.
Usage
lcovUpdate(lcov, DATA)
Arguments
lcov |
A list that contains all information about the handled covariance-structure |
DATA |
Input Data: must be oriented so that each column is a variable and each row a new measurement |
Value
list containing the COVMTX, avg and tlen
See Also
Custom Nonlinear Dimension Calculation
Description
Compute the dimension, used for the customexpansion demo.
Usage
nlDim(n)
Arguments
n |
Dimension of input vector |
Value
Dimension of expanded vector
See Also
Expand a signal in the for Nonlinear Expansion demo
Description
This is an optional expansion function, calculating the expanded data in [x; x^4].
Usage
nlExpand(sfaList, DATA)
Arguments
sfaList |
A list that contains all information about the handled sfa-structure |
DATA |
Input data, each column a different variable |
Value
expanded matrix DATA
See Also
The SFA1 algorithm, linear SFA.
Description
Y = sfa1(X) performs linear Slow Feature Analysis on the input data X and returns the output signals Y ordered by increasing temporal variation, i.e. the first signal Y[,1] is the slowest varying one, Y[,2] the next slowest and so on. The input data have to be organized with each variable in a column and each data (time) point in a row, i.e. X(t,i) is the value of variable nr. i at time t.
Usage
sfa1(x)
Arguments
x |
Input data, each column a different variable |
Value
list sfaList
with all learned information, where sfaList$y
contains the outputs
See Also
Create structured list for linear SFA
Description
Create structured list for linear SFA
Usage
sfa1Create(sfaRange, axType = "ORD1", regCt = 0)
Arguments
sfaRange |
number of slowly-varying functions to be kept |
axType |
is the type of derivative approximation to be used, see |
regCt |
regularization constant, currently not used |
Value
list sfaList
contains all arguments passed into sfa1create plus
deg |
2 |
This list will be expanded by other SFA functions with further SFa results
See Also
A step in the SFA1 algorithm.
Description
!!! Do not use this function directly, use sfaStep instead !!!
Usage
sfa1Step(sfaList, arg = NULL, step = NULL, method = NULL)
Arguments
sfaList |
A list that contains all information about the handled sfa-structure |
arg |
Input data, each column a different variable |
step |
Specifies the current SFA step. Must be given in the right sequence:
for SFA1 objects: "preprocessing", "sfa" |
method |
Method to be used: For |
Value
list sfaList
taken from the input, with new information added to this list.
Among the new items are:
avg0 |
mean vector in input space |
SF |
(sfaRange x sfaRange)-matrix with rows which contain the directions in expanded space with slow signals. The rows are sorted acc. to increasing eigenvalues of time-diff covariance matrix |
See Also
The SFA2 algorithm, SFA with degree 2 expansion.
Description
Y = sfa2(X) performs expanded Slow Feature Analysis on the input data X and returns the output signals Y ordered by increasing temporal variation, i.e. the first signal Y[,1] is the slowest varying one, Y[,2] the next slowest varying one and so on. The input data have to be organized with each variable in a column and each data (time) point in a row, i.e. X(t,i) is the value of variable i at time t. By default an expansion to the space of 2nd degree polynomials is done, this can be changed by using different functions for xpDimFun and sfaExpandFun.
Usage
sfa2(
x,
method = "SVDSFA",
ppType = "PCA",
xpDimFun = xpDim,
sfaExpandFun = sfaExpand
)
Arguments
x |
input data |
method |
eigenvector calculation method: ="SVDSFA" for singular value decomposition (recommended) or ="GENEIG" for generalized eigenvalues (unstable!). GENEIG is not implemented in the current version, since R lacks an easy option to calculate generalized eigenvalues. |
ppType |
preprocessing type: ="PCA" (principal component analysis) or ="SFA1" (linear sfa) |
xpDimFun |
function to calculate dimension of expanded data |
sfaExpandFun |
function to expand data |
Value
list sfaList
with all SFA information, among them are
y |
a matrix containing the output Y (as described above) |
- |
all input parameters to |
- |
all elements of |
See Also
sfa2Step
sfa2Create
sfaExecute
sfa1
Examples
## prepare input data for simple demo
t=seq.int(from=0,by=0.011,to=2*pi)
x1=sin(t)+cos(11*t)^2
x2=cos(11*t)
x=data.frame(x1,x2)
## perform sfa2 algorithm with data
res = sfa2(x)
## plot slowest varying function of result
plot(t, res$y[,1],type="l",main="output of the slowest varying function")
## see http://www.scholarpedia.org/article/Slow_feature_analysis#The_algorithm
## for detailed description of this example
Create structured list for expanded SFA
Description
'Expanded' SFA means that the input data are expanded into a higher-dimensional
space with the function sfaExpandFun. See sfaExpand
for the default
expansion function.
Usage
sfa2Create(
ppRange,
sfaRange,
ppType = "SFA1",
axType = "ORD1",
regCt = 0,
opts = NULL,
xpDimFun = xpDim,
sfaExpandFun = sfaExpand
)
Arguments
ppRange |
umber of dimensions to be kept after preprocessing step - or - a two-number vector with lower and upper dimension number |
sfaRange |
umber of slowly-varying functions to be kept |
ppType |
preprocessing type: ="PCA", "PCA2" (principal component analysis) or ="SFA1" (linear sfa) |
axType |
is the type of derivative approximation to be used, see |
regCt |
regularization constant, currently not used |
opts |
optional list of additional options |
xpDimFun |
Function to calculate dimension of expanded data |
sfaExpandFun |
Function to expand data |
Value
list sfaList
contains all arguments passed into sfa2create plus
xpRange |
evaluates to |
deg |
2 |
This list will be expanded by other SFA functions with further SFa results
See Also
A step in the SFA2 algorithm.
Description
!!! Do not use this function directly, use sfaStep instead !!!
Usage
sfa2Step(sfaList, arg = NULL, step = NULL, method = NULL)
Arguments
sfaList |
A list that contains all information about the handled sfa-structure |
arg |
Input data, each column a different variable |
step |
Specifies the current SFA step. Must be given in the right sequence:
for SFA1 objects: "preprocessing", "sfa" |
method |
Method to be used: For |
Value
list sfaList
taken from the input, with new information added to this list.
Among the new items are:
avg0 |
mean vector in input space |
avg1 |
mean vector in expanded space |
W0 |
(ppRange x ppRange)-matrix, the whitening matrix for the input data |
C |
covariance matrix of the time-diff of expanded and sphered data |
SF |
(sfaRange x sfaRange)-matrix with rows which contain the directions in expanded space with slow signals. The rows are sorted acc. to increasing eigenvalues of C |
See Also
Backslash operator.
Description
Reproduce what MATLAB's backslash operator can do, using qr() and qr.coef().
Usage
sfaBSh(X, Y)
Arguments
X |
X matrix |
Y |
Y vector |
Value
Returns coefficients
Check Condition of a matrix for SFA
Description
Creates warnings with recommendations for different settings, if given matrix is ill-conditioned.
Usage
sfaCheckCondition(matr, datatype)
Arguments
matr |
matrix to be checked |
datatype |
string to identify "input" or "expanded" data |
Predict Class for SFA classification
Description
Use a SFA classification model (stored in opts$*Filename), predict & evaluate on new data (xtst,realc_tst).
Author of orig. matlab version: Wolfgang Konen, Jan 2011-Mar 2011.
See also [Berkes05] Pietro Berkes: Pattern recognition with Slow Feature Analysis.
Cognitive Sciences EPrint Archive (CogPrint) 4104, http://cogprints.org/4104/ (2005)
Usage
sfaClassPredict(xtst, realcTst, opts)
Arguments
xtst |
NTST x IDIM, test input data |
realcTst |
1 x NTST, test class labels |
opts |
list with several parameter settings:
|
Value
list res
containing
res$errtst |
1 x 2 matrix: error rate with / w/o SFA on test set |
res$ytst |
output from SFA when applied to test data |
res$predT |
predictions with SFA + GaussClassifier on test set |
res$predX |
predictions w/o SFA (only GaussClassifier) on test set (only if opts.xFilename exists) |
See Also
Predict Class for SFA classification
Description
Create a SFA classification mode, predict & evaluate on new data (xtst,realc_tst).
Author of orig. matlab version: Wolfgang Konen, May 2009 - Jan 2010
See also [Berkes05] Pietro Berkes: Pattern recognition with Slow Feature Analysis.
Cognitive Sciences EPrint Archive (CogPrint) 4104, http://cogprints.org/4104/ (2005)
Usage
sfaClassify(x, realclass, xtst = 0, realcTst = 0, opts)
Arguments
x |
NREC x IDIM, training input data |
realclass |
1 x NREC, training class labels |
xtst |
NTST x IDIM, test input data |
realcTst |
1 x NTST, test class labels |
opts |
list with several parameter settings:
|
Value
list res
containing
res$errtrn |
1 x 2 matrix: error rate with / w/o SFA on training set |
res$errtst |
1 x 2 matrix: error rate with / w/o SFA on test set |
res$y |
output from SFA when applied to training data |
res$ytst |
output from SFA when applied to test data |
res$predT |
predictions with SFA + GaussClassifier on test set |
res$predX |
predictions w/o SFA (only GaussClassifier) on test set (only if opts.xFilename exists) |
See Also
Execute learned function for input data
Description
After completion of the learning phase (step="sfa") this function can be used
to apply the learned function to the input data.
The execution is completed in 4 steps:
1. projection on the input principal components (dimensionality
reduction)
2. expansion (if necessary)
3. projection on the whitened (expanded) space
4. projection on the slow functions
Usage
sfaExecute(sfaList, DATA, prj = NULL, ncomp = NULL)
Arguments
sfaList |
A list that contains all information about the handled sfa-structure |
DATA |
Input data, each column a different variable |
prj |
If not NULL, the preprocessing step 1 is skipped for SFA2 |
ncomp |
number of learned functions to be used |
Value
matrix DATA
containing the calculated output
See Also
Degree 2 Expansion
Description
Expand a signal in the space of polynomials of degree 2. This is the default expansion function used by rSFA.
Usage
sfaExpand(sfaList, DATA)
Arguments
sfaList |
A list that contains all information about the handled sfa-structure |
DATA |
Input data, each column a different variable |
Value
expanded matrix DATA
See Also
Return a SFA function as a quadratic form.
Description
sfaGetHf returns function number NR in the
sfa object referenced by HDL in the form of a quadratic form
q(x) = 1/2*x'*H*x + f'*x + c
Of course, this only works if a quadratic expansion was used during
training.
The quadratic form can lie in different spaces, i.e. it can receive
as input preprocessed or non-preprocessed vectors. This is specified
by setting the argument WHERE. The quadratic form lies
- in the preprocessed space for WHERE==0 (e.g. the whitened space if
the preprocessing type is PCA)
- in the PCA space (i.e. projected on the principal components but
not whitened, works only if PCA was used for preprocessing) for
WHERE==1
- in the input, mean-free space for WHERE==2
- in the input space for WHERE==3
In general you will need to set WHERE to 2 or 3, but working in the
preprocessed spaces can often drastically improve the speed of
analysis.
Usage
sfaGetHf(sfaList, nr, where)
Arguments
sfaList |
A list that contains all information about the handled sfa-structure |
nr |
function number |
where |
WHERE parameter |
Value
list res
- res
contains:
res$H
res$f
res$c
See Also
Helper Function of SFA.
Description
Helper Function of SFA.
Usage
sfaGetIntRange(range)
Arguments
range |
Range |
Value
numeric vector int
Load a SFA object.
Description
Load a SFA object.
Usage
sfaLoad(filename)
Arguments
filename |
Load list |
Value
list sfaList
References
Perform non-linear regression
Description
Given the data in arg, expand them nonlinearly in the same way as it was
done in the SFA-object sfaList (expanded dimension M) and search the vector
RCOEF of M constant coefficients, such that the sum of squared residuals
between a given function in time FUNC and the function
R(t) = (v(t) - v0)' * RCOEF, t=1,...,T,
is minimal
Usage
sfaNlRegress(sfaList, arg, func)
Arguments
sfaList |
A list that contains all information about the handled sfa-structure |
arg |
Input data, each column a different variable |
func |
(T x 1) the function to be fitted nonlinearly |
Value
returns a list res
with elements
res$R |
(T x 1) the function fitted by NL-regression |
res$rcoef |
(M x 1) the coefficients for the NL-expanded dimensions |
Parametric Bootstrap
Description
If training set too small, augment it with parametric bootstrap
Usage
sfaPBootstrap(realclass, x, sfaList)
Arguments
realclass |
true class of training data (can be vector, numerics, integers, factors) |
x |
matrix containing the training data |
sfaList |
list with several parameter settings, e.g. as created by |
Value
a list list
containing:
x |
training set extended to minimu number of recors1.5*(xpdim+nclass), if necessary |
realclass |
training class labels, extended analogously |
See Also
Preprocessing for SFA classification
Description
Helper function for sfaClassify
Usage
sfaPreproc(sfaList, x, opts)
Arguments
sfaList |
A list that contains all information about the handled sfa-structure |
x |
Input data, each column a different variable |
opts |
list |
Value
preprocessed data
See Also
Save a SFA object.
Description
Save a SFA object.
Usage
sfaSave(sfaList, filename)
Arguments
sfaList |
A list that contains all information about the handled sfa-structure |
filename |
Save list |
References
Update a step of the SFA algorithm.
Description
sfaStep() updates the current step of the SFA algorithm. Depending on sfaList$deg
it calls either sfa1Step
or sfa2Step
to do the main work.
See further documentation there
Usage
sfaStep(sfaList, arg, step = NULL, method = NULL)
Arguments
sfaList |
A list that contains all information about the handled sfa-structure |
arg |
Input data, each column a different variable |
step |
Specifies the current SFA step. Must be given in the right sequence:
for SFA1 objects: "preprocessing", "sfa" |
method |
Method to be used: For |
Value
list sfaList
taken from the input, with new information added to this list.
See sfa1Step
or sfa2Step
for details.
See Also
sfa1Step
sfa2Step
sfa1Create
sfa2Create
sfaExecute
Examples
## Suppose you have divided your training data into two chunks,
## DATA1 and DATA2. Let the number of input dimensions be N. To apply
## SFA on them write:
## Not run:
sfaList = sfa2Create(N,xpDim(N))
sfaList = sfaStep(sfaList, DATA1, "preprocessing")
sfaList = sfaStep(sfaList, DATA2)
sfaList = sfaStep(sfaList, DATA1, "expansion")
sfaList = sfaStep(sfaList, DATA2)
sfaList = sfaStep(sfaList, NULL, "sfa")
output1 = sfaExecute(sfaList, DATA1)
output2 = sfaExecute(sfaList, DATA2)
## End(Not run)
Calculates the first derivative of signal data
Description
Calculates the first derivative of signal data
Usage
sfaTimediff(DATA, axType = "ORD1")
Arguments
DATA |
The matrix of signals for which the derivative is calculated (one column per signal) |
axType |
Type of interpolation: "ORD1" (default) first order, "SCD" second ,"TRD" third, "ORD3a" cubic polynom |
Value
matrix DATA
- DATA
contains the derivative signals, with the same structure as the input data.
Note
setting axType to invalid values will lead to first order interpolation.
Degree 2 Dimension Calculation
Description
Compute the dimension of a vector expanded in the space of polynomials of 2nd degree.
Usage
xpDim(n)
Arguments
n |
Dimension of input vector |
Value
Dimension of expanded vector