Revolutions

AzureR update: new in May/June

by Hong Ooi

This is a summary of the updates to AzureR family of packages in May and June 2021.

AzureAuth

• Change the default caching behaviour to disable the cache if running inside Shiny.
• Update Shiny vignette to clean up redirect page after authenticating (thanks to Tyler Littlefield).
• Add a create_AzureR_dir function to create the caching directory manually. This can be useful not just for non-interactive sessions, but also Jupyter and R notebooks, which are not technically interactive in the sense that they cannot read user input from a console prompt.

AzureGraph

• Add enhanced support for the paging API. Many Graph calls that return lists of objects do so in pages: the first response contains a subset of the full list, along with a link to the next subset. AzureGraph now features a new ms_graph_pager R6 class, which is an iterator for the pages in the result. All list_* R6 methods have been rewritten to use this class, and have filter and n arguments to filter the result set and cap the number of results.
• Also add support for the batch request feature: you can pass multiple calls to the API with the graph_request R6 class and call_batch_endpoint function, and get the results back in a single response.
• See the Batching and paging vignette for more information on these APIs.
• Add list_users(), list_groups(), list_apps() and list_service_principals() methods to the main ms_graph client class.
• There is also a new Authentication vignette to guide users through the various ways to authenticate to Microsoft Graph.

AzureRMR

• Similar to AzureGraph, AzureRMR has a new Authentication vignette that details how to authenticate to Resource Manager. This replaces the old “Service principal” vignette.
• Update Resource Manager API version to “2021-04-01”; also update az_subscription$list_locations to handle the new response format in this API version.

AzureStor

