PTAk                  package:PTAk                  R Documentation

_P_r_i_n_c_i_p_a_l _T_e_n_s_o_r _A_n_a_l_y_s_i_s _o_n _k _m_o_d_e_s

_D_e_s_c_r_i_p_t_i_o_n:

     Performs a truncated SVD-_k_modes analysis with or without
     specific metrics, penalised or not.

_U_s_a_g_e:

      PTAk(X,nbPT=2,nbPT2=1,minpct=0.1,
                     smoothing=FALSE,
                        smoo=list(NA),
                         verbose=getOption("verbose"),file=NULL,
                          modesnam=NULL,addedcomment="")

_A_r_g_u_m_e_n_t_s:

       X: a tensor (as an array) of order _k_, if non-identity metrics
          are used 'X' is a list with 'data'  as the array and 'met' a
          list of metrics

    nbPT: integer vector of length _(k-2)_  specifying the  maximum
          number of Principal Tensors requested for the _(3,...,k-1,
          k)_ modes levels (see details), if it is not a vector every
          levels would have the same given nbPT value 

   nbPT2: if 0 no 2-modes solutions will be computed, 1 =all, >1
          otherwise

  minpct: numerical 0-100 to control of computation of future solutions
          at this level and below

smoothing: see 'PTA3', 'SVDgen'

    smoo: see 'PTA3'

 verbose: control printing

    file: output printed at the prompt if 'NULL', or printed in the
          given  'file'

modesnam: character vector of the names of the modes, if 'NULL' 'mo 1'
          ...'mo k'

addedcomment: character string printed if 'printt' after the title of
          the analysis

_D_e_t_a_i_l_s:

     According to the decomposition described in Leibovici(1993) and
     Leibovici and Sabatier(1998) the function gives a generalisation
     of the SVD (2 modes) to _k_ modes. The algorithm is recursive,
     calling 'APSOLUk' which calls 'PTAk' for _(k-1)_. 'nbPT', 'nbPT2'
     and 'minpct' control the number of Principal Tensors desired. For
     example 'nbPT=c(2,4,3)' means a tensor of order _5_ is analysed,
     the maximum number of 5-modes PT is set to _3_, for _each of them_
     one sets a maximum of _4_ associated _4-modes_ (for each of the
     five components), for _each of these later_ a maximum of _2_
     associated _3-modes_ PT is asked (for each of the four
     components). Then 'nbPT2' complete for _2-modes_ associated or
     not. Overall 'minpct' controls to carry on the algorithm at any
     level and lower, _i.e._ stops if 100(vs^2/ssx)<minpct (where vs is
     the singular value, and _ssx_ is the total sum of squares of the
     tensor X or the "metric transformed" X). Putting a 0 at a given
     level in 'nbPT' obviously automatically puts 0  in 'nbPT' at lower
     levels. Putting high values in 'nbPT' allows control only on
     'minpct' helping to reach the full decomposition. All these
     controls allow to truncate the full decomposition in a
     level-controlled fashion. Notice the full decomposition always
     contains any possible choice of truncation, _i.e._ the solutions
     are not dependant on the truncation scheme (Generalised
     Eckart-Young Theorem). 
      Recent work from Tamara G Kolda showed on an example that
     _orthogonal rank_ decompositions are not necesseraly nested. This
     makes PTA-_k_modes a model with nested decompositions not giving
     the exact _orthogonal rank_. So PTA-_k_modes will look for best
     approximation according to orthogonal tensors in a nested
     approximmation process.

_V_a_l_u_e:

     a 'PTAk' object

_N_o_t_e:

     The use of metrics (diagonal or not) allows flexibility of
     analysis like in _2_ modes _e.g._ correspondence analysis,
     discriminant analysis, robust analysis.  Smoothing option
     extending the analysis towards functional data analysis is
     theoretically valid for Principal Tensors  belonging to a tensor
     product of separable Hilbert spaces (_e.g._ Sobolev spaces) see
     Leibovici and El Maach (1997).

_A_u_t_h_o_r(_s):

     Didier Leibovici c3s2i@free.fr

_R_e_f_e_r_e_n_c_e_s:

     Leibovici D(1993) _Facteurs  Mesures Rptes et Analyses
     Factorielles : applications  un suivi pidmiologique_.
     Universit de Montpellier II. PhD Thesis in Mathmatiques et
     Applications (Biostatistiques).

     Leibovici D and El Maache H (1997) _Une dcomposition en Valeurs
     Singulires d'un lment d'un produit Tensoriel de k espaces de
     Hilbert Sparables_. Compte Rendus de l'Acadmie des Sciences tome
     325, srie I, Statistiques (Statistics) & Probabilits
     (Probability Theory): 779-782.

     Leibovici D and Sabatier R (1998) _A Singular Value Decomposition
     of a k-ways array for a Principal Component Analysis of multi-way
     data, the PTA-k_. Linear Algebra and its Applications,
     269:307-329.

     Leibovici D (2001) _A Penalised algorithm for SVD and Multiway
     functional methods_. (in preparation)

     Kolda T.G (2003)_ A Counterexample to the Possibility of an
     Extension of the Eckart-Young Low-Rank Approximation Theorem for
     the Orthogonal Rank Tensor Decomposition_. SIAM J. Matrix
     Analysis, 24(2):763-767, Jan. 2003.

_S_e_e _A_l_s_o:

     'REBUILD', 'FCAk', 'PTA3' 'summary.PTAk'

_E_x_a_m_p_l_e_s:

       # don <- array((1:3)

     don <- array(1:360,c(5,4,6,3))
      don <- don + rnorm(360,1,2)

      dimnames(don) <- list(paste("s",1:5,sep=""),paste("T",1:4,sep=""),
               paste("t",1:6,sep=""),c("young","normal","old"))
        # hypothetic data on learning curve at different age and period of year

      ones <-list(list(v=rep(1,5)),list(v=rep(1,4)),list(v=rep(1,6)),list(v=rep(1,3)))

      don <- PROJOT(don,ones)
      don.sol <- PTAk(don,nbPT=1,nbPT2=2,minpct=0.01,
                    verbose=TRUE,
                     modesnam=c("Subjects","Trimester","Time","Age"),
                      addedcomment="centered on each mode")
      summary(don.sol,testvar=2)
       plot(don.sol,mod=c(1,2,3,4),nb1=1,nb2=NULL,
          xlab="Subjects/Trimester/Time/Age",main="Best rank-one approx" )
       plot(don.sol,mod=c(1,2,3,4),nb1=4,nb2=NULL,
           xlab="Subjects/Trimester/Time/Age",main="Associated to Subject vs1111")

     #  demo function
      # demo.PTAk()

       

