.. _R-api:

======== R API

The MLflow R <https://www.r-project.org/about.html>_ API allows you to use MLflow Tracking <../tracking/index.html>, Projects <../projects/index.html> and Models <../models/index.html>_.

Prerequisites

To use the MLflow R API, you must install the MLflow Python package <https://pypi.org/project/mlflow/>_.

.. code-block:: bash

pip install mlflow

Installing with an Available Conda Environment example:

.. code-block:: bash

conda create -n mlflow-env python
conda activate mlflow-env
pip install mlflow

The above provided commands create a new Conda environment named mlflow-env, specifying the default Python version. It then activates this environment, making it the active working environment. Finally, it installs the MLflow package using pip, ensuring that MLflow is isolated within this environment, allowing for independent Python and package management for MLflow-related tasks.

Optionally, you can set the MLFLOW_PYTHON_BIN and MLFLOW_BIN environment variables to specify the Python and MLflow binaries to use. By default, the R client automatically finds them using Sys.which('python') and Sys.which('mlflow').

.. code-block:: bash

export MLFLOW_PYTHON_BIN=/path/to/bin/python
export MLFLOW_BIN=/path/to/bin/mlflow

You can use the R API to start the user interface <mlflow_ui_>, create experiment <mlflow_create_experiment_> and search experiments <mlflow_search_experiments_>, save models <mlflow_save_model.crate_>, run projects <mlflow_run_>_ and serve models <mlflow_rfunc_serve_>_ among many other functions available in the R API.

.. contents:: Table of Contents :local: :depth: 1

`build_context_tags_from_databricks_job_info`

Get information from a Databricks job execution context

Parses the data from a job execution context when running on Databricks in a non-interactive mode. This function extracts relevant data that MLflow needs in order to properly utilize the MLflow APIs from this context.

.. code:: r

build_context_tags_from_databricks_job_info(job_info)

Arguments

============ ====================================================== Argument Description ============ ====================================================== job_info The job-related metadata from a running Databricks job ============ ======================================================

Value

A list of tags to be set by the run context when creating MLflow runs in the current Databricks Job environment

`build_context_tags_from_databricks_notebook_info`

Get information from Databricks Notebook environment

Retrieves the notebook id, path, url, name, version, and type from the Databricks Notebook execution environment and sets them to a list to be used for setting the configured environment for executing an MLflow run in R from Databricks.

.. code:: r

build_context_tags_from_databricks_notebook_info(notebook_info)

.. _arguments-1:

Arguments

.. _value-1:

Value

A list of tags to be set by the run context when creating MLflow runs in the current Databricks Notebook environment

`mlflow_client`

Initialize an MLflow Client

Initializes and returns an MLflow client that communicates with the tracking server or store at the specified URI.

.. code:: r

mlflow_client(tracking_uri = NULL)

.. _arguments-2:

Arguments

`mlflow_create_experiment`

Create Experiment

Creates an MLflow experiment and returns its id.

.. code:: r

mlflow_create_experiment( name, artifact_location = NULL, client = NULL, tags = NULL )

.. _arguments-3:

Arguments

`mlflow_create_model_version`

Create a model version

.. code:: r

mlflow_create_model_version( name, source, run_id = NULL, tags = NULL, run_link = NULL, description = NULL, client = NULL )

.. _arguments-4:

Arguments

`mlflow_create_registered_model`

Create registered model

Creates a new registered model in the model registry

.. code:: r

mlflow_create_registered_model( name, tags = NULL, description = NULL, client = NULL )

.. _arguments-5:

Arguments

`mlflow_delete_experiment`

Delete Experiment

Marks an experiment and associated runs, params, metrics, etc. for deletion. If the experiment uses FileStore, artifacts associated with experiment are also deleted.

.. code:: r

mlflow_delete_experiment(experiment_id, client = NULL)

.. _arguments-6:

Arguments

`mlflow_delete_model_version`

Delete a model version

.. code:: r

mlflow_delete_model_version(name, version, client = NULL)

.. _arguments-7:

Arguments

`mlflow_delete_registered_model`

Delete registered model

Deletes an existing registered model by name

.. code:: r

mlflow_delete_registered_model(name, client = NULL)

.. _arguments-8:

Arguments

`mlflow_delete_run`

Delete a Run

Deletes the run with the specified ID.

.. code:: r

mlflow_delete_run(run_id, client = NULL)

.. _arguments-9:

Arguments

`mlflow_delete_tag`

Delete Tag

Deletes a tag on a run. This is irreversible. Tags are run metadata that can be updated during a run and after a run completes.

.. code:: r

