From c011362251409fbe3b8dd835bfba7593bed1f372 Mon Sep 17 00:00:00 2001 From: Pierre Chelle <45343665+pchelle@users.noreply.github.com> Date: Fri, 6 Sep 2024 10:14:37 -0400 Subject: [PATCH] 1233 installation procedure (#1246) * Fixes #1233 details installation procedures in readme * Noticed there was orcid for everyone, adding mine to appear in readme * Update installation procedures --- DESCRIPTION | 3 +- README.md | 145 ++++++++++++++++++++++++++++++++++++---------------- 2 files changed, 102 insertions(+), 46 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 793ad1f9..5045fb92 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -18,7 +18,8 @@ Authors@R: person(given = "Pierre", family = "Chelle", role = "aut", - email = "chelle.pierre@gmail.com"), + email = "chelle.pierre@gmail.com", + comment = c(ORCID = "0000-0002-0167-4774")), person(given = "Abdullah", family = "Hamadeh", role = "aut", diff --git a/README.md b/README.md index ba97531d..ac71b8c9 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ # OSPSuite.ReportingEngine -OSPSuite.ReportingEngine implementation in R +The `{ospsuite.reportingengine}` package provides a framework in R to design and create reports evaluating PBPK models developed in the [Open Systems Pharmacology](https://github.com/Open-Systems-Pharmacology) ecosystem. + @@ -14,72 +15,126 @@ OSPSuite.ReportingEngine implementation in R -# Installation - -The **OSPSuite.ReportingEngine** package is compatible with version 4.x.x of R. Please follow the installation instructions below: +## Installation -**OSPSuite.ReportingEngine** requires following packages to be installed: +The `{ospsuite.reportingengine}` package is compatible with version 4.x.x of R. Please follow the installation instructions below: -- From CRAN: - - **ggplot2** (>= 3.3.0) - - **jsonlite** - - **knitr** - - **pander** - - **patchwork** - - **readxl** - - **reshape2** - - **rmarkdown** - - **styler** - - ... (s. [Installation instructions for the package **ospsuite**](https://github.com/Open-Systems-Pharmacology/OSPSuite-R#installation)) -- Must be downloaded manually: - - **ospsuite.utils** (>= 1.4.0) - - [Package download](https://github.com/Open-Systems-Pharmacology/OSPSuite.RUtils/releases) - - **tlf** (>= 1.5.0) - - [Package download](https://github.com/Open-Systems-Pharmacology/TLF-Library/releases) - - **rSharp** (s. [Installation instructions for the package **ospsuite**](https://github.com/Open-Systems-Pharmacology/OSPSuite-R#installation)) - - **ospsuite** (>= 11.1) - - [Package download](https://github.com/Open-Systems-Pharmacology/OSPSuite-R/releases) - - [Installation instructions](https://github.com/Open-Systems-Pharmacology/OSPSuite-R#installation) +### From Github -[OPTIONAL] Install **Pandoc** (required for generation of reports in MS-Word format): +You can install the development version of `{ospsuite.reportingengine}` from [GitHub](https://github.com/) with: -* [Pandoc Installer (Windows)](https://github.com/jgm/pandoc/releases/download/2.9.2.1/pandoc-2.9.2.1-windows-x86_64.msi) -* [Pandoc Installer (Linux)](https://github.com/jgm/pandoc/releases/download/2.9.2.1/pandoc-2.9.2.1-linux-amd64.tar.gz) +```r +# install.packages("remotes") +remotes::install_github("Open-Systems-Pharmacology/OSPSuite.ReportingEngine") +``` +### Using the package bundle 📦 -[OPTIONAL] Install **rsvg-convert** (required by Pandoc for conversion of images in SVG format) +You can install the `{ospsuite.reportingengine}` package by downloading and installing its zip or tar.gz bundle. -* [Installer (Windows)](https://github.com/miyako/console-rsvg-convert/releases) - * The installation folder must be added to the system path. -* For Linux, **librsvg** package must be installed (package name depends on distribution, e.g. **librsvg2-bin** for Ubuntu). +- The package bundle for the __release__ version is available [here 📦](https://ci.appveyor.com/project/open-systems-pharmacology-ci/OSPSuite-ReportingEngine/branch/master/artifacts). +- The package bundle for the __development__ version is available [here 📦](https://ci.appveyor.com/project/open-systems-pharmacology-ci/OSPSuite-ReportingEngine/branch/develop/artifacts). +- The package bundles for specific versions of `{ospsuite.reportingengine}` are available [here 📦](https://ci.appveyor.com/project/open-systems-pharmacology-ci/OSPSuite-ReportingEngine/history). -# Development tasks +Then, to install manually, replace the `path/to/ospsuite.reportingengine.zip` by your actual local path to the `.zip` or `tar.gz` file in the code below: -## dev_mode +```r +install.packages(path/to/ospsuite.reportingengine.zip, repos = NULL) +``` - `devtools::dev_mode` function switches your version of R into "development mode". This is useful to avoid clobbering the existing versions of CRAN packages that you need for other tasks. Calling dev_mode() again will turn development mode off, and return you to your default library setup. +To install the package along with its tests, the `.tar.gz` bundle is required. Then, use the `install-tests` option as illustrated below. -```R -# This will install the package in the folder C:/Rpackages -devtools::dev_mode(path="C:/Rpackages") +```r +install.packages(path/to/ospsuite.reportingengine.tar.gz, repos = NULL, INSTALL_opts = "--install-tests") ``` -## Reload the package +### Required packages + +`{ospsuite.reportingengine}` requires following packages to be installed: + +- From the [Open Systems Pharmacology](https://github.com/Open-Systems-Pharmacology) ecosystem: + +|Package|Version|Installation Instructions| +|-------|-------|------------| +|[`{ospsuite.utils}`](https://github.com/Open-Systems-Pharmacology/OSPSuite.RUtils)|$\geq$ 1.5|Download and install package bundle [here 📦](https://github.com/Open-Systems-Pharmacology/OSPSuite.RUtils/releases)| +|[`{tlf}`](https://github.com/Open-Systems-Pharmacology/TLF-Library)|$\geq$ 1.5|Download and install package bundle [here 📦](https://github.com/Open-Systems-Pharmacology/TLF-Library/releases)
⚠ Visit [`{tlf}` Documentation](https://github.com/Open-Systems-Pharmacology/TLF-Library) to install its dependencies ⚠| +|[`{rSharp}`](https://github.com/Open-Systems-Pharmacology/rSharp)|$\geq$ 1.0|Instructions are available [here 📖](https://github.com/Open-Systems-Pharmacology/rSharp#installation)| +|[`{ospsuite}`](https://github.com/Open-Systems-Pharmacology/OSPSuite-R)|$\geq$ 12.1|Download and install package bundle [here 📦](https://github.com/Open-Systems-Pharmacology/OSPSuite-R/releases)
Instructions are available [here 📖](https://github.com/Open-Systems-Pharmacology/OSPSuite-R#installation)
⚠ Visit [`{ospsuite}` Documentation](https://github.com/Open-Systems-Pharmacology/OSPSuite-R) to install its dependencies ⚠| + +Once the bundles downloaded, you can install the packages by using the code below: + +```r +# bundlePath <- path/to/osp/bundles +install.packages(file.path(bundlePath,"ospsuite.utils.zip"), repos = NULL) +install.packages(file.path(bundlePath,"tlf.zip"), repos = NULL) +install.packages(file.path(bundlePath,"rSharp.zip"), repos = NULL) +install.packages(file.path(bundlePath,"ospsuite.zip"), repos = NULL) +``` -```R -devtools::load_all() +- Required packages from [CRAN](https://cran.r-project.org/): + > Some of these packages may already be installed as dependencies of the Open Systems Pharmacology ecosystem + - [`{dplyr}`](https://cran.r-project.org/web/packages/dplyr) + - [`{ggplot2}` >= 3.3.0](https://cran.r-project.org/web/packages/ggplot2) + - [`{jsonlite}`](https://cran.r-project.org/web/packages/jsonlite) + - [`{R6}`](https://cran.r-project.org/web/packages/R6) + - [`{tidyr}`](https://cran.r-project.org/web/packages/tidyr) +- Optional packages from [CRAN](https://cran.r-project.org/) + - [`{crayon}`](https://cran.r-project.org/web/packages/crayon) + - [`{knitr}`](https://cran.r-project.org/web/packages/knitr) + - [`{parallel}`](https://cran.r-project.org/web/packages/parallel) + - [`{readxl}`](https://cran.r-project.org/web/packages/readxl) + - [`{Rmpi}`](https://cran.r-project.org/web/packages/Rmpi) + - [`{styler}`](https://cran.r-project.org/web/packages/styler) + +To install these packages, use the code below: + +```r +# Required packages +install.packages("dplyr") +install.packages("ggplot2") +install.packages("jsonlite") +install.packages("R6") +install.packages("tidyr") +# Optional packages +install.packages("crayon") +install.packages("knitr") +install.packages("parallel") +install.packages("readxl") +install.packages("Rmpi") +install.packages("styler") ``` -or `Ctrl + Shift + L` +## MS-Word reports + +It is possible to convert markdown reports to MS-Word (`.docx` format) from the `{ospsuite.reportingengine}` package. +This conversion requires the installation of an additional software: [Pandoc](https://pandoc.org/). + +A dedicated article details how to create MS-Word reports using the `{ospsuite.reportingengine}` package: [here](https://www.open-systems-pharmacology.org/OSPSuite.ReportingEngine/dev/articles/word-report.html) + +### [OPTIONAL] Pandoc Installation + +Install **Pandoc** (required for generation of reports in MS-Word format) by downloading one of the following files: + +- [Pandoc Installer (Windows)](https://github.com/jgm/pandoc/releases/download/3.1.2/pandoc-3.1.2-windows-x86_64.msi) + +- [Pandoc Installer (Linux)](https://github.com/jgm/pandoc/releases/download/3.1.2/pandoc-3.1.2-linux-amd64.tar.gz) + +### [OPTIONAL] Use SVG figures + +In order to use SVG figures in MS-Word report, you need to install **rsvg-convert** (required by Pandoc for conversion of images in SVG format) + +- [Installer (Windows)](https://github.com/miyako/console-rsvg-convert/releases) + - ⚠ The installation folder must be added to the **system path**. ⚠ +- For Linux, **librsvg** package must be installed (package name depends on distribution, e.g. **librsvg2-bin** for Ubuntu). -## Add or update script files +## Documentation 📖 - `.R` files defined in `tests\dev\` will be removed from the package and can be used to simulate interaction with the package. See [scripts.R](tests/dev/scripts.R) +A detailed account of existing functions and articles on how to use them can be found on the [dedicated website](https://www.open-systems-pharmacology.org/OSPSuite.ReportingEngine/). ## 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 +## Contribution 💡 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).