Package 'azuremlsdk'

Description

Deploy a web service to Azure Container Instances for testing or debugging. Use ACI for low-scale CPU-based workloads that require less than 48 GB of RAM.

Deploy to ACI if one of the following conditions is true:

• You need to quickly deploy and validate your model. You do not need to create ACI containers ahead of time. They are created as part of the deployment process.

• You are testing a model that is under development.

Usage

aci_webservice_deployment_config(
  cpu_cores = NULL,
  memory_gb = NULL,
  tags = NULL,
  properties = NULL,
  description = NULL,
  location = NULL,
  auth_enabled = NULL,
  ssl_enabled = NULL,
  enable_app_insights = NULL,
  ssl_cert_pem_file = NULL,
  ssl_key_pem_file = NULL,
  ssl_cname = NULL,
  dns_name_label = NULL
)

Arguments

Value

The AciServiceDeploymentConfiguration object.

See Also

deploy_model()

Examples

## Not run: 
deployment_config <- aci_webservice_deployment_config(cpu_cores = 1, memory_gb = 1)

## End(Not run)

Description

Deploy a web service to Azure Kubernetes Service for high-scale prodution deployments. Provides fast response time and autoscaling of the deployed service. Using GPU for inference when deployed as a web service is only supported on AKS.

Deploy to AKS if you need one or more of the following capabilities:

• Fast response time

• Autoscaling of the deployed service

• Hardware acceleration options

Usage

aks_webservice_deployment_config(
  autoscale_enabled = NULL,
  autoscale_min_replicas = NULL,
  autoscale_max_replicas = NULL,
  autoscale_refresh_seconds = NULL,
  autoscale_target_utilization = NULL,
  auth_enabled = NULL,
  cpu_cores = NULL,
  memory_gb = NULL,
  enable_app_insights = NULL,
  scoring_timeout_ms = NULL,
  replica_max_concurrent_requests = NULL,
  max_request_wait_time = NULL,
  num_replicas = NULL,
  primary_key = NULL,
  secondary_key = NULL,
  tags = NULL,
  properties = NULL,
  description = NULL,
  gpu_cores = NULL,
  period_seconds = NULL,
  initial_delay_seconds = NULL,
  timeout_seconds = NULL,
  success_threshold = NULL,
  failure_threshold = NULL,
  namespace = NULL,
  token_auth_enabled = NULL
)

Arguments

Details

AKS compute target

When deploying to AKS, you deploy to an AKS cluster that is connected to your workspace. There are two ways to connect an AKS cluster to your workspace:

• Create the AKS cluster using Azure ML (see create_aks_compute()).

• Attach an existing AKS cluster to your workspace (see attach_aks_compute()).

Pass the AksCompute object to the deployment_target parameter of deploy_model().

Token-based authentication

We strongly recommend that you create your Azure ML workspace in the same region as your AKS cluster. To authenticate with a token, the web service will make a call to the region in which your workspace is created. If your workspace's region is unavailable, then you will not be able to fetch a token for your web service, even if your cluster is in a different region than your workspace. This effectively results in token-based auth being unavailable until your workspace's region is available again. In addition, the greater the distance between your cluster's region and your workspace's region, the longer it will take to fetch a token.

Value

The AksServiceDeploymentConfiguration object.

See Also

deploy_model()

Examples

## Not run: 
deployment_config <- aks_webservice_deployment_config(cpu_cores = 1, memory_gb = 1)

## End(Not run)

Description

If you already have an AKS cluster in your Azure subscription, and it is version 1.12.##, you can attach it to your workspace to use for deployments. The existing AKS cluster can be in a different Azure region than your workspace.

If you want to secure your AKS cluster using an Azure Virtual Network, you must create the virtual network first. For more information, see Secure Azure ML experimentation and inference jobs within an Azure Virtual Network

If you want to re-attach an AKS cluster, for example to to change SSL or other cluster configuration settings, you must first remove the existing attachment with detach_aks_compute().

Attaching a cluster will take approximately 5 minutes.

Usage

attach_aks_compute(
  workspace,
  resource_group,
  cluster_name,
  cluster_purpose = c("FastProd", "DevTest")
)

Arguments

Value

The AksCompute object.

Examples

ws <- load_workspace_from_config()
compute_target <- attach_aks_compute(ws,
                                     resource_group = 'myresourcegroup',
                                     cluster_name = 'myakscluster')

If the cluster has less than 12 virtual CPUs, you will need to also specify the cluster_purpose parameter in the attach_aks_compute() call: cluster_purpose = 'DevTest'.

See Also

detach_aks_compute()

Description

azureml module User can access functions/modules in azureml that are not exposed through the exported R functions.

Usage

azureml

Format

An object of class python.builtin.module (inherits from python.builtin.object) of length 5.

Description

Bandit is an early termination policy based on slack factor/slack amount and evaluation interval. The policy early terminates any runs where the primary metric is not within the specified slack factor/slack amount with respect to the best performing training run.

Usage

bandit_policy(
  slack_factor = NULL,
  slack_amount = NULL,
  evaluation_interval = 1L,
  delay_evaluation = 0L
)

Arguments

Value

The BanditPolicy object.

Details

The Bandit policy takes the following configuration parameters:

• slack_factor or slack_amount: The slack allowed with respect to the best performing training run. slack_factor specifies the allowable slack as a ration. slack_amount specifies the allowable slack as an absolute amount, instead of a ratio.

• evaluation_interval: Optional. The frequency for applying the policy. Each time the training script logs the primary metric counts as one interval.

• delay_evaluation: Optional. The number of intervals to delay the policy evaluation. Use this parameter to avoid premature termination of training runs. If specified, the policy applies every multiple of evaluation_interval that is greater than or equal to delay_evaluation.

Any run that doesn't fall within the slack factor or slack amount of the evaluation metric with respect to the best performing run will be terminated.

Consider a Bandit policy with slack_factor = 0.2 and evaluation_interval = 100. Assume that run X is the currently best performing run with an AUC (performance metric) of 0.8 after 100 intervals. Further, assume the best AUC reported for a run is Y. This policy compares the value (Y + Y * 0.2) to 0.8, and if smaller, cancels the run. If delay_evaluation = 200, then the first time the policy will be applied is at interval 200.

Now, consider a Bandit policy with slack_amount = 0.2 and evaluation_interval = 100. If run 3 is the currently best performing run with an AUC (performance metric) of 0.8 after 100 intervals, then any run with an AUC less than 0.6 (0.8 - 0.2) after 100 iterations will be terminated. Similarly, the delay_evaluation can also be used to delay the first termination policy evaluation for a specific number of sequences.

Examples

# In this example, the early termination policy is applied at every interval
# when metrics are reported, starting at evaluation interval 5. Any run whose
# best metric is less than (1 / (1 + 0.1)) or 91\% of the best performing run will
# be terminated
## Not run: 
early_termination_policy = bandit_policy(slack_factor = 0.1,
                                         evaluation_interval = 1L,
                                         delay_evaluation = 5L)

## End(Not run)

Description

Bayesian sampling is based on the Bayesian optimization algorithm and makes intelligent choices on the hyperparameter values to sample next. It picks the sample based on how the previous samples performed, such that the new sample improves the reported primary metric.

Usage

bayesian_parameter_sampling(parameter_space)

Arguments

Value

The BayesianParameterSampling object.

Details

When you use Bayesian sampling, the number of concurrent runs has an impact on the effectiveness of the tuning process. Typically, a smaller number of concurrent runs can lead to better sampling convergence, since the smaller degree of parallelism increases the number of runs that benefit from previously completed runs.

Bayesian sampling only supports choice(), uniform(), and quniform() distributions over the search space.

Bayesian sampling does not support any early termination policy. When using Bayesian parameter sampling, early_termination_policy must be NULL.

See Also

choice(), uniform(), quniform()

Examples

## Not run: 
param_sampling <- bayesian_parameter_sampling(list("learning_rate" = uniform(0.05, 0.1),
                                                   "batch_size" = choice(c(16, 32, 64, 128))))

## End(Not run)

Description

Cancel an ongoing run.

Usage

cancel_run(run)

Arguments

Value

TRUE if cancellation was successful, else FALSE.

Description

Specify a discrete set of options to sample the hyperparameters from.

Usage

choice(options)

Arguments

Value

A list of the stochastic expression.

See Also

random_parameter_sampling(), grid_parameter_sampling(), bayesian_parameter_sampling()

Description

Mark the run as completed. Use for an interactive logging run.

Usage

complete_run(run)

Arguments

Value

None

See Also

start_logging_run()

Description

Returns a ContainerRegistry object with the details for an Azure Container Registry (ACR). This is needed when a custom Docker image used for training or deployment is located in a private image registry. Provide a ContainerRegistry object to the image_registry_details parameter of either r_environment() or estimator().

Usage

container_registry(address = NULL, username = NULL, password = NULL)

Arguments

Value

The ContainerRegistry object.

See Also

r_environment(), estimator()

Description