mlflow_delete_tag(key, run_id = NULL, client = NULL)

.. _arguments-10:

Arguments

`mlflow_download_artifacts`

Download Artifacts

Download an artifact file or directory from a run to a local directory if applicable, and return a local path for it.

.. code:: r

mlflow_download_artifacts(path, run_id = NULL, client = NULL)

.. _arguments-11:

Arguments

`mlflow_end_run`

End a Run

Terminates a run. Attempts to end the current active run if run_id is not specified.

.. code:: r

mlflow_end_run( status = c("FINISHED", "FAILED", "KILLED"), end_time = NULL, run_id = NULL, client = NULL )

.. _arguments-12:

Arguments

`mlflow_get_experiment`

Get Experiment

Gets metadata for an experiment and a list of runs for the experiment. Attempts to obtain the active experiment if both experiment_id and name are unspecified.

.. code:: r

mlflow_get_experiment(experiment_id = NULL, name = NULL, client = NULL)

.. _arguments-13:

Arguments

`mlflow_get_latest_versions`

Get latest model versions

Retrieves a list of the latest model versions for a given model.

.. code:: r

mlflow_get_latest_versions(name, stages = list(), client = NULL)

.. _arguments-14:

Arguments

`mlflow_get_metric_history`

Get Metric History

Get a list of all values for the specified metric for a given run.

.. code:: r

mlflow_get_metric_history(metric_key, run_id = NULL, client = NULL)

.. _arguments-15:

Arguments

`mlflow_get_model_version`

Get a model version

.. code:: r

mlflow_get_model_version(name, version, client = NULL)

.. _arguments-16:

Arguments

`mlflow_get_registered_model`

Get a registered model

Retrieves a registered model from the Model Registry.

.. code:: r

mlflow_get_registered_model(name, client = NULL)

.. _arguments-17:

Arguments

`mlflow_get_run`

Get Run

Gets metadata, params, tags, and metrics for a run. Returns a single value for each metric key: the most recently logged metric value at the largest step.

.. code:: r

mlflow_get_run(run_id = NULL, client = NULL)

.. _arguments-18:

Arguments

`mlflow_get_tracking_uri`

Get Remote Tracking URI

Gets the remote tracking URI.

.. code:: r

mlflow_get_tracking_uri()

`mlflow_id`

Get Run or Experiment ID

Extracts the ID of the run or experiment.

.. code:: r

mlflow_id(object) list(list("mlflow_id"), list("mlflow_run"))(object) list(list("mlflow_id"), list("mlflow_experiment"))(object)

.. _arguments-19:

Arguments

========== ================================================== Argument Description ========== ================================================== object An mlflow_run or mlflow_experiment object. ========== ==================================================

`mlflow_list_artifacts`

List Artifacts

Gets a list of artifacts.

.. code:: r

mlflow_list_artifacts(path = NULL, run_id = NULL, client = NULL)

.. _arguments-20:

Arguments

`mlflow_load_flavor`

Load MLflow Model Flavor

Loads an MLflow model using a specific flavor. This method is called internally by mlflow_load_model <#mlflow-load-model>__ , but is exposed for package authors to extend the supported MLflow models. See https://mlflow.org/docs/latest/models.html#storage-format for more info on MLflow model flavors.

.. code:: r

mlflow_load_flavor(flavor, model_path)

.. _arguments-21:

Arguments

`mlflow_load_model`

Load MLflow Model

Loads an MLflow model. MLflow models can have multiple model flavors. Not all flavors / models can be loaded in R. This method by default searches for a flavor supported by R/MLflow.

.. code:: r

mlflow_load_model(model_uri, flavor = NULL, client = mlflow_client())

.. _arguments-22:

Arguments

Details

The URI scheme must be supported by MLflow - i.e. there has to be an MLflow artifact repository corresponding to the scheme of the URI. The content is expected to point to a directory containing MLmodel. The following are examples of valid model uris:

file:///absolute/path/to/local/model
file:relative/path/to/local/model
s3://my_bucket/path/to/model
runs:/<mlflow_run_id>/run-relative/path/to/model
models:/<model_name>/<model_version>
models:/<model_name>/<stage>

For more information about supported URI schemes, see the Artifacts Documentation at https://www.mlflow.org/docs/latest/tracking.html#artifact-stores.

`mlflow_log_artifact`

Log Artifact

Logs a specific file or directory as an artifact for a run.

.. code:: r

mlflow_log_artifact(path, artifact_path = NULL, run_id = NULL, client = NULL)

.. _arguments-23:

Arguments

.. _details-1:

Details

