Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updated installation instructions #249

Merged
merged 8 commits into from
Apr 23, 2024
Merged

Updated installation instructions #249

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
b8ea72a
Updated installation instructions
Lilly-May Apr 2, 2024
17a0eb2
Added dependency installation recommendations
Lilly-May Apr 2, 2024
bbf3464
Simplified installation instructions
Lilly-May Apr 3, 2024
1ed54dd
Improved text and fixed typos
Lilly-May Apr 3, 2024
5ca39d1
minor fixes
bio-la Apr 22, 2024
da89f2c
small
bio-la Apr 22, 2024
fd7dd7e
Add note for Windows machines
Lilly-May Apr 22, 2024
a106e8b
Fixed link
Lilly-May Apr 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 13 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,28 +25,30 @@ Available workflows:

## Installation and configuration

See [installation instructions here](https://panpipes-pipelines.readthedocs.io/en/latest/install.html)
For detailed installation instructions (including those for Apple Silicon machines), refer to the [installation instructions here](https://panpipes-pipelines.readthedocs.io/en/latest/install.html).

We recommend installing panpipes in a conda environment, we provide a minimal conda config file in `pipeline_env.yaml`
We recommend installing panpipes in a conda environment.
For that, we provide a minimal conda config file in `pipeline_env.yaml`.
First, clone this repository and navigate to the root directory of the repository:

```
conda env create --file=pipeline_env.yaml
```bash
git clone https://github.com/DendrouLab/panpipes.git
cd panpipes
```

In this environment, you can install nightly version of panpipes, i.e. cloning this repo and installing it from main.
Then, create the conda environment and install the nightly version of panpipes using the following command:

```
git clone https://github.com/DendrouLab/panpipes.git
cd panpipes
```bash
conda env create --file=pipeline_env.yaml
conda activate pipeline_env
pip install -e .
```


Oxford BMRC Rescomp users find additional advice in [docs/installation_rescomp](https://github.com/DendrouLab/panpipes/blob/main/docs/installation_rescomp.md)
Oxford BMRC Rescomp users find additional advice on the installation [here](https://github.com/DendrouLab/panpipes/blob/main/docs/installation_rescomp.md).

## Releases

Since `panpipes v0.4.0` ,the `ingest` workflow expects different headers for the RNA and Protein modalities from the previous releases.
Since `panpipes v0.4.0`, the `ingest` workflow expects different headers for the RNA and Protein modalities from the previous releases.
Check the example [submission file](https://github.com/DendrouLab/panpipes/blob/main/docs/usage/sample_file_qc_mm.md) and the [documentation](https://panpipes-pipelines.readthedocs.io/en/latest/usage/setup_for_qc_mm.html) for more detailed instructions.

## Citation
Expand Down
168 changes: 97 additions & 71 deletions docs/install.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,44 +1,48 @@

# Installation of panpipes

## Create virtual environment

We recommend running panpipes within a virtual environment to prevent conflicts.
In the following, we provide instructions on how to do this using conda, mamba, or python venv.

### Option 1: create conda environment (Recommended)
>Note: For installation instructions on Apple machines with M chips, scroll down.
> **Note**: For installation instructions on **Apple machines with M chips**, scroll down.
> If you are working on a **Windows** machine, please use Windows Subsystem for Linux (WSL) to run panpipes in order to have access to the latest r-base version.
> **Oxford BMRC Rescomp** users find additional advice on the installation [here](https://github.com/DendrouLab/panpipes/blob/main/docs/installation_rescomp.md).

To Run panpipes, we install it in a conda environment with R and python.
## Option 1: Installation in manually configured conda environment
To run panpipes, we install it in a conda environment with R and python.
Panpipes has a lot of dependencies, so you may want to consider the faster [`mamba`](https://mamba.readthedocs.io/en/latest/index.html) instead of `conda` for installation.
Panpipes can be installed via different methods, either from `PyPi` or from the Github repository.
Option 1 describes the installation via `PyPi` in a manually configured conda environment (no cloning of the repository necessary).

```bash
#This follows the suggestions made here: [https://www.biostars.org/p/498049/](https://www.biostars.org/p/498049/)
### Create conda environment
First, create a conda environment to run panpipes in. For that, we replicate the suggestions made [here](https://www.biostars.org/p/498049/):

```bash
conda config --add channels conda-forge
conda config --set channel_priority strict
# you should remove the strict priority afterwards!
conda search r-base
conda create --name pipeline_env python=3.10 r-base=4.3.0
```

now we activate the environment
Next, we activate the environment:

```bash
conda activate pipeline_env
```

Let's first install the R packages
Let's first install the R packages:

```bash
conda install -c conda-forge r-tidyverse r-optparse r-ggforce r-ggraph r-xtable r-hdf5r r-clustree r-cowplot
```

Then we can install panpipes:

#### 1. Installing panpipes from PyPi

You can install `panpipes` directly from `PyPi` with:
### Install panpipes
Finally, we install panpipes.
You can install it either from `PyPi` (shown here) or a nightly version from the Github repository (shown in Option 2):

```bash
# Install panpipes from PyPi
pip install panpipes
```

Expand All @@ -47,104 +51,81 @@ If you intend to use panpipes for spatial analysis, instead install:
```bash
pip install 'panpipes[spatial]'
```
The extra `[spatial]` includes squidpy, cell2location, and tangram-sc packages.
The extra `[spatial]` includes the `squidpy`, `cell2location`, and `tangram-sc` packages.

#### 2. Nightly versions of panpipes

If you prefer to use the most recent dev version, install from Github
## Option 2: Install nightly panpipes version with preconfigured conda config file

```bash
git clone https://github.com/DendrouLab/panpipes
cd panpipes
pip install -e .
```
If you prefer to use the most recent development version, install the nightly panpipes version from the Github repository.
To make the installation easier, we provide a minimal conda config file in `pipeline_env.yaml`.

Panpipes requires the unix package `time`.
You can check if it installed with `dpkg-query -W time`. If time not already installed, you can
### Clone the repository
First, clone the [panpipes repository](https://github.com/DendrouLab/panpipes) and navigate to the root directory of the repository:

```bash
conda install time
```

or

```bash
apt-get install time
git clone https://github.com/DendrouLab/panpipes.git
cd panpipes
```

#### Installation on Apple Silicon M chips
If you intend to install panpipes via conda on a macOS machine with M-Chip, you might face issues when installing or using certain workflows of panpipes.
This is because panpipes relies on [scvi-tools], which currently only supports execution on Apple Silicon machines when installed using a native Python version (owing to a dependency on JAX).

Follow these steps to install pertpy on an Apple Silicon machine:

1. Install [Homebrew](https://brew.sh/)

2. Install Apple Silicon version of Mambaforge (If you already have Anaconda/Miniconda installed, make sure
having both mamba and conda won't cause conflicts). Additionally, we need clang which is included in llvm, so we install that as well.
### Create conda environment and install nightly panpipes version
Then, create the conda environment and install the nightly version of panpipes using the following command:

```bash
brew install --cask mambaforge
brew install llvm
conda env create --file=pipeline_env.yaml
conda activate pipeline_env
pip install -e .
```

3. Create a new environment using mamba (here with python 3.10) and activate it
To install the spatial dependencies from the repo, use

```bash
conda config --add channels conda-forge
conda config --set channel_priority strict
# you should remove the strict priority afterwards!
mamba search r-base
mamba create --name pipeline_env
mamba activate pipeline_env
pip install .[spatial]
```

4. Add the osx-64 channel to the environment, then install Python and R
Because not all R packages are available via the ARM64 channel, we need to specify the osx-64 channel to install all required R packages.
Panpipes requires the unix package `time`.
You can check if it installed with `dpkg-query -W time`.
If `time` is not already installed, you can install it using:

```bash
conda config --env --set subdir osx-64
mamba install python=3.10 r-base=4.3.0
conda install time
```

5. Install dependencies
or

```bash
conda install -c conda-forge r-tidyverse r-optparse r-ggforce r-ggraph r-xtable r-hdf5r r-clustree r-cowplot
pip install panpipes
apt-get install time
```


### Option 2: python venv environment

Navigate to where you want to create your virtual environment and follow the steps below to create a pip virtual environment.
## Option 3: python venv environment
As an alternative to a conda environment, you can also install panpipes in a python virtual environment.
Navigate to where you want to create your virtual environment and follow the steps below to create a `pip` virtual environment.

```bash
# Create a panpipes/venv folder
python3 -m venv --prompt=panpipes python3-venv-panpipes/
# This will create a panpipes/venv folder
```

Activate the environment
Activate the environment:

```bash
source python3-venv-panpipes/bin/activate
```

As explained in the conda installation, you can install `panpipes` with:
As explained above, you can install panpipes from `PyPi` with:

```bash
pip install panpipes
```

or install a nightly version of panpipes by cloning the Github repository.
Alternatively, you can install a nightly version of panpipes by cloning the Github repository (see instructions above).

#### R packages installation in python venv
### R packages installation in python venv

If you are using a venv virtual environment, the pipeline will call a local R installation, so make sure R is installed and install the required packages with the command we provide below.
(This executable requires that you specify a CRAN mirror in your `.Rprofile`).
for example, add this line to your `.Rprofile` to automatically fetch the preferred mirror:

*remember to customise with your preferred [R mirror](https://cran.r-project.org/mirrors.html).*
> **Note:** Remember to customise with your preferred [R mirror](https://cran.r-project.org/mirrors.html).

```R
options(repos = c(CRAN="https://cran.uni-muenster.de/"))
Expand All @@ -160,23 +141,68 @@ If you want more control over your installation use the [script on github](https
Running with the option `--vanilla` or `--no-site-file` prevents R from reading your `.Renvironment` or `.Rprofile` in case you want to use different settings from you local R installation.
You can expect the installation of R libraries to take quite some time, this is not something related to `panpipes` but how R manages their libraries and dependencies!

#### Check installation
### Check installation

To check the installation was successful run the following line
To check the installation was successful, run the following line:

```bash
panpipes --help
```

A list of available pipelines should appear!


## Installation on Apple Silicon M chips
If you intend to install panpipes via conda on a macOS machine with M-Chip, you might face issues when installing or using certain workflows of panpipes.
This is because panpipes relies on `scvi-tools`, which currently [only supports execution on Apple Silicon machines when installed using a native Python version](https://docs.scvi-tools.org/en/stable/installation.html#apple-silicon) (due to a dependency on JAX).

Follow these steps to install panpipes on an Apple Silicon machine:

1. Install [Homebrew](https://brew.sh/)

2. Install Apple Silicon version of Mambaforge (If you already have Anaconda/Miniconda installed, make sure
having both mamba and conda won't cause conflicts). Additionally, we need clang which is included in llvm, so we install that as well:

```bash
brew install --cask mambaforge
brew install llvm
```

3. Create a new environment using mamba (here with python 3.10) and activate it:

```bash
conda config --add channels conda-forge
conda config --set channel_priority strict
# you should remove the strict priority afterwards!
mamba search r-base
mamba create --name pipeline_env
mamba activate pipeline_env
```

4. Add the osx-64 channel to the environment, then install Python and R
Because not all R packages are available via the ARM64 channel, we need to specify the osx-64 channel to install all required R packages:

```bash
conda config --env --set subdir osx-64
mamba install python=3.10 r-base=4.3.0
```

5. Install R dependencies and panpipes itself:

```bash
conda install -c conda-forge r-tidyverse r-optparse r-ggforce r-ggraph r-xtable r-hdf5r r-clustree r-cowplot
pip install panpipes
```


You're all set to run `panpipes` on your local machine.
If you want to configure it on a HPC server, follow the next instructions.

## Pipeline configuration for HPC clusters

(For SGE or SLURM clusters)
*Note: You only need this configuration step if you want to use an HPC to dispatch individual task as separate parallel jobs. You won't need this for a local installation of panpipes.*
This section is for users who want to run panpipes on a High-Performance Computing (HPC) cluster with a job scheduler like SGE or SLURM.

>Note: You only need this configuration step if you want to use an HPC to dispatch individual task as separate parallel jobs. You won't need this for a local installation of panpipes.

Create a yml file for the cgat core pipeline software to read

Expand Down