Convert the current dataset into a FileDataset containing CSV files.

Usage

convert_to_dataset_with_csv_files(dataset, separator = ",")

Arguments

Value

A new FileDataset object with a set of CSV files containing the data in this dataset.

Description

Convert the current dataset into a FileDataset containing Parquet files. The resulting dataset will contain one or more Parquet files, each corresponding to a partition of data from the current dataset. These files are not materialized until they are downloaded or read from.

Usage

convert_to_dataset_with_parquet_files(dataset)

Arguments

Value

A new FileDataset object with a set of Parquet files containing the data in this dataset.

Description

Specifies a CRAN package to install in run environment

Usage

cran_package(name, version = NULL, repo = "https://cloud.r-project.org")

Arguments

Value

A named list containing the package specifications

Examples

pkg1 <- cran_package("ggplot2", version = "3.3.0")
pkg2 <- cran_package("stringr")
pkg3 <- cran_package("ggplot2", version = "0.9.1",
                     repo = "http://cran.us.r-project.org")

env <- r_environment(name = "r_env",
                     cran_packages = list(pkg1, pkg2, pkg3))

See Also

r_environment()

Description

Provision an Azure Kubernetes Service instance (AksCompute) as a compute target for web service deployment. AksCompute is recommended for high-scale production deployments and provides fast response time and autoscaling of the deployed service. Cluster autoscaling isn't supported through the Azure ML R SDK. To change the nodes in the AksCompute cluster, use the UI for the cluster in the Azure portal. Once created, the cluster can be reused for multiple deployments.

Usage

create_aks_compute(
  workspace,
  cluster_name,
  agent_count = NULL,
  vm_size = NULL,
  ssl_cname = NULL,
  ssl_cert_pem_file = NULL,
  ssl_key_pem_file = NULL,
  location = NULL,
  vnet_resourcegroup_name = NULL,
  vnet_name = NULL,
  subnet_name = NULL,
  service_cidr = NULL,
  dns_service_ip = NULL,
  docker_bridge_cidr = NULL,
  cluster_purpose = c("FastProd", "DevTest")
)

Arguments

Value

An AksCompute object.

Details

For more information on using an AksCompute resource within a virtual network, see Secure Azure ML experimentation and inference jobs within an Azure Virtual Network.

Examples

# Create an AksCompute cluster using the default configuration (you can also
# provide parameters to customize this)

ws <- load_workspace_from_config()

compute_target <- create_aks_compute(ws, cluster_name = 'mycluster')
wait_for_provisioning_completion(compute_target)

Description

Provision Azure Machine Learning Compute (AmlCompute) as a compute target for training. AmlCompute is a managed-compute infrastructure that allows the user to easily create a single or multi-node compute. To create a persistent AmlCompute resource that can be reused across jobs, make sure to specify the vm_size and max_nodes parameters. The compute can then be shared with other users in the workspace and is kept between jobs. If min_nodes = 0, the compute autoscales down to zero nodes when it isn't used, and scales up automatically when a job is submitted.

AmlCompute has default limits, such as the number of cores that can be allocated. For more information, see Manage and request quotas for Azure resources.

Usage

create_aml_compute(
  workspace,
  cluster_name,
  vm_size,
  vm_priority = "dedicated",
  min_nodes = 0,
  max_nodes = NULL,
  idle_seconds_before_scaledown = NULL,
  admin_username = NULL,
  admin_user_password = NULL,
  admin_user_ssh_key = NULL,
  vnet_resourcegroup_name = NULL,
  vnet_name = NULL,
  subnet_name = NULL,
  tags = NULL,
  description = NULL
)

Arguments

Value

The AmlCompute object.

Details

For more information on using an Azure Machine Learning Compute resource in a virtual network, see Secure Azure ML experimentation and inference jobs within an Azure Virtual Network.

See Also

wait_for_provisioning_completion()

Examples

## Not run: 
ws <- load_workspace_from_config()
compute_target <- create_aml_compute(ws,
                                     cluster_name = 'mycluster',
                                     vm_size = 'STANDARD_D2_V2',
                                     max_nodes = 1)
wait_for_provisioning_completion(compute_target, show_output = TRUE)

## End(Not run)

Description

Create a child run. This is used to isolate part of a run into a subsection.

Usage

create_child_run(parent_run, name = NULL, run_id = NULL, outputs = NULL)

Arguments

Value

The child run, a Run object.

Description

Create one or many child runs.

Usage

create_child_runs(parent_run, count = NULL, tag_key = NULL, tag_values = NULL)

Arguments

Value

The list of child runs, Run objects.

Description

Create a FileDataset to represent file streams.

Usage

create_file_dataset_from_files(path, validate = TRUE)

Arguments

Value

The FileDataset object

See Also

data_path

Description

Create an unregistered, in-memory Dataset from delimited files. Use this method to read delimited text files when you want to control the options used.

Usage

create_tabular_dataset_from_delimited_files(
  path,
  validate = TRUE,
  include_path = FALSE,
  infer_column_types = TRUE,
  set_column_types = NULL,
  separator = ",",
  header = TRUE,
  partition_format = NULL,
  support_multi_line = FALSE,
  empty_as_string = FALSE
)

Arguments

Value

The Tabular Dataset object.

See Also

data_path

Description

