Fixes #1 provide nice documentation of addins

.gitignore

@@ -1 +1,2 @@
 .Rproj.user
+inst/doc

DESCRIPTION

@@ -10,8 +10,10 @@ Authors@R:
              email = "[email protected]",
              comment = c(ORCID = "0000-0002-0167-4774")))
 Description: This package provides functions and interactive apps as addins to work with R packages from OSPSuite framework.
-License: MIT + file LICENSE
+License: GPL (>= 3)
 Suggests: 
+    knitr,
+    rmarkdown,
     testthat (>= 3.0.0)
 Config/testthat/edition: 3
 Encoding: UTF-8
@@ -25,3 +27,4 @@ Depends:
     miniUI,
     rstudioapi,
     shiny
+VignetteBuilder: knitr

R/ospsuite-ui.R

@@ -185,17 +185,26 @@ unitConverter <- function() {
     isConcentration <- reactive({
       input$dimension %in% c("Concentration (mass)", "Concentration (molar)")
     })
+    isAUC <- reactive({
+      input$dimension %in% c("AUC (mass)", "AUC (molar)")
+    })
     isAmount <- reactive({
       input$dimension %in% c("Amount", "Mass")
     })
-
+    
     observeEvent(input$dimension, {
-      availableUnits <- ospsuite::ospUnits[[input$dimension]]
+      # In ospUnits, round brackets are replaced by squared brackets
+      bracketDimension <- gsub(pattern = "\\(", replacement = "[", x = input$dimension)
+      bracketDimension <- gsub(pattern = "\\)", replacement = "]", x = bracketDimension) 
+      availableUnits <- ospsuite::ospUnits[[bracketDimension]]
       # Providing available units as a named list
       # creates categories in the selector
       if (isConcentration()) {
         availableUnits <- ospsuite::ospUnits[c("Concentration [mass]", "Concentration [molar]")]
       }
+      if (isAUC()) {
+        availableUnits <- ospsuite::ospUnits[c("AUC [mass]", "AUC [molar]")]
+      }
       if (isAmount()) {
         availableUnits <- ospsuite::ospUnits[c("Mass", "Amount")]
       }
@@ -205,7 +214,7 @@ unitConverter <- function() {
 
     # Reactive green notification stating combined units are supported
     output$molWeightNotification <- renderText({
-      if (!any(isConcentration(), isAmount())) {
+      if (!any(isConcentration(), isAUC(), isAmount())) {
         return(NULL)
       }
       HTML(paste0(
@@ -214,13 +223,18 @@ unitConverter <- function() {
         ifelse(
           isConcentration(),
           " Both Mass and Molar Concentrations are supported.",
-          " Both Mass and Amount are supported."
+          ifelse(
+            isAUC(),
+            " Both Mass and Molar AUCs are supported.",
+            " Both Mass and Amount are supported."
+          )
         ),
         "<br>Please ensure the Molecular Weight is provided appropriately.",
         "</font>"
       ))
     })
 
+    #inverse conc
     # Every modification will update value2 in right side
     # Except when modified by user
     observeEvent(
@@ -232,8 +246,8 @@ unitConverter <- function() {
           value = ospsuite::toUnit(
             quantityOrDimension = input$dimension,
             values = input$value1,
-            targetUnit = input$unit2,
-            sourceUnit = input$unit1,
+            targetUnit = ifelse(input$unit2 %in% "Unitless", "", input$unit2),
+            sourceUnit = ifelse(input$unit1 %in% "Unitless", "", input$unit1),
             molWeight = input$molWeight,
             molWeightUnit = input$molWeightUnit
           )
@@ -248,8 +262,8 @@ unitConverter <- function() {
         value = ospsuite::toUnit(
           quantityOrDimension = input$dimension,
           values = input$value2,
-          targetUnit = input$unit1,
-          sourceUnit = input$unit2,
+          targetUnit = ifelse(input$unit1 %in% "Unitless", "", input$unit1),
+          sourceUnit = ifelse(input$unit2 %in% "Unitless", "", input$unit2),
           molWeight = input$molWeight,
           molWeightUnit = input$molWeightUnit
         )

README.md

@@ -11,23 +11,29 @@ experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](h
 status](https://www.r-pkg.org/badges/version/OSPSuite.Addins)](https://CRAN.R-project.org/package=OSPSuite.Addins)
 <!-- badges: end -->
 
-The goal of `{ospsuite.addins}` is to provide RStudio addins to work
-with the Open System Pharmacology ecosystem.
+The goal of `{ospsuite.addins}` is to provide RStudio [addins](https://rstudio.github.io/rstudio-extensions/rstudio_addins.html) to work with the Open System Pharmacology ecosystem.
 
-## Installation
+## Installation &#x1f4bb;
 
 You can install the development version of OSPSuite.Addins from
 [GitHub](https://github.com/) with:
 
 ``` r
 # install.packages("remotes")
-remotes::install_github("pchelle/OSPSuite.Addins")
+remotes::install_github("Open-Systems-Pharmacology/OSPSuite.Addins")
 ```
 
-> [!IMPORTANT] 
+> <font color = "violet"><strong> &#x1f6c8;  Important </strong></font>
+> 
 > Once installed, you may need to restart RStudio to see the functions from `{ospsuite.addins}` in the Addins list.
 
-## Addins for `{ospsuite}`
+## Documentation &#128214;
+
+Quick tutorial videos showing how each addin works are available in the Articles tab. 
+
+Sections below provide a quick snapshot of the current addins and their purpose.
+
+## Addins for [`{ospsuite}`](https://www.open-systems-pharmacology.org/OSPSuite-R/) &#11088;
 
 > [!NOTE]
 > All the functions introduced in the examples below can be access by clicking in the __Addins__ menu in RStudio and select the corresponding item.
@@ -42,10 +48,26 @@ remotes::install_github("pchelle/OSPSuite.Addins")
 | __Insert OSPSuite Template__ | Insert OSPSuite Template | `insertOSPSuiteTemplate()` |
 
 
-## Addins for `{ospsuite.reportingengine}`
+## Addins for [`{ospsuite.reportingengine}`](https://www.open-systems-pharmacology.org/OSPSuite.ReportingEngine/) &#11088;
 
 | &#128204; Name | &#128203; Description | &#128223; Function |
 |----------------|-----------------------|----------|
 | __View Report__ | View Reporting Engine Report | `viewReport()` |
 | __Copy Qualification Template__ | Copy and open the Qualification Template file | `copyQualificationTemplate()` |
 
+
+## Code of conduct
+
+Everyone interacting in the Open Systems Pharmacology community (codebases, issue trackers, chat rooms, mailing lists etc...) is expected to follow the Open Systems Pharmacology [code of conduct](https://github.com/Open-Systems-Pharmacology/Suite/blob/master/CODE_OF_CONDUCT.md).
+
+## Contribution &#128161;
+
+We encourage contribution to the Open Systems Pharmacology community. Before getting started please read the [contribution guidelines](https://github.com/Open-Systems-Pharmacology/Suite/blob/master/CONTRIBUTING.md). If you are contributing code, please be familiar with the [coding standards](https://github.com/Open-Systems-Pharmacology/Suite/blob/master/CODING_STANDARDS_R.md).
+
+Please submit new feature ideas &#128161; and bug reports &#x1F41B; using the Github [__issues__](https://github.com/Open-Systems-Pharmacology/OSPSuite.Addins/issues) tab.
+
+## License
+
+OSPSuite.Addins Library is released under the [GPLv3 License](LICENSE.md).
+
+All trademarks within this document belong to their legitimate owners.

vignettes/.gitignore

@@ -0,0 +1,2 @@
+*.html
+*.R

vignettes/copy-qualification-template.Rmd

@@ -0,0 +1,34 @@
+---
+title: "Copy the Qualification Template"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Copy the Qualification Template}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+
+## Qualification template
+
+The Qualification template is an R script that provides the typical workflow for the qualification of a model. 
+
+More details are available in the documentation of the OSPSuite Reporting Engine package [🔗](https://www.open-systems-pharmacology.org/OSPSuite.ReportingEngine/articles/qualification-workflow.html)
+
+## Copying the qualification template
+
+The function `copyQualificationTemplate()` copies the RScript `qualification-template-workflow.R` in the current working directory (see `getwd()` and `setwd()`) as illustrated in the tutorial video below.
+
+Users can then modify the template to fit their needs.
+
+<details><summary>View Insert Template Video</summary>
+
+![](videos/copy-qualification-template.mp4){width="90%"}
+
+</details>

vignettes/insert-osp-template.Rmd

@@ -0,0 +1,27 @@
+---
+title: "Insert OSPSuite Template"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Insert OSPSuite Template}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+The function `insertOSPSuiteTemplate()` inserts in the current location of a RStudio (i.e. last position clicked) a template R code for loading a simulation, defining outputs and running its simulation results and PK analyses.
+
+Users can then modify the template to fit their needs.
+
+The tutorial video below illustrates the first step.
+
+<details><summary>View Insert Template Video</summary>
+
+![](videos/inserting-osp-template.mp4){width="90%"}
+
+</details>

vignettes/simulation-tree.Rmd

@@ -0,0 +1,29 @@
+---
+title: "Simulation Tree"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Simulation Tree}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+## Browsing the simulation tree
+
+The function `runSimulationTree()` starts a shiny app in a RStudio dialog window that allows users to browse the simulation tree of a pkml simulation file, and select desired branches/leafs to be copied, as illustrated in the video below.
+
+<details><summary>View Simulation Tree Video</summary>
+
+![](videos/simulation-tree.mp4){width="90%"}
+
+</details>
+
+The shiny app includes a search bar to highlight branches/leafs that include defined keywords. However, using the search bar may slow down the interactivity of the app.
+
+The shiny app is based on the function [`ospsuite::getSimulationTree()`](https://www.open-systems-pharmacology.org/OSPSuite-R/reference/getSimulationTree.html) that returns a tree like structured list allowing for intuitive navigation in the simulation tree.

vignettes/tables.Rmd

@@ -0,0 +1,42 @@
+---
+title: "Tables of Units and PK Parameters"
+resource_files:
+  - videos
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Tables of Units and PK Parameters}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+## View OSP Units
+
+The function `tableOfUnits()` displays a datatable (see [`{DT}`](https://rstudio.github.io/DT/) package) of dimensions and units available in OSPSuite. RStudio users can also access the table using the Addin as illustrated in the video below.
+
+<details><summary>View OSP Units Video</summary>
+
+![](videos/table-units.mp4){width="90%"}
+
+</details>
+
+> <font color = "dodgerblue"><strong> &#x1f6c8;  Note </strong></font>
+> 
+> OSPSuite.Addins also provides a unit converter addin,
+> whose dedicated article is available [here &#x1F517;](./unit-converter.html)
+
+## View PK Parameters
+
+The function `tableOfPKParameters()` displays a datatable (see [`{DT}`](https://rstudio.github.io/DT/) package) of PK Parameters available in OSPSuite. RStudio users can also access the table using the Addin as illustrated in the video below.
+
+<details><summary>View OSP Units Video</summary>
+
+![](videos/table-pk-parameters.mp4){width="90%"}
+
+</details>

vignettes/unit-converter.Rmd

@@ -0,0 +1,51 @@
+---
+title: "Unit Converter"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Unit Converter}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+## Converter
+
+The function `unitConverter()` starts a shiny app in the RStudio Viewer pane that allows users to convert between units of the same dimension as illustrated in the video below.
+
+<details><summary>View Unit Converter Video</summary>
+
+![](videos/unit-converter.mp4){width="90%"}
+
+</details>
+
+## Bridging Dimensions with Molecular Weight
+
+So far, the following dimensions can be bridged by __Molecular Weight__:
+
+- __Amount__ and __Mass__
+- __Concentration (mass)__ and __Concentration (molar)__
+- __AUC (mass)__ and __AUC (molar)__
+
+<!---
+TODO: include more units when ospsuite will provide the conversion
+- __Amount per time__ and __Mass per time__
+- __Amount per area__ and __Mass per area__
+- __Amount per area per time__ and __Mass per area per time__
+- __Amount per tissue__ and __Mass per tissue__
+--->
+
+When selecting one of these dimensions, users are notified by the app that conversion to the bridged dimension is supported.
+
+The __Molecular Weight__ and its __Unit__ defined by the user will be taken into account if converting to the bridged dimension.
+
+## Fractions
+
+For the  __Fraction__ dimension, the unit named `Unitless` is defined as such in the enum `ospUnits` and corresponds to the fraction as is. 
+
+If users need to convert between fractions, they should currently provide the unit `""` instead of `"Unitless"`.