Document get_r_func()

Author: khaeru

doc/api/r.rst

@@ -0,0 +1,62 @@
+Integrate R code (:mod:`.util.r`)
+*********************************
+
+Developers working with :mod:`message_ix_models` can integrate existing R codes or use R to perform data processing related to building, running, and reporting models.
+:mod:`message_ix_models.util.r` provides utility code to help with using :mod:`rpy2` to achieve this integration.
+
+Two patterns are supported.
+To use either, place a  :file:`r_code.R` *in-line* in the source tree, either in :mod:`message_ix_models`, :mod:`message_data`, or another package::
+
+    message_ix_models/
+        project/
+            example/
+                __init__.py
+                module_a.py
+                module_b.py
+                r_code.R
+
+The patterns are:
+
+.. contents::
+   :local:
+   :backlinks: none
+
+
+R ‘Modules’
+===========
+
+In this pattern, :func:`get_r_func` is used to source (i.e. import or run) R code from a file that defines one or more functions or other objects.
+:func:`get_r_func` returns this function, which can then be called from Python code.
+In this way, the R source file functions somewhat like a Python **‘module’**, while still being lighter weight than a full, installable R package.
+
+.. code-block:: R
+   :caption: :file:`r_code.R`
+
+   # R file that defines functions and other entry points
+
+   mul <- function(x, y) {
+     # Multiply operands
+     return(x, y)
+   }
+
+.. code-block:: python
+
+   from message_ix_models.util import get_r_func
+
+   # Source r_code.R, retrieve the function named "mul"
+   mul = get_r_func("message_ix_models.project.example.r_code:mul")
+
+   # Call the function
+   result = mul(1.2, 3.4)
+
+   # …use `result` in further Python code
+
+.. currentmodule:: message_ix_models.util.r
+
+.. autofunction:: get_r_func
+
+
+Stand-alone scripts
+===================
+
+In this method, the R script is placed inline.

doc/index.rst

@@ -74,6 +74,7 @@ Commonly used classes may be imported directly from :mod:`message_ix_models`.
    api/tools-messagev
    api/data-sources
    api/util
+   api/r
    api/testing
    api/workflow
 

message_ix_models/util/r.py

@@ -1,5 +1,6 @@
 """Utilities for compatibility with R code."""
 import re
+from typing import Any
 
 from .common import MESSAGE_DATA_PATH, MESSAGE_MODELS_PATH
 
@@ -30,11 +31,21 @@ def source_module(path):
         r.source(str(path))
 
 
-def get_r_func(path):
+def get_r_func(path: str) -> Any:
+    """Source R code and return an R function or other object.
+
+    Parameters
+    ----------
+    path : str
+        Identifies the path to the R ‘module’ and the name of the object to be loaded.
+    """
     from rpy2.robjects import r
 
+    # Separate R code path and object name
     path, name = path.rsplit(":", maxsplit=1)
 
+    # Source the R code
     source_module(path)
 
+    # Retrieve and return the object
     return r[name]