|
1 | 1 | # Installation Guides |
2 | 2 |
|
3 | | -This document is intended to provide help installing and running acro-r in different settings. |
| 3 | +This document is intended to provide help installing and running acro-r. |
4 | 4 |
|
5 | | -Keeping this comprehensive will require input from the community. |
| 5 | +## Prerequisites |
6 | 6 |
|
7 | | -So please email sacro.contact@uwe.ac.uk, or [raise an issue on the GitHub repository](https://github.com/AI-SDC/ACRO-R/issues/new/choose) if: |
8 | | - - you have a setting that is not covered, or |
9 | | - - the steps outlined below do not work for you, |
| 7 | +- **Python 3.10+**: You must have Python installed on your system. |
| 8 | +- **R**: You need a working installation of R. |
10 | 9 |
|
11 | | -**Please note**: most of the scenarios below assume that |
12 | | -- you have a working version of Python 3 (version 3.9 or higher) on your system |
13 | | -- you are able to access a terminal or command prompt to write and execute some commands. |
| 10 | +## Installation |
14 | 11 |
|
15 | | ---- |
| 12 | +### Step 1: Install the R package |
16 | 13 |
|
17 | | -## Step 1 create a python virtual environment and install the base python package *acro* |
18 | | -**In every case** we recommend that you create what is called a 'python virtual environment' called **r-acro**. |
19 | | -Virtual environments (*venv's*) are recommended best practice. |
20 | | -This is because they isolate the impact of any changes you make in one venv - such as adding or updating a package- from the rest of your system. |
| 14 | +Install the **acro** package from CRAN: |
21 | 15 |
|
22 | | -There are many tutorials available on the web if you get stuck. |
23 | | -We do not endorse any particular site, but here are some examples: |
24 | | -- [an overview with examples for windows/linux/mac](https://python.land/virtual-environments/virtualenv) |
25 | | -- [another that also contains instructions for VSCode and Pycharm](https://realpython.com/python-virtual-environments-a-primer/) |
26 | | - |
27 | | -**For individual users** we suggest that you do this in your home directory where you should have write permission. |
28 | | - |
29 | | -**To install site-wide** we assume you have access rights and know where your organisation's preferred locations are (for example, this might be ```/usr/local``` on a linux system). |
30 | | - |
31 | | -### Make a dedicated virtual environment |
32 | | -You can make a new virtual environment via: |
33 | | -- the Anaconda GUI interface to the conda system |
34 | | -- command line access - by opening a terminal or command prompt and entering the command: |
35 | | - ```sh |
36 | | - conda create --n r-acro |
37 | | - ``` |
38 | | -if you have a version of conda installed or |
39 | | - ```sh |
40 | | -python -m venv ./r-acro |
41 | | -``` |
42 | | -to use the native python *venv* package. |
43 | | - |
44 | | -### Change to that virtual environment and install acro |
45 | | -Anaconda comes with its own GUI to makes this process easy. |
46 | | - |
47 | | -**On any system** using *conda* from the command line : |
48 | | -```sh |
49 | | -conda activate r-acro |
50 | | -conda install conda-forge::acro |
51 | | - |
52 | | -#assuming this completes successfully you can now exit |
53 | | -conda deactivate r-acro |
54 | | -``` |
55 | | - |
56 | | -**On Windows**from the command line with python's *pip* package manager: |
57 | | -```sh |
58 | | -# In cmd.exe |
59 | | -r-acro\Scripts\activate.bat |
60 | | -# In PowerShell |
61 | | -r-acro\Scripts\Activate.ps1 |
62 | | -``` |
63 | | -followed by |
64 | | -```sh |
65 | | -python -m pip install acro |
66 | | -#assuming this completes successfully you can now exit the virtual environment |
67 | | -deactivate |
68 | | -``` |
69 | | - |
70 | | -**On linux/mac** using conda: |
71 | | - |
72 | | -```sh |
73 | | -source r-acro/bin/activate |
74 | | -#you should see the your command prompt change to show (r-acro) |
75 | | -python -m pip install acro |
76 | | -#assuming this completes successfully you can now exit the virtual environment |
77 | | -deactivate |
78 | | -``` |
79 | | ---- |
80 | | - |
81 | | -## Step 2 Install the R packages *reticulate* and *acro* |
82 | | - |
83 | | -The *reticulate* package is the industry-standard method for supporting communications between R and Python. |
84 | | -It provides the `plumbing` between the R `front-end' |
85 | | - |
86 | | -These commands should work whether you are |
87 | | -- working on a machine outside the TRE: in which case packages should install from a mirror of the CRAN service |
88 | | -- working on a machine inside a TRE: in which case the administrator should have set up a local mirror of approved packages from CRAN |
89 | | - |
90 | | -**For individual users** without permission to make site-wide or machine-wide changes |
91 | | -Open your preferred R interface - for example, RStudio, and in a R window type |
92 | | -```R |
93 | | -install.packages*("reticulate") |
| 16 | +```r |
94 | 17 | install.packages("acro") |
95 | 18 | ``` |
96 | 19 |
|
97 | | -**For administrators wishing to install for all users site-wide** the commands are the same but you will need to run them in *sudo* mode. |
98 | | - |
99 | | ---- |
100 | | - |
101 | | -## Step 3: Telling R and reticulate to use the new python virtual environment |
102 | | -The final step of the process is to tell the R package reticulate which version of python to use. |
103 | | - |
104 | | -What we need to do is to set the value of a global variable ```RETICULATE_PYTHON``` |
105 | | -The [R documentation for doing this](https://rstudio.github.io/reticulate/articles/versions.html) is a little inconsistent here, but the following options all seem to work. |
| 20 | +### Step 2: Initialize ACRO |
106 | 21 |
|
107 | | -### Option 1- For individuals using RStudio |
108 | | -If you follow the menu items from ```Tools->Project Options ->Python``` or ```Tools->Global Options->Python``` you can tell it to use the version of python from the virtual environment you create in step 1, either for a specific R project or for all your sessions as shown below |
| 22 | +The `acro` package interfaces with the Python `acro` library. The package provides a helper function to set up the necessary Python environment and dependencies automatically. |
109 | 23 |
|
110 | | - |
| 24 | +Run the following in your R console: |
111 | 25 |
|
112 | | - |
113 | | - |
114 | | - |
115 | | - |
116 | | - |
117 | | - |
118 | | -### Option 2 - Adding code to an individual project file |
119 | | - you add add one of the following lines at the start of your file |
120 | | - ```R |
121 | | - #Either |
122 | | - use_python("~/r-acro/bin/python") |
123 | | - #or |
124 | | - use_virtualenv("~/r-acro") |
125 | | - #or |
126 | | - use_condaenv("r-acro") |
127 | | - #finally followed by |
128 | | - library(reticulate) |
129 | | - library("acro)" |
130 | | - ``` |
131 | | - |
132 | | -### Option 3 - Editing your personal R preferences |
133 | | -In your home directory create (or edit) the file ```.Rprofile``` file, adding the lines |
134 | | - |
135 | | -```R |
136 | | -Sys.setenv(RETICULATE_PYTHON=file.path(Sys.getenv("USERPROFILE"),"r-acro/bin/python")) |
137 | | -Sys.setenv(RETICULATE_PYTHON_ENV=file.path(Sys.getenv("USERPROFILE"),"r-acro")) |
| 26 | +```r |
| 27 | +library("acro") |
| 28 | +acro_init() |
138 | 29 | ``` |
139 | 30 |
|
| 31 | +This command will: |
| 32 | +1. Check for a valid Python installation. |
| 33 | +2. Create a virtual environment named `r-acro`. |
| 34 | +3. Install the required Python `acro` package into this environment. |
| 35 | + |
| 36 | +Once initialized, you are ready to use ACRO-R! |
140 | 37 |
|
| 38 | +## Troubleshooting |
141 | 39 |
|
142 | | -### Option 4- Making site-wide changes |
143 | | - You can also edit the [site-wide Rprofile]() file to add these global environment variables, using replacing *~/r-acro* with the path to wherever you created the dedicated virtual environment. |
| 40 | +If you encounter issues during `acro_init()`: |
| 41 | +- Ensure Python 3.10+ is installed and added to your system PATH. |
| 42 | +- If you are on a restricted network, you may need to configure proxy settings for Python package installation. |
0 commit comments