----------------------------------------------------------------------------
README file for sample code on Semi-supervised Coclustering for Heterogeneous Data
----------------------------------------------------------------------------

YANHUA CHEN 
July, 2010
Version 1.1

This Matlab package implements and tests semi-supervised non-negative
matrix factorization (SS-NMF) algorithm for clustering heterogeneous data. 
This package is associated with the articles:

(1)Yanhua Chen, Lijun Wang, and Ming Dong, Non-negative Matrix Factorization for Semisupervised
Heterogeneous Data Coclustering, IEEE Transactions on Knowledge and Data Engineering (TKDE),
Vol. 22, No. 10, pp. 1459-147, 2010
(2) Yanhua Chen, Ming Dong, and Wanggen Wan, Image Co-clustering with Multi-modality Features
and User Feedbacks, Proc. of the ACM International Conference on Multimedia(ACM MM), pp.
689-692, Beijing, China, 2009 (acceptance rate: 28%)
(3)Yanhua Chen, Lijun Wang, and Ming Dong, A Matrix-based Approach for Semi-supervised
Document Co-clustering, Proc. of the ACM 17th Conference on Information and Knowledge
Management (CIKM), pp. 1523-1524, Napa Valley, CA, USA, 2008 (acceptance rate: 16%)

IF YOU USE THIS PACKAGE IN PUBLISHED RESEARCH, PLEASE CITE THE ABOVE
PAPERS. THANKS!

----------------------------------------------------------------------------
Version history
----------------------------------------------------------------------------

1.0	July, 2008	Original version. 

1.1	July, 2010	Modifications/improvements:
			- Improved the documentation somewhat and added a detailed implementation.


	


----------------------------------------------------------------------------
List of contents of package (code)
----------------------------------------------------------------------------

Test_multiplerelationsHighorderCoclustering1.m       - main file 
Go_webimage_test_2feature.m                          - for building original relational matrix
GenConstraints_LDA.m                                 - for generating constraits
DistanceMatrixLearning_LDA_Multi.m                   - for learning new relational matirx
HighorderMultiNMF.m                                  - for claculating NMF clustering and modality importance
ComputeAc.m                                          - for computing clustering accuracy
mapminmax.m, LDA_regular.m, OptiErrorMulti.m         - supplementary files
  


----------------------------------------------------------------------------
Using the package
----------------------------------------------------------------------------


(1) DOWNLOADING THE ZiP FILE and UNZIP.

(2) RUNNING THE Matlab CODE PROCEDURE:


(A) Build Relational matrix Rs 
[Rs is combination of 2 or more than 2 matrix (relations), row is number of samples,
column is number of features]. If there is two relations, the Matrix Rs should have #of rows= samples*2. 
"Go_webimage_test_2feature.m" can build "Rs". 
In this example, there exists two modalities, each with 600 samples. First one size =600*45 and the other one size=600*42. 
Thus "Rs" becomes a large matrix with size 600*2=1200 samples with 45 features 
(note that the second one 600*42 also has 45 columns with 43-45 columns equal to 0).

(B) Run "Test_multiplerelationsHighorderCoclustering1.m":
Parameters:
axis_x is the constraints percentage (such as 1 is 1%);
nSamples is total number of samples;
label is class label of each samples vector;
bound is size of bound of each types of samples;
alpha_c is importance of each modality.
 (i)calling function "GenConstraints_LDA()", generate constraints based on axis_x;
 (ii)calling function "DistanceMatrixLearning_LDA_Multi(pa1, pa2,...)", get the new Relation Matrices "YRs".
 (iii)calling function "HighorderMultiNMF.m", obtain NMF co-clustering accuracy and each modality importance.

(C) The results are in "meanNMFAC, maxNMFAC, and alpha_c" variables, the first two variables give clustering accuracy, and the last 
one gives the importance of modality.

(D) Notice that experiment results are based on the following parameters, for example, 
(i) running times "tt"=10; 
(ii)learning distance matrix "L", based on iterative time=20;
(iii)NMF learning iterative times=2000.
You can change these three parameters based on your data.

----------------------------------------------------------------------------
Using/Testing YOUR DATA
----------------------------------------------------------------------------


Of course, your can test your data by just call/modify our program as a function.



----------------------------------------------------------------------------
Problems?
----------------------------------------------------------------------------

In case of questions or problems, do not hesitate to contact me,
preferrably by email at chenyanh@wayne.edu. However, I would
appreciate it if you would take the time to examine the code a little
and try to figure out the problem yourself. If you cannot figure it
out, at least try to provide as much info as possible on the nature of
the problem (including your exact commands and the error messages), so
that I can have a chance to help you.


----------------------------------------------------------------------------
Disclaimer
----------------------------------------------------------------------------

This software is provided as-is, and there are no guarantees
that it fits your purposes or that it is bug-free. Use it at your own 
risk! 

