From 1a99bcf64de99f9deccadeb44a20eb72fe0a4dad Mon Sep 17 00:00:00 2001
From: Mariana P Braga <mpiresbr@gmail.com>
Date: Wed, 28 Jan 2026 17:40:45 +0100
Subject: [PATCH 1/2] Update R interface page

---
 docs/R-interface/index.md |  12 -----
 docs/r-interface.md       | 106 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 106 insertions(+), 12 deletions(-)
 delete mode 100644 docs/R-interface/index.md
 create mode 100644 docs/r-interface.md

diff --git a/docs/R-interface/index.md b/docs/R-interface/index.md
deleted file mode 100644
index 119be57..0000000
--- a/docs/R-interface/index.md
+++ /dev/null
@@ -1,12 +0,0 @@
----
-id: r
-sidebar_position: 5
----
-
-# R interface
-
-`treepplr` is an R package for using TreePPL:
-
-  - [Download *treepplr* here](https://github.com/treeppl/treepplr)
-  - [Coin-flipping example using *treepplr*](https://treeppl.org/treepplr/articles/coin-example.html)
-  - [Host-repertoire model using *treepplr*](https://treeppl.org/treepplr/articles/hostrep-example.html)
diff --git a/docs/r-interface.md b/docs/r-interface.md
new file mode 100644
index 0000000..37bf29a
--- /dev/null
+++ b/docs/r-interface.md
@@ -0,0 +1,106 @@
+---
+layout: default
+id: r
+sidebar_position: 5
+---
+
+# R interface
+
+`treepplr` is an interface for using the TreePPL program. All functions start
+with `tp_` to easily distinguish them from functions from other packages.
+
+The three necessary parts for doing analysis with TreePPL are: model, data and 
+inference machinery. 
+
+## Model
+
+You can choose a model in TreePPL language from our 
+[library](https://treeppl.org/docs/model-library) or you can write your own model.
+
+To list all available models in our library, use `tp_model_library()` to retrieve
+the models within the [TreePPL github repository](https://github.com/treeppl/treeppl/tree/main/models). 
+
+```r
+model_lib <- tp_model_library()
+````
+To use one of these models you just need its name in `model_lib$model_name`.
+
+If you want to use your own custom model, you will need to write it in TreePPL 
+language and pass it to an R object that contains either the full path to the 
+`.tppl` file containing the model, or a string with the full model.
+
+```r
+# import a model from file
+model_path <- "path/to/my_model.tppl"
+```
+
+## Data
+
+<!-- waiting -->
+<!-- Each model accepts specific data types. There is a helper function that tells -->
+<!-- you which data input a given model needs. -->
+
+<!-- ```{r} -->
+<!-- tp_expected_input() -->
+<!-- ``` -->
+
+TreePPL only reads a custom JSON format, so `treepplr` converts a variety of
+input data to this format and writes to file, which will then be used by TreePPL.
+Here are some examples:
+
+```r
+# for models that only need a phylogenetic tree
+phylo <- ape::read.tree(file = "path/to/your/file.tre")
+data_path <- tp_data(data_input = phylo)
+
+# or sequence data
+fasta_file <- "path/to/your/file.fasta"
+data_path <- tp_data(data_input = fasta_file)
+```
+
+As for models, you can also use test datasets from the TreePPL library by passing
+the name of the model (we'll come back to this later).
+
+## Inference method
+
+TreePPL offers a variety of inference methods. Different methods work best for
+different models. See the [model library](https://treeppl.org/docs/model-library)
+for our recommendations of which inference methods to choose for each model.
+
+<!-- waiting -->
+<!-- For a full list of inference methods supported by TreePPL run: -->
+
+<!-- ```{r} -->
+<!-- tp_compile_options() -->
+<!-- ``` -->
+
+
+## Compilation
+
+Once you have chosen the model and the inference method you want to use, you can
+compile your model to en executable that also contains the necessary machinery
+to run the chosen inference method.
+
+```r
+# Using a model from the library and a Sequential Monte Carlo method
+exe_path <- tp_compile(model = "crbd", method = "smc-apf", particles = 10000)
+
+# Using a custom model and a Markov chain Monte Carlo method
+exe_path <- tp_compile(model = model_path, method = "mcmc-lightweight",
+                       iterations = 10000)
+```
+
+
+## Running 
+
+Now you are ready to run your analysis. All you have to do is to pass your data
+to the compiled executable and choose how many independent runs you want to do.
+
+```r
+output <- tp_run(compiled_model = exe_path, data = data_path, n_runs = 4)
+```
+
+<!-- ## Convergence -->
+
+<!-- ## Post-processing -->
+

From d270fe62e731c9a809f3589d75ea4600b73dc8ee Mon Sep 17 00:00:00 2001
From: Mariana P Braga <mpiresbr@gmail.com>
Date: Fri, 30 Jan 2026 16:55:00 +0100
Subject: [PATCH 2/2] Update R interface page

---
 docs/r-interface.md | 23 +++++++++++++++++++++--
 1 file changed, 21 insertions(+), 2 deletions(-)

diff --git a/docs/r-interface.md b/docs/r-interface.md
index 37bf29a..d65dd3e 100644
--- a/docs/r-interface.md
+++ b/docs/r-interface.md
@@ -100,7 +100,26 @@ to the compiled executable and choose how many independent runs you want to do.
 output <- tp_run(compiled_model = exe_path, data = data_path, n_runs = 4)
 ```
 
-<!-- ## Convergence -->
 
-<!-- ## Post-processing -->
+## Convergence
+
+Then you can parse your output to produce a data frame and check for convergence.
+
+```r
+# If using SMC
+output_df_smc <- tp_parse_smc(output)
+
+tp_smc_convergence(output_df_smc)
+```
+
+```r
+# If using MCMC
+output_df_mcmc <- tp_parse_mcmc(output)
+```
+
+
+## Post-processing
+
+Different models produce different outputs and thus require different post-processing.
+See the model-specific tutorials for ways to process your TreePPL output.