When logging to Amazon S3, ensure that you have the s3:PutObject, s3:GetObject, s3:ListBucket, and s3:GetBucketLocation permissions on your bucket.

Additionally, at least the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables must be set to the corresponding key and secrets provided by Amazon IAM.

`mlflow_log_batch`

Log Batch

Log a batch of metrics, params, and/or tags for a run. The server will respond with an error (non-200 status code) if any data failed to be persisted. In case of error (due to internal server error or an invalid request), partial data may be written.

.. code:: r

mlflow_log_batch( metrics = NULL, params = NULL, tags = NULL, run_id = NULL, client = NULL )

.. _arguments-24:

Arguments

`mlflow_log_metric`

Log Metric

Logs a metric for a run. Metrics key-value pair that records a single float measure. During a single execution of a run, a particular metric can be logged several times. The MLflow Backend keeps track of historical metric values along two axes: timestamp and step.

.. code:: r

mlflow_log_metric( key, value, timestamp = NULL, step = NULL, run_id = NULL, client = NULL )

.. _arguments-25:

Arguments

`mlflow_log_model`

Log Model

Logs a model for this run. Similar to mlflow_save_model() but stores model as an artifact within the active run.

.. code:: r

mlflow_log_model(model, artifact_path, ...)

.. _arguments-26:

Arguments

`mlflow_log_param`

Log Parameter

Logs a parameter for a run. Examples are params and hyperparams used for ML training, or constant dates and values used in an ETL pipeline. A param is a STRING key-value pair. For a run, a single parameter is allowed to be logged only once.

.. code:: r

mlflow_log_param(key, value, run_id = NULL, client = NULL)

.. _arguments-27:

Arguments

`mlflow_param`

Read Command-Line Parameter

Reads a command-line parameter passed to an MLflow project MLflow allows you to define named, typed input parameters to your R scripts via the mlflow_param API. This is useful for experimentation, e.g. tracking multiple invocations of the same script with different parameters.

.. code:: r

mlflow_param(name, default = NULL, type = NULL, description = NULL)

.. _arguments-28:

Arguments

Examples

.. code:: r

This parametrized script trains a GBM model on the Iris dataset and can be run as an MLflow

