----------------------------------------------------------------------------
README file for sample code on SS-NMF for Homogeneous Data
----------------------------------------------------------------------------

YANHUA CHEN 
July, 2011
Version 1.2

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

(1)Yanhua Chen, Manjeet Rege, Ming Dong and Jing Hua, 
"Non-negative Matrix Factorization for Semi-supervised Data Clustering", 
Journal of Knowledge and Information Systems (Springer),
Vol. 17, No. 3, pp. 355 - 379, 2008. (invited as a best paper of ICDM 07, 
conference version: "Incorporating User provided Constraints into Document Clustering", 
was published in Proc. of IEEE International Conference on Data Mining, Omaha, NE, USA
pp. 103-112, 2007 as a Regular paper, acceptance rate 7.2%). 
(2) Yanhua Chen, Manjeet Rege, Ming Dong and Farshad Fotouhi, 
"Deriving Semantics for Image Clustering from Accumulated User Feedbacks", 
Proc. of ACM Multimedia, Germany, pp. 313-316, 2007 (acceptance rate: 24%). 


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

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

1.0	July, 2007	Original version. 

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

1.2     July, 2011      Remove a random initialization bug.
	


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


  icdm2007_clustering_semi_nmf_toydata.m       - main file 
  bestMap.m                                    - for computing clustering accuracy
  hungarian.m                                  - for computing clustering accuracy
  MutualInfo.m                                 - for caculating normalized mutual information
  


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


(1) DOWNLOADING THE ZiP FILE and UNZIP.

(2) RUNNING THE NMF EXPERIMENTS:


>>icdm2007_clustering_semi_nmf_toydata;

(3) OUTPUT RESULTS:

(i)Toy data (2 classes), 
(ii)Convergence of NMF and SS-NMF objective function, 
(iii)Accuracy and Mutual Information of NMF and SS-NMF.


----------------------------------------------------------------------------
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! 
