============
Description:
============

This is the main function to perform Functional Singular Component
Analysis of two functions X(t_x) and Y(t_y).

Includes the following steps:

1) Functional singular value decomposition using smoothing
   of the cross-covariance surface between X and Y.

2) Computation of the singular values and singular functions.

3) Computation of a derived measure for functional correlation.

========
Usage:
========

res = FSVD(x, t_x, param_X, y, t_y, param_Y, nsvd, bwccov)

=======
Input:
=======

x    :  1*n cell array for function x,  x{i} is the row vector of measurements
        for the ith subject, i=1,...,n. 

t_x  :  1*n cell array, t_x{i} is the row vector of time points for the ith
        subject at which corresponding measurements x{i} are taken,
        i=1,...,n.

y    :  1*n cell array for function y,  y{i} is the row vector of measurements
        for the ith subject, i=1,...,n. 

t_y  :  1*n cell array, t_y{i} is the row vector of time points for the ith
        subject at which corresponding measurements y{i} are taken,
        i=1,...,n.

param_X: an object that is returned by setOptions(), it sets the input
        arguments for FPCA() of the X (predictor) functions (for default, set param_X = []).
        For default values of parameters, see setOptions() for more details.

param_Y: an object that is returned by setOptions(), it sets the input
        arguments for FPCA() of the X (predictor) functions (for default, set param_X = []).
        For default values of parameters, see setOptions() for more details.

nsvd:   positive integer. Number of singular components used in regression.
        Default nsvd = [], then use 'FVE' (fraction of variance explained) 
        criteria to select the number of singular components that explain at least
        75% of total variation.

bwccov:  1*2 vector, bandwidths for covariance surface used for
         smoothing of cov(X(t),Y(s))
         bwccov(i): ith coordinate of bandwidth vector, i=1,2.
         bwccov(1)>0 & bwccov(2)>0: user-specified bandwidths.
         bwccov(1)==0 & bwccov(2)==0: use generalized cross-validation
         (GCV) for automatic selection.                     [Default]
         For the purpose of estimating singular value, the GCV-chosen 
         bandwidth is multiplied by an empirical factor depending on the
         sparsity of the data.

SingularScores: An indicator (0 or 1) saying if the singular component scores
            should be returned or not; default is 0, not to return the
            scores.
         
Details: i) Any non-used or optional arguments can be set to "[]" for
            default values;
        ii) FPCA() calls PCA(), so setOptions() sets the input
            arguments for PCA() and the returned object contains all
            values returned by PCA();
       iii) Names of objects can be retrieved through names() function i.e.,
            names(xx), names(yy), names(res) and the actual values can be
            retrieved through getVal() function, example: getVal(res, 'BETA'),
            getVal(res, 'newy') etc.

=======
Output:
=======
  res:  an aggregated object that contains nsvd, fc, sv, ss_x, ss_y, sc_x, sc_y, out_x, out_y, out2x, out2y, ccov_s, ccovfit.

        1) nsvd: automatically or subjectively selected value of the number of singular components.

        2) fc:   functional correlation, a scalar between 0 and 1 .

        3) sv:   a 1*nsvd vector, estimated singular values (covariances of
                 functional singluar components scores).

        4) ss_x:  if SingularScores = 1, n*nsvd matrix, predictions for random coeffecients
                 (singular scores) of X for n subjects; [] for
                 SingularScores = 0.

        5) ss_y:  if SingularScores =1,  n*nsvd matrix, predictions for random coeffecients
                 (singular scores) of Y for n subjects; [] for SingularScores = 0.

        6) out_x: 1*Nx vector, distinct input time points of X with ascending
                  order from all subjects.

        7) out_y: 1*Ny vector, distinct input time points of Y with ascending
                  order from all subjects.

        8) sc_x:  Nx*nsvd matrix, estimated singular component functions
                  valued at distinct input time points with ascending
                  order of all subjects, corresponding to out_x.

        9) sc_y:  Ny*nsvd matrix, estimated singular component functions
                  valued at distinct input time points with ascending
                  order of all subjects, corresponding to out_y.

       10) out2x, out2y: both are 1*51 vectors, providing a grid of time points 
                  for which the smoothed cross-covariance surface assumes values.

       11) ccov_s: 51*51 matrix, smoothed covariance surface, corresponding to 
                   out2x and out2y.

       12) ccovfit:  51*51 matrix, fitted cross-covariance surface, based
                  on truncated estimates of singular values and components 
                  functions, corresponding to out2x and out2y


 See
   o    example0.m for an example of sparse irregular data case,
        when both x and y are functional
   o    example2.m for example of regular data case,
        when both x and y are functional

See also PCA, FPCA