---
title: "aNCA Shiny App User Guide"
description: >
  Learn how to get started with the basics of aNCA Shiny application.
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{aNCA Shiny App User Guide}
  %\VignetteEngine{knitr::knitr}
  %\VignetteEncoding{UTF-8}
---

This guide will provide users with information on how to get started with the aNCA app.

# Step 1: Prepare Dataset

### Uploading a dataset

Click **Upload File** and select the dataset you would like to use. The data can be in `.csv`, `sas7bdat`, `.xslx`, `.parquet` or `.rds` format. The best input for the app is data that follows the ADNCA format according to CDISC guidelines. Other formats of data will also work. Alternatively, for exploring the app, Users can use the Dummy dataset that is already uploaded.

<img src="images/get_started/01.png" alt="Data upload"/>

### Data format

Some variables are mandatory (marked with \*), while others are optional. Custom variable names are supported as long as they are correctly mapped during the [Data Mapping](###%20Data%20mapping) step.

|                          | **Variable**   | **Description**                                                    | **Format**        |
|------------------|------------------|-------------------|------------------|
| **Grouping Identifiers** | STUDYID \*     | Study Identifier                                                   | character         |
|                          | USUBJID \*     | Unique Subject Identifier                                          | character/numeric |
|                          | ATPTREF \* | Can be any column, and used to filter data for NCA calculations     | any               |
|                          | TRT01A         | Treatment Group Identifier (Actual)                                | character         |
|                          | TRT01P         | Treatment Group Identifier (Planned)                               | character         |
|                          | AGE            | Age of Subject                                                     | numeric           |
|                          | RACE           | Race of Subject                                                    | character         |
|                          | SEX            | Sex of Subject                                                     | character         |
|                          |                |                                                                    |                   |
| **Sample variables**     | PARAM \*       | Analyte studied in the sample                                      | character         |
|                          | PCSPEC \*      | Specimen Material Type                                             | character         |
|                          | AVAL \*        | Analysis Value                                                     | numeric           |
|                          |                |                                                                    |                   |
| **Dose Variables**       | DOSETRT \*        | Drug/Treatment compound. When relevant, should match with PARAM    | character         |
|                          | ROUTE \*       | Route of Administration, either {intravascular} or {extravascular} | character         |
|                          | DOSEA \*       | Actual Treatment Dose                                              | numeric           |
|                          | ADOSEDUR       | Actual Treatment Dose                                              | numeric           |
|                          |                |                                                                    |                   |
| **Time Variables**       | AFRLT \*       | Actual Relative Time from Analyte First Dose                       | numeric           |
|                          | ARRLT \*       | Actual Relative Time from Reference Dose                           | numeric           |
|                          | NFRLT \*       | Nominal Relative Time from Analyte First Dose                      | numeric           |
|                          | NRRLT \*       | Nominal Relative Time from Reference Dose                          | numeric           |
|                          |                |                                                                    |                   |
| **Time Variables**       | AVALU          | Analysis Value Unit                                                | character         |
|                          | DOSEU          | Treatment Dose Units                                               | character         |
|                          | RRLTU          | Relative Time from Reference Dose Unit                             | character         |

### Adding Filters

Once your data is uploaded, examine it and then click "Next". If you want to change the data by adding filters, click the *Add Filter* button.

<img src="images/get_started/02.png" alt="Adding filters"/>

<blockquote class="important">

Don’t forget to click **Submit Filters**!

</blockquote>

### Data Mapping

Click "Next" to get to the *Mapping* section.

-   Map the correct columns in your dataset to the corresponding label.

-   For Unit Variables, if your dataset has a defined column for units, select it. Otherwise, by scrolling down, you can select the units for the corresponding columns.

-   Click **Submit Mapping**. You will be automatically directed to the next tab.

<img src="images/get_started/03.png" alt="Mapping"/>

### Preview

Review the data and ensure that the columns have been mapped correctly, and all your filters have been applied. If there are any problems with your data (duplicates, missing times), application will display a warning message and in certain situations manual edits will be requested. Just follow the instructions.

# Step 2: Exploratory Analysis

In the *Exploration* tab, you will find the different visualization options, including Individual Plots and Mean Plots. Here you can check out your data to see if the profiles and subjects look good.

# Step 3: Run NCA

Click on the *NCA* tab in the menu bar to switch to the next section.

## Data selection

1.  *Settings*: Choose the Analyte, Dose Number(s) and/or Specimen(s) you would like to run the NCA on, the extrapolation method and the NCA parameters to calculate.
Select additional options including partial AUCs, units, or rule sets to flag the data. In the summary tab, a table summarizes the settings you have selected.
You can also download the settings you have created, and upload them again the next time you use the app, which will implement the saved setup.
<img src="images/get_started/04.png" alt="NCA settings"/>

2.  Click **Run NCA** at the top of the page and check that the data is as expected. You will automatically be redirected to the *Results* tab.

<img src="images/get_started/05.png" alt="Running NCA"/>

# Step 4: NCA Results

## Main Results

The *NCA Results* tab shows the individual results of the NCA. You can select which parameters you would like to view. Results in red have been flagged as "FALSE" for the rule sets selected, results in purple are flagged as "MISSING", and results in white are not flagged.

## Exclusions and Manual Slopes

Click on the *Slopes Information* tab to view more detailed information about the slopes selected in the NCA. To add exclusions or manual slope selections, redirect to the *Slope Selector* tab in the *Setup* page.

<img src="images/get_started/08.png" alt="Slope selection"/>

There are two different ways to add exclusions/selections to the slopes.

#### Via the Buttons

1.  For selection and exclusion, click **+ Exclusion/Selection** and input the corresponding information. RANGE refers to the data point number in the slope, which can be seen by hovering over the points in the plots below.
2.  To remove, select the sample row and click **- Remove selected rows**.

<img src="images/get_started/09.png" alt="Slope selection buttons"/>

#### Via the Plots

For in-app guidance, you can click the [?]{.help-button} button.

<img src="images/get_started/10.png" alt="Guidance"/>

1.  For selection, click the first point and then the last point you want included in the slope. The plot should then update and a row should be added to the table. There you can add your reason for selection.
2.  For exclusion, double click the point you want to exclude. The plot should update along with the table.
3.  To remove, either remove via the table selection, or repeat the same action (i.e. select a new slope, double click the same point).

#### Applying the exclusions

Once the exclusions/selections have been added, click **Run NCA** again.

You can check if they have been applied in the *Slopes Information* page, on the *Manual Adjustments* tab.

<blockquote class="important">

If you do not click **Run NCA**, the manual slopes will not be added!

</blockquote>

### Parameter Datasets

In the Parameter Datasets tab you can see and export the ADPP, ADNCA, and PP datasets.

<img src="images/get_started/12.png" alt="Parameter Datasets"/>

## Additional Analysis

In the *Additional Analysis* tab, you can calculate tissue-matrix ratios using the concentration ratios tab. Input which specimen you would like as the numerator and denominator, and click **Submit**.

<img src="images/get_started/13.png" alt="Additional Analysis"/>

# Step 5: TLGs

<blockquote class="warning">

Currently work in progress. Not all TLGs and features are available.

</blockquote>

After performing the analysis, you can prepare reports regarding the analysis, including various tables, listings and graphs.

### Order details

Firstly, you will need to prepare an order for TLGs. Table in the *Order details* tab will display some default TLGs with their metadata. You can add additional reports by clicking the **Add TLG** button. This will bring up a list of available, defined TLGs. Select the ones you are interested in and click the **Add TLGs to Order** button. You can also remove unwanted entries by selecting them and clicking **Remove TLG**.

When you are happy with the selection, click **Submit Order Details**.

<img src="images/get_started/tlg_01.png" alt="Default TLG table"/>

### Navigating the TLGs

The application provides three separate tabs for differentiating **Tables**, **Listings** and **Graphs**.

Each tab will show a sidebar on the left of the screen. This will let you navigate each specific entry.

<img src="images/get_started/tlg_02.png" alt="TLG navigation"/>

Using the widgets at the top you can specify the number of entries per page and change the pages.

<img src="images/get_started/tlg_03.png" alt="TLG pages"/>

Lastly, the widgets on the right are used for customizing the resulting reports.

<img src="images/get_started/tlg_04.png" alt="TLG customization"/>

### Customizing the TLGs

Exact customization options available for any given TLGs will depend on their implementation. Usually, you will be able to specify things like titles and footnotes, axis labels, limits or grouping variables.

Simply provide the desired value in a given widget and the TLG will update in real time.

Leaving a widget empty will induce default behavior of the TLG.

Some fields will provide additional functionalities. For text fields, a special syntax might be used to reference the values or attributes of the data:

-   prefacing a column name with `!` will reference the **label attribute** of a given column, e.g. `!DOSEU` will translate to `Treatment Dose Units`.
-   prefacing a column name with `$` will reference the **value** for a given column, e.g. `$DOSEU` will translate to mg (for the dummy dataset).

You can always click on the [?]{.help-button} button for help.
