Package {AplosNCA}

Download Results Information from Aplos NCA Analysis

Description

Retrieves download URLs and files from Aplos NCA analysis results.

Usage

aplos_download_results(url, token, execution_id)

Arguments

Value

A data frame with download URL and filename.

Examples

## Not run: 
  df <- aplos_download_results("https://api.app.aplos-nca.com", token, "exec_123")

## End(Not run)

Execute NCA Analysis in Aplos

Description

Submits and executes an NCA analysis on uploaded data.

Usage

aplos_execute_analysis(
  result,
  data_cleaning = "{}",
  analysis = "{}",
  calcs = "{}",
  plots = "{}",
  tables = "{}",
  metadata = "{}",
  url,
  token,
  name = "NCA Analysis via R",
  save_body = FALSE
)

Arguments

Value

The execution ID.

Examples

## Not run: 
  exec_id <- aplos_execute_analysis(upload_result,
  url = "https://api.app.aplos-nca.com", token = token)

## End(Not run)

Check Execution Status in Aplos NCA

Description

Polls the status of an NCA analysis execution until complete or failed.

Usage

aplos_execution_status(url, token, execution_id, sleep = 10)

Arguments

Value

The status result if succeeded, or stops with error if failed.

Examples

## Not run: 
  status <- aplos_execution_status("https://api.app.aplos-nca.com", token, "exec_123")

## End(Not run)

Fetch and Optionally Unzip Aplos NCA Results

Description

Downloads the results file from the provided download information and optionally unzips it.

Usage

aplos_fetch_results(download_info, dest_dir = "", unzip = FALSE)

Arguments

Value

The path to the downloaded file (or unzip directory if unzip=TRUE).

Examples

## Not run: 
  # Assuming status is "succeeded"
  download_info <- aplos_download_results(url, token, execution_id)
  file_path <- aplos_fetch_results(download_info, unzip = TRUE)

## End(Not run)

Obtain Aplos NCA API JWT Token

Description

Authenticates with the Aplos NCA API using AWS Cognito. This function sends a POST request to retrieve a JWT token for subsequent API calls. All API calls require a valid JWT.

The Aplos NCA JWT expires one hour after it is issued. The package checks the JWT before every API call and, when less than 20 minutes remain, transparently refreshes it using the Aplos NCA Refresh Token returned at login. This refresh happens inside the API functions, so a script can keep using the token object returned here without authenticating again.

If the Aplos NCA Refresh Token is rejected or unavailable, the API call stops with a message asking you to authenticate again; the package never retries with a stored password.

Users who sign in through single sign-on (SSO) cannot use username/password authentication. Those users should copy an Aplos NCA Refresh Token from their profile page (API Settings) in the Aplos NCA web application and use aplos_import_jwt() instead.

The API URL is not involved in authentication: Cognito is addressed with the client ID and AWS region. The URL identifies the Aplos NCA API and is passed to the analysis functions.

Note: Store credentials securely; do not hardcode them in scripts. It is recommended that you use a hidden text file (e.g. ".aplos_creds") stored on your local computer. Read that file in and then parse it to update the required information for authentication. An example credential file may look like the following: APLOS_API_URL="https://api.app.aplos-nca.com" COGNITO_CLIENT_KEY="your_cognito_client_id/key" COGNITO_USER_NAME="your_username" COGNITO_PASSWORD="your_password" COGNITO_REGION="your_aws_region" All of this information can be found in your user profile for your Aplos NCA account under "API Settings".

Usage

aplos_get_jwt(client_id, username, password, region, return_refresh = FALSE)

Arguments

Value

A character string containing the JWT token, or, when return_refresh = TRUE, a list with elements token and refresh_token.

See Also

aplos_import_jwt() for SSO users.

Examples

## Not run: 
  token <- aplos_get_jwt(client_id = "your_client_id", username = "user",
                         password = "pass", region = "us-east-1")

## End(Not run)

Get Presigned Upload URL for Aplos NCA

Description

Retrieves a presigned URL for uploading files to Aplos NCA.

Usage

aplos_get_upload_url(input_file, url, token)

Arguments

Value

A list with upload details.

Examples

## Not run: 
  result <- aplos_get_upload_url("path/to/file.csv", "https://api.app.aplos-nca.com", token)

## End(Not run)

Import Aplos NCA Credentials from a File

Description

Reads an Aplos NCA Refresh Token from a hidden text file, exchanges it for an Aplos NCA JWT, and registers both for use with the other Aplos NCA API functions. This is the authentication path for users who sign in through single sign-on (SSO), because SSO accounts cannot authenticate with a username and password through aplos_get_jwt().

SSO users only need the Aplos NCA Refresh Token, copied from their profile page (API Settings) in the Aplos NCA web application, together with the Cognito client ID and region shown on the same page. The package obtains the Aplos NCA JWT itself and renews it automatically, so the file does not have to be refreshed every hour. The API URL is not involved in authentication; it is passed to the analysis functions.

Aplos NCA Refresh Tokens have their own lifetime, set on the Cognito app client (30 days by default), and using one does not extend it. When it expires or is revoked, this function fails with a "Cognito rejected the Aplos NCA Refresh Token" message and a new Aplos NCA Refresh Token must be imported.

Save the values in a hidden file in your home directory, for example ⁠~/.token⁠, and restrict it (⁠chmod 600 ~/.token⁠ on macOS and Linux):

REFRESH_TOKEN="..."
COGNITO_CLIENT_KEY="..."
COGNITO_REGION="us-east-1"

A single line containing only the Aplos NCA Refresh Token is also accepted when client_id and region are supplied as arguments or environment variables (APLOS_COGNITO_CLIENT_ID, APLOS_COGNITO_REGION).

The refresh token, client ID, and region belong to one Aplos NCA instance (development, demo, or production). They are not interchangeable between instances, which run separate Cognito user pools.

The tenant and user identifiers are read from the JWT custom attributes. Both naming schemes are accepted: custom:aplos_user_tenant_id / custom:aplos_user_id, and custom:tenant_id / custom:user_id.

A file containing an Aplos NCA JWT instead of an Aplos NCA Refresh Token is still accepted for backwards compatibility, but such a token cannot be renewed by the package: it is used until it expires, then the call stops with a message asking for a Aplos NCA Refresh Token.

Usage

aplos_import_jwt(path = NULL, client_id = NULL, region = NULL)

Arguments

Value

The JWT token, invisibly.

See Also

aplos_get_jwt() for username/password authentication.

Examples

## Not run: 
  # SSO users: save the Aplos NCA Refresh Token and client settings to ~/.token first.
  token <- aplos_import_jwt()

  result <- aplos_get_upload_url("data.csv",
                                 "https://api.app.aplos-nca.com", token)

## End(Not run)

Upload File to Aplos NCA

Description

Uploads a file using the presigned URL.

Usage

aplos_upload_file(input_file, result, token)

Arguments

Value

Invisible NULL. Uploads the file to the API as a side effect; throws an error if the upload fails.

Examples

## Not run: 
  aplos_upload_file("path/to/file.csv", upload_result, token)

## End(Not run)