From b839ae1a2182fba1dd7a11eace60cb8c333068c0 Mon Sep 17 00:00:00 2001
From: Roberto S <rhobis@gmail.com>
Date: Thu, 4 Jan 2018 22:59:55 +0100
Subject: [PATCH] more and more clear information

---
 README.md | 64 ++++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 49 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index d9ea998..8b01f32 100644
--- a/README.md
+++ b/README.md
@@ -1,29 +1,63 @@
-[![CRAN\_Status\_Badge](https://www.r-pkg.org/badges/version/convergenceClubs)](https://cran.r-project.org/package=convergenceClubs)
+ConvergenceClubs
+======================================================
 
-# Description 
-This package contains R code to find Convergence Clubs of regions.
+[![CRAN\_Status\_Badge](https://www.r-pkg.org/badges/version/ConvergenceClubs)](https://cran.r-project.org/package=ConvergenceClubs)
 
-The main functions are:
+Description 
+-----------------
 
-* findClubs(): applies Phillips and Sul clustering procedure to find clubs of convergence;
-* mergeClubs(): applies Phillips and Sul or von Lyncker and Thoennessen merging procedures to a list of clubs generated by findClubs().
+ConvergenceClubs provides functions for clustering regions that form convergence clubs, 
+according to the definition of Phillips and Sul (2009) <doi:10.1002/jae.1080>.
 
+The main functions are:
 
+- `findClubs()`: finds clubs of convergence, given a dataset with regions in rows and
+    years in columns, returning an object of class `convergence.clubs`. 
+- `mergeClubs()`: takes as argument an object of class `convergence.clubs` and
+    applies the clustering procedure to the convergence clubs contained in the argument,
+    according to either Phillips and Sul (2009) or  von Lyncker and Thoennessen (2016) procedure.
 
 
-# Installation
+Installation
+------------
 
-To install the package, simply run the following code:
+To install the package from CRAN, simply run the following code in *R*:
+``` r
+install.packages("ConvergenceClubs")
+```
 
+Or, if you want to install the development version from GitHub:
 ``` r
 # if not present, install 'devtools' package
-if(!('devtools' %in% installed.packages())) install.packages("devtools")
+install.packages("devtools")
+devtools::install_github("rhobis/ConvergenceClubs")
+```
+
+Usage
+-----
+
+``` r
+library(ConvergenceClubs)
+
+data("countryGDP")
+
+# Cluster Countries using GDP from year 2000 to year 2014, with 2014 as reference year
+clubs <- findClubs(countryGDP, dataCols=2:35, regions = 1, refCol=35, 
+                    time_trim = 1/3, cstar = 0, HACmethod = "AQSB")
+summary(clubs)
+
+# Merge clusters using Phillips and Sul (2009) method
+mclubs <- mergeClubs(clubs, mergeMethod='PS', mergeDivergent=FALSE)
+summary(mclubs)
+
+# Merge clusters using von Lyncker and Thoennessen (2016) method
+mclubs <- mergeClubs(clubs, mergeMethod='vLT', mergeDivergent=FALSE)
+summary(mclubs)
 
-# install ConvergenceClubs package
-library(devtools)
-install_github("rhobis/ConvergenceClubs")
 ```
 
-# More
-* Please, report any bug or issue [here](https://github.com/rhobis/ConvergenceClubs/issues)
-* For more information, please write to roberto.sichera@unipa.it 
+More
+----
+
+- Please, report any bug or issue [here](https://github.com/rhobis/ConvergenceClubs/issues).
+- For more information, please contact the manteiner at `roberto.sichera@unipa.it`.