Create a TabularDataset to represent tabular data in JSON Lines files (http://jsonlines.org/). “from_json_lines_files“' creates a Tabular Dataset object , which defines the operations to load data from JSON Lines files into tabular representation. For the data to be accessible by Azure Machine Learning, the JSON Lines files specified by path must be located in a Datastore or behind public web urls. Column data types are read from data types saved in the JSON Lines files. Providing 'set_column_types' will override the data type for the specified columns in the returned Tabular Dataset.

Usage

create_tabular_dataset_from_json_lines_files(
  path,
  validate = TRUE,
  include_path = FALSE,
  set_column_types = NULL,
  partition_format = NULL
)

Arguments

Value

The Tabular Dataset object.

See Also

data_path

Description

Create an unregistered, in-memory Dataset from parquet files.

Usage

create_tabular_dataset_from_parquet_files(
  path,
  validate = TRUE,
  include_path = FALSE,
  set_column_types = NULL,
  partition_format = NULL
)

Arguments

Value

The Tabular Dataset object.

See Also

data_path

Description

Create a TabularDataset to represent tabular data in SQL databases. “from_sql_query“' creates a Tabular Dataset object , which defines the operations to load data from SQL databases into tabular representation. For the data to be accessible by Azure Machine Learning, the SQL database specified by query must be located in a Datastore and the datastore type must be of a SQL kind. Column data types are read from data types in SQL query result. Providing 'set_column_types' will override the data type for the specified columns in the returned Tabular Dataset.

Usage

create_tabular_dataset_from_sql_query(
  query,
  validate = TRUE,
  set_column_types = NULL,
  query_timeout = 30L
)

Arguments

Value

A TabularDataset object

Examples

# create tabular dataset from a SQL database in datastore
datastore <- get_datastore(ws, 'sql-db')
query <- data_path(datastore, 'SELECT * FROM my_table')
tab_ds <- create_tabular_dataset_from_sql_query(query, query_timeout = 10)

# use `set_column_types` param to set column data types
data_types <- list(ID = data_type_string(),
                   Date = data_type_datetime('%d/%m/%Y %I:%M:%S %p'),
                   Count = data_type_long(),
                   Latitude = data_type_double(),
                   Found = data_type_bool())

set_tab_ds <- create_tabular_dataset_from_sql_query(query, set_column_types = data_types)

See Also

data_path() data_type_datetime() data_type_bool() data_type_double() data_type_string() data_type_long()

Description

Create a new Azure Machine Learning workspace. Throws an exception if the workspace already exists or any of the workspace requirements are not satisfied. When you create new workspace, it automatically creates several Azure resources that are used in the workspace:

• Azure Container Registry: Registers Docker containers that you use during training and when you deploy a model. To minimize costs, ACR is lazy-loaded until deployment images are created.

• Azure Storage account: Used as the default datastore for the workspace.

• Azure Application Insights: Stores monitoring information about your models.

• Azure Key Vault: Stores secrets that are used by compute targets and other sensitive information that's needed by the workspace.

Usage

create_workspace(
  name,
  auth = NULL,
  subscription_id = NULL,
  resource_group = NULL,
  location = NULL,
  create_resource_group = TRUE,
  friendly_name = NULL,
  storage_account = NULL,
  key_vault = NULL,
  app_insights = NULL,
  container_registry = NULL,
  cmk_keyvault = NULL,
  resource_cmk_uri = NULL,
  hbi_workspace = FALSE,
  exist_ok = FALSE,
  show_output = TRUE,
  sku = "basic"
)

Arguments

Value

The Workspace object.

Examples

This example requires only minimal specification, and all dependent resources as well as the resource group will be created automatically.

ws <- create_workspace(name = 'myworkspace',
                       subscription_id = '<azure-subscription-id>',
                       resource_group = 'myresourcegroup',
                       location = 'eastus2')

This example shows how to reuse existing Azure resources by making use of all parameters utilizing the Azure resource ID format. The specific Azure resource IDs can be retrieved through the Azure Portal or SDK. This assumes that the resource group, storage account, key vault, App Insights and container registry already exist.

prefix = "subscriptions/<azure-subscription-id>/resourcegroups/myresourcegroup/providers/"
ws <- create_workspace(
       name = 'myworkspace',
       subscription_id = '<azure-subscription-id>',
       resource_group = 'myresourcegroup',
       create_resource_group = FALSE,
       location = 'eastus2',
       friendly_name = 'My workspace',
       storage_account = paste0(prefix, 'microsoft.storage/storageaccounts/mystorageaccount'),
       key_vault = paste0(prefix, 'microsoft.keyvault/vaults/mykeyvault'),
       app_insights = paste0(prefix, 'microsoft.insights/components/myappinsights'),
       container_registry = paste0(
         prefix,
         'microsoft.containerregistry/registries/mycontainerregistry'))

See Also

get_workspace() service_principal_authentication() interactive_login_authentication()

Description

The path represented by DataPath object can point to a directory or a data artifact (blob, file).

Usage

data_path(datastore, path_on_datastore = NULL, name = NULL)

Arguments

Value

The DataPath object.

Examples

my_data <- register_azure_blob_container_datastore(
    workspace = ws,
    datastore_name = blob_datastore_name,
    container_name = ws_blob_datastore$container_name,
    account_name = ws_blob_datastore$account_name,
    account_key = ws_blob_datastore$account_key,
    create_if_not_exists = TRUE)

datapath <- data_path(my_data, <path_on_my_datastore>)
dataset <- create_file_dataset_from_files(datapath)

See Also

create_file_dataset_from_files create_tabular_dataset_from_parquet_files create_tabular_dataset_from_delimited_files create_tabular_dataset_from_json_lines_files create_tabular_dataset_from_sql_query

Description

Configure conversion to bool.

Usage

data_type_bool()

Value

Converted DataType object.

Description

Configure conversion to datetime.

Usage

data_type_datetime(formats = NULL)

Arguments

Value

Converted DataType object.

Description

Configure conversion to 53-bit double.

Usage

data_type_double()

Value

Converted DataType object.

Description

Configure conversion to 64-bit integer.

Usage

data_type_long()

Value

Converted DataType object.

Description

Configure conversion to string.

Usage

data_type_string()

Value

Converted DataType object.

Description

Represent how to deliver the dataset to a compute target.

Usage

dataset_consumption_config(
  name,
  dataset,
  mode = "direct",
  path_on_compute = NULL
)

Arguments

Value

The DatasetConsumptionConfig object.

Examples

est <- estimator(source_directory = ".",
                 entry_script = "train.R",
                 inputs = list(dataset_consumption_config('mydataset', dataset, mode = 'download')),
                 compute_target = compute_target)

See Also

estimator

Description

Define timestamp columns for the dataset. The method defines columns to be used as timestamps. Timestamp columns on a dataset make it possible to treat the data as time-series data and enable additional capabilities. When a dataset has both fine_grain_timestamp and ⁠coarse_grain_timestamp defined⁠ specified, the two columns should represent the same timeline.

Usage

define_timestamp_columns_for_dataset(
  dataset,
  fine_grain_timestamp,
  coarse_grain_timestamp = NULL,
  validate = FALSE
)

Arguments

Value

The Tabular Dataset with timestamp columns defined.

Description

Remove the compute object from its associated workspace and delete the corresponding cloud-based resource.

Usage

delete_compute(cluster)

Arguments

Value

None

Examples

## Not run: 
ws <- load_workspace_from_config()
compute_target <- get_compute(ws, cluster_name = 'mycluster')
delete_compute(compute_target)

## End(Not run)

Description

Delete a local web service from the local machine. This function call is not asynchronous; it runs until the service is deleted.

Usage

delete_local_webservice(webservice, delete_cache = TRUE, delete_image = FALSE)

Arguments

Value

None

Description

Delete the registered model from its associated workspace. Note that you cannot delete a registered model that is being used by an active web service deployment.

Usage

delete_model(model)

Arguments

Value

None

Description

Delete secrets from the keyvault associated with the workspace for a specified set of secret names.

Usage

delete_secrets(keyvault, secrets)

Arguments

Value

None

Description

Delete a deployed ACI or AKS web service from the given workspace. This function call is not asynchronous; it runs until the resource is deleted.

To delete a LocalWebservice see delete_local_webservice().

Usage

delete_webservice(webservice)

Arguments

Value

None

Description

Delete the Azure Machine Learning workspace resource. delete_workspace() can also delete the workspace's associated resources.

Usage

delete_workspace(
  workspace,
  delete_dependent_resources = FALSE,
  no_wait = FALSE
)

Arguments

Value

None

Description

Deploy a web service from zero or more registered models. Types of web services that can be deployed are LocalWebservice, which will deploy a model locally, and AciWebservice and AksWebservice, which will deploy a model to Azure Container Instances (ACI) and Azure Kubernetes Service (AKS), respectively.The type of web service deployed will be determined by the deployment_config specified. Returns a Webservice object corresponding to the deployed web service.

Usage

deploy_model(
  workspace,
  name,
  models,
  inference_config,
  deployment_config = NULL,
  deployment_target = NULL
)

Arguments

Value

The LocalWebservice, AciWebservice, or AksWebservice object.

Details

If you encounter any issue in deploying your web service, please visit this troubleshooting guide.

See Also

inference_config(), aci_webservice_deployment_config(), aks_webservice_deployment_config(), local_webservice_deployment_config()

Examples

## Not run: 
ws <- load_workspace_from_config()
model <- get_model(ws, name = "my_model")
r_env <- r_environment(name = "r_env")
inference_config <- inference_config(entry_script = "score.R",
                                     source_directory = ".",
                                     environment = r_env)
deployment_config <- aci_webservice_deployment_config(cpu_cores = 1, memory_gb = 1)
service <- deploy_model(ws,
                        name = "my_webservice",
                        models = list(model),
                        inference_config = inference_config,
                        deployment_config = deployment_config)
wait_for_deployment(service, show_output = TRUE)

## End(Not run)

Description

Detach the AksCompute cluster from its associated workspace. No underlying cloud resource will be deleted; the association will just be removed.

Usage

detach_aks_compute(cluster)

Arguments

Value

None

Description

Download a file from the run record. You can download any file that was uploaded to the run record via upload_files_to_run() or upload_folder_to_run(), or any file that was written out to the ./outputs or ./logs folders during a run.

You can see what files are available to download from the run record by calling get_run_file_names().

Usage

download_file_from_run(run, name, output_file_path = NULL)

Arguments

Value

None

See Also

download_files_from_run()

Description

Download files from the run record. You can download any files that were uploaded to the run record via upload_files_to_run() or upload_folder_to_run(), or any files that were written out to the ./outputs or ./logs folders during a run.

Usage

download_files_from_run(
  run,
  prefix = NULL,
  output_directory = NULL,
  output_paths = NULL,
  batch_size = 100L
)

Arguments

Value

None

See Also

download_file_from_run()

Description

Download data from the datastore to the local file system.

Usage

download_from_datastore(
  datastore,
  target_path,
  prefix = NULL,
  overwrite = FALSE,
  show_progress = TRUE
)

Arguments

Value

An integer of the number of files successfully downloaded.

Description

Download file streams defined by the dataset as local files. If target_path starts with a /, then it will be treated as an absolute path. If it doesn't start with a /, then it will be treated as a relative path relative to the current working directory.

Usage

download_from_file_dataset(dataset, target_path = NULL, overwrite = FALSE)

Arguments

Value

A list of file paths for each file downloaded.

Description

Download a registered model to the target_dir of your local file system.

Usage

download_model(model, target_dir = ".", exist_ok = FALSE)

Arguments

Value

A string of the path to the file or folder of the downloaded model.

Examples

## Not run: 
ws <- load_workspace_from_config()
model <- get_model(ws, name = "my_model", version = 2)
download_model(model, target_dir = tempdir(), exist_ok = TRUE)

## End(Not run)

Description

Drop the specified columns from the dataset. If a timeseries column is dropped, the corresponding capabilities will be dropped for the returned dataset as well.

Usage

drop_columns_from_dataset(dataset, columns)

Arguments

Value

A new TabularDataset object with the specified columns dropped.

Description

An Estimator wraps run configuration information for specifying details of executing an R script. Running an Estimator experiment (using submit_experiment()) will return a ScriptRun object and execute your training script on the specified compute target.

To define the environment to use for training, you can either directly provide the environment-related parameters (e.g. cran_packages, custom_docker_image) to estimator(), or you can provide an Environment object to the environment parameter. For more information on the predefined Docker images that are used for training if custom_docker_image is not specified, see the documentation here.

Usage

estimator(
  source_directory,
  compute_target = NULL,
  vm_size = NULL,
  vm_priority = NULL,
  entry_script = NULL,
  script_params = NULL,
  cran_packages = NULL,
  github_packages = NULL,
  custom_url_packages = NULL,
  custom_docker_image = NULL,
  image_registry_details = NULL,
  use_gpu = FALSE,
  environment_variables = NULL,
  shm_size = NULL,
  max_run_duration_seconds = NULL,
  environment = NULL,
  inputs = NULL
)

Arguments

Value

The Estimator object.

Examples

r_env <- r_environment(name = "r-env",
                       cran_packages = list(cran_package("dplyr"),
                                            cran_package("ggplot2")))
est <- estimator(source_directory = ".",
                 entry_script = "train.R",
                 compute_target = compute_target,
                 environment = r_env)

See Also

r_environment(), container_registry(), submit_experiment(), dataset_consumption_config(), cran_package()

Description

An experiment is a grouping of many runs from a specified script.

Usage

experiment(workspace, name)

Arguments

Value

The Experiment object.

See Also

submit_experiment()

Examples

## Not run: 
ws <- load_workspace_from_config()
exp <- experiment(ws, name = 'myexperiment')

## End(Not run)

Description

Filter Tabular Dataset with time stamp columns after a specified start time.

Usage

filter_dataset_after_time(dataset, start_time, include_boundary = TRUE)

Arguments

Value

The filtered Tabular Dataset

Description

Filter Tabular Dataset with time stamp columns before a specified end time.

Usage

filter_dataset_before_time(dataset, end_time, include_boundary = TRUE)

Arguments

Value

The filtered Tabular Dataset

Description

Filter Tabular Dataset between a specified start and end time.

Usage

filter_dataset_between_time(
  dataset,
  start_time,
  end_time,
  include_boundary = TRUE
)

Arguments

Value

The filtered Tabular Dataset

Description

Filter Tabular Dataset to contain only the specified duration (amount) of recent data.

Usage

filter_dataset_from_recent_time(dataset, time_delta, include_boundary = TRUE)

Arguments

Value

The filtered Tabular Dataset

Description

Generates the control script for the experiment.

Usage

generate_entry_script(source_directory)

Arguments

Description

Regenerate either the primary or secondary authentication key for an AciWebservice or AksWebservice.The web service must have been deployed with key-based authentication enabled.

Not supported for LocalWebservice deployments.

Usage

generate_new_webservice_key(webservice, key_type)

Arguments

Value

None

Description

Retrieve the credentials for an AksCompute cluster.

Usage

get_aks_compute_credentials(cluster)

Arguments

Value

Named list of the cluster details.

Description

Find and return the run that corresponds to the best performing run amongst all the completed runs.

The best performing run is identified solely based on the primary metric parameter specified in the HyperDriveConfig (primary_metric_name). The PrimaryMetricGoal governs whether the minimum or maximum of the primary metric is used. To do a more detailed analysis of all the run metrics launched by this HyperDrive run, use get_child_run_metrics(). Only one of the runs is returned from get_best_run_by_primary_metric(), even if several of the runs launched by this HyperDrive run reached the same best metric.

Usage

get_best_run_by_primary_metric(
  hyperdrive_run,
  include_failed = TRUE,
  include_canceled = TRUE
)

Arguments

Value

The Run object.

Description

Return the hyperparameters for all the child runs of the HyperDrive run.

Usage

get_child_run_hyperparameters(hyperdrive_run)

Arguments

Value

The named list of hyperparameters where element name is the run_id, e.g. list("run_id" = hyperparameters).

Description

Return the metrics from all the child runs of the HyperDrive run.

Usage

get_child_run_metrics(hyperdrive_run)

Arguments

Value

The named list of metrics where element name is the run_id, e.g. list("run_id" = metrics).

Description

Get all children for the current run selected by specified filters.

Usage

get_child_runs(
  parent_run,
  recursive = FALSE,
  tags = NULL,
  properties = NULL,
  type = NULL,
  status = NULL
)

Arguments

Value

A list of child runs, Run objects.

Description

Return a list of child runs of the HyperDrive run sorted by their best primary metric. The sorting is done according to the primary metric and its goal: if it is maximize, then the child runs are returned in descending order of their best primary metric. If reverse = TRUE, the order is reversed. Each child in the result has run id, hyperparameters, best primary metric value, and status.

Child runs without the primary metric are discarded when discard_no_metric = TRUE. Otherwise, they are appended to the list behind other child runs with the primary metric. Note that the reverse option has no impact on them.

Usage

get_child_runs_sorted_by_primary_metric(
  hyperdrive_run,
  top = 0L,
  reverse = FALSE,
  discard_no_metric = FALSE
)

Arguments

Value

The named list of child runs.

Description

Returns an AmlCompute or AksCompute object for an existing compute resource. If the compute target doesn't exist, the function will return NULL.

Usage

get_compute(workspace, cluster_name)

Arguments

Value

The AmlCompute or AksCompute object.

Examples

## Not run: 
ws <- load_workspace_from_config()
compute_target <- get_compute(ws, cluster_name = 'mycluster')

## End(Not run)

Description

This function is commonly used to retrieve the authenticated run object inside of a script to be submitted for execution via submit_experiment(). Note that the logging functions (⁠log_*⁠ methods, upload_files_to_run(), upload_folder_to_run()) will by default log the specified metrics or files to the run returned from get_current_run().

Usage

get_current_run(allow_offline = TRUE)

Arguments

Value

The Run object.

Description

Get a Dataset which is saved to the workspace using its ID.

Usage

get_dataset_by_id(workspace, id)

Arguments

Value

The Dataset object

Description

Get a registered Dataset from the workspace by its registration name.

Usage

get_dataset_by_name(workspace, name, version = "latest")

Arguments

Value

The registered Dataset object.

Description

Get the corresponding datastore object for an existing datastore by name from the given workspace.

Usage

get_datastore(workspace, datastore_name)

Arguments

Value

The azureml.data.azure_sql_database.AzureBlobDatastore, azureml.data.azure_sql_database.AzureFileDatastore, azureml.data.azure_sql_database.AzureSqlDatabaseDatastore, azureml.data.azure_data_lake_datastore.AzureDataLakeGen2Datastore, azureml.data.azure_postgre_sql_datastore.AzurePostgreSqlDatastore, or azureml.data.azure_sql_database.AzureSqlDatabaseDatastore object.

Description

Returns the default datastore associated with the workspace.

When you create a workspace, an Azure blob container and Azure file share are registered to the workspace with the names workspaceblobstore and workspacefilestore, respectively. They store the connection information of the blob container and the file share that is provisioned in the storage account attached to the workspace. The workspaceblobstore is set as the default datastore, and remains the default datastore unless you set a new datastore as the default with set_default_datastore().

Usage

get_default_datastore(workspace)

Arguments

Value

The default Datastore object.

Examples

Get the default datastore for the datastore:

ws <- load_workspace_from_config()
ds <- get_default_datastore(ws)

If you have not changed the default datastore for the workspace, the following code will return the same datastore object as the above example:

ws <- load_workspace_from_config()
ds <- get_datastore(ws, datastore_name = 'workspaceblobstore')

See Also

set_default_datastore()

Description

Returns a Keyvault object representing the default Azure Key Vault associated with the workspace.

Usage

get_default_keyvault(workspace)

Arguments

Value

The Keyvault object.

See Also

set_secrets() get_secrets() list_secrets() delete_secrets()

Description

Returns an Environment object for an existing environment in the workspace.

Usage

get_environment(workspace, name, version = NULL)

Arguments

Value

The Environment object.

Examples

## Not run: 
ws <- load_workspace_from_config()
env <- get_environment(ws, name = 'myenv', version = '1')

## End(Not run)

Description

Get a list of file paths for each file stream defined by the dataset. The file paths are relative paths for local files when the file srteam are downloaded or mounted. A common prefix will be removed from the file paths based on how data source was specified to create the dataset.

Usage

get_file_dataset_paths(dataset)

Arguments

Value

A list of file paths.

Description

Return the named list for input datasets.

Usage

get_input_dataset_from_run(name, run = NULL)

Arguments

Value

A dataset object corresponding to the "name"

Description

Returns a Model object for an existing model that has been previously registered to the given workspace.

Usage

get_model(
  workspace,
  name = NULL,
  id = NULL,
  tags = NULL,
  properties = NULL,
  version = NULL,
  run_id = NULL
)

Arguments

Value

The Model object.

Description

Return a ContainerRegistry object for where the image (or base image, for Dockerfile packages) is stored in an Azure container registry.

Usage

get_model_package_container_registry(package)

Arguments

Value

The ContainerRegistry object.

See Also

container_registry()

Examples

# Given a ModelPackage object,
# get the container registry information
## Not run: 
container_registry <- get_model_package_container_registry(package)
address <- container_registry$address
username <- container_registry$username
password <- container_registry$password

## End(Not run)

# To then authenticate Docker with the Azure container registry from
# a shell or command-line session, use the following command, replacing
# <address>, <username>, and <password> with the values retrieved
# from above:
# ```bash
# docker login <address> -u <username> -p <password>
# ```

Description

Retrieve the creation logs from packaging a model with package_model().

Usage

get_model_package_creation_logs(package, decode = TRUE, offset = 0)

Arguments

Value

A string or character vector of package creation logs.

Description

Given the associated experiment and run ID, return the run object for a previously submitted/tracked run.

Usage

get_run(experiment, run_id)

Arguments

Value

The Run object.

Description

Get the definition, status information, current log files, and other details of the run.

Usage

get_run_details(run)

Arguments

Details

The returned list contains the following named elements:

• runId: ID of the run.

• target: The compute target of the run.

• status: The run's current status.

• startTimeUtc: UTC time of when the run was started, in ISO8601.

• endTimeUtc: UTC time of when the run was finished (either Completed or Failed), in ISO8601. This element does not exist if the run is still in progress.

• properties: Immutable key-value pairs associated with the run.

• logFiles: Log files from the run.

Value

A named list of the details for the run.

See Also

get_run_details_with_logs()

Description

Get the details of a run along with the log files' contents

Usage

get_run_details_with_logs(run)

Arguments

Value

A named list of the run details and log file contents.

See Also

get_run_details()

Description

Get the list of files stored in a run record.

Usage

get_run_file_names(run)

Arguments

Value

A list of strings of the paths for existing artifacts in the run record.

See Also

download_file_from_run() download_files_from_run()

Description

Retrieve the metrics logged to a run that were logged with the ⁠log_*()⁠ methods.

Usage

get_run_metrics(
  run,
  name = NULL,
  recursive = FALSE,
  run_type = NULL,
  populate = FALSE
)

Arguments

Value

A named list of the metrics associated with the run, e.g. list("metric_name" = metric).

Examples

ws <- load_workspace_from_config()
exp <- experiment(ws, name = 'myexperiment')
run <- get_run(exp, run_id = "myrunid")
metrics <- get_run_metrics(run)

Description

Return a generator of the runs for an experiment, in reverse chronological order.

Usage

get_runs_in_experiment(
  experiment,
  type = NULL,
  tags = NULL,
  properties = NULL,
  include_children = FALSE
)

Arguments

Value

The list of runs matching supplied filters.

Description

Returns the secret values from the keyvault associated with the workspace for a given set of secret names. For runs submitted using submit_experiment(), you can use get_secrets_from_run() instead, as that method shortcuts workspace instantiation (since a submitted run is aware of its workspace).

Usage

get_secrets(keyvault, secrets)

Arguments

Value

A named list of found and not found secrets, where element name corresponds to the secret name. If a secret was not found, the corresponding element will be NULL.

Description

From within the script of a run submitted using submit_experiment(), you can use get_secrets_from_run() to get secrets that are stored in the keyvault of the associated workspace.

Note that this method is slightly different than get_secrets(), which first requires you to instantiate the workspace object. Since a submitted run is aware of its workspace, get_secrets_from_run() shortcuts workspace instantiation and returns the secret value directly.

Be careful not to expose the secret(s) values by writing or printing them out.

Usage

get_secrets_from_run(run, secrets)

Arguments

Value

A named list of found and not found secrets. If a secret was not found, the corresponding element will be NULL.

See Also

set_secrets()

Description

Return the corresponding Webservice object of a deployed web service from a given workspace.

Usage

get_webservice(workspace, name)

Arguments

Value

The LocalWebservice, AciWebservice, or AksWebservice object.

Description

Get the authentication keys for a web service that is deployed with key-based authentication enabled. In order to enable key-based authentication, set the auth_enabled = TRUE parameter when you are creating or updating a deployment (either aci_webservice_deployment_config() or aks_webservice_deployment_config() for creation and update_aci_webservice() or update_aks_webservice() for updating). Note that key-based auth is enabled by default for AksWebservice but not for AciWebservice.

To check if a web service has key-based auth enabled, you can access the following boolean property from the Webservice object: service$auth_enabled

Not supported for LocalWebservice deployments.

Usage

get_webservice_keys(webservice)

Arguments

Value

A list of two strings corresponding to the primary and secondary authentication keys.

See Also

generate_new_webservice_key()

Description

You can get the detailed Docker engine log messages from your web service deployment. You can view the logs for local, ACI, and AKS deployments.

For example, if your web service deployment fails, you can inspect the logs to help troubleshoot.

Usage

get_webservice_logs(webservice, num_lines = 5000L)

Arguments

Value

A string of the logs for the web service.

Description

Get the authentication token, scoped to the current user, for a web service that was deployed with token-based authentication enabled. Token-based authentication requires clients to use an Azure Active Directory account to request an authentication token, which is used to make requests to the deployed service. Only available for AKS deployments.

In order to enable token-based authentication, set the token_auth_enabled = TRUE parameter when you are creating or updating a deployment (aks_webservice_deployment_config() for creation or update_aks_webservice() for updating). Note that you cannot have both key-based authentication and token-based authentication enabled. Token-based authentication is not enabled by default.

To check if a web service has token-based auth enabled, you can access the following boolean property from the Webservice object: service$token_auth_enabled

Usage

get_webservice_token(webservice)

Arguments

Value

An AksServiceAccessToken object.

Description

Returns a Workspace object for an existing Azure Machine Learning workspace. Throws an exception if the workpsace doesn't exist or the required fields don't lead to a uniquely identifiable workspace.

Usage

get_workspace(name, auth = NULL, subscription_id = NULL, resource_group = NULL)

Arguments

Value

The Workspace object.

See Also

create_workspace() service_principal_authentication() interactive_login_authentication()

Description

Returns the details of the workspace.

Usage

get_workspace_details(workspace)

Arguments

Value

Named list of the workspace details.

Details

The returned named list contains the following elements:

• id: URI pointing to the workspace resource, containing subscription ID, resource group, and workspace name.

• name: Workspace name.

• location: Workspace region.

• type: URI of the format "{providerName}/workspaces".

• workspaceid: Workspace ID.

• description: Workspace description.

• friendlyName: Workspace friendly name.

• creationTime: Time the workspace was created, in ISO8601.

• containerRegistry: Workspace container registry.

• keyVault: Workspace key vault.

• applicationInsights: Workspace App Insights.

• identityPrincipalId: Workspace identity principal ID.

• identityTenantId: Workspace tenant ID.

• identityType: Workspace identity type.

• storageAccount: Workspace storage account.

Description

Specifies a Github package to install in run environment

Usage

github_package(repository, auth_token = NULL)

Arguments

Value

A named list containing the package specifications

Examples

pkg1 <- github_package("Azure/azureml-sdk-for-r")

env <- r_environment(name = "r_env",
                     github_packages = list(pkg1))

See Also

r_environment()

Description

Grid sampling performs a simple grid search over all feasible values in the defined search space. It can only be used with hyperparameters specified using choice().

Usage

grid_parameter_sampling(parameter_space)

Arguments

Value

The GridParameterSampling object.

See Also

choice()

Examples

## Not run: 
param_sampling <- grid_parameter_sampling(list("num_hidden_layers" = choice(c(1, 2, 3)),
                                               "batch_size" = choice(c(16, 32))))

## End(Not run)

Description

The HyperDrive configuration includes information about hyperparameter space sampling, termination policy, primary metric, estimator, and the compute target to execute the experiment runs on.

To submit the HyperDrive experiment, pass the HyperDriveConfig object returned from this method to submit_experiment().

Usage

hyperdrive_config(
  hyperparameter_sampling,
  primary_metric_name,
  primary_metric_goal,
  max_total_runs,
  max_concurrent_runs = NULL,
  max_duration_minutes = 10080L,
  policy = NULL,
  estimator = NULL
)

Arguments

Value

The HyperDriveConfig object.

See Also

submit_experiment()

Examples

## Not run: 
# Load the workspace
ws <- load_workspace_from_config()

# Get the compute target
compute_target <- get_compute(ws, cluster_name = 'mycluster')

# Define the primary metric goal
goal = primary_metric_goal("MAXIMIZE")

# Define the early termination policy
early_termination_policy = median_stopping_policy(evaluation_interval = 1L,
                                                  delay_evaluation = 5L)

# Create the estimator
est <- estimator(source_directory = '.',
                 entry_script = 'train.R',
                 compute_target = compute_target)

# Create the HyperDrive configuration
hyperdrive_run_config = hyperdrive_config(
                                   hyperparameter_sampling = param_sampling,
                                   primary_metric_name = 'accuracy',
                                   primary_metric_goal = goal,
                                   max_total_runs = 100,
                                   max_concurrent_runs = 4,
                                   policy = early_termination_policy,
                                   estimator = est)

# Submit the HyperDrive experiment
exp <- experiment(ws, name = 'myexperiment')
run = submit_experiment(exp, hyperdrive_run_config)

## End(Not run)

Description

The inference configuration describes how to configure the model to make predictions. It references your scoring script (entry_script) and is used to locate all the resources required for the deployment. Inference configurations use Azure Machine Learning environments (see r_environment()) to define the software dependencies needed for your deployment.

Usage

inference_config(
  entry_script,
  source_directory = ".",
  description = NULL,
  environment = NULL
)

Arguments

Value

The InferenceConfig object.

Defining the entry script

To deploy a model, you must provide an entry script that accepts requests, scores the requests by using the model, and returns the results. The entry script is specific to your model. It must understand the format of the incoming request data, the format of the data expected by your model, and the format of the data returned to clients. If the request data is in a format that is not usable by your model, the script can transform it into an acceptable format. It can also transform the response before returning it to the client.

The entry script must contain an init() method that loads your model and then returns a function that uses the model to make a prediction based on the input data passed to the function. Azure ML runs the init() method once, when the Docker container for your web service is started. The prediction function returned by init() will be run every time the service is invoked to make a prediction on some input data. The inputs and outputs of this prediction function typically use JSON for serialization and deserialization.

To locate the model in your entry script (when you load the model in the script's init() method), use AZUREML_MODEL_DIR, an environment variable containing the path to the model location. The environment variable is created during service deployment, and you can use it to find the location of your deployed model(s).

To get the path to a file in a model, combine the environment variable with the filename you're looking for. The filenames of the model files are preserved during registration and deployment.

Single model example:

model_path <- file.path(Sys.getenv("AZUREML_MODEL_DIR"), "my_model.rds")

Multiple model example:

model1_path <- file.path(Sys.getenv("AZUREML_MODEL_DIR"), "my_model/1/my_model.rds")

See Also

r_environment(), deploy_model()

Description

Install azureml sdk package

Usage

install_azureml(
  version = "1.10.0",
  envname = "r-reticulate",
  conda_python_version = "3.6",
  restart_session = TRUE,
  remove_existing_env = FALSE
)

Arguments

Value

None

Description

Interactive login authentication is suitable for local experimentation on your own computer, and is the default authentication model when using Azure Machine Learning SDK. The constructor of the class will prompt you to login. The constructor then will save the credentials for any subsequent attempts. If you are already logged in with the Azure CLI or have logged-in before, the constructor will load the existing credentials without prompt.

Usage

interactive_login_authentication(
  force = FALSE,
  tenant_id = NULL,
  cloud = "AzureCloud"
)

Arguments

Value

InteractiveLoginAuthentication object

Examples

interactive_auth <- interactive_login_authentication(tenant_id="your-tenant-id")

ws <- get_workspace("<your workspace name>",
                    "<your subscription ID>",
                    "<your resource group>",
                    auth = interactive_auth)

See Also

get_workspace() service_principal_authentication()

Description

Invoke the web service with the provided input and to receive predictions from the deployed model. The structure of the provided input data needs to match what the service's scoring script and model expect. See the "Details" section of inference_config().

Usage

invoke_webservice(webservice, input_data)

Arguments

Details

Instead of invoking the web service using invoke_webservice(), you can also consume the web service using the service's REST API. If you've enabled key-based authentication for your service, you will need to provide a service key as a token in your request header (see get_webservice_keys()). If you've enabled token-based authentication, you will need to provide an JWT token as a bearer token in your request header (see get_webservice_token()).

To get the REST API address for the service's scoring endpoint, you can access the following property from the Webservice object: service$scoring_uri

Value

A named list of the result of calling the web service. This will return the predictions run from your model.

Description

Keep the specified columns and drops all others from the dataset. If a timeseries column is dropped, the corresponding capabilities will be dropped for the returned dataset as well.

Usage

keep_columns_from_dataset(dataset, columns, validate = FALSE)

Arguments

Value

A new Tabular Dataset object with only the specified columns kept.

Description

Get the details (e.g IP address, port etc) of all the compute nodes in the compute target

Usage

list_nodes_in_aml_compute(cluster)

Arguments

Value

Details of all the compute nodes in the cluster in data frame

Description

Returns the list of secret names for all the secrets in the keyvault associated with the workspace.

Usage

list_secrets(keyvault)

Arguments

Value

A list of secret names.

Description

List the supported VM sizes in a region

Usage

list_supported_vm_sizes(workspace, location = NULL)

Arguments

Value

A data frame of supported VM sizes in a region with name of the VM, VCPUs, RAM.

Description

List all workspaces that the user has access to in the specified subscription_id parameter. The list of workspaces can be filtered based on the resource group.

Usage

list_workspaces(subscription_id, resource_group = NULL)

Arguments

Value

A named list of Workspace objects where element name corresponds to the workspace name.

Description

Load all records from the dataset into a dataframe.

Usage

load_dataset_into_data_frame(
  dataset,
  on_error = "null",
  out_of_range_datetime = "null"
)

Arguments

Value

A data.frame.

Description

Returns a Workspace object for an existing Azure Machine Learning workspace by reading the workspace configuration from a file. The method provides a simple way of reusing the same workspace across multiple files or projects. Users can save the workspace ARM properties using write_workspace_config(), and use this method to load the same workspace in different files or projects without retyping the workspace ARM properties.

Usage

load_workspace_from_config(path = NULL, file_name = NULL)

Arguments

Value

The Workspace object.

See Also

write_workspace_config()

Description

You can deploy a model locally for limited testing and troubleshooting. To do so, you will need to have Docker installed on your local machine.

If you are using an Azure Machine Learning Compute Instance for development, you can also deploy locally on your compute instance.

Usage

local_webservice_deployment_config(port = NULL)

Arguments

Value

The LocalWebserviceDeploymentConfiguration object.

Examples

## Not run: 
deployment_config <- local_webservice_deployment_config(port = 8890)

## End(Not run)

Description

The accuracy table metric is a multi-use non-scalar metric that can be used to produce multiple types of line charts that vary continuously over the space of predicted probabilities. Examples of these charts are ROC, precision-recall, and lift curves.

Usage

log_accuracy_table_to_run(name, value, description = "", run = NULL)

Arguments

Details

The calculation of the accuracy table is similar to the calculation of an ROC curve. An ROC curve stores true positive rates and false positive rates at many different probability thresholds. The accuracy table stores the raw number of true positives, false positives, true negatives, and false negatives at many probability thresholds.

There are two methods used for selecting thresholds: "probability" and "percentile." They differ in how they sample from the space of predicted probabilities.

Probability thresholds are uniformly spaced thresholds between 0 and 1. If NUM_POINTS were 5 the probability thresholds would be c(0.0, 0.25, 0.5, 0.75, 1.0).

Percentile thresholds are spaced according to the distribution of predicted probabilities. Each threshold corresponds to the percentile of the data at a probability threshold. For example, if NUM_POINTS were 5, then the first threshold would be at the 0th percentile, the second at the 25th percentile, the third at the 50th, and so on.

The probability tables and percentile tables are both 3D lists where the first dimension represents the class label, the second dimension represents the sample at one threshold (scales with NUM_POINTS), and the third dimension always has 4 values: TP, FP, TN, FN, and always in that order.

The confusion values (TP, FP, TN, FN) are computed with the one vs. rest strategy. See the following link for more details: https://en.wikipedia.org/wiki/Multiclass_classification.

N = # of samples in validation dataset (200 in example), M = # thresholds = # samples taken from the probability space (5 in example), C = # classes in full dataset (3 in example)

Some invariants of the accuracy table:

• TP + FP + TN + FN = N for all thresholds for all classes

• TP + FN is the same at all thresholds for any class

• TN + FP is the same at all thresholds for any class

• Probability tables and percentile tables have shape (C, M, 4)

Note: M can be any value and controls the resolution of the charts. This is independent of the dataset, is defined when calculating metrics, and trades off storage space, computation time, and resolution.

Class labels should be strings, confusion values should be integers, and thresholds should be doubles.

Value

None

Description

Log a confusion matrix metric to a run

Usage

log_confusion_matrix_to_run(name, value, description = "", run = NULL)

Arguments

Value

None

Description

Log an image to the run with the give metric name. Use log_image_to_run() to log an image file or ggplot2 plot to the run. These images will be visible and comparable in the run record.

Usage

log_image_to_run(name, path = NULL, plot = NULL, description = "", run = NULL)

Arguments

Value

None

Description

Log a vector with the given metric name to the run.

Usage

log_list_to_run(name, value, description = "", run = NULL)

Arguments

Value

None

Examples

log_list_to_run("Accuracies", c(0.6, 0.7, 0.87))

Description

Log a numerical or string value with the given metric name to the run. Logging a metric to a run causes that metric to be stored in the run record in the experiment. You can log the same metric multiple times within a run, the result being considered a vector of that metric.

Usage

log_metric_to_run(name, value, run = NULL)

Arguments

Value

None

Examples

log_metric_to_run("Accuracy", 0.95)

Description

log_predictions_to_run() logs a metric score that can be used to compare the distributions of true target values to the distribution of predicted values for a regression task.

The predictions are binned and standard deviations are calculated for error bars on a line chart.

Usage

log_predictions_to_run(name, value, description = "", run = NULL)

Arguments

Value

None

Examples

data <- list("bin_averages" = c(0.25, 0.75),
             "bin_errors" = c(0.013, 0.042),
             "bin_counts" = c(56, 34),
             "bin_edges" = c(0.0, 0.5, 1.0))
predictions <- list("schema_type" = "predictions",
                    "schema_version" = "v1",
                    "data" = data)
log_predictions_to_run("mypredictions", predictions)

Description

log_residuals_to_run() logs the data needed to display a histogram of residuals for a regression task. The residuals are predicted - actual.

There should be one more edge than the number of counts.

Usage

log_residuals_to_run(name, value, description = "", run = NULL)

Arguments

Value

None

Examples

data <- list("bin_edges" = c(50, 100, 200, 300, 350),
             "bin_counts" = c(0.88, 20, 30, 50.99))
residuals <- list("schema_type" = "residuals",
                    "schema_version" = "v1",
                    "data" = data)
log_predictions_to_run("myresiduals", predictions)

Description

Using log_row_to_run() creates a metric with multiple columns as described in .... Each named parameter generates a column with the value specified. log_row_to_run() can be called once to log an arbitrary tuple, or multiple times in a loop to generate a complete table.

Usage

log_row_to_run(name, description = "", run = NULL, ...)

Arguments

Value

None

Examples

Log an arbitrary tuple:

log_row_to_run("Y over X", x = 1, y = 0.4)

Log the complete table:

citrus <- c("orange", "lemon", "lime")
sizes <- c(10, 7, 3)
for (i in seq_along(citrus)) {
    log_row_to_run("citrus", fruit = citrus[i], size = sizes[i])
}

Description

Log a table metric with the given metric name to the run. The table value is a named list where each element corresponds to a column of the table.

Usage

log_table_to_run(name, value, description = "", run = NULL)

Arguments

Value

None

Examples

log_table_to_run("Y over X",
                 list("x" = c(1, 2, 3), "y" = c(0.6, 0.7, 0.89)))

Description

Specify a normal distribution of the form exp(normal(mu, sigma)).

The logarithm of the return value is normally distributed. When optimizing, this variable is constrained to be positive.

Usage

lognormal(mu, sigma)

Arguments

Value

A list of the stochastic expression.

See Also

random_parameter_sampling(), grid_parameter_sampling(), bayesian_parameter_sampling()

Description

Specify a log uniform distribution.

A value is drawn according to exp(uniform(min_value, max_value)) so that the logarithm of the return value is uniformly distributed. When optimizing, this variable is constrained to the interval ⁠[exp(min_value), exp(max_value)]⁠.

Usage

loguniform(min_value, max_value)

Arguments

Value

A list of the stochastic expression.

See Also

random_parameter_sampling(), grid_parameter_sampling(), bayesian_parameter_sampling()

Description

Median stopping is an early termination policy based on running averages of primary metrics reported by the runs. This policy computes running averages across all training runs and terminates runs whose performance is worse than the median of the running averages. Specifically, a run will be canceled at interval N if its best primary metric reported up to interval N is worse than the median of the running averages for intervals 1:N across all runs.

Usage

median_stopping_policy(evaluation_interval = 1L, delay_evaluation = 0L)

Arguments

Value

The MedianStoppingPolicy object.

Details

The median stopping policy takes the following optional configuration parameters:

• evaluation_interval: Optional. The frequency for applying the policy. Each time the training script logs the primary metric counts as one interval.

• delay_evaluation: Optional. The number of intervals to delay the policy evaluation. Use this parameter to avoid premature termination of training runs. If specified, the policy applies every multiple of evaluation_interval that is greater than or equal to delay_evaluation.

This policy is inspired from the research publication Google Vizier: A Service for Black-Box Optimization.

If you are looking for a conservative policy that provides savings without terminating promising jobs, you can use a MedianStoppingPolicy with evaluation_interval = 1 and delay_evaluation = 5. These are conservative settings that can provide approximately 25%-35% savings with no loss on the primary metric (based on our evaluation data).

Examples

# In this example, the early termination policy is applied at every
# interval starting at evaluation interval 5. A run will be terminated at
# interval 5 if its best primary metric is worse than the median of the
# running averages over intervals 1:5 across all training runs
## Not run: 
early_termination_policy = median_stopping_policy(evaluation_interval = 1L,
                                                  delay_evaluation = 5L)

## End(Not run)

Description

Combine the results from the parallel training.

Usage

merge_results(node_count, process_count_per_node, run, source_directory)

Arguments

Description

Create a context manager for mounting file streams defined by the dataset as local files. A context manager will be returned to manage the lifecycle of the mount. To mount, you will need to enter the context manager and to unmount, exit from the context manager. Mount is only supported on Unix or Unix-like operating systems and libfuse must be present. If you are running inside a docker container, the docker container must be started with the --privileged flag or started with ⁠--cap-add SYS_ADMIN --device /dev/fuse⁠.

Usage

mount_file_dataset(dataset, mount_point = NULL)

Arguments

Value

Returns a context manager for managing the lifecycle of the mount of type azureml.dataprep.fuse.daemon.MountContext.

Description

Specify a real value that is normally-distributed with mean mu and standard deviation sigma.

When optimizing, this is an unconstrained variable.

Usage

normal(mu, sigma)

Arguments

Value

A list of the stochastic expression.

See Also

random_parameter_sampling(), grid_parameter_sampling(), bayesian_parameter_sampling()

Description

In some cases, you might want to create a Docker image without deploying the model (for example, if you plan to deploy to Azure App Service). Or you might want to download the image and run it on a local Docker installation. You might even want to download the files used to build the image, inspect them, modify them, and build the image manually.

Model packaging enables you to do these things. package_model() packages all the assets needed to host a model as a web service and allows you to download either a fully built Docker image or the files needed to build one. There are two ways to use model packaging:

• Download a packaged model: Download a Docker image that contains the model and other files needed to host it as a web service.

• Generate a Dockerfile: Download the Dockerfile, model, entry script, and other assets needed to build a Docker image. You can then inspect the files or make changes before you build the image locally. To use this method, make sure to set generate_dockerfile = TRUE. With either scenario, you will need to have Docker installed in your development environment.

Usage

package_model(workspace, models, inference_config, generate_dockerfile = FALSE)

Arguments

Value

The ModelPackage object.

See Also

wait_for_model_package_creation(), get_model_package_container_registry(), get_model_package_creation_logs(), pull_model_package_image(), save_model_package_files()

Examples

# Package a registered model
## Not run: 
ws <- load_workspace_from_config()
model <- get_model(ws, name = "my_model")
r_env <- r_environment(name = "r_env")
inference_config <- inference_config(entry_script = "score.R",
                                     source_directory = ".",
                                     environment = r_env)
package <- package_model(ws,
                         models = list(model),
                         inference_config = inference_config)
wait_for_model_package_creation(show_output = TRUE)

## End(Not run)

Description

Plot a table of run details including

• ID

• Status

• Start Time

• Duration

• Script Name

• Arguments

• Link to Web Portal view

• Errors

Usage

plot_run_details(run)

Arguments

Value

Datatable containing run details

Description

A metric goal is used to determine whether a higher value for a metric is better or worse. Metric goals are used when comparing runs based on the primary metric. For example, you may want to maximize accuracy or minimize error.

The primary metric name and goal are specified to hyperdrive_config() when you configure a HyperDrive run.

Usage

primary_metric_goal(goal)

Arguments

Value

The PrimaryMetricGoal object.

Description

Defines options for how column headers are processed when reading data from files to create a dataset. These enumeration values are used in the Dataset class method.

Usage

promote_headers_behavior(option)

Arguments

Value

The PromoteHeadersBehavior object.

Description

Pull the Docker image from a created ModelPackage to your local Docker environment. The output of this call will display the name of the image. For example: ⁠Status: Downloaded newer image for myworkspacef78fd10.azurecr.io/package:20190822181338⁠.

This can only be used with a Docker image ModelPackage (where package_model() was called with generate_dockerfile = FALSE).

After you've pulled the image, you can start a local container based on this image using Docker commands.

Usage

pull_model_package_image(package)

Arguments

Value

None

See Also

package_model()

Description

Specify a normal distribution of the form round(exp(normal(mu, sigma)) / q) * q.

Suitable for a discrete variable with respect to which the objective is smooth and gets smoother with the size of the variable, which is bounded from one side.

Usage

qlognormal(mu, sigma, q)

Arguments

Value

A list of the stochastic expression.

See Also

random_parameter_sampling(), grid_parameter_sampling(), bayesian_parameter_sampling()

Description

Specify a uniform distribution of the form ⁠round(exp(uniform(min_value, max_value) / q) * q⁠.

This is suitable for a discrete variable with respect to which the objective is "smooth", and gets smoother with the size of the value, but which should be bounded both above and below.

Usage

qloguniform(min_value, max_value, q)

Arguments

Value

A list of the stochastic expression.

See Also

random_parameter_sampling(), grid_parameter_sampling(), bayesian_parameter_sampling()

Description

Specify a normal distribution of the form round(normal(mu, sigma) / q) * q.

Suitable for a discrete variable that probably takes a value around mu, but is fundamentally unbounded.

Usage

qnormal(mu, sigma, q)

Arguments

Value

A list of the stochastic expression.

See Also

random_parameter_sampling(), grid_parameter_sampling(), bayesian_parameter_sampling()

Description

Specify a uniform distribution of the form round(uniform(min_value, max_value) / q) * q.

This is suitable for a discrete value with respect to which the objective is still somewhat "smooth", but which should be bounded both above and below.

Usage

quniform(min_value, max_value, q)

Arguments

Value

A list of the stochastic expression.

See Also

random_parameter_sampling(), grid_parameter_sampling(), bayesian_parameter_sampling()

Description

Configure the R environment to be used for training or web service deployments. When you submit a run or deploy a model, Azure ML builds a Docker image and creates a conda environment with your specifications from your Environment object within that Docker container.

If the custom_docker_image parameter is not set, Azure ML will build a predefined base image (CPU or GPU depending on the use_gpu flag) and install any R packages specified in the cran_packages, github_packages, or custom_url_packages parameters.

Usage

r_environment(
  name,
  version = NULL,
  environment_variables = NULL,
  r_version = NULL,
  rscript_path = NULL,
  snapshot_date = NULL,
  cran_packages = NULL,
  github_packages = NULL,
  custom_url_packages = NULL,
  bioconductor_packages = NULL,
  custom_docker_image = NULL,
  image_registry_details = NULL,
  use_gpu = FALSE,
  shm_size = NULL
)

Arguments

Value

The Environment object.

Details

Once built, the Docker image appears in the Azure Container Registry associated with your workspace, by default. The repository name has the form azureml/azureml_<uuid>. The unique identifier (uuid) part corresponds to a hash computed from the environment configuration. This allows the service to determine whether an image corresponding to the given environment already exists for reuse.

If you make changes to an existing environment, such as adding an R package, a new version of the environment is created when you either submit a run, deploy a model, or manually register the environment. The versioning allows you to view changes to the environment over time.

Predefined Docker images

When submitting a training job or deploying a model, Azure ML runs your training script or scoring script within a Docker container. If no custom Docker image is specified with the custom_docker_image parameter, Azure ML will build a predefined CPU or GPU Docker image. The predefine images extend the Ubuntu 16.04 Azure ML base images and include the following dependencies:

See Also

estimator(), inference_config()

Examples

# The following example defines an environment that will build the default
# base CPU image.
## Not run: 
r_env <- r_environment(name = 'myr_env',
                       version = '1')

## End(Not run)

Description

Specify a set of random integers in the range ⁠[0, upper)⁠ to sample the hyperparameters from.

The semantics of this distribution is that there is no more correlation in the loss function between nearby integer values, as compared with more distant integer values. This is an appropriate distribution for describing random seeds, for example. If the loss function is probably more correlated for nearby integer values, then you should probably use one of the "quantized" continuous distributions, such as either quniform(), qloguniform(), qnormal(), or qlognormal().

Usage

randint(upper)

Arguments

Value

A list of the stochastic expression.

See Also

random_parameter_sampling(), grid_parameter_sampling(), bayesian_parameter_sampling()

Description

In random sampling, hyperparameter values are randomly selected from the defined search space. Random sampling allows the search space to include both discrete and continuous hyperparameters.

Usage

random_parameter_sampling(parameter_space, properties = NULL)

Arguments

Value

The RandomParameterSampling object.

Details

In this sampling algorithm, parameter values are chosen from a set of discrete values or a distribution over a continuous range. Functions you can use include: choice(), randint(), uniform(), quniform(), loguniform(), qloguniform(), normal(), qnormal(), lognormal(), and qlognormal().

See Also

choice(), randint(), uniform(), quniform(), loguniform(), qloguniform(), normal(), qnormal(), lognormal(), qlognormal()

Examples

## Not run: 
param_sampling <- random_parameter_sampling(list("learning_rate" = normal(10, 3),
                                                 "keep_probability" = uniform(0.05, 0.1),
                                                 "batch_size" = choice(c(16, 32, 64, 128))))

## End(Not run)

Description

Split file streams in the dataset into two parts randomly and approximately by the percentage specified.

Usage

random_split_dataset(dataset, percentage, seed = NULL)

Arguments

Value

A new Dataset object representing the two datasets after the split.

Description

Register an Azure blob container as a datastore. You can choose to use either the SAS token or the storage account key.

Usage

register_azure_blob_container_datastore(
  workspace,
  datastore_name,
  container_name,
  account_name,
  sas_token = NULL,
  account_key = NULL,
  protocol = NULL,
  endpoint = NULL,
  overwrite = FALSE,
  create_if_not_exists = FALSE,
  skip_validation = FALSE,
  blob_cache_timeout = NULL,
  grant_workspace_access = FALSE,
  subscription_id = NULL,
  resource_group = NULL
)

Arguments

Value

The AzureBlobDatastore object.

Details

In general we recommend Azure Blob storage over Azure File storage. Both standard and premium storage are available for blobs. Although more expensive, we suggest premium storage due to faster throughput speeds that may improve the speed of your training runs, particularly if you train against a large dataset.

Examples

## Not run: 
ws <- load_workspace_from_config()
ds <- register_azure_blob_container_datastore(ws,
                                              datastore_name = 'mydatastore',
                                              container_name = 'myazureblobcontainername',
                                              account_name = 'mystorageaccoutname',
                                              account_key = 'mystorageaccountkey')

## End(Not run)

Description

Initialize a new Azure Data Lake Gen2 Datastore.

Usage

register_azure_data_lake_gen2_datastore(
  workspace,
  datastore_name,
  filesystem,
  account_name,
  tenant_id,
  client_id,
  client_secret,
  resource_url = NULL,
  authority_url = NULL,
  protocol = NULL,
  endpoint = NULL,
  overwrite = FALSE
)

Arguments

Value

The azureml.data.azure_data_lake_datastore.AzureDataLakeGen2Datastore object.

Examples

# Create and register an Azure Data Lake Gen2 Datastore to a workspace.

my_adlsgen2_ds <- register_azure_data_lake_gen2_datastore(workspace = your_workspace,
                                                          datastore_name = <name for this datastore>,
                                                          filesystem = 'test',
                                                          tenant_id = your_workspace$auth$tenant_id,
                                                          client_id = your_workspace$auth$service_principal_id,
                                                          client_secret = your_workspace$auth$service_principal_password)

See Also

unregister_datastore(), get_datastore()

Description

Register an Azure file share as a datastore. You can choose to use either the SAS token or the storage account key.

Usage

register_azure_file_share_datastore(
  workspace,
  datastore_name,
  file_share_name,
  account_name,
  sas_token = NULL,
  account_key = NULL,
  protocol = NULL,
  endpoint = NULL,
  overwrite = FALSE,
  create_if_not_exists = FALSE,
  skip_validation = FALSE
)

Arguments

Value

The AzureFileDatastore object.

Details

In general we recommend Azure Blob storage over Azure File storage. Both standard and premium storage are available for blobs. Although more expensive, we suggest premium storage due to faster throughput speeds that may improve the speed of your training runs, particularly if you train against a large dataset.

Examples

## Not run: 
ws <- load_workspace_from_config()
ds <- register_azure_file_share_datastore(ws,
                                          datastore_name = 'mydatastore',
                                          file_share_name = 'myazurefilesharename',
                                          account_name = 'mystorageaccoutname',
                                          account_key = 'mystorageaccountkey')

## End(Not run)

Description

Initialize a new Azure PostgreSQL Datastore.

Usage

register_azure_postgre_sql_datastore(
  workspace,
  datastore_name,
  server_name,
  database_name,
  user_id,
  user_password,
  port_number = NULL,
  endpoint = NULL,
  overwrite = FALSE
)

Arguments

Value

The azureml.data.azure_postgre_sql_datastore.AzurePostgreSqlDatastore object.

Description

Initialize a new Azure SQL database Datastore.

Usage

register_azure_sql_database_datastore(
  workspace,
  datastore_name,
  server_name,
  database_name,
  tenant_id,
  client_id,
  client_secret,
  resource_url = NULL,
  authority_url = NULL,
  endpoint = NULL,
  overwrite = FALSE,
  username = NULL,
  password = NULL
)

Arguments

Value

The azureml.data.azure_sql_database_datastore.AzureSqlDatabaseDatastore object.

Description

Register the Dataset in the workspace, making it available to other users of the workspace.

Usage

register_dataset(
  workspace,
  dataset,
  name,
  description = NULL,
  tags = NULL,
  create_new_version = FALSE
)

Arguments

Value

The registered Dataset object.

Description

Registers AMLCompute as a parallel backend with the foreach package.

Usage

register_do_azureml_parallel(workspace, compute_target)

Arguments

Description