The hardware and bandwidth for this mirror is donated by METANET, the Webhosting and Full Service-Cloud Provider.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]metanet.ch.
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.
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.
If you want to log out, you can call the logout
function.
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:
You can also use the native function in R to set the option:
It’s possible to get the project_id by calling the
get_project_id
function.
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.
Get all devices. Set the “consibio.project_id” option, before calling the function.
Get a specific device. Set the “consibio.project_id” option, before calling the function.
Get all elements. Set the “consibio.project_id” option, before calling the function.
Get a specific element. Set the “consibio.project_id” option, before calling the function.
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
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)
These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.