From 3c62d2d3b1600c9ee86c29e54b3b5f53de65de3a Mon Sep 17 00:00:00 2001
From: BlackLight <blacklight@autistici.org>
Date: Thu, 18 Nov 2010 19:50:53 +0100
Subject: [PATCH] README added

---
 README | 80 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)
 create mode 100644 README

diff --git a/README b/README
new file mode 100644
index 0000000..16840e0
--- /dev/null
+++ b/README
@@ -0,0 +1,80 @@
+fkmeans is a tiny C library that allows you to perform k-means clustering
+algorithm over arbitrary sets of n-dimensional data. All you need to do is:
+
+- Include the file kmeans.h in your sources;
+
+- Consider your data set as a vector of vectors of double items (double**),
+  where each vector is an n-dimensional item of your data set;
+
+- If you want to perform the k-means algorithm over your data and you already
+  know the number k of clusters there contained, or its estimate, you want to
+  execute some code like this (in this example, the data set is 3-dimensional,
+  i.e. it contains N vectors whose size is 3, and we know it contains n_clus
+  clusters):
+
+    kmeans_t *km;
+    double **dataset;
+    ...
+    km = kmeans_new ( dataset, N, 3, n_clus );
+    kmeans ( km );
+    ...
+    kmeans_free ( km );
+
+  If you don't already know the number of clusters contained in your data set,
+  you can use the function kmeans_auto() for automatically attempting to find
+  the best one using Schwarz's criterion. Be careful, this operation can be very
+  slow, especially if executed on data set having many elements. The example
+  above would simply become something like:
+
+    kmeans_t *km;
+    double **dataset;
+    ...
+    km = kmeans_auto ( dataset, N, 3 );
+    ...
+    kmeans_free ( km );
+
+- Once the clustering has been performed, the clusters of data can be simply
+  accessed from your kmeans_t* structure, as they are held as a double*** field
+  named "clusters". Each vector in this structure represents a cluter, whose
+  size is specified in the field cluster_sizes[i] of the structure. Each cluster
+  contains the items that form it, each of it is an n-dimensional vector. The
+  number of clusters is specified in the field "k" of the structure, the
+  number of dimensions of each element is specified in the field "dataset_dim"
+  and the number of elements in the originary data set is specified in the field
+  "dataset_size". So, for example:
+
+    for ( i=0; i < km->k; i++ )
+    {
+	    printf ( "cluster %d: [ ", i );
+
+	    for ( j=0; j < km->cluster_sizes[i]; j++ )
+	    {
+		    printf ( "(" );
+
+		    for ( k=0; k < km->dataset_size; k++ )
+		    {
+			    printf ( "%f, ", km->clusters[i][j][k] );
+		    }
+
+		    printf ( "), ");
+		}
+
+	    printf ( "]\n" );
+	}
+
+  The library however already comes with a sample implementation, contained in
+  "test.c", and typing "make" this example will be built;
+
+- After you write your source, remember to include the file "kmeans.c",
+  containing the implementation of the library, in the list of your sources
+  files;
+
+- That's all. Include "kmeans.h", write your code using
+  kmeans_new()+kmeans()+kmeans_free() or kmeans_auto()+kmeans_free(), explore
+  your clusters, remember to include "kmeans.c" in the list of your source
+  files, and you're ready for k-means clustering.
+
+Author: Fabio "BlackLight" Manganiello,
+        <blacklight@autistici.org>,
+        http://0x00.ath.cx
+