Using the Consibio Cloud Package

2024-07-29

Introduction

This vignette provides a detailed example of how to use the consibiocloudclient package.

The consibiocloudclient package is a R-package that allows you to interact with the Consibio Cloud API.

The package provides a simple interface to the Consibio Cloud API, allowing you to fetch data from the server, and plot it using ggplot2.

If you ever need to look deeper into our API, you can find the Swagger user interface at https://api.v2.consibio.com/api-docs/.

Please note that our R-package does not cover all the endpoints in our API. The primary usage are to fetch data to be used in R, and to plot it.

Your first call to the Consibio Cloud API

The first thing to do after loading our library, is to make a call to our API. Before going into the details on how to authenticate, fetch data, and plot it, we’ll show you how to make a simple call to our API.

We’ll use our /test endpoint, which should be seen as our health check endpoint. We expose a JSON object with a “status” and a “time” key.

library(consibiocloudclient)

# After loading our package, try and make a api status call.
result <- get_test()
status <- result$status
time <- result$time

Authentication

Logging in to Consibio Cloud is done by calling the login function, which takes your username (email) as argument.

Once executed, a password prompt will appear, and you’ll be asked to enter your password.

After a successful login, a token will be stored in memory.

login("bob@helloworld.com")

If you want to log out, you can call the logout function.

logout()

After logging out, it’s necessary to restart your R-session in other to remove any token stored in memory.

Setting credentials in environment file

It’s possible to set your credentials in a .env file, which is a common way to store sensitive information.

Add the following values:

CONSIBIO_USERNAME=your_username
CONSIBIO_PASSWORD=your_password

Always remember to clean up your .env file after usage.

Getting data

The R-package does not scope the full API, but it does provide a simple way to fetch data from the server.

Therefore it’s limited to GET-requests at the moment.

Endpoints specific for a given project, like “get_elements”, requires you to set the option “consibio.project_id”.

That can be done with the following command:

set_project_id(target_project)

You can also use the native function in R to set the option:

options("consibio.project_id" = "your_project_id")

It’s possible to get the project_id by calling the get_project_id function.

Get users/me

Get your own user information.

user <- get_users_me()

Get projects

Get all projects.

projects <- get_projects()

Get project

Get a specific project.

Here it’s possible to provide the project_id as an argument. But you can also set the “consibio.project_id” option.

If you set the option, you can call the function without any arguments.

project <- get_project()

Get devices

Get all devices. Set the “consibio.project_id” option, before calling the function.

devices <- get_devices()

Get device

Get a specific device. Set the “consibio.project_id” option, before calling the function.

device <- get_device("your_device_id")

Get elements

Get all elements. Set the “consibio.project_id” option, before calling the function.

elements <- get_elements()

# Get element ids
element_ids <- names(elements)

Get element

Get a specific element. Set the “consibio.project_id” option, before calling the function.

element <- get_element("your_element_id")

Get datalog

Get datalog for a list of elements. Set the “consibio.project_id” option, before calling the function.

The datalog expects:

Optional parameters:

The function will return a data frame with the datalog, containing the following columns:

element_ids <- c("your_element_id_1", "your_element_id_2")
to_time <- Sys.time()
from_time <- to_time - 1 * 24 * 60 * 60 # 1 days
df <- get_datalog(element_ids, from_time, to_time)

Plotting data

There’s no build in plotting function in the package, but it’s easy to plot the data using ggplot2.

Here’s a full example of how to use all the mentioned functions in the package, manipulate it, and plot it with ggplot2.

library(consibiocloudclient)

# Login 
login("bob@helloworld.com") # This will shows a prompt to enter password. If you wan't to use a static password (not recommended), set CONSIBIO_PASSWORD as env. variable before trying to login

# Get user
get_users_me()

# Get projects
projects <- get_projects()
target_project <- names(projects)[1]

# Set target project (can also be done with the native R function: options(consibio.project_id = target_project))
set_project_id(target_project)

# Get project
project <- get_project()

# Get devices
devices <- get_devices()

# Get elements
elements <- get_elements()

# Make list with elements
element_ids <- names(elements)

# Limit the scope to maximum 25 elements, which are the maximum amount of elements that can be fetched at once
element_ids <- element_ids[1:25]

# Get datalog
to_time <- Sys.time()
from_time <- to_time - 1 * 24 * 60 * 60 # 1 days
df <- get_datalog(element_ids, from_time, to_time)

############
# Element checks before plotting the data
############
# Get the elements from the df without data, but was queried
elements_without_data <- c() # Initialize an empty vector to store the elements without data
# Loop over each element in element_ids If the element is not in df$element_id, add it to elements_without_data
for (element in element_ids)
  if (!element %in% df$element_id)
    elements_without_data <- c(elements_without_data, element)
# print(elements_without_data)

# Find the elements in element_ids that are in df$element_id
elements_with_data <- setdiff(element_ids, elements_without_data)
# print(elements_with_data)

# Print a single line statement with the total, with and without
sprintf(
  "Got %d elements with data, and %d witout.",
  length(elements_with_data),
  length(elements_without_data)
)


############
# Example on how to print a plot with the dataframe values, where we use the name and color of each fetched element
############
# Create a data frame with the element IDs, names, and colors
df_element_default <- data.frame(
  element_id = names(elements),
  name = sapply(elements, function(x)
    x$name),
  color = sapply(elements, function(x)
    x$color)
)

# Merge the element data frame with the original data frame
df_extended <- merge(df, df_element_default, by = "element_id", all.x = TRUE)

# df_extended <- df_extended[df_extended$element_id == "jedBIJcmzw6tGLKvmtbm",] # Limit to a single element, if you need to test something

if (!require(ggplot2)) {
  install.packages("ggplot2")
}
library(ggplot2)

# Create a line plot with `ggplot2`
render_without_colors <- TRUE # If the colors are identical, or similar, the plot will replace the existing scales. If so, it's possible to render without the colors
if (render_without_colors) {
  ggplot(df_extended,
         aes(
           x = timestamp,
           y = value,
           color = name,
           group = element_id
         )) +
    geom_line() +
    labs(title = "Consibio Cloud Plot", x = "Timestamp", y = "Value") +
    theme(plot.title = element_text(hjust = 0.5)) +
    scale_color_manual(
      values = setNames(df_extended$color, df_extended$name),
      guide = guide_legend(title = "Element Name")
    ) +
    scale_x_datetime(date_labels = "%Y-%m-%d %H:%M:%S")
} else{
  ggplot(df_extended,
         aes(
           x = timestamp,
           y = value,
           color = color,
           group = element_id
         )) +
    geom_line() +
    labs(title = "Consibio Cloud Plot", x = "Timestamp", y = "Value") +
    theme(plot.title = element_text(hjust = 0.5)) +
    scale_color_identity() +
    guides(color = guide_legend(title = "Element Name")) +
    scale_color_discrete(labels = df_extended$name) +
    scale_x_datetime(date_labels = "%Y-%m-%d %H:%M:%S")
}

# Logout
logout() # Will remove username and user_id. Please reset your R-session to remove any tokens (which are saved automatically in memory)