
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
This is Readme file for SDWT tool. 
SDWT is available as Free Software under the terms of the Free Software Foundation¡¯s GNU General Public License. It compiles and runs on  Windows operating system.

If you have any questions about using the software, please contact Jing Wei at 2276887838@qq.com, Jie Lin at linjie891@163.com,or Yue Jiang at yueljiang@163.com.

Date: written on March 27, 2018.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
SDWT implements an alignment-free approach which is a k-mer based frequency profile feature method.
 There are 4 steps in SDWT. 
 Step (1) kmer Extraction: it breaks a sequence (DNA or protein sequence) into k-mers.
 Step (2) NumberTransform: it turn a k-mer into a complex number, then, a sequence can be represented as a series of complex numbers
 Step (3) FeatureTransform: a series of complex numbers is transformed into a feature vector by using stationary discrete wavelet transformation (equation Haar function).
 Step (4) Application: The feature vector is used to classification and/or cluster 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


1.Pre-requirement: need to install R packages and Matlab.
In order to use SDWT tool, statistical software R package and Matlab are required.  
Software R packages can be downloaded from (https://www.r-project.org/), our used version is 3.2.4. Used 1-NN(One-Nearest-Neighborhoods) and K-mean packages come with R packages which do not need extra installation.
Matlab should be installed, used version is R2016b. Used package,Haar function, does not need extra installation.   


How to install SDWT? There is no installation required for SDWT. Directly execute our scripts in R enviroment should be OK.  


2. SDWT Usage:

(a). Read file function: Reads sequence data in R.
Function: seqsAndLabel = readFile("familylist")
input parameters: 
    familylist: the input file name, which contains a list of file names. Each file contains the corresponding (DNA/protein) sequences in FST(DNA) or FASTA(protein).

output parameters: 
     seqsAndLabel: a matrix named seqsAndLabel is generated. Each line of matrix contains two elements:  sequence and its corresponding family label.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
(b). Feature Constructor: Constructs a feature vector based on the input sequences which implements the above mentioned Step (1), Step (2), and Step (3) together.
Function : feature = Feature(K,dat,decomLevel,char,alphabet)
input parameters:
      K:  the length of k-mer in integer number. 
    dat:  DNA/protein sequences, i.e, GCTGGCCTACGTGAAAC 
    decomLevel: decomposition level of stationary wavelet transform in integer.  
	char: the alphabet size where DNA is 4 and protein is 20. 
	alphabet: the actual alphabet for DNA/protein. For DNA, it is the set "ACGT". For protein, it is the set "ACDEFGHIKLMNPQRSTVWY".

output parameters:  
    featrue: a matrix contains feature vector. This feature vector is the output mentioned in Step (3). 
    
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
(c). Training Feature Constructor: Constructs a feature vector based on the input sequences which implements the above mentioned Step (1), Step (2), and Step (3) together.

Function: trainfeature = TrainFeature(K,dat,decomLevel,char,alphabet)
input parameters:
      K:  the length of k-mer in integer number. 
    dat:  DNA/protein sequences,i.e, GCTGGCCTACGTGAAAC 
    decomLevel: decomposition level of stationary wavelet transform in integer.  
	char: the alphabet size where DNA is 4 and protein is 20. 
	alphabet: the actual alphabet for DNA/protein. For DNA, it is the set "ACGT". For protein, it is the set "ACDEFGHIKLMNPQRSTVWY".

output parameters:   
	trainseqfeature: a matrix contains feature vector. This feature vector is the output mentioned in Step (3). 
       means: mean of a specific k-mer.
          SD: Standard Deviation of a specific k-mer.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
(d). Predictive Feature Constructors: Constructs a feature vector based on the input sequences which implements the above mentioned Step (1), Step (2), and Step (3) together.

Function: testfeature = TestFeature(K,dat,decomLevel,center,sde,char,alphabet)
input parameters:
    K:  the length of k-mer in integer number. 
    dat:  DNA/protein sequences,i.e, GCTGGCCTACGTGAAAC 
    decomLevel: decomposition level of stationary wavelet transform in integer.  
	char: the alphabet size where DNA is 4 and protein is 20. 
	alphabet: the actual alphabet for DNA/protein. For DNA, it is the set "ACGT". For protein, it is the set "ACDEFGHIKLMNPQRSTVWY".


output parameters:  
    testfeature: a matrix contains feature vector. This feature vector is the output mentioned in Step (3). 

Examples for usage:
Classification example:
> source("SDWTfunction.R")  #execute SDWT scripts which is in a file named SDWTfunction.R
> seqsAndLabel = readFile("traindata/file.lst")  
> testseqs = testReadFile("testdata/file.lst")
> trainfeature = TrainFeature(3,seqsAndLabel$seqs,3,4,DNAalphabet)
> testfeature = TestFeature(3,testseqs,3,trainfeature$means,trainfeature$SD,4,DNAalphabet)
> library(class)    # class library is needed to use knn
> predictResult = knn(trainfeature$trainseqfeature,testfeature,seqsAndLabel$seqLabel,k=1)


-------------------------------------------------------------------

Clustering example:
> source("SDWTfunction.R") #execute SDWT scripts which is in a file named SDWTfunction.R
> seqsAndLabel = readFile("cluster/file.lst")
> feature = Feature(3,seqsAndLabel$seqs,3,4,DNAalphabet)
> KmeansResult = kmeans(feature,100)

----------------------------------------------------------------------