• Add support for generating a service SAS. There is a new S3 generic get_service_sas with methods for az_storage and storage_endpoint objects, and a similar R6 method for az_storage objects. See ?sas for more information.
• Fix storage_save_rds and storage_load_rds to handle compression correctly. In particular, storage_load_rds should now correctly load files saved with saveRDS (#83).
• Fix a bug that caused list_blobs to fail when leases were present.
• Use a raw connection instead of a raw vector when calling readr::read_delim and read_csv2. This works around an issue introduced in readr 1.4.0 (#85, #86).
• Update client API version to “2020-04-08”. In particular, this allows specifying resource_type="d" when creating a service or user delegation SAS for blob storage.
• Add an optional service argument to storage_endpoint, to specify the service in question: blob, file, ADLS2, queue or table. This allows use of the generic endpoint function with URLs that don’t fit the usual pattern where the service is part of the hostname, eg custom domain names, IP addresses, etc.
  • For the same reason, remove the warning about an unrecognised endpoint URL from blob_endpoint, file_endpoint and adls_endpoint.

Microsoft365R

Microsoft365R has some significant new features in the latest version:

OneDrive/SharePoint

• Add a list_shared_items() method for the ms_drive class to access files and folders shared with you (#45).
• Allow getting drives for groups, sites and teams by name. The first argument to the get_drive() method for these classes is now drive_name; to get a drive by ID, specify the argument name explicitly: get_drive(drive_id=*)
• Add a by_item argument to the delete_item() method for drives and the delete() method for drive items (#21). This is to allow deletion of non-empty folders on SharePoint sites with data protection policies in place. Use with caution.

Outlook

• Add a search argument to the ms_outlook_folder$list_emails() method. The default is to search in the from, subject and body of the emails.

Teams

• Add list_members() and get_member() methods for teams and channels.
• Add support for @mentions in Teams channel messages (#26).

Other

• All list_* class methods now have filter and n arguments to filter the result set and cap the number of results, following the pattern in AzureGraph. The default values are filter=NULL and n=Inf. If n=NULL, an ms_graph_pager iterator object is returned instead to allow manual iteration over the results. Note that support for filtering in the underlying Graph API is somewhat uneven at the moment.
• Experimental read-only support for plans, contributed by Roman Zenka.
  • Add get_plan() and list_plans() methods to the az_group class. Note that only Microsoft 365 groups can have plans, not any other type of group.
  • To get the plan(s) for a site or team, call its get_group() method to retrieve the associated group, and then get the plan from the group.
  • A plan has methods to retrieve tasks and buckets, as well as plan details.

Microsoft365R 2.1.0 with Outlook support now on CRAN

by Hong Ooi

I’m happy to announce that Microsoft365R 2.1.0 is now on CRAN with Outlook email support! Here’s a quick summary of the new features:

• Send, reply to and forward emails, optionally composed with blastula or emayili
• Copy and move emails between folders
• Create, delete, copy and move folders
• Add, remove and download attachments

Here’s a sample of how to write an email using blastula:

library(Microsoft365R)

# 1st one is for your personal Microsoft account
# 2nd is for your work & school account
outl <- get_personal_outlook()
outlb <- get_business_outlook()

# compose an email with blastula
library(blastula)
bl_body <- "## Hello!

This is an email message that was generated by the blastula package.

We can use **Markdown** formatting with the `md()` function.

Cheers,

The blastula team"

bl_em <- compose_email(
    body=md(bl_body),
    footer=md("sent via Microsoft365R")
)
em <- outl$create_email(bl_em, subject="Hello from R",
                        to="[email protected]")

# add an attachment and send it
em$add_attachment("mydocument.docx")
em$send()

And on the other side, here’s a sample of how to work with the emails in your inbox:

# list the most recent emails in your inbox
emlst <- outl$list_emails()

# get the most recent email
em <- emlst[[1]]

# list and download attachments
em$list_attachments()
em$download_attachment("mydatafile.csv")

# reply to it
em$create_reply("Replying from R")$send()

# list the folders in your account
outl$list_folders()

# move the move recent email to a given folder
folder <- outl$get_folder("My project folder")
em$move(folder)

In addition, this release fixes a bug in the list_files() method for OneDrive/Sharepoint drives and drive items, and adds the ability to create nested drive folders in one call.

Please note that if you’re using one of the workarounds mentioned in the authentication vignette, they won’t work with Outlook. You’ll need to get the Microsoft365R app approved for your tenant, or alternatively, if you have admin rights you can create your own tenant with the required permissions. (This applies if you’re using Microsoft365R at work; if you’re using it at home on your personal account, you shouldn’t have any problems.)

If you have any feedback or comments, you can email me or open an issue at the repo.

Outlook client support in Microsoft365R available for beta test

by Hong Ooi

This is an announcement that a beta Outlook email client is now part of the Microsoft365R package. You can install it from the GitHub repository with:

devtools::install_github("Azure/Microsoft365R")

The client provides the following features:

• Send, reply to and forward emails, optionally composed with blastula or emayili
• Copy and move emails between folders
• Create, delete, copy and move folders
• Add, remove and download attachments

The plan is to submit this to CRAN sometime next month, after a period of public testing. Please give it a try and give me your feedback: either via email or by opening an issue at the repo.

Here’s a small sample of the client in action (taken from the README):

library(Microsoft365R)

# 1st one is for your personal Microsoft account
# 2nd is for your work & school account
outl <- get_personal_outlook()
outlb <- get_business_outlook()

# compose an email with blastula
library(blastula)
bl_body <- "## Hello!

This is an email message that was generated by the blastula package.

We can use **Markdown** formatting with the `md()` function.

Cheers,

The blastula team"

bl_em <- compose_email(
    body=md(bl_body),
    footer=md("sent via Microsoft365R")
)
em <- outl$create_email(bl_em, subject="Hello from R",
                        to="[email protected]")

# add an attachment and send it
em$add_attachment("mydocument.docx")
em$send()

# list the most recent emails in your inbox
emlst <- outl$list_emails()

# reply to the most recent email
emlst[[1]]$
    create_reply("Replying from R")$
    send()

Please note though, that if you’re using one of the workarounds mentioned in the authentication vignette, they won’t work with Outlook. You’ll need to get the Microsoft365R app approved for your tenant, or alternatively, if you have admin rights you can create your own tenant with the required permissions. (This applies if you’re using Microsoft365R at work; if you’re using it at home on your personal account, you shouldn’t have any problems.)

Teams support in Microsoft365R

by Hong Ooi

I’m happy to announce that version 2.0 of Microsoft365R, the R interface to Microsoft 365, is now on CRAN! This version adds support for Microsoft Teams, a much-requested feature.

To access a team in Microsoft Teams, use the get_team() function and provide the team name or ID. You can also list the teams you’re in with list_teams(). These return objects of R6 class ms_team, which has methods for working with channels and drives.

list_teams()
team <- get_team("My team")

# list the channels in a team (including your private channels)
team$list_channels()

# get the primary channel for a team
team$get_channel()

# get a specific channel
team$get_channel("My channel")

# drives for a team
team$list_drives()
team$get_drive()

A drive is an ms_drive object, so if you’re already using Microsoft365R to interface with OneDrive and SharePoint document libraries, you already know how to use a team’s drives. Each team will generally have at least one drive, and possibly two: the default “Shared Documents” drive, which is where uploaded files are stored, and the “Teams Wiki Data” drive, if the team has a wiki. Each team channel will usually also have an associated folder in each drive.

drv <- team$get_drive()

# one folder per channel
drv$list_files()

# upload will appear in Files tab of "My channel" in the Teams client
drv$upload_file("myfile.csv", "My channel/myfile.csv")

Channels

A team object has methods for listing, retrieving, creating and deleting channels. However you should not create and delete channels unnecessarily, since Teams tracks all channels ever created, even after you delete them. In turn, a channel object has methods for listing and sending messages, and uploading and deleting files.

Channel messages

Teams channels are semi-threaded. Getting the list of messages for a channel retrieves only the first message in each thread; to get an entire thread, you get the starting message and then retrieve the replies to it. Note that channels don’t have nested replies, so you can’t reply to a reply—only to the starting message.

The body of a message is part of the list of properties returned from the host, and can be found in the properties field of the object. Other properties include metadata such as the author, date, list of attachments, etc.

chan <- team$get_channel()

# retrieve most recent messages from the server
msgs <- chan$list_messages()

# get the latest message by ID
msg <- chan$get_message(msgs[[1]]$properties$id)

# body of the message
msg$properties$body

# 10 most recent replies
repl_list <- msg$list_replies(n=10)

# body of an individual reply
repl_list[[1]]$properties$body

You can send a message to a channel as plain text (the default) or HTML. A message can also include attachments and inline images.

# sending messages to a channel
chan$send_message("Hello from R")
chan$send_message(
    "<div>Hello from <em>R</em></div>", content_type="html")

# attachments and inline images
chan$send_message("Hello with attachments",
    attachments=c("intro.md", "myfile.csv"))
chan$send_message("",
    content_type="html", inline="graph.png")

# send a reply to a message
msg <- chan$send_message("Starting a new thread in R")
msg$send_reply("Reply from R")

Currently, Microsoft365R only supports messaging in channels. Support for chats between individuals may come later.

Channel files

Uploading a file to a channel will place it in the channel’s drive folder. The channel object itself provides convenience functions to list, upload and download files. It also provides a get_folder() method to retrieve the folder for the channel, as an ms_drive_item object; this object has more general methods for working with files.

# files for the channel
chan$list_files()

# upload a file to the channel
chan$upload_file("myfile.docx")

# open the uploaded document for editing in Word Online
chan_folder <- chan$get_folder()
item <- chan_folder$get_item("myfile.docx")
item$open()

# download it again
item$download(overwrite=TRUE)

Providing Feedback

Let us know how this works for you! You can provide feedback and make feature requests by opening an issue at the repo, or by emailing me at hongooi73 (@) gmail.com.

Microsoft365R: an R interface to the Microsoft 365 suite

I’m very happy to announce Microsoft365R, a package for working with the Microsoft 365 (formerly known as Office 365) suite of cloud services. Microsoft365R extends the interface to the Microsoft Graph API provided by the AzureGraph package to provide a lightweight yet powerful interface to SharePoint and OneDrive, with support for Teams and Outlook soon to come.

Microsoft365R is now available on CRAN, or you can install the development version from GitHub with devtools::install_github("Azure/Microsoft365R").

Authentication

The first time you call one of the Microsoft365R functions (see below), it will use your Internet browser to authenticate with Azure Active Directory (AAD), in a similar manner to other web apps. You will get a dialog box asking for permission to access your information.

Microsoft365R is registered as an app in the “aicatr” AAD tenant. Because it needs read/write access to groups and SharePoint sites, you’ll need an admin to grant it access to your tenant. Alternatively, if the environment variable CLIMICROSOFT365_AADAPPID is set, Microsoft365R will use its value as the app ID for authenticating; or you can specify the app ID as an argument when calling the functions below. See also this issue at the GitHub repo for some possible workarounds.

OneDrive

To access your personal OneDrive, call the personal_onedrive() function, and to access OneDrive for Business call business_onedrive(). Both functions return an R6 client object of class ms_drive, which has methods for working with files and folders. Note that OneDrive for Business is technically part of SharePoint, and requires a Microsoft 365 Business subscription.

od <- personal_onedrive()
odb <- business_onedrive(tenant="mycompany")

# use the device code authentication flow in RStudio Server
od <- personal_onedrive(auth_type="device_code")

# list files and folders
od$list_items()
od$list_items("Documents")

# upload and download files
od$download_file("Documents/myfile.docx")
od$upload_file("somedata.xlsx")

# create a folder
od$create_folder("Documents/newfolder")

You can open a file or folder in your browser with the open_item() method. For example, a Word document or Excel spreadsheet will open in Word or Excel Online, and a folder will be shown in OneDrive.

od$open_item("Documents/myfile.docx")

You can get and set the metadata properties for a file or folder with get_item_properties() and set_item_properties(). For the latter, provide the new properties as named arguments to the method. Not all properties can be changed; some, like the file size and last modified date, are read-only. You can also retrieve an object representing the file or folder with get_item(), which has methods appropriate for drive items.

od$get_item_properties("Documents/myfile.docx")

# rename a file -- version control via filename is bad, mmkay
od$set_item_properties("Documents/myfile.docx", name="myfile version 2.docx")

# alternatively, you can call the file object's update() method
item <- od$get_item("Documents/myfile.docx")
item$update(name="myfile version 2.docx")

SharePoint

To access a SharePoint site, use the sharepoint_site() function and provide the site URL or ID.

site <- sharepoint_site("https://myaadtenant.sharepoint.com/sites/my-site-name")

The client object has methods to retrieve drives (document libraries) and lists. To show all drives in a site, use the list_drives() method, and to retrieve a specific drive, use get_drive(). Each drive is an object of class ms_drive, just like the OneDrive clients above.

# list of all document libraries under this site
site$list_drives()

# default document library
drv <- site$get_drive()

# same methods as for OneDrive
drv$list_items()
drv$open_item("teamproject/plan.xlsx")

To show all lists in a site, use the get_lists() method, and to retrieve a specific list, use get_list() and supply either the list name or ID.

site$get_lists()
lst <- site$get_list("my-list")

You can retrieve the items in a list as a data frame, with list_items(). This has arguments filter and select to do row and column subsetting respectively. filter should be an OData expression provided as a string, and select should be a string containing a comma-separated list of columns. Any column names in the filter expression must be prefixed with fields/ to distinguish them from item metadata.

# return a data frame containing all list items
lst$list_items()

# get subset of rows and columns
lst$list_items(
    filter="startsWith(fields/firstname, 'John')",
    select="firstname,lastname,title"
)

Finally, you can retrieve subsites with list_subsites() and get_subsite(). These also return SharePoint site objects, so all the methods above are available for a subsite.

Future plans

Currently, Microsoft365R supports OneDrive and SharePoint Online; future updates will add the ability to post to Teams channels and send emails via Outlook. You can also provide feedback and make feature requests by opening an issue at the repo, or by emailing me at hongooi73 (@) gmail.com.

AzureTableStor: R interface to Azure table storage service

by Hong Ooi

I’m pleased to announce that the AzureTableStor package, providing a simple yet powerful interface to the Azure table storage service, is now on CRAN. This is something that many people have requested since the initial release of the AzureR packages nearly two years ago.

Azure table storage is a service that stores structured NoSQL data in the cloud, providing a key/attribute store with a schemaless design. Because table storage is schemaless, it’s easy to adapt your data as the needs of your application evolve. Access to table storage data is fast and cost-effective for many types of applications, and is typically lower in cost than traditional SQL for similar volumes of data.

You can use table storage to store flexible datasets like user data for web applications, address books, device information, or other types of metadata your service requires. You can store any number of entities in a table, and a storage account may contain any number of tables, up to the capacity limit of the storage account.

AzureTableStor builds on the functionality provided by the AzureStor package. The table storage service is available both as part of general Azure storage and via Azure Cosmos DB; AzureTableStor is able to work with either.

Tables

AzureTableStor provides a table_endpoint function that is the analogue of AzureStor’s blob_endpoint, file_endpoint and adls_endpoint functions. There are methods for retrieving, creating, listing and deleting tables within the endpoint.

library(AzureTableStor)

# storage account endpoint
endp <- table_endpoint(
    "https://mystorageacct.table.core.windows.net",
    key="mykey")
# Cosmos DB w/table API endpoint
endp <- table_endpoint(
    "https://mycosmosdb.table.cosmos.azure.com:443",
    key="mykey")

create_storage_table(endp, "mytable")
list_storage_tables(endp)
tab <- storage_table(endp, "mytable")

Entities

In table storage jargon, an entity is a row in a table. The columns of the table are properties. Note that table storage does not enforce a schema; that is, individual entities in a table can have different properties. An entity is identified by its RowKey and PartitionKey properties, which must be unique for each entity.

AzureTableStor provides the following functions to work with data in a table:

• insert_table_entity: inserts a row into the table.
• update_table_entity: updates a row with new data, or inserts a new row if it doesn’t already exist.
• get_table_entity: retrieves an individual row from the table.
• delete_table_entity: deletes a row from the table.
• import_table_entities: inserts multiple rows of data from a data frame into the table.

insert_table_entity(tab, list(
    RowKey="row1",
    PartitionKey="partition1",
    firstname="Bill",
    lastname="Gates"
))

get_table_entity(tab, "row1", "partition1")

# we can import to the same table as above:
# table storage doesn't enforce a schema
import_table_entities(tab, mtcars,
    row_key=row.names(mtcars),
    partition_key=as.character(mtcars$cyl))

list_table_entities(tab)
list_table_entities(tab, filter="firstname eq 'Satya'")
list_table_entities(tab, filter="RowKey eq 'Toyota Corolla'")

Batch transactions

With the exception of import_table_entities, all of the above entity functions work on a single row of data. Table storage provides a batch execution facility, which lets you bundle up single-row operations into a single transaction that will be executed atomically. In the jargon, this is known as an entity group transaction. import_table_entities is an example of an entity group transaction: it bundles up multiple rows of data into batch jobs, which is much more efficient than sending each row individually to the server.

The create_table_operation, create_batch_transaction and do_batch_transaction functions let you perform entity group transactions. Here is an example of a simple batch insert. The actual import_table_entities function is more complex as it can also handle multiple partition keys and more than 100 rows of data.

ir <- subset(iris, Species == "setosa")

# property names must be valid C# variable names
names(ir) <- sub("\\.", "_", names(ir))

# create the PartitionKey and RowKey properties
ir$PartitionKey <- ir$Species
ir$RowKey <- sprintf("%03d", seq_len(nrow(ir)))

# generate the array of insert operations: 1 per row
ops <- lapply(seq_len(nrow(ir)), function(i)
    create_table_operation(endp, "mytable", body=ir[i, ],
                           http_verb="POST")))

# create a batch transaction and send it to the endpoint
bat <- create_batch_transaction(endp, ops)
do_batch_transaction(bat)

If you have any feedback, or to report bugs with the package, please contact me at [email protected] or open an issue on GitHub.

Create and deploy a Custom Vision predictive service in R with AzureVision

The AzureVision package is an R frontend to Azure Computer Vision and Azure Custom Vision. These services let you leverage Microsoft’s Azure cloud to carry out visual recognition tasks using advanced image processing models, with minimal machine learning expertise.

The basic idea behind Custom Vision is to take a pre-built image recognition model supplied by Azure, and customise it for your needs by supplying a set of images with which to update it. All model training and prediction is done in the cloud, so you don’t need a powerful machine of your own. Similarly, since you are starting with a model that has already been trained, you don’t need a very large dataset or long training times to obtain good predictions (ideally).

This article walks you through how to create, train and deploy a Custom Vision model in R, using AzureVision.

Creating the resources

You can create the Custom Vision resources via the Azure portal, or in R using the facilities provided by AzureVision. Note that Custom Vision requires at least two resources to be created: one for training, and one for prediction. The available service tiers for Custom Vision are F0 (free, limited to 2 projects for training and 10k transactions/month for prediction) and S0. Here is the R code for creating the resources:

library(AzureVision)

# insert your tenant, subscription, resgroup name and location here
rg <- AzureRMR::get_azure_login(tenant)$
    get_subscription(sub_id)$
    create_resource_group(rg_name, location=rg_location)

# insert your desired Custom Vision resource names here
res <- rg$create_cognitive_service(custvis_resname,
    service_type="CustomVision.Training", service_tier="S0")
pred_res <- rg$create_cognitive_service(custvis_predresname,
    service_type="CustomVision.Prediction", service_tier="S0")

Training

Custom Vision defines two different types of endpoint: a training endpoint, and a prediction endpoint. Somewhat confusingly, they can both use the same hostname, but with different URL paths and authentication keys. To start, call the customvision_training_endpoint function with the service URL and key.

url <- res$properties$endpoint
key <- res$list_keys()[1]

endp <- customvision_training_endpoint(url=url, key=key)

Custom Vision is organised hierarchically. At the top level, we have a project, which represents the data and model for a specific task. Within a project, we have one or more iterations of the model, built on different sets of training images. Each iteration in a project is independent: you can create (train) an iteration, deploy it, and delete it without affecting other iterations.

In turn, there are three different types of projects:

• A multiclass classification project is for classifying images into a set of tags, or target labels. An image can be assigned to one tag only.
• A multilabel classification project is similar, but each image can have multiple tags assigned to it.
• An object detection project is for detecting which objects, if any, from a set of candidates are present in an image.

Let’s create a classification project:

testproj <- create_classification_project(endp, "testproj",
    export_target="standard")

Here, we specify the export target to be standard to support exporting the final model to one of various standalone formats, eg TensorFlow, CoreML or ONNX. The default is none, in which case the model stays on the Custom Vision server. The advantage of none is that the model can be more complex, resulting in potentially better accuracy.

Adding and tagging images

Since a Custom Vision model is trained in Azure and not locally, we need to upload some images. The data we’ll use comes from the Microsoft Computer Vision Best Practices project. This is a simple set of images containing 4 kinds of objects one might find in a fridge: cans, cartons, milk bottles, and water bottles.

download.file(
    "https://cvbp.blob.core.windows.net/public/datasets/image_classification/fridgeObjects.zip",
    "fridgeObjects.zip"
)
unzip("fridgeObjects.zip")

The generic function to add images to a project is add_images, which takes a vector of filenames, Internet URLs or raw vectors as the images to upload. It returns a vector of image IDs, which are how Custom Vision keeps track of the images it uses.

Let’s upload the fridge objects to the project. The method for classification projects has a tags argument which can be used to assign labels to the images as they are uploaded. We’ll keep aside 5 images from each class of object to use as validation data.

cans <- dir("fridgeObjects/can", full.names=TRUE)
cartons <- dir("fridgeObjects/carton", full.names=TRUE)
milk <- dir("fridgeObjects/milk_bottle", full.names=TRUE)
water <- dir("fridgeObjects/water_bottle", full.names=TRUE)

# upload all but 5 images from cans and cartons, and tag them
can_ids <- add_images(testproj, cans[-(1:5)], tags="can")
carton_ids <- add_images(testproj, cartons[-(1:5)], tags="carton")

If you don’t tag the images at upload time, you can do so later with add_image_tags:

# upload all but 5 images from milk and water bottles
milk_ids <- add_images(testproj, milk[-(1:5)])
water_ids <- add_images(testproj, water[-(1:5)])

add_image_tags(testproj, milk_ids, tags="milk_bottle")
add_image_tags(testproj, water_ids, tags="water_bottle")

Other image functions to be aware of include list_images, remove_images, and add_image_regions (which is for object detection projects). A useful one is browse_images, which takes a vector of IDs and displays the corresponding images in your browser.

browse_images(testproj, water_ids[1:5])

Training the model

Having uploaded the data, we can train the Custom Vision model with train_model. This trains the model on the server and returns a model iteration, which is the result of running the training algorithm on the current set of images. Each time you call train_model, for example to update the model after adding or removing images, you will obtain a different model iteration. In general, you can rely on AzureVision to keep track of the iterations for you, and automatically return the relevant results for the latest iteration.

mod <- train_model(testproj)

We can examine the model performance on the training data with the summary method. For this toy problem, the model manages to obtain a perfect fit.

summary(mod)

Obtaining predictions from the trained model is done with the predict method. By default, this returns the predicted tag (class label) for the image, but you can also get the predicted class probabilities by specifying type="prob".

validation_imgs <- c(cans[1:5], cartons[1:5], milk[1:5], water[1:5])
validation_tags <- rep(c("can", "carton", "milk_bottle", "water_bottle"), each=5)

predicted_tags <- predict(mod, validation_imgs)

table(predicted_tags, validation_tags)

##               validation_tags
## predicted_tags can carton milk_bottle water_bottle
##   can            4      0           0            0
##   carton         0      5           0            0
##   milk_bottle    1      0           5            0
##   water_bottle   0      0           0            5

This shows that the model got 19 out of 20 predictions correct on the validation data, misclassifying one of the cans as a milk bottle.

Deployment

Publishing to a prediction resource

The code above demonstrates using the training endpoint to obtain predictions, which is really meant only for model testing and validation. In a production setting, we would normally publish a trained model to a Custom Vision prediction resource. Among other things, a user with access to the training endpoint has complete freedom to modify the model and the data, whereas access to the prediction endpoint only allows getting predictions.

Publishing a model requires knowing the Azure resource ID of the prediction resource. Here, we’ll use the resource object that we created earlier; you can also obtain this information from the Azure Portal.

# publish to the prediction resource we created above
publish_model(mod, "iteration1", pred_res)

Once a model has been published, we can obtain predictions from the prediction endpoint in a manner very similar to previously. We create a predictive service object with classification_service, and then call the predict method. Note that a required input is the project ID; you can supply this directly or via the project object. It may also take some time before a published model shows up on the prediction endpoint.

Sys.sleep(60)  # wait for Azure to finish publishing

pred_url <- pred_res$properties$endpoint
pred_key <- pred_res$list_keys()[1]

pred_endp <- customvision_prediction_endpoint(url=pred_url, key=pred_key)

project_id <- testproj$project$id
pred_svc <- classification_service(pred_endp, project_id, "iteration1")

# predictions from prediction endpoint -- same as before
predsvc_tags <- predict(pred_svc, validation_imgs)
table(predsvc_tags, validation_tags)

##               validation_tags
## predsvc_tags   can carton milk_bottle water_bottle
##   can            4      0           0            0
##   carton         0      5           0            0
##   milk_bottle    1      0           5            0
##   water_bottle   0      0           0            5

Exporting as standalone

As an alternative to deploying the model to an online predictive service resource, for example if you want to create a custom deployment solution, you can also export the model as a standalone object. This is only possible if the project was created to support exporting. The formats supported include:

• ONNX 1.2
• CoreML
• TensorFlow or TensorFlow Lite
• A Docker image for either the Linux, Windows or Raspberry Pi environment
• Vision AI Development Kit (VAIDK)

To export the model, simply call export_model and specify the target format. This will download the model to your local machine.

export_model(mod, "tensorflow")

More information

AzureVision is part of the AzureR family of packages. This provides a range of tools to facilitate access to Azure services for data scientists working in R, such as AAD authentication, blob and file storage, Resource Manager, container services, Data Explorer (Kusto), and more.

If you are interested in Custom Vision, you may also want to check out CustomVision.ai, which is an interactive frontend for building Custom Vision models.

AzureQstor: R interface to Azure Queue Storage now on GitHub

This post is to announce that the AzureQstor package is now on GitHub. AzureQstor provides an R interface to Azure queue storage, building on the facilities provided by AzureStor.

Queue Storage is a service for storing large numbers of messages, for example from automated sensors, that can be accessed remotely via authenticated calls using HTTP or HTTPS. A single queue message can be up to 64 KB in size, and a queue can contain millions of messages, up to the total capacity limit of a storage account. Queue storage is often used to create a backlog of work to process asynchronously.

AzureQstor uses a combination of S3 and R6 classes. The queue endpoint is an S3 object for compatibility with AzureStor, while R6 classes are used to represent queues and messages.

library(AzureQstor)

endp <- storage_endpoint("https://mystorage.queue.core.windows.net",
                         key="access_key")

# creating, retrieving and deleting queues
create_storage_queue(endp, "myqueue")
qu <- storage_queue(endp, "myqueue")

qu2 <- create_storage_queue(endp, "myqueue2")
delete_storage_queue(qu2)

The queue object exposes methods for getting (reading), peeking, deleting, updating, popping (reading and deleting) and putting (writing) messages:

qu$put_message("Hello queue")
msg <- qu$get_message()

msg$text
## [1] "Hello queue"

# get several messages at once
qu$get_messages(n=30)

The message object exposes methods for deleting and updating the message:

msg$update(visibility_timeout=30, text="Updated message")
msg$delete()

You can also get and set metadata for a queue with the AzureStor get/set_storage_metadata generics:

get_storage_metadata(qu)
set_storage_metadata(qu, name1="value1", name2="value2")

It’s anticipated that AzureQstor will be submitted to CRAN before long. If you are a queue storage user, please install it and give it a try; any feedback or bug report is much appreciated. You can email me or open an issue on GitHub.

foreach 1.5.0 now available on CRAN

This post is to announce that version 1.5.0 of the foreach package is now on CRAN. Foreach is an idiom that allows for iterating over elements in a collection, without the use of an explicit loop counter. The foreach package is now more than 10 years old, and is used by nearly 700 packages across CRAN and Bioconductor. (If you're interested in an overview of the foreach package and its history, this RStudio::conf talk by Bryan Lewis is worth watching.)

The main change is 1.5.0 is intended to help reduce errors associated with modifying global variables. Now, %dopar% loops with a sequential backend will evaluate the loop body inside a local environment. Why make that change? Let's illustrate with an example:

library(foreach)
registerDoSEQ()

a <- 0
foreach(i=1:10) %dopar% {a <- a + 1}
a
## [1] 0

Here, the assignment inside the %dopar% is to a local copy of a, so the global variable a remains unchanged. The reason for this change is because %dopar% is intended for use in a parallel context, where modifying the global environment doesn’t make sense: the work will be taking place in different R processes, sometimes on different physical machines, possibly in the cloud. In this context there is no shared global environment to manipulate, unlike the case of a sequential backend.

Because of this, it’s almost always a mistake to modify global variables from %dopar%, even if it used to succeed. This change will hopefully reduce the incidence of programming errors where people prototype their code with a sequential backend, only to have it fail when they use it with a real (parallel) backend.

Note that the behaviour of the %do% operator, which is intended for a sequential backend, remains the same. It matches that of a regular for loop:

a <- 0
foreach(i=1:10) %do% {a <- a + 1}
a
## [1] 10

If you have any questions or comments, please email me or open an issue at the GitHub repo.

Changes in the foreach package

by Hong Ooi, Senior Data Scientist at Microsoft and maintainer of the foreach package

This post is to announce some new and upcoming changes in the foreach package.

First, foreach can now be found on GitHub! The repository is at https://github.com/RevolutionAnalytics/foreach, replacing its old home on R-Forge. Right now the repo hosts both the foreach and iterators packages, but that may change later.

The latest 1.4.8 version of foreach, which is now live on CRAN, adds preliminary support for evaluating %dopar% expressions in a local environment when a sequential backend is used. This addresses a long-standing inconsistency in the behaviour of %dopar% with parallel and sequential backends, where the latter would evaluate the loop body in the global environment by default. This is a common source of bugs: code that works when prototyped with a sequential backend, mysteriously fails with a “real” parallel backend.

From version 1.4.8, the behaviour of %dopar% can be controlled with

options(foreachDoparLocal=TRUE|FALSE)

or equivalently via the system environment variable

R_FOREACH_DOPAR_LOCAL=TRUE|FALSE

with the R option taking its value from the environment variable. The current default value is FALSE, which retains the pre-existing behaviour. It is intended that over time this will be changed to TRUE.

A side-effect of this change is that %do% and %dopar% will (eventually) behave differently for a sequential backend. See this Github issue for more discussion on this topic.

In the background, the repo has also been updated to use modern tooling such as Roxygen, RMarkdown and testthat. None of these should affect how the package works, although there are some minor changes to documentation formats (in particular, the vignettes are now in HTML format rather than PDF).

Some further changes are also planned down the road, to better integrate foreach with the future package by Henrik Bengtsson. See this Github issue for further details.

Please feel free to leave comments, bug reports and pull requests at the foreach repo, or you can contact me directly at [email protected].