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
Open-Systems-Pharmacology · Sep 6, 2024 · c011362 · c011362
1 parent f736335
commit c011362
Show file tree

Hide file tree

Showing 2 changed files with 102 additions and 46 deletions.
diff --git 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
@@ -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.
+
 
 <!-- badges: start -->
 
@@ -14,72 +15,126 @@ OSPSuite.ReportingEngine implementation in R
 
 <!-- badges: end -->
 
-# 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 <img src=https://avatars.githubusercontent.com/github width=15px></img>
 
-[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 &#128230;
 
-[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 &#128230;](https://ci.appveyor.com/project/open-systems-pharmacology-ci/OSPSuite-ReportingEngine/branch/master/artifacts).
+- The package bundle for the __development__ version is available [here &#128230;](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 &#128230;](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 &#128230;](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 &#128230;](https://github.com/Open-Systems-Pharmacology/TLF-Library/releases)<br>&#9888; Visit [`{tlf}` Documentation](https://github.com/Open-Systems-Pharmacology/TLF-Library) to install its dependencies &#9888;|
+|[`{rSharp}`](https://github.com/Open-Systems-Pharmacology/rSharp)|$\geq$ 1.0|Instructions are available [here &#128214;](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 &#128230;](https://github.com/Open-Systems-Pharmacology/OSPSuite-R/releases)<br>Instructions are available [here &#128214;](https://github.com/Open-Systems-Pharmacology/OSPSuite-R#installation)<br>&#9888; Visit [`{ospsuite}` Documentation](https://github.com/Open-Systems-Pharmacology/OSPSuite-R) to install its dependencies &#9888;|
+
+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)
+  - &#9888; The installation folder must be added to the **system path**. &#9888;
+- For Linux, **librsvg** package must be installed (package name depends on distribution, e.g. **librsvg2-bin** for Ubuntu).
 
-## Add or update script files
+## Documentation &#128214;
 
-  `.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 &#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).