| 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: | 2.0.2 |
| Built: | 2026-06-07 06:56:47 UTC |
| Source: | https://github.com/gofigr/gofigr |
Creates an object representing a relationship between a figure and an asset.
asset_linked_to_figure(figure_revision, asset_revision, use_type = "indirect")asset_linked_to_figure(figure_revision, asset_revision, use_type = "indirect")
figure_revision |
figure revision ID or object |
asset_revision |
asset revision ID or object |
use_type |
direct or indirect |
relationship object
Performs JWT authentication with username and password. Saves tokens in the GoFigr client.
authenticate_jwt(gf)authenticate_jwt(gf)
gf |
GoFigr client |
NA
Calculates a checksum for a file
calc_checksum(path)calc_checksum(path)
path |
path to the file |
checksum, as a hex digest
Default cat method for GoFigr revisions.
cat.gofigr_revision(x, ...)cat.gofigr_revision(x, ...)
x |
revision |
... |
passed to cat |
NA
Check total DataFrame size against MAX_CLEAN_ROOM_BYTES. Returns a list with $ok (logical) and $total_bytes.
check_clean_room_size(descriptors)check_clean_room_size(descriptors)
descriptors |
named list of gf_param descriptors |
list with ok and total_bytes fields
Checks whether GoFigr has been correctly configured.
check_configured(response = warning)check_configured(response = warning)
response |
function to use to show the warning message if not configured. Default: warning. |
TRUE if configured, FALSE otherwise
reproducible functions.Creates a checkbox parameter for use in reproducible functions.
checkbox(default)checkbox(default)
default |
default logical value |
a gf_param object
Default path to the config file
CONFIG_PATHCONFIG_PATH
An object of class character of length 1.
file path
Analyses act as containers for figures, data and revisions. This helper creates a fresh analysis under the specified workspace.
create_analysis(gf, name, description = NULL, workspace = NULL)create_analysis(gf, name, description = NULL, workspace = NULL)
gf |
GoFigr client. |
name |
Human-readable analysis name. |
description |
Optional longer description of the analysis. |
workspace |
Workspace under which the analysis will be created. Can be a workspace object or an API ID. If ‘NULL', the client’s default workspace is used. |
The created analysis object as returned by the API.
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 asset
create_asset(gf, workspace, name, description = NULL, analysis = NULL)create_asset(gf, workspace, name, description = NULL, analysis = NULL)
gf |
GoFigr client |
workspace |
parent workspace |
name |
name of the asset |
description |
description of the asset |
analysis |
optional analysis API ID to scope the asset under |
asset object
Creates a new asset revision
create_asset_revision(gf, asset, metadata = list(), data = NULL)create_asset_revision(gf, asset, metadata = list(), data = NULL)
gf |
GoFigr client |
asset |
asset under which to create the revision |
metadata |
metadata for the revision, as a named list |
data |
list of Data objects |
created revision object
The newly created figure is initially blank and contains no revisions. Use the revision helpers to attach content once the figure has been created.
create_figure(gf, analysis, name, description = NULL)create_figure(gf, analysis, name, description = NULL)
gf |
GoFigr client. |
analysis |
Parent analysis under which to create the figure. Can be an analysis object or an API ID. |
name |
Human-readable name for the new figure. |
description |
Optional longer description of the figure's purpose or contents. |
The created figure object as returned by the API.
Creates a list of arguments for ggplot2::ggsave() with optional dimension and DPI parameters.
create_ggsave_args( filename, plot, width = NULL, height = NULL, units = "in", dpi = NULL )create_ggsave_args( filename, plot, width = NULL, height = NULL, units = "in", dpi = NULL )
filename |
output filename |
plot |
plot object |
width |
width of the output image. If NULL, not included in arguments. |
height |
height of the output image. If NULL, not included in arguments. |
units |
units for width and height. If NULL, not included in arguments. |
dpi |
resolution of the output image. If NULL, not included in arguments. |
list of arguments suitable for do.call(ggplot2::ggsave, ...)
Creates a new revision
create_revision( gf, figure, metadata = list(), data = NULL, client_id = NULL, short_id = NULL )create_revision( gf, figure, metadata = list(), data = NULL, client_id = NULL, short_id = NULL )
gf |
GoFigr client |
figure |
figure under which to create the revision |
metadata |
metadata for the revision, as a named list |
data |
list of Data objects |
client_id |
optional client-generated UUID for idempotent creation. When provided, the server uses this as the revision's ID and returns 409 Conflict if a revision with the same client_id already exists. |
short_id |
optional short ID for compact QR codes. Generated via
|
created revision object
The server creates a temporary figure, processes the image data, then uses
AI to assign the revision to the correct figure. The revision will have
is_processing=TRUE until assignment completes.
create_revision_auto_assign( gf, analysis, metadata = list(), data = NULL, client_id = NULL, short_id = NULL )create_revision_auto_assign( gf, analysis, metadata = list(), data = NULL, client_id = NULL, short_id = NULL )
gf |
GoFigr client |
analysis |
analysis under which to auto-assign the revision |
metadata |
metadata for the revision, as a named list |
data |
list of Data objects |
client_id |
optional client-generated UUID for idempotent creation |
short_id |
optional short ID for compact QR codes |
created revision object
Workspaces are top-level containers for analyses and figures. This helper creates a new workspace owned by the current user.
create_workspace(gf, name, description = NULL)create_workspace(gf, name, description = NULL)
gf |
GoFigr client. |
name |
Human-readable workspace name. |
description |
Optional longer description of the workspace. |
The created workspace object as returned by the API.
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
This permanently removes the analysis and its associated figures and revisions from the workspace.
delete_analysis(gf, api_id)delete_analysis(gf, api_id)
gf |
GoFigr client. |
api_id |
Character string with the API ID of the analysis to delete. |
Invisibly returns 'NULL'. An error is thrown if the deletion fails.
reproducible functions.Creates a dropdown parameter for use in reproducible functions.
dropdown(default, choices)dropdown(default, choices)
default |
default value |
choices |
character vector of allowed values |
a gf_param object
Enables GoFigr in the current R/Rmd file.
enable( auto_publish = FALSE, analysis_api_id = NULL, analysis_name = NULL, workspace = NULL, workspace_name = NULL, create_analysis = TRUE, create_workspace = TRUE, analysis_description = NULL, workspace_description = NULL, watermark = QR_WATERMARK, verbose = FALSE, debug = FALSE, auto_assign = NULL, api_key = NULL, url = NULL, show = "watermark" )enable( auto_publish = FALSE, analysis_api_id = NULL, analysis_name = NULL, workspace = NULL, workspace_name = NULL, create_analysis = TRUE, create_workspace = TRUE, analysis_description = NULL, workspace_description = NULL, watermark = QR_WATERMARK, verbose = FALSE, debug = FALSE, auto_assign = NULL, api_key = NULL, url = NULL, show = "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. |
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 |
workspace_name |
Workspace name (if workspace is NULL) |
create_analysis |
if TRUE and analysis_name does not exist, it will be automatically created |
create_workspace |
if TRUE and workspace_name does not exist, it will be automatically created |
analysis_description |
analysis description if creating a new analysis |
workspace_description |
workspace description if creating a new workspace |
watermark |
watermark class to use, e.g. QR_WATERMARK, LINK_WATERMARK or NO_WATERMARK |
verbose |
whether to show verbose output |
debug |
whether to show debugging information |
auto_assign |
if TRUE, use AI-based auto-assignment of figures instead of
explicit figure names. Requires AI to be enabled on the server. Can be
overridden per-call in |
api_key |
GoFigr API key |
url |
GoFigr API URL |
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
Do not call publish() from forked child processes
(e.g. inside parallel::mclapply or future::plan(multicore)).
Forks inherit the short ID counter, which can produce duplicate IDs and
server-side conflicts. Graphics devices also do not survive forks.
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)
Searches the analyses within a workspace by name and, optionally, creates a new analysis when no match is found.
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 |
Optional description to assign if a new analysis is created. |
workspace |
Parent workspace (object or API ID). If 'NULL', the client's default workspace is used. |
create |
Logical; if 'TRUE' and the analysis does not exist, a new one is created. If 'FALSE', an error is thrown when no matching analysis is found. |
An analysis object corresponding to the matching (or newly created) analysis.
Finds an asset by name
find_asset_by_name(gf, name, analysis = NULL)find_asset_by_name(gf, name, analysis = NULL)
gf |
GoFigr client |
name |
name of the asset to search for |
analysis |
optional analysis API ID to scope the search |
list of matching assets, or an empty list if none found
Finds all asset revisions with a matching hash digest
find_asset_revision_by_hash(gf, digest, hash_type = "blake3", analysis = NULL)find_asset_revision_by_hash(gf, digest, hash_type = "blake3", analysis = NULL)
gf |
GoFigr client |
digest |
hex digest string |
hash_type |
digest type |
analysis |
optional analysis API ID to scope the search |
list of asset revisions, or empty list
Finds the .gofigr config file in current directory or any of the parent directories. If the file cannot be found, will also check CONFIG_PATH.
find_config(start_dir = NULL)find_config(start_dir = NULL)
start_dir |
top-level directory where to start looking. getwd() by default. |
path to .gofigr, or NULL if not found
Searches the figures attached to a given analysis by name and optionally creates a new figure when no match is found. This is often the most convenient way to obtain a figure handle in scripts and notebooks.
find_figure(gf, analysis, name, description = NULL, create = FALSE)find_figure(gf, analysis, name, description = NULL, create = FALSE)
gf |
GoFigr client. |
analysis |
Parent analysis object (or environment) in which to look for the figure. |
name |
Name of the figure to find. |
description |
Optional description to use if a new figure must be created. |
create |
Logical; if ‘TRUE' and the figure doesn’t exist, a new one is created. If 'FALSE', an error is thrown when no matching figure is found. |
A figure object corresponding to the matching (or newly created) figure.
Searches the workspaces visible to the current user by name and, optionally, creates a new workspace when no match is found.
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 |
Optional description to use if a new workspace is created. |
create |
Logical; if 'TRUE' and the workspace does not exist, a new one is created. If 'FALSE', an error is thrown when no matching workspace is found. |
A workspace object corresponding to the matching (or newly created) workspace.
Fetch an analysis by API ID.
get_analysis(gf, api_id)get_analysis(gf, api_id)
gf |
GoFigr client. |
api_id |
Character string with the API ID of the analysis to fetch. |
An analysis object as returned by the API.
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
Resolves the short-redirect URL used for watermark/QR code links. Returns the bare "gofigr.io" domain (without app. prefix) so the resulting URLs and QR codes are as compact as possible.
get_app_short_url(client = NULL)get_app_short_url(client = NULL)
client |
GoFigr client object. If NULL, returns APP_SHORT_URL. |
short app base URL string
get_app_short_url instead.Resolves the app (frontend) URL from a GoFigr client's API base URL.
Used for full app links (asset URLs, "View on GoFigr" links, etc).
For watermark/QR code URLs, use get_app_short_url instead.
get_app_url(client = NULL)get_app_url(client = NULL)
client |
GoFigr client object. If NULL, returns APP_URL. |
app base URL string
Fetches an asset given an API ID.
get_asset(gf, api_id)get_asset(gf, api_id)
gf |
GoFigr client |
api_id |
API ID for the asset |
asset object
Gets an asset revision given an API ID
get_asset_revision(gf, api_id)get_asset_revision(gf, api_id)
gf |
GoFigr client |
api_id |
API ID for the revision |
asset revision object
Fetches Auth0 configuration from the server's /info endpoint.
get_auth0_config(api_url)get_auth0_config(api_url)
api_url |
Base API URL (e.g. "https://api.gofigr.io") |
A list with domain, client_id, and audience, or NULL if unavailable.
Gets the currently configured GoFigr client
get_client()get_client()
GoFigr client
Retrieves a data object. Use in conjunction with get_revision or get_asset_revision, to retrieve the full data for a data object.
get_data(gf, api_id)get_data(gf, api_id)
gf |
GoFigr client |
api_id |
API ID of the data object |
full data object
Gets the execution context: input path, chunk code, and other metadata.
get_execution_context()get_execution_context()
named list with the execution context.
get_execution_context()get_execution_context()
This is a low-level helper that retrieves the raw figure object from the GoFigr API. It is typically used after you already know the figure's 'api_id', for example from an analysis or figure listing.
get_figure(gf, api_id)get_figure(gf, api_id)
gf |
GoFigr client created by 'gofigr_client()'. |
api_id |
Character string with the API ID of the figure to fetch. |
A figure object as returned by the API (an environment), including metadata and revision information.
Gets configured GoFigr options.
get_options()get_options()
GoFigr options, or NULL if not set.
Generates a QR code and converts it into an img element.
get_qr_png(url, xres = 400, yres = 400, width = 100, height = 100)get_qr_png(url, xres = 400, yres = 400, width = 100, height = 100)
url |
URL to generate the code for |
xres |
QR width, in pixels |
yres |
QR height, in pixels |
width |
width of the HTML img element |
height |
height of the HTML img element |
HTML string
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
Gets a title from a plot
get_title(p)get_title(p)
p |
plot object |
title or NULL
Retrieve workspace details.
get_workspace(gf, api_id)get_workspace(gf, api_id)
gf |
GoFigr client created by 'gofigr_client()'. |
api_id |
Character string with the API ID of the workspace to fetch. |
A workspace object as returned by the API, including metadata and lists of analyses and members.
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(...)
Runs a simple text-based wizard that authenticates via Auth0 Device Code flow, generates or verifies an API key, lets the user choose a default workspace, and then writes a configuration file to '~/.gofigr'. This configuration is used by 'gofigr_client()' when explicit credentials are not provided.
gfconfig(url = NULL, max_attempts = 3)gfconfig(url = NULL, max_attempts = 3)
url |
API URL. Default: https://api.gofigr.io |
max_attempts |
Maximum number of API key attempts before the wizard aborts with an error. |
Invisibly returns 'NULL'. The main effect is writing configuration to disk and printing progress messages.
Generates a div container for the GoFigr widget.
gfContainer(..., jc = "center")gfContainer(..., jc = "center")
... |
passed to the div |
jc |
justify-content CSS value |
styled div element
Defines a GoFigr plot area.
gfPlot(id, ...)gfPlot(id, ...)
id |
ID of this plot area |
... |
same as plotOutput |
HTML elements
Creates a Shiny component to handle plotting and publishing. Has to be paired with a gfPlot element in the UI.
gfPlotServer( id, expr, metadata = NULL, env = parent.frame(), figure_name = NULL, quoted = FALSE, base_graphics = FALSE )gfPlotServer( id, expr, metadata = NULL, env = parent.frame(), figure_name = NULL, quoted = FALSE, base_graphics = FALSE )
id |
id of the gfPlot element |
expr |
expression generating a plot |
metadata |
metadata to publish with the figure. You can pass the shiny input object to capture input values. |
env |
environment in which to evaluate the expression |
figure_name |
name of the figure to publish under. Inferred from figure's title if NULL. |
quoted |
whether the passed expression is quoted |
base_graphics |
whether the passed expression uses base graphics |
moduleServer
Applies a watermark to a plot object/function.
ggwatermark(qr, plot_obj)ggwatermark(qr, plot_obj)
qr |
pre-generated QR code, as an image |
plot_obj |
plot object |
ggplot object with the watermark applied
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 supplied workspace if present, otherwise the default workspace configured on the GoFigr client. Throws an error if neither is available.
infer_workspace(gf, workspace)infer_workspace(gf, workspace)
gf |
GoFigr client. |
workspace |
Optional workspace object or API ID. If 'NULL', the client's default workspace is used. |
A workspace object or API ID suitable for passing to other helpers.
Wraps a plotting function (e.g. plot) so that its output is intercepted by GoFigr.
intercept(plot_func)intercept(plot_func)
plot_func |
function to intercept |
intercepted function
gf_plot <- intercept(base::plot)gf_plot <- intercept(base::plot)
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
Checks whether GoFigr intercept is on
is_intercept_on()is_intercept_on()
TRUE if intercept is on, FALSE otherwise
Check whether a value is serializable for clean room storage.
is_serializable(value)is_serializable(value)
value |
the value to check |
TRUE if serializable, FALSE otherwise
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)
This is a convenience wrapper around 'get_workspace()' that returns only the analyses associated with a workspace, rather than the full workspace object.
list_analyses(gf, workspace_id = NULL)list_analyses(gf, workspace_id = NULL)
gf |
GoFigr client. |
workspace_id |
Optional API ID of the workspace to inspect. If 'NULL', the default workspace configured on the client ('gf$workspace') is used. |
A list of analysis objects associated with the selected workspace.
Lists all active GoFigr sessions.
list_sessions(pretty = TRUE)list_sessions(pretty = TRUE)
pretty |
if TRUE (default), returns a data frame summary; if FALSE, returns the raw named list of session option environments |
data frame or named list of sessions
List all workspaces available to the authenticated user.
list_workspaces(gf)list_workspaces(gf)
gf |
GoFigr client. |
A list of workspace objects visible to the current user.
Given an authenticated GoFigr client, this helper either accepts an existing API key entered by the user or creates a new API key via the API. The newly created key is associated with the authenticated user.
login_with_api_key(gf, max_attempts)login_with_api_key(gf, max_attempts)
gf |
Authenticated GoFigr client created by 'gofigr_client()'. |
max_attempts |
Maximum number of attempts when validating a user- supplied API key. |
A character string containing a valid API key, either supplied by the user or newly created.
Requests a device code, displays the verification URL, optionally opens the browser, and polls for authorization. Returns a GoFigr client authenticated with the Auth0 access token.
login_with_device_flow(api_url, auth0_config, max_attempts = 3)login_with_device_flow(api_url, auth0_config, max_attempts = 3)
api_url |
Base API URL |
auth0_config |
Auth0 configuration from get_auth0_config() |
max_attempts |
Not used (kept for API consistency) |
A configured GoFigr client authenticated with an Auth0 token.
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
Creates a new asset revision from file.
new_asset_revision_from_file(gf, workspace_id, path, analysis_id = NULL)new_asset_revision_from_file(gf, workspace_id, path, analysis_id = NULL)
gf |
GoFigr client |
workspace_id |
parent workspace in case we have to create a brand new asset |
path |
path to file |
analysis_id |
optional analysis API ID to scope the asset under |
asset revision object
Does not draw any watermarks.
NO_WATERMARKNO_WATERMARK
An object of class NULL of length 0.
does not return anything (NULL)
Build a Shiny input widget from a gf_param descriptor.
param_to_shiny_input(ns, name, desc)param_to_shiny_input(ns, name, desc)
ns |
Shiny namespace function |
name |
parameter name |
desc |
gf_param descriptor |
Shiny input element, or NULL for static params
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 method for GoFigr revisions.
## S3 method for class 'gofigr_revision' print(x, ...)## S3 method for class 'gofigr_revision' print(x, ...)
x |
revision |
... |
passed to base::print |
NA
Publishes a figure to the GoFigr service.
publish( plot_obj, figure_name = NULL, input_path = NULL, input_contents = NULL, chunk_code = NULL, image_formats = c("eps"), data = NULL, metadata = NULL, show = TRUE, base_convert = TRUE, width = NULL, height = NULL, units = "in", dpi = NULL, auto_assign = NULL )publish( plot_obj, figure_name = NULL, input_path = NULL, input_contents = NULL, chunk_code = NULL, image_formats = c("eps"), data = NULL, metadata = NULL, show = TRUE, base_convert = TRUE, width = NULL, height = NULL, units = "in", dpi = NULL, auto_assign = NULL )
plot_obj |
plot to publish |
figure_name |
name of the figure. If NULL, it will be inferred from the figure's title |
input_path |
path to the source file |
input_contents |
contents of the source file |
chunk_code |
chunk code, if running R markdown |
image_formats |
image formats to save |
data |
optional data to save with this figure. The data will be saved as RDS. |
metadata |
optional metadata |
show |
whether to display the figure after publication |
base_convert |
whether to try converting base graphics to grid graphics |
width |
width of the output image. If NULL, uses current device dimensions. |
height |
height of the output image. If NULL, uses current device dimensions. |
units |
units for width and height. Default is "in" (inches). Other options include "cm", "mm", "px". |
dpi |
resolution of the output image. If NULL, uses ggsave default (300). |
auto_assign |
if TRUE, use AI-based auto-assignment instead of explicit
figure names. If NULL (default), uses the value set in |
GoFigr revision object
Captures output from grid graphics (ggplot2, lattice, ComplexHeatmap, etc.) and publishes it to GoFigr.
publish_base(expr, ...)publish_base(expr, ...)
expr |
the expression to plot |
... |
passed through to publish() |
GoFigr Revision object
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 = NULL)read_config(path = NULL)
path |
path to the config file, default find_config() |
parsed configuration or empty list if not available
Syncs a file with the GoFigr service and stores a reference. The file will be associated with all figures published after this call.
read_csv(path, ...)read_csv(path, ...)
path |
path to the file |
... |
passed to readr::read_csv |
data frame
Syncs a file with the GoFigr service and stores a reference. The file will be associated with all figures published after this call.
read_csv2(path, ...)read_csv2(path, ...)
path |
path to the file |
... |
passed to readr::read_csv2 |
data frame
Syncs a file with the GoFigr service and stores a reference. The file will be associated with all figures published after this call.
read_delim(path, ...)read_delim(path, ...)
path |
path to the file |
... |
passed to readr::read_delim |
data frame
This is a small helper used by the GoFigr configuration wizard to collect user input interactively. When a validation function is supplied, the input will be repeatedly requested until it passes validation or the maximum number of attempts is reached.
read_prompt(prompt, validate = NULL, attempt = 1, max_attempts = 2)read_prompt(prompt, validate = NULL, attempt = 1, max_attempts = 2)
prompt |
Character string shown to the user, e.g. "Enter username: ". |
validate |
Optional function taking a single character argument and either returning a transformed value or throwing an error if the value is invalid. |
attempt |
Current attempt number (used internally for recursion). |
max_attempts |
Maximum number of attempts before giving up and throwing an error. |
The raw input string, or the result of 'validate(input)' if a validation function is supplied.
Syncs a file with the GoFigr service and stores a reference. The file will be associated with all figures published after this call.
read_tsv(path, ...)read_tsv(path, ...)
path |
path to the file |
... |
passed to readr::read_tsv |
data frame
Syncs a file with the GoFigr service and stores a reference. The file will be associated with all figures published after this call.
read.csv(path, ...)read.csv(path, ...)
path |
path to the file |
... |
passed to utils::read.csv |
data frame
Syncs a file with the GoFigr service and stores a reference. The file will be associated with all figures published after this call.
read.csv2(path, ...)read.csv2(path, ...)
path |
path to the file |
... |
passed to utils::read.csv |
data frame
Syncs a file with the GoFigr service and stores a reference. The file will be associated with all figures published after this call.
read.xlsx(path, ...)read.xlsx(path, ...)
path |
path to the file |
... |
passed to openxlsx::read.xlsx |
data frame
Refreshes the JWT access token. Attempts re-authentication if refresh fails.
refresh_jwt(gf)refresh_jwt(gf)
gf |
GoFigr client. |
NA
The function's formal parameters should use slider, dropdown,
checkbox, text_input, or static to declare
parameter types. Call publish inside the function body to publish figures
with clean room metadata attached.
reproducible( fn, packages = character(0), imports = list(), name = NULL, interactive = FALSE, viewer = NULL )reproducible( fn, packages = character(0), imports = list(), name = NULL, interactive = FALSE, viewer = NULL )
fn |
a function whose formals use |
packages |
character vector of package names, or named list with versions
(e.g. |
imports |
named list mapping aliases to package names (e.g.
|
name |
optional display name for the function (shown in the webapp) |
interactive |
if TRUE, launches a Shiny gadget with parameter widgets for interactive exploration. The user can adjust parameters and re-run the figure live, then click Publish to publish with clean room metadata. |
viewer |
Shiny viewer function for the interactive gadget. Only used when
|
whatever the function body returns (typically the result of publish())
The prefix can be combined with a sequential base62 index to generate compact, unique short IDs for figure revisions. Returns NULL if the server does not support short IDs.
reserve_short_id_prefix(gf)reserve_short_id_prefix(gf)
gf |
GoFigr client |
8-character alphanumeric prefix string, or NULL on failure
By default, 'jsonlite::fromJSON' returns nested named lists. For mutable objects that we want to update in-place (e.g. adding 'figures' to an ‘analysis'), it’s more convenient to work with environments, since they are passed by reference.
response_to_JSON(response)response_to_JSON(response)
response |
httr response |
This helper converts named lists to environments recursively, while keeping unnamed lists (arrays) as lists of elements. Atomic values are returned as-is.
parsed JSON where JSON objects are represented as environments and JSON arrays as R lists.
Round-trip parameters through serialization to ensure what the function sees matches what will be stored. DataFrames go through Parquet; other values go through JSON.
round_trip_params(descriptors)round_trip_params(descriptors)
descriptors |
named list of gf_param descriptors |
named list of round-tripped default values
Run the Shiny gadget for interactive clean room exploration.
run_reproducible_gadget( fn, descriptors, resolved_params, packages, clean_env, context, viewer = NULL )run_reproducible_gadget( fn, descriptors, resolved_params, packages, clean_env, context, viewer = NULL )
fn |
the user's function |
descriptors |
named list of gf_param descriptors |
resolved_params |
named list of default values |
packages |
package names |
clean_env |
the clean execution environment |
context |
the clean room context |
viewer |
Shiny viewer function, or NULL for default dialogViewer |
Returns cached server info from the /info/ endpoint.
server_info(gf)server_info(gf)
gf |
GoFigr client |
named list with server info, or empty list if the call fails
Sets GoFigr options.
set_options(options)set_options(options)
options |
New options that will replace existing options. |
NA
reproducible functions.Creates a slider parameter for use in reproducible functions.
slider(default, min = NULL, max = NULL, step = NULL)slider(default, min = NULL, max = NULL, step = NULL)
default |
default value (integer or numeric) |
min |
minimum value |
max |
maximum value |
step |
step size |
a gf_param object
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
reproducible functions.Use this for data frames and other non-interactive values.
static(default)static(default)
default |
the value |
a gf_param object
Suppresses any automatic GoFigr publication hooks.
suppress(func)suppress(func)
func |
function in which to suppress intercepts |
the function with GoFigr supressed
Syncs a file with the GoFigr service and stores a reference. The file will be associated with all figures published after this call.
sync_file(path)sync_file(path)
path |
path to the file |
null
If we haven't seen this file before, creates a new asset and a new revision
If we have seen the file but haven't seen this revision, creates a new revision
If we have seen this revision, returns the existing revision
sync_workspace_asset(gf, workspace_id, path, analysis_id = NULL)sync_workspace_asset(gf, workspace_id, path, analysis_id = NULL)
gf |
GoFigr client |
workspace_id |
parent workspace in case we have to create a brand new asset |
path |
path to file |
analysis_id |
optional analysis API ID to scope the asset under |
asset revision object
reproducible functions.Creates a text input parameter for use in reproducible functions.
text_input(default)text_input(default)
default |
default character value |
a gf_param object
Tries to convert expression to a grob, returning it unchanged if it fails.
try_base2grob(expr)try_base2grob(expr)
expr |
expression/object to convert |
grob if successful, expr if not
Updates data associated with a figure
update_revision_data( gf, revision, new_data, silent = FALSE, assets = list(), is_clean_room = NULL )update_revision_data( gf, revision, new_data, silent = FALSE, assets = list(), is_clean_room = NULL )
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. |
assets |
list of asset revision IDs to be assocaited with this revision |
is_clean_room |
if TRUE, marks the revision as a clean room revision |
updated revision
Fetches user details for the currently logged in user.
user_info(gf)user_info(gf)
gf |
GoFigr client |
user details
Validate that all parameters are serializable for clean room storage. Returns a list with $valid (logical) and $errors (character vector of messages).
validate_params(descriptors)validate_params(descriptors)
descriptors |
named list of gf_param descriptors |
list with valid and errors fields
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", dynamic_size = TRUE )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", dynamic_size = TRUE )
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" |
dynamic_size |
whether to automatically adjust the watermark size depending on the size of the current graphics device |
a function which you can pass to enable_knitr(watermark)
Executes an expression while isolating any new graphics devices it creates.
with_isolated_devices(expr)with_isolated_devices(expr)
expr |
The R expression to evaluate. |
result of evaluating expr