SAR (version 1.0.3)

rec_endpoint: Azure product recommendations endpoint class

Description

Class representing the client endpoint to the product recommendations service.

Format

An R6 object of class rec_endpoint.

Methods

• new(...): Initialize a client endpoint object. See 'Initialization' for more details.

• train_model(...): Train a new product recommendations model; return an object of class rec_model. See Training for more details.

• get_model(description, id): Get an existing product recommendations model from either its description or ID; return an object of class rec_model.

• delete_model(description, id): Delete the specified model.

• upload_data(data, destfile): Upload a data frame to the endpoint, as a CSV file. By default, the name of the uploaded file will be the name of the data frame with a ".csv" extension.

• upload_csv(srcfile, destfile): Upload a CSV file to the endpoint. By default, the name of the uploaded file will be the same as the source file.

• sync_model_list(): Update the stored list of models for this service.

• get_swagger_url(): Get the Swagger URL for this service.

• get_service_url(): Get the service URL, which is used to train models and obtain recommendations.

Initialization

The following arguments are used to initialize a new client endpoint:

• name: The name of the endpoint; see below. Alternatively, this can also be the full URL of the endpoint.

• admin_key: The administration key for the endpoint. Use this to retrieve, train, and delete models.

• rec_key: The recommender key for the endpoint. Use this to get recommendations.

• service_host: The hostname for the endpoint. For the public Azure cloud, this is azurewebsites.net.

• storage_key: The access key for the storage account associated with the service.

• storage_sas: A shared access signature (SAS) for the storage account associated with the service. You must provide either storage_key or storage_sas if you want to upload new datasets to the backend.

• storage_host: The hostname for the storage account. For the public Azure cloud, this is core.windows.net.

• storage_endpoint: The storage account endpoint for the service. By default, uses the account that was created at service creation.

• data_container: The default blob container for input datasets. Defaults to "inputdata".

Note that the name of the client endpoint for a product recommendations service is not the name that was supplied when deploying the service. Instead, it is a randomly generated unique string that starts with the service name. For example, if you deployed a service called "myrec", the name of the endpoint is "myrecusacvjwpk4raost".

Training

To train a new model, supply the following arguments to the train_model method:

• description: A character string describing the model.

• usage_data: The training dataset. This is required.

• catalog_data: An optional dataset giving features for each item. Only used for imputing cold items.

• eval_data: An optional dataset to use for evaluating model performance.

• support_threshold: The minimum support for an item to be considered warm.

• cooccurrence: How to measure cooccurrence: either user ID, or user-by-time.

• similarity: The similarity metric to use; defaults to "Jaccard".

• cold_items: Whether recommendations should include cold items.

• cold_to_cold: Whether similarities between cold items should be computed.

• user_affinity: Whether event type and time should be considered.

• include_seed_items: Whether seed items (those already seen by a user) should be allowed as recommendations.

• half_life: The time decay parameter for computing user-item affinities.

• user_to_items: Whether user ID is used when computing personalised recommendations.

• wait: Whether to wait until the model has finished training.

• container: The container where the input datasets are stored. Defaults to the input container for the endpoint, usually "inputdata".

For detailed information on these arguments see the API reference.

See Also

az_rec_service for the service itself, rec_model for an individual recommmendations model

API reference and SAR model description at the Product Recommendations API repo on GitHub

Examples

# NOT RUN {
# creating a recommendations service endpoint from an Azure resource
svc <- resgroup$get_rec_service("myrec")
rec_endp <- svc$get_rec_endpoint()

# creating the endpoint from scratch -- must supply admin, recommender and storage keys
rec_endp <- rec_endpoint$new("myrecusacvjwpk4raost",
    admin_key="key1", rec_key="key2", storage_key="key3")

# upload the Microsoft store data
data(ms_usage)
rec_endp$upload_data(ms_usage)

# train a recommender
rec_model <- rec_endp$train_model("model1", usage="ms_usage.csv", support_threshold=10,
    similarity="Jaccard", user_affinity=TRUE, user_to_items=TRUE,
    backfill=TRUE, include_seed_items=FALSE)

# list of trained models
rec_endp$sync_model_list()

# delete the trained model (will ask for confirmation)
rec_endp$delete_model("model1")

# }