project. You can run this script (assuming it's saved at /some/directory/params_example.R)

with custom parameters via:

mlflow_run(entry_point = "params_example.R", uri = "/some/directory",

parameters = list(num_trees = 200, learning_rate = 0.1))

install.packages("gbm") library(mlflow) library(gbm)

define and read input parameters

num_trees <- mlflow_param(name = "num_trees", default = 200, type = "integer") lr <- mlflow_param(name = "learning_rate", default = 0.1, type = "numeric")

use params to fit a model

ir.adaboost <- gbm(Species ~., data=iris, n.trees=num_trees, shrinkage=lr)

`mlflow_predict`

Generate Prediction with MLflow Model

Performs prediction over a model loaded using mlflow_load_model() , to be used by package authors to extend the supported MLflow models.

.. code:: r

mlflow_predict(model, data, ...)

.. _arguments-29:

Arguments

+-----------+---------------------------------------------------------+ | Argument | Description | +===========+=========================================================+ | model | The loaded MLflow model flavor. | +-----------+---------------------------------------------------------+ | data | A data frame to perform scoring. | +-----------+---------------------------------------------------------+ | ... | Optional additional arguments passed to underlying | | | predict methods. | +-----------+---------------------------------------------------------+

`mlflow_register_external_observer`

Registers an external MLflow observer that will receive a register_tracking_event(event_name, data) callback on any model tracking event such as “create_run”, “delete_run”, or “log_metric”. Each observer should have a register_tracking_event(event_name, data) callback accepting a character vector event_name specifying the name of the tracking event, and data containing a list of attributes of the event. The callback should be non-blocking, and ideally should complete instantaneously. Any exception thrown from the callback will be ignored.

.. code:: r

mlflow_register_external_observer(observer)

.. _arguments-30:

Arguments

============ ================================= Argument Description ============ ================================= observer The observer object (see example) ============ =================================

.. _examples-1:

Examples

.. code:: r

library(mlflow)

observer <- structure(list()) observer$register_tracking_event <- function(event_name, data) { print(event_name) print(data) } mlflow_register_external_observer(observer)

`mlflow_rename_experiment`

Rename Experiment

Renames an experiment.

.. code:: r

mlflow_rename_experiment(new_name, experiment_id = NULL, client = NULL)

.. _arguments-31:

Arguments

`mlflow_rename_registered_model`

Rename a registered model

Renames a model in the Model Registry.

.. code:: r

mlflow_rename_registered_model(name, new_name, client = NULL)

.. _arguments-32:

Arguments

`mlflow_restore_experiment`

Restore Experiment

Restores an experiment marked for deletion. This also restores associated metadata, runs, metrics, and params. If experiment uses FileStore, underlying artifacts associated with experiment are also restored.

.. code:: r

mlflow_restore_experiment(experiment_id, client = NULL)

.. _arguments-33:

Arguments

.. _details-2:

Details

Throws RESOURCE_DOES_NOT_EXIST if the experiment was never created or was permanently deleted.

`mlflow_restore_run`

Restore a Run

Restores the run with the specified ID.

.. code:: r

mlflow_restore_run(run_id, client = NULL)

.. _arguments-34:

Arguments

`mlflow_rfunc_serve`

Serve an RFunc MLflow Model

Serves an RFunc MLflow model as a local REST API server. This interface provides similar functionality to mlflow models serve cli command, however, it can only be used to deploy models that include RFunc flavor. The deployed server supports standard mlflow models interface with /ping and /invocation endpoints. In addition, R function models also support deprecated /predict endpoint for generating predictions. The /predict endpoint will be removed in a future version of mlflow.

.. code:: r

mlflow_rfunc_serve( model_uri, host = "127.0.0.1", port = 8090, daemonized = FALSE, browse = !daemonized, ... )

.. _arguments-35:

Arguments

.. _details-3:

Details

file:///absolute/path/to/local/model
file:relative/path/to/local/model
s3://my_bucket/path/to/model
runs:/<mlflow_run_id>/run-relative/path/to/model
models:/<model_name>/<model_version>
models:/<model_name>/<stage>

For more information about supported URI schemes, see the Artifacts Documentation at https://www.mlflow.org/docs/latest/tracking.html#artifact-stores.

.. _examples-2:

Examples

.. code:: r

library(mlflow)

save simple model with constant prediction

mlflow_save_model(function(df) 1, "mlflow_constant")

serve an existing model over a web interface

mlflow_rfunc_serve("mlflow_constant")

request prediction from server

httr::POST("http://127.0.0.1:8090/predict/")

`mlflow_run`

Run an MLflow Project

Wrapper for the mlflow run CLI command. See https://www.mlflow.org/docs/latest/cli.html#mlflow-run for more info.

.. code:: r

mlflow_run( uri = ".", entry_point = NULL, version = NULL, parameters = NULL, experiment_id = NULL, experiment_name = NULL, backend = NULL, backend_config = NULL, env_manager = NULL, storage_dir = NULL )

.. _arguments-36:

Arguments

.. _value-2:

Value

The run associated with this run.

.. _examples-3:

Examples

.. code:: r

This parametrized script trains a GBM model on the Iris dataset and can be run as an MLflow

project. You can run this script (assuming it's saved at /some/directory/params_example.R)

with custom parameters via:

mlflow_run(entry_point = "params_example.R", uri = "/some/directory",

parameters = list(num_trees = 200, learning_rate = 0.1))

install.packages("gbm") library(mlflow) library(gbm)

define and read input parameters

num_trees <- mlflow_param(name = "num_trees", default = 200, type = "integer") lr <- mlflow_param(name = "learning_rate", default = 0.1, type = "numeric")

use params to fit a model

ir.adaboost <- gbm(Species ~., data=iris, n.trees=num_trees, shrinkage=lr)

`mlflow_save_model.crate`

Save Model for MLflow

Saves model in MLflow format that can later be used for prediction and serving. This method is generic to allow package authors to save custom model types.

.. code:: r

list(list("mlflow_save_model"), list("crate"))(model, path, model_spec = list(), ...) mlflow_save_model(model, path, model_spec = list(), ...) list(list("mlflow_save_model"), list("H2OModel"))(model, path, model_spec = list(), conda_env = NULL, ...) list(list("mlflow_save_model"), list("keras.engine.training.Model"))(model, path, model_spec = list(), conda_env = NULL, ...) list(list("mlflow_save_model"), list("xgb.Booster"))(model, path, model_spec = list(), conda_env = NULL, ...)

.. _arguments-37:

Arguments

`mlflow_search_experiments`

Search Experiments

Search for experiments that satisfy specified criteria.

.. code:: r

mlflow_search_experiments( filter = NULL, experiment_view_type = c("ACTIVE_ONLY", "DELETED_ONLY", "ALL"), max_results = 1000, order_by = list(), page_token = NULL, client = NULL )

.. _arguments-38:

Arguments

`mlflow_search_registered_models`

List registered models

Retrieves a list of registered models.

.. code:: r

mlflow_search_registered_models( filter = NULL, max_results = 100, order_by = list(), page_token = NULL, client = NULL )

.. _arguments-39:

Arguments

`mlflow_search_runs`

Search Runs

Search for runs that satisfy expressions. Search expressions can use Metric and Param keys.

.. code:: r

mlflow_search_runs( filter = NULL, run_view_type = c("ACTIVE_ONLY", "DELETED_ONLY", "ALL"), experiment_ids = NULL, order_by = list(), client = NULL )

.. _arguments-40:

Arguments

`mlflow_server`

Run MLflow Tracking Server

Wrapper for mlflow server.

.. code:: r

mlflow_server( file_store = "mlruns", default_artifact_root = NULL, host = "127.0.0.1", port = 5000, workers = NULL, static_prefix = NULL, serve_artifacts = FALSE )

.. _arguments-41:

Arguments

`mlflow_set_experiment_tag`

Set Experiment Tag

Sets a tag on an experiment with the specified ID. Tags are experiment metadata that can be updated.

.. code:: r

mlflow_set_experiment_tag(key, value, experiment_id = NULL, client = NULL)

.. _arguments-42:

Arguments

`mlflow_set_experiment`

Set Experiment

Sets an experiment as the active experiment. Either the name or ID of the experiment can be provided. If the a name is provided but the experiment does not exist, this function creates an experiment with provided name. Returns the ID of the active experiment.

.. code:: r

mlflow_set_experiment( experiment_name = NULL, experiment_id = NULL, artifact_location = NULL )

.. _arguments-43:

Arguments

`mlflow_set_model_version_tag`

Set Model version tag

Set a tag for the model version. When stage is set, tag will be set for latest model version of the stage. Setting both version and stage parameter will result in error.

.. code:: r

mlflow_set_model_version_tag( name, version = NULL, key = NULL, value = NULL, stage = NULL, client = NULL )

.. _arguments-44:

Arguments

`mlflow_set_tag`

Set Tag

Sets a tag on a run. Tags are run metadata that can be updated during a run and after a run completes.

.. code:: r

mlflow_set_tag(key, value, run_id = NULL, client = NULL)

.. _arguments-45:

Arguments

`mlflow_set_tracking_uri`

Set Remote Tracking URI

Specifies the URI to the remote MLflow server that will be used to track experiments.

.. code:: r

mlflow_set_tracking_uri(uri)

.. _arguments-46:

Arguments

======== ==================================== Argument Description ======== ==================================== uri The URI to the remote MLflow server. ======== ====================================

`mlflow_source`

Source a Script with MLflow Params

This function should not be used interactively. It is designed to be called via Rscript from the terminal or through the MLflow CLI.

.. code:: r

mlflow_source(uri)

.. _arguments-47:

Arguments

======== ======================================================== Argument Description ======== ======================================================== uri Path to an R script, can be a quoted or unquoted string. ======== ========================================================

`mlflow_start_run`

Start Run

Starts a new run. If client is not provided, this function infers contextual information such as source name and version, and also registers the created run as the active run. If client is provided, no inference is done, and additional arguments such as start_time can be provided.

.. code:: r

mlflow_start_run( run_id = NULL, experiment_id = NULL, start_time = NULL, tags = NULL, client = NULL, nested = FALSE )

.. _arguments-48:

Arguments

.. _examples-4:

Examples

.. code:: r

with(mlflow_start_run(), { mlflow_log_metric("test", 10) })

`mlflow_transition_model_version_stage`

Transition ModelVersion Stage

Transition a model version to a different stage.

.. code:: r

mlflow_transition_model_version_stage( name, version, stage, archive_existing_versions = FALSE, client = NULL )

.. _arguments-49:

Arguments

`mlflow_ui`

Run MLflow User Interface

Launches the MLflow user interface.

.. code:: r

mlflow_ui(client, ...)

.. _arguments-50:

Arguments

.. _examples-5:

Examples

.. code:: r

library(mlflow)

launch mlflow ui locally

mlflow_ui()

launch mlflow ui for existing mlflow server

mlflow_set_tracking_uri("http://tracking-server:5000") mlflow_ui()

`mlflow_update_model_version`

Update model version

Updates a model version

.. code:: r

mlflow_update_model_version(name, version, description, client = NULL)

.. _arguments-51:

Arguments

`mlflow_update_registered_model`

Update a registered model

Updates a model in the Model Registry.

.. code:: r

mlflow_update_registered_model(name, description, client = NULL)

.. _arguments-52:

Arguments