| Title: | Client for 'GoFigr.io' |
|---|---|
| Description: | Integrates with your 'RMarkdown' documents to automatically publish figures to the <https://GoFigr.io> service. Supports both 'knitr' and interactive execution within 'RStudio'. |
| Authors: | Maciej Pacula [cre, aut], Flagstaff Solutions, LLC [cph] |
| Maintainer: | Maciej Pacula <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.2.2 |
| Built: | 2025-03-09 07:03:56 UTC |
| Source: | CRAN |
Performs JWT authentication with username and password. Saves tokens in the GoFigr client.
authenticate_jwt(gf)authenticate_jwt(gf)
gf |
GoFigr client |
NA
Captures output of an expression and publishes it to GoFigr. This function is helpful if you have multiple function calls which incrementally build a single figure.
capture(expr, data = NULL, env = parent.frame())capture(expr, data = NULL, env = parent.frame())
expr |
expression which generates your figure |
data |
input data to publish with the figure |
env |
environment in which to evaluate the captured expression (default=parent.frame()) |
result of evaluating your expression
Creates a new analysis
create_analysis(gf, name, description = NULL, workspace = NULL)create_analysis(gf, name, description = NULL, workspace = NULL)
gf |
GoFigr client |
name |
analysis name |
description |
analysis description |
workspace |
analysis will be created under this workspace. Can be a workspace object or an API ID. |
created analysis
Creates a new API key. This function will only succeed if using password authentication.
create_api_key(gf, name)create_api_key(gf, name)
gf |
GoFigr client. Must be using password authentication. |
name |
human-readable name of the API key to create, e.g. "John's laptop" |
response JSON. The "token" property will contain the API key if successful.
Creates a new figure. The created figure will be blank and won't contain any revisions.
create_figure(gf, analysis, name, description = NULL)create_figure(gf, analysis, name, description = NULL)
gf |
GoFigr object |
analysis |
analysis under which to create the figure |
name |
name for the new figure |
description |
description for the new figure |
created figure object
Creates a new revision
create_revision(gf, figure, metadata = list(), data = NULL)create_revision(gf, figure, metadata = list(), data = NULL)
gf |
GoFigr client |
figure |
figure under which to create the revision |
metadata |
metadata for the revision, as named list |
data |
list of Data objects |
created revision object
Creates a new workspace
create_workspace(gf, name, description = NULL)create_workspace(gf, name, description = NULL)
gf |
GoFigr client |
name |
workspace name |
description |
workspace description |
created workspace object
List of data types supported by GoFigr
DATA_TYPESDATA_TYPES
An object of class list of length 5.
list where names are human-readable names of data types, and values are corresponding API types (strings).
Returns a default value if argument is null or empty
default_if_null(x, default)default_if_null(x, default)
x |
argument |
default |
default value if x is null, NA or "" |
x if not null, NA or "", or the default value
Enables GoFigr support.
enable( analysis_api_id = NULL, analysis_name = NULL, workspace = NULL, create_analysis = TRUE, analysis_description = NULL, watermark = QR_WATERMARK, auto_publish = FALSE, verbose = FALSE, debug = FALSE, show = "watermark" )enable( analysis_api_id = NULL, analysis_name = NULL, workspace = NULL, create_analysis = TRUE, analysis_description = NULL, watermark = QR_WATERMARK, auto_publish = FALSE, verbose = FALSE, debug = FALSE, show = "watermark" )
analysis_api_id |
Analysis API ID (if analysis_name is NULL) |
analysis_name |
Analysis name (if analysis_api_id is NULL) |
workspace |
API ID of the workspace |
create_analysis |
if TRUE and analysis_name does not exist, it will be automatically created |
analysis_description |
analysis description if creating a new analysis |
watermark |
watermark class to use, e.g. QR_WATERMARK, LINK_WATERMARK or NO_WATERMARK |
auto_publish |
will publish all plots automatically if TRUE. Note that setting this option will re-assign plot() and print() in the global environment. |
verbose |
whether to show verbose output |
debug |
whether to show debugging information |
show |
which figure to display in the document: original, watermark, or hide. Note that this setting \ only affects the display and doesn't change what gets published: e.g. even if you choose to display \ the original figure, the watermarked version will still be published to GoFigr. |
named list of GoFigr options
Converts a GoFigr data object into R primitives that can be converted to JSON, performing base64 encoding of binary data.
encode_raw_data(data)encode_raw_data(data)
data |
GoFigr data object |
encoded data object
data <- make_raw_data("test", "text", list(a=1), charToRaw("abcdefksjdfklsd")) encode_raw_data(data)data <- make_raw_data("test", "text", list(a=1), charToRaw("abcdefksjdfklsd")) encode_raw_data(data)
Finds an analysis by name, optionally creating one if it doesn't exist.
find_analysis(gf, name, description = NULL, workspace = NULL, create = FALSE)find_analysis(gf, name, description = NULL, workspace = NULL, create = FALSE)
gf |
GoFigr client |
name |
name of the analysis to find |
description |
description of the analysis if it needs to be created |
workspace |
parent workspace |
create |
if TRUE and the analysis doesn't exist, it will be created; throws an error otherwise. |
analysis object
Finds a figure by name
find_figure(gf, analysis, name, description = NULL, create = FALSE)find_figure(gf, analysis, name, description = NULL, create = FALSE)
gf |
GoFigr client |
analysis |
parent analysis |
name |
name of the figure to find |
description |
description of the figure if it needs to be created |
create |
if TRUE and the figure doesn't exist, it will be created; throws an error otherwise. |
figure object
Finds a workspace by name, optionally creating it if doesn't exist
find_workspace(gf, name, description = NULL, create = FALSE)find_workspace(gf, name, description = NULL, create = FALSE)
gf |
GoFigr client |
name |
name of the workspace to find |
description |
workspace description if creating a new one |
create |
if TRUE and workspace is not found, it will be created |
workspace if found; throws an error if not.
Fetches an analysis given an API ID.
get_analysis(gf, api_id)get_analysis(gf, api_id)
gf |
GoFigr client |
api_id |
API ID for the analysis |
analysis object
Returns obj$api_id if argument is an object, or identity if it's a string.
get_api_id(obj)get_api_id(obj)
obj |
object for which to get the API ID |
API ID, a string
Fetches a figure given an API ID.
get_figure(gf, api_id)get_figure(gf, api_id)
gf |
GoFigr client |
api_id |
API ID for the figure |
figure object
Gets configured GoFigr options.
get_options()get_options()
GoFigr options, or NULL if not set.
Fetches a revision given an API ID.
get_revision(gf, api_id)get_revision(gf, api_id)
gf |
GoFigr client |
api_id |
API ID for the revision |
revision object
Gets the full URL for a revision
get_revision_url(rev)get_revision_url(rev)
rev |
revision object |
URL, a string
Retrieves workspace details.
get_workspace(gf, api_id)get_workspace(gf, api_id)
gf |
GoFigr client |
api_id |
API ID of the workspace |
workspace details
Plots and publishes an object (if supported)
gf_plot(...)gf_plot(...)
... |
passed directly to plot |
result of the call to plot(...)
Prints and publishes an object (if supported)
gf_print(...)gf_print(...)
... |
passed directly to print |
result of the call to print(...)
Configures gofigr for use on this machine. Saves configuration to ~/.gofigr.
gfconfig(max_attempts = 3)gfconfig(max_attempts = 3)
max_attempts |
Maximum number of password attempts |
No return value
Equivalent to cat but only outputs if GoFigr client is verbose.
gofigr_cat(gf, content, ...)gofigr_cat(gf, content, ...)
gf |
GoFigr client |
content |
text to print |
... |
passed to cat |
NA
Username, password, API key and workspace are read from the GoFigr configuration file (~/.gofigr) or environment variables if not supplied:
gofigr_client( username = NULL, password = NULL, api_key = NULL, url = NULL, anonymous = FALSE, verbose = FALSE, workspace = NULL, ignore_config = FALSE )gofigr_client( username = NULL, password = NULL, api_key = NULL, url = NULL, anonymous = FALSE, verbose = FALSE, workspace = NULL, ignore_config = FALSE )
username |
username (if not using API key) |
password |
password (if not using API key) |
api_key |
API key (if not using password authentication) |
url |
API URL (optional, you generally won't want to modify this) |
anonymous |
whether to login anonymously |
verbose |
set to TRUE to enable verbose output |
workspace |
default workspace (API ID) |
ignore_config |
if TRUE, will ignore environment variables and other external configuration |
* GF_USERNAME or config$username * GF_PASSWORD or config$password * GF_API_KEY or config$api_key * GF_WORKSPACE of config$workspace * GF_URL or config$url
configured GoFigr client which you can pass to other functions
## Not run: gofigr_client() # use config from ~/.gofigr or environment variables ## Not run: gofigr_client(username="joe", password="abc123") # password login ## Not run: gofigr_client(api_key="abcdef0123456789") # API key login## Not run: gofigr_client() # use config from ~/.gofigr or environment variables ## Not run: gofigr_client(username="joe", password="abc123") # password login ## Not run: gofigr_client(api_key="abcdef0123456789") # API key login
Wrapper for httr::DELETE that automatically handles authentication.
gofigr_DELETE(gf, url, expected_status_code = 200, ...)gofigr_DELETE(gf, url, expected_status_code = 200, ...)
gf |
configured GoFigr client |
url |
URL to make the request to, relative to the API URL e.g. user/ |
expected_status_code |
expected HTTP response code. We will throw an exception if it differs. |
... |
passed to the httr request function |
result of calling the underlying httr request function
Wrapper for httr::GET that automatically handles authentication.
gofigr_GET(gf, url, expected_status_code = 200, ...)gofigr_GET(gf, url, expected_status_code = 200, ...)
gf |
configured GoFigr client |
url |
URL to make the request to, relative to the API URL e.g. user/ |
expected_status_code |
expected HTTP response code. We will throw an exception if it differs. |
... |
passed to the httr request function |
result of calling the underlying httr request function
Wraps an HTTR method e.g. GET to provide relative URL resolution and authentication
gofigr_make_handler(name, method)gofigr_make_handler(name, method)
name |
method name, e.g. "GET" |
method |
HTTR method, e.g. httr::GET |
wrapped method which takes a GoFigr client, a relative URL and an expected HTTP status code.
Wrapper for httr::PATCH that automatically handles authentication.
gofigr_PATCH(gf, url, expected_status_code = 200, ...)gofigr_PATCH(gf, url, expected_status_code = 200, ...)
gf |
configured GoFigr client |
url |
URL to make the request to, relative to the API URL e.g. user/ |
expected_status_code |
expected HTTP response code. We will throw an exception if it differs. |
... |
passed to the httr request function |
result of calling the underlying httr request function
Wrapper for httr::POST that automatically handles authentication.
gofigr_POST(gf, url, expected_status_code = 200, ...)gofigr_POST(gf, url, expected_status_code = 200, ...)
gf |
configured GoFigr client |
url |
URL to make the request to, relative to the API URL e.g. user/ |
expected_status_code |
expected HTTP response code. We will throw an exception if it differs. |
... |
passed to the httr request function |
result of calling the underlying httr request function
Wrapper for httr::PUT that automatically handles authentication.
gofigr_PUT(gf, url, expected_status_code = 200, ...)gofigr_PUT(gf, url, expected_status_code = 200, ...)
gf |
configured GoFigr client |
url |
URL to make the request to, relative to the API URL e.g. user/ |
expected_status_code |
expected HTTP response code. We will throw an exception if it differs. |
... |
passed to the httr request function |
result of calling the underlying httr request function
Returns the argument if a valid workspace is passed, or the default workspace from the GoFigr client otherwise. Throws an error if both are NULL.
infer_workspace(gf, workspace)infer_workspace(gf, workspace)
gf |
GoFigr client |
workspace |
workspace or NULL |
workspace object
Wraps a plotting function (e.g. heatmap.2) so that its output is intercepted by GoFigr.
intercept(plot_func, supported_classes = NULL, force = FALSE)intercept(plot_func, supported_classes = NULL, force = FALSE)
plot_func |
function to intercept |
supported_classes |
calls will be intercepted *only if* the first argument is an \ instance of any of these classes |
force |
force intercept even if auto_publish is off |
intercepted function
heatmap.2 <- intercept(gplots::heatmap.2)heatmap.2 <- intercept(gplots::heatmap.2)
Returns True if the response indicates an expired JWT token
is_expired_token(res)is_expired_token(res)
res |
httr response |
True if token expired
Draws a watermark with just a GoFigr link
LINK_WATERMARK(revision, image)LINK_WATERMARK(revision, image)
revision |
GoFigr revision object for which to generate a watermark |
image |
Magick image to which to add the watermark |
a function which you can pass to enable_knitr(watermark)
Lists analyses under a workspace.
list_analyses(gf, workspace_id = NULL)list_analyses(gf, workspace_id = NULL)
gf |
GoFigr client |
workspace_id |
API id of the workspace |
list of analyses
List all workspaces available to the user.
list_workspaces(gf)list_workspaces(gf)
gf |
GoFigr client |
List of workspaces
Prompts the user for an API key or creates a new one
login_with_api_key(gf, max_attempts)login_with_api_key(gf, max_attempts)
gf |
Password-authenticated GoFigr client |
max_attempts |
Maximum number of login attempts before giving up |
API key, either supplied by the user or newly created
Prompts the user for username & password and logs into GoFigr
login_with_username(max_attempts)login_with_username(max_attempts)
max_attempts |
maximum number of login attempts before giving up |
GoFigr client
Creates a GoFigr data object storing source code
make_code_data( name, contents_or_file, language, format = "text", metadata = NULL )make_code_data( name, contents_or_file, language, format = "text", metadata = NULL )
name |
name of this code object |
contents_or_file |
contents, a character string or file object |
language |
programming language, e.g. Python or R |
format |
not supported at the moment; please use the default |
metadata |
metadata associated with this object |
GoFigr data object
Creates a GoFigr data object storing file data
make_file_data(name, file_or_raw, path = NULL, metadata = NULL)make_file_data(name, file_or_raw, path = NULL, metadata = NULL)
name |
name of this file |
file_or_raw |
image data, either a file or a raw vector |
path |
file path |
metadata |
metadata associated with this file |
GoFigr data object
Creates a GoFigr data object storing image data
make_image_data(name, file_or_raw, format, is_watermarked, metadata = NULL)make_image_data(name, file_or_raw, format, is_watermarked, metadata = NULL)
name |
name of this image |
file_or_raw |
image data, either a file or a raw vector |
format |
format, e.g. "png" |
is_watermarked |
whether this file has a GoFigr watermark |
metadata |
metadata associated with this image |
GoFigr data object
Creates a GoFigr data object which can be attached to revisions.
make_raw_data(name, type, metadata, data)make_raw_data(name, type, metadata, data)
name |
name of this data |
type |
data type, e.g. DATA_TYPES$image |
metadata |
metadata associated with this data object |
data |
raw bytes |
data object
Creates a GoFigr data object storing data.frame/tabular data
make_table_data(name, frame, metadata = NULL)make_table_data(name, frame, metadata = NULL)
name |
name of this data object |
frame |
data.frame |
metadata |
metadata associated with this data object |
GoFigr data object
Creates a GoFigr data object to store text
make_text_data(name, contents, metadata = NULL)make_text_data(name, contents, metadata = NULL)
name |
name of this data object |
contents |
contents, a character string |
metadata |
metadata associated with this object |
GoFigr data object
Does not draw any watermarks.
NO_WATERMARKNO_WATERMARK
An object of class NULL of length 0.
does not return anything (NULL)
Replacement for plot in an interactive session outside of RStudio (e.g. terminal). Captures the plot and publishes to GoFigr.
plot_interactive(..., base_func)plot_interactive(..., base_func)
... |
same as plot() |
base_func |
the function whose output we are trying to capture |
same as plot()
Replacement for plot() in a knitr context. Captures the plot and publishes it to GoFigr.
plot_knitr(..., base_func)plot_knitr(..., base_func)
... |
same as plot() |
base_func |
the function whose output we are trying to capture |
same as plot()
Replacement for plot within RStudio. Captures the plot and publishes to GoFigr.
plot_rstudio(..., base_func)plot_rstudio(..., base_func)
... |
same as plot() |
base_func |
the function whose output we are trying to capture |
same as plot()
Replacement for plot in a script. Captures the plot and publishes to GoFigr.
plot_script(..., base_func)plot_script(..., base_func)
... |
same as plot() |
base_func |
the function whose output we are trying to capture |
same as plot()
Default print method for a GoFigr client.
## S3 method for class 'gofigr' print(x, ...)## S3 method for class 'gofigr' print(x, ...)
x |
GoFigr client |
... |
passed to cat |
NA
Default print representation of GoFigr data objects.
## S3 method for class 'gofigrdata' print(x, ...)## S3 method for class 'gofigrdata' print(x, ...)
x |
object to print |
... |
passed to cat |
NA
Draws a watermark with a GoFigr link and a QR code
QR_WATERMARK(revision, image)QR_WATERMARK(revision, image)
revision |
GoFigr revision object for which to generate a watermark |
image |
Magick image to which to add the watermark |
a function which you can pass to enable_knitr(watermark)
* GF_USERNAME or config["username"] * GF_PASSWORD or config["password"] * GF_API_KEY or config["api_key"] * GF_WORKSPACE or config["workspace"] * GF_URL or config["url"]
read_config(path = CONFIG_PATH)read_config(path = CONFIG_PATH)
path |
path to the config file, default ~/.gofigr |
parsed configuration or empty list if not available
Reads a prompt from stdin and performs optional validation
read_prompt(prompt, validate = NULL, attempt = 1, max_attempts = 2)read_prompt(prompt, validate = NULL, attempt = 1, max_attempts = 2)
prompt |
prompt, e.g. "Enter username: " |
validate |
function input => transformed input if input is valid or, error |
attempt |
current attempt at getting a valid input |
max_attempts |
maximum number of attempts |
input, or result of validate(input) if validate is supplied
Refreshes the JWT access token. Attempts re-authentication if refresh fails.
refresh_jwt(gf)refresh_jwt(gf)
gf |
GoFigr client. |
NA
Convenience function for parsing JSON from httr responses
response_to_JSON(response)response_to_JSON(response)
response |
httr response |
parsed JSON
Sets GoFigr options.
set_options(options)set_options(options)
options |
New options that will replace existing options. |
NA
Stacks images horizontally, centering them vertically.
stack_horizontally(images)stack_horizontally(images)
images |
vector of images to stack |
composite image
Stacks images vertically, centering them horizontally.
stack_vertically(images)stack_vertically(images)
images |
vector of images to stack |
composite image
Suppresses any automatic GoFigr publication hooks.
suppress(func)suppress(func)
func |
function in which to suppress intercepts |
the function with GoFigr supressed
Updates data associated with a figure
update_revision_data(gf, revision, new_data, silent = FALSE)update_revision_data(gf, revision, new_data, silent = FALSE)
gf |
GoFigr client |
revision |
revision or its API ID for which to update the data |
new_data |
new data, as a list of GoFigrData objects (e.g. make_image_data or make_text_data) |
silent |
whether to generate an activity. Internal use only. |
updated revision
Fetches user details for the currently logged in user.
user_info(gf)user_info(gf)
gf |
GoFigr client |
user details
Makes a watermark generator. You can use the result with enable(watermark=...).
watermark_generator( show_qr = TRUE, qr_size_px = c(100, 100), link_size_px = c(500, 100), link_bg = "#ffffff", font_color = "#000000", font_size = 14, font = "mono" )watermark_generator( show_qr = TRUE, qr_size_px = c(100, 100), link_size_px = c(500, 100), link_bg = "#ffffff", font_color = "#000000", font_size = 14, font = "mono" )
show_qr |
show QR code |
qr_size_px |
two-element vector specifying the width, height of the QR code |
link_size_px |
two-element vector specifying the width, height of the link |
link_bg |
background color for the link |
font_color |
font color for the link |
font_size |
font size for the link |
font |
font name or family, e.g. "mono" |
a function which you can pass to enable_knitr(watermark)