docs: Document usage in R with reticulate (#1227)

* docs: Document usage in R with `reticulate`

* Update docs/how-to.md

* Revert "Update docs/how-to.md"

This reverts commit e0e7351.

.changes/unreleased/Documentation-20241129-214818.yaml

@@ -0,0 +1,5 @@
+kind: Documentation
+body: survey_data
+time: 2024-11-29T21:48:18.300822-06:00
+custom:
+    Issue: "1227"

code_samples/citric.R

@@ -0,0 +1,8 @@
+# start example
+> library(reticulate)
+> reticulate::use_virtualenv("venv")
+> reticulate::source_python("export_ls_responses.py")
+> py$survey_data
+  submitdate lastpage startlanguage        seed     G01Q01 G01Q02 G02Q03 G02Q03[filecount]
+1      [nan]      [1]        ['en'] [245240561] ['lalala']    [5]  [nan]             [nan]
+# end example

code_samples/reticulate.py

@@ -0,0 +1,26 @@
+"""Use reticulate to export LimeSurvey data to R."""
+
+# ruff: noqa: T201
+
+from __future__ import annotations
+
+# start example
+# export_ls_responses.py
+import io
+
+import citric
+import pandas as pd
+
+client = citric.Client(
+    "http://localhost:8001/index.php/admin/remotecontrol",
+    "iamadmin",
+    "secret",
+)
+data = client.export_responses(123456, file_format="csv")
+survey_data = pd.read_csv(
+    io.BytesIO(data),
+    delimiter=";",
+    parse_dates=["datestamp", "startdate", "submitdate"],
+    index_col="id",
+)
+# end example

docs/how-to.md

@@ -79,10 +79,29 @@ This library doesn't implement all RPC methods, so if you're in dire need of usi
 :end-before: end example
 ```
 
+## Use with _R_ via [reticulate]
+
+If you prefer using _R_ instead of _Python_, you can use the `reticulate` package to get survey data downloaded with `citric`.
+
+Write a Python script to get the survey data, making sure to assign a dataframe to a variable (e.g., `survey_data`):
+
+```{literalinclude} ../code_samples/reticulate.py
+:start-after: start example
+:end-before: end example
+```
+
+Then, in _R_, use the `reticulate` package to call the Python script and use the `df` variable:
+
+```{literalinclude} ../code_samples/citric.R
+:start-after: start example
+:end-before: end example
+```
+
 ## Notebook samples
 
 - [Import a survey file from S3](https://github.com/edgarrmondragon/citric/blob/main/docs/notebooks/import_s3.ipynb)
 - [Download responses and analyze them with DuckDB](https://github.com/edgarrmondragon/citric/blob/main/docs/notebooks/duckdb.ipynb)
 - [Download responses and save them to a SQLite database](https://github.com/edgarrmondragon/citric/blob/main/docs/notebooks/pandas_sqlite.ipynb)
 
 [rc2api]: https://api.limesurvey.org/classes/remotecontrol_handle.html
+[reticulate]: https://rstudio.github.io/reticulate/

docs/index.md

@@ -42,6 +42,7 @@ But also, the latest 5.x and 6.x are tested continuously and are expected to wor
 - [Use a different authentication plugin](how-to.md#use-a-different-authentication-plugin)
 - [Get files uploaded to a survey and move them to S3](how-to.md#get-files-uploaded-to-a-survey-and-move-them-to-s3)
 - [Use the raw `Client.session` for low-level interaction](how-to.md#use-the-session-attribute-for-low-level-interaction)
+- [Use with _R_ via `reticulate`](how-to.md#use-with-r-via-reticulate)
 - [Notebook samples](how-to.md#notebook-samples)
 
 ```{toctree}