diff --git a/README.Rmd b/README.Rmd
new file mode 100644
index 0000000000000000000000000000000000000000..6ff6aca2461928749c93e49f52e17b290c670ea3
--- /dev/null
+++ b/README.Rmd
@@ -0,0 +1,82 @@
+---
+output: github_document
+---
+
+<!-- README.md is generated from README.Rmd. Please edit that file -->
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+ collapse = TRUE,
+ comment = "#>",
+ fig.path = "man/figures/README-",
+ out.width = "100%"
+)
+```
+
+# gmGeostats
+
+<!-- badges: start -->
+<!-- badges: end -->
+
+The goal of gmGeostats is to provide a unified framework for the geostatistical analysis of multivariate data from any statistical scale, e.g. data honoring a ratio scale, or with constraints such as spherical or compositional data.
+
+This R package offers support for geostatistical analysis of multivariate data, in particular data with restrictions, e.g. positive amounts data, compositional data, distributional data, microstructural data, etc. It includes descriptive analysis and modelling for such data, both from a two-point Gaussian perspective and multipoint perspective. The package is devised for supporting 3D, multi-scale and large data sets and grids. This is a building block of the suite of HIF geometallurgical software.
+
+
+## Installation
+
+You can install the released version of gmGeostats from [CRAN](https://CRAN.R-project.org) with:
+
+``` r
+install.packages("gmGeostats")
+```
+
+## Example
+
+Read the [./vignettes/gmGeostats.html](vignette) for an extended scheme of the package functionality. The fundamental steps are:
+
+```{r example}
+## load the package and its dependencies
+library(gmGeostats)
+
+## read your data, identify coordinates and sets of variables
+data("Windarling") # use here some read*(...) function
+colnames(Windarling)
+X = Windarling[,c("Easting", "Northing")]
+Z = Windarling[,c(9:12,14,16)]
+
+## declare the scale of each set of variables
+Zc = compositions::acomp(Z) # other scales will come in the future
+
+## pack the data in a gmSpatialModel object using an appropriate
+# make.** function
+gsm = make.gmCompositionalGaussianSpatialModel(
+ data = Zc, coords = X, V = "alr", formula = ~1
+)
+```
+
+From this point on, what you do depends on which model do you have in mind. Here we briefly cover the case of a Gaussian model, though a multipoint approach can also be tackled with function `make.gmCompositionalMPSSpatialModel()` providing a training image as model. See [./vignettes/gmGeostats.html](vignette) for details.
+
+A structural analysis can be obtained in the following steps
+```{r structural}
+## empirical variogram
+vge = variogram(gsm)
+
+## model specification
+vm = gstat::vgm(model="Sph", range=25, nugget=1, psill=1)
+# you can use gstat specifications!
+
+## variogram fit
+gsm.f = fit_lmc(v = vge, g = gsm, model = vm)
+
+## plot
+variogramModelPlot(vge, model = gsm.f)
+```
+
+This model can then be validated, interpolated and/or simulated. The workflow for each of these tasks is always:
+
+1.- define some method parameters with a tailored function, e.g. `LeaveOneOut()` for validation, `KrigingNeighbourhood()` for cokriging or `SequentialSimulation()` for sequential Gaussian Simulation
+2.- if desired, define some new locations where to interpolate or simulate, using `expand.grid()` or `sp::GridTopology()` or similar
+3.- call an appropriate function, specifying the model, potential new data, and the parameters created in the preceding steps; e.g. `validate(model, pars)` for validation, or `predict(model, newdata, pars)` for interpolation or validation
+
+More information can be found in [./vignettes/gmGeostats.html](vignette).
\ No newline at end of file
diff --git a/README.md b/README.md
index fc43a9db9a4ec5f384173bb7e95fb8f7db6452d3..362d77f8b741a689353c65cd6c7f559112dda4ca 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,105 @@
-# gmGeostats: Geostatistics for Compositional Analysis with R
-This R package offers support for geostatistical analysis of multivariate data, in particular data with restrictions, e.g. positive amounts data, compositional data, distributional data, microstructural data, etc. It includes descriptive analysis and modelling for such data, both from a two-point Gaussian perspective and multipoint perspective. The package is devised for supporting 3D, multi-scale and large data sets and grids. This is a building block of the suite of HIF geometallurgical software.
+<!-- README.md is generated from README.Rmd. Please edit that file -->
-## More information
+# gmGeostats
-Read the [./vignettes/gmGeostats.html](vignette) for a scheme of the package functionality.
+<!-- badges: start -->
+<!-- badges: end -->
+
+The goal of gmGeostats is to provide a unified framework for the
+geostatistical analysis of multivariate data from any statistical scale,
+e.g. data honoring a ratio scale, or with constraints such as spherical
+or compositional data.
+
+This R package offers support for geostatistical analysis of
+multivariate data, in particular data with restrictions, e.g. positive
+amounts data, compositional data, distributional data, microstructural
+data, etc. It includes descriptive analysis and modelling for such data,
+both from a two-point Gaussian perspective and multipoint perspective.
+The package is devised for supporting 3D, multi-scale and large data
+sets and grids. This is a building block of the suite of HIF
+geometallurgical software.
+
+## Installation
+
+You can install the released version of gmGeostats from
+[CRAN](https://CRAN.R-project.org) with:
+
+``` r
+install.packages("gmGeostats")
+```
+
+## Example
+
+Read the [./vignettes/gmGeostats.html](vignette) for an extended scheme
+of the package functionality. The fundamental steps are:
+
+``` r
+## load the package and its dependencies
+library(gmGeostats)
+#> Warning: replacing previous import 'compositions::fit.lmc' by 'gstat::fit.lmc'
+#> when loading 'gmGeostats'
+#> Welcome to 'gmGeostats', a package for multivariate geostatistical analysis.
+#> Note: use 'fit_lmc' instead of fit.lmc
+
+## read your data, identify coordinates and sets of variables
+data("Windarling") # use here some read*(...) function
+colnames(Windarling)
+#> [1] "Hole_id" "Sample.West" "Sample.East" "West" "East"
+#> [6] "Easting" "Northing" "Lithotype" "Fe" "P"
+#> [11] "SiO2" "Al2O3" "S" "Mn" "CL"
+#> [16] "LOI"
+X = Windarling[,c("Easting", "Northing")]
+Z = Windarling[,c(9:12,14,16)]
+
+## declare the scale of each set of variables
+Zc = compositions::acomp(Z) # other scales will come in the future
+
+## pack the data in a gmSpatialModel object using an appropriate
+# make.** function
+gsm = make.gmCompositionalGaussianSpatialModel(
+ data = Zc, coords = X, V = "alr", formula = ~1
+)
+```
+
+From this point on, what you do depends on which model do you have in
+mind. Here we briefly cover the case of a Gaussian model, though a
+multipoint approach can also be tackled with function
+`make.gmCompositionalMPSSpatialModel()` providing a training image as
+model. See [./vignettes/gmGeostats.html](vignette) for details.
+
+A structural analysis can be obtained in the following steps
+
+``` r
+## empirical variogram
+vge = variogram(gsm)
+
+## model specification
+vm = gstat::vgm(model="Sph", range=25, nugget=1, psill=1)
+# you can use gstat specifications!
+
+## variogram fit
+gsm.f = fit_lmc(v = vge, g = gsm, model = vm)
+
+## plot
+variogramModelPlot(vge, model = gsm.f)
+```
+
+<img src="man/figures/README-structural-1.png" width="100%" />
+
+This model can then be validated, interpolated and/or simulated. The
+workflow for each of these tasks is always:
+
+1.- define some method parameters with a tailored function, e.g.
+`LeaveOneOut()` for validation, `KrigingNeighbourhood()` for cokriging
+or `SequentialSimulation()` for sequential Gaussian Simulation 2.- if
+desired, define some new locations where to interpolate or simulate,
+using `expand.grid()` or `sp::GridTopology()` or similar 3.- call an
+appropriate function, specifying the model, potential new data, and the
+parameters created in the preceding steps; e.g. `validate(model, pars)`
+for validation, or `predict(model, newdata, pars)` for interpolation or
+validation
+
+More information can be found in
+[./vignettes/gmGeostats.html](vignette).
diff --git a/man/figures/README-structural-1.png b/man/figures/README-structural-1.png
new file mode 100644
index 0000000000000000000000000000000000000000..834c1310700442142e8495bb62c6a2627021a5ed
Binary files /dev/null and b/man/figures/README-structural-1.png differ