knitr::opts_chunk$set( collapse = TRUE, comment = "#>", eval = FALSE )
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.
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
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.
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.
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 your own user information.
user <- get_users_me()
Get all projects.
projects <- get_projects()
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 all devices. Set the "consibio.project_id" option, before calling the function.
devices <- get_devices()
Get a specific device. Set the "consibio.project_id" option, before calling the function.
device <- get_device("your_device_id")
Get all elements. Set the "consibio.project_id" option, before calling the function.
elements <- get_elements() # Get element ids element_ids <- names(elements)
Get a specific element. Set the "consibio.project_id" option, before calling the function.
element <- get_element("your_element_id")
Get datalog for a list of elements. Set the "consibio.project_id" option, before calling the function.
The datalog expects:
element_ids
: A list of element ids (Max 25 elements)from_time
: A start date (POSIXct
or numeric)to_time
: An end date (POSIXct
or numeric)Optional parameters:
interval
: Optional: An interval in seconds (numeric)raw
: Optional: A boolean to get raw data (logical)The function will return a data frame with the datalog, containing the following columns:
element_id
time
value
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)
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)
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.