Added documentation for use

README.md

@@ -33,7 +33,100 @@ python setup.py install
 
 ```
 
+
 ## How to use
 
-Coming soon!
+The workflow for using quLATi is:
+
+* solve the eigenproblem for the mesh
+* set the data, kernel, and mean function
+* optimize the hyperparameters
+* make predictions
+
+The atrial mesh must be defined by numpy arrays X (vertices/nodes) and Tri (triangles/faces, indexed from zero). The mesh must be manifold.
+
+```python
+from qulati import gpmi, gpmi_rr, eigensolver
+```
+
+### Solve the eigenproblem
+
+For a mesh with 5 holes (4 pulmonary veins and 1 mitral valve), where 10 layers of mesh elements are to be appeneded to the edges representing these holes, the Laplacian eigenvalue problem can be solved for the 256 smallest eigenvalues with:
+
+```python
+Q, V, gradV, centroids = eigensolver(X, Tri, holes = 5, layers = 10, num = 256)
+```
+
+`Q` are the 256 smallest eigenvalues, and `V` are the corresponding eigenfunction values at vertex and centroid locations. The gradient of the eigenfunctions at face `centroids` are given by `gradV`.
+
+Note that this problem only needs solving a single time given a specific mesh, so results ought to be saved for future use.
+
+The class for doing the interpolation can then be intialized with
+
+```python
+# model with reduced rank efficiency
+model = gpmi_rr.Matern(X, Tri, Q, V, gradV)
+
+# slower, but more general modelling is possible
+#model = gpmi.Matern(X, Tri, Q, V, gradV)
+```
+
+### Set the data
+
+For observations (preferably standardized) defined at vertices and centroids, data can be set using
+
+```python
+# when using gpmi_rr model
+model.set_data(obs, vertices)
+
+# when using gpmi model
+#model.set_data(obs, obs_std, vertices)
+```
+
+where `vertices` is a zero indexed integer array referencing which vertex or face centroid an observation belongs to. Observations can be assigned to vertices with indices `0:X.shape[0]` and assigned to face centroids with indices `X.shape[0] + Tri_index` (where `Tri_index` refers to faces defined in `Tri`).
 
+For the Matern kernel class, the kernel smoothness and explicit mean function must both be set:
+
+```python
+model.kernelSetup(smoothness = 3./2.)
+model.setMeanFunction() # zero for gpmi.Matern class
+```
+
+### Optimization
+
+To optimize the kernel hyperparameters:
+
+```python
+# optimize the nugget
+model.optimize(nugget = None, restarts = 5)
+
+# fix the nugget to 0.123
+#model.optimize(nugget = 0.123, restarts = 5)
+```
+
+
+### Predictions
+
+Predictions at vertices and centroids can be obtained with:
+
+```python
+pred_mean, pred_stdev = model.posterior()
+```
+
+where the posterior mean and standard deviation are returned (vertex predictions are indexed `0:X.shape[0]`, centroid predictions are indexed `X.shape[0]:(X.shape[0] + Tri.shape[0]`).
+
+The posterior mean of the gradient for face centroids, calculated from the gradients of the eigenfunctions, can be obtained with
+
+```python
+grad_pred = model.posteriorGradient()
+```
+
+Statistics on the magnitude of the posterior gradient can be obtained with
+
+```python
+# for all face centroids
+mag_stats = model.gradientStatistics()
+
+# for specific centroids given by centroid_index
+#mag_stats = model.gradientStatistics(centroid_index)
+```

qulati/gpmi.py

@@ -10,7 +10,7 @@ class splinesAndMatern(AbstractModel)
       class basisAndMatern(AbstractModel)
 
    Although the covariance matrix is reduced-rank, the covariance matrix is formed and used with regular log-likelihood and prediction equations.
-   This is to allow generality, such that we can included gradient observations and auxillary inputs.
+   This is to allow generality, such that we can include gradient observations and auxillary inputs (such as pacing value).
 
 
    Created: 03-Feb-2020

setup.py

@@ -1,7 +1,7 @@
 from setuptools import setup
 
 setup(name = 'qulati',
-      version = '0.1',
+      version = '1.0',
       description = 'Quantifying Uncertainty in Local Activation Time Interpolation',
       url = 'http://github.com/samcoveney/quLATi',
       author = 'Sam Coveney',