# 🛠️ Troubleshooting
<a name="troubleshooting"></a>

## Conda environment installation fails
For some environments (e.g. `envs/rapids_singlecell.yaml`) you need to set the channel priority to flexible in order for conda to properly resolve the environment.

```
conda config --set channel_priority flexible
```

After setting the flag and calling the installation command, the environment should resolve.

## Working with GPUs

Some scripts can run faster if their dependencies are installed with GPU support.
Currently, whether the GPU version of a package with GPU support is installed, depends on the architecture of the system that you install you **install** the environment on.
If you work on a single computer with GPU, GPU-support should work out of the box.
However, if you want to your code to recognize GPUs when working on a cluster, you need to make sure you install the conda environments from a node that has access to a GPU.

Environments that support GPU are:

* `rapids_singlecell` (only installs when NVIDIA GPU is available)
* `scarches`
* `scib_metrics`
* `scvi-tools`

If you have already installed a GPU environment on CPU, you need to remove and re-install it on node with a GPU.

```
conda env remove -n <env_name>
mamba env create -f envs/<env_name>.yaml
```

In case you are working with `env_mode: from_yaml`, gather the environment name from the Snakemake log, remove the environment manually.
The next time you call your pipeline again, Snakemake should automatically reinstall the missing environment.

## Working with CPUs only

If your system doesn't have any GPUs, you can set the following flag in your config.

```yaml
use_gpu: false
```

This will force Snakemake to use the CPU versions of an environment.

## Working on Apple Silicon

Not all packages that are available for Intel Mac are available for Apple Silicon machines, resulting in environments failing to install.
This is an issue for `bioconda` dependencies in R-heavy environments e.g. `envs/funkyheatmap.yaml`.
As a workaround, you can set the [`CONDA_SUBDIR`](https://conda-forge.org/docs/user/tipsandtricks/?utm_source=chatgpt.com#installing-apple-intel-packages-on-apple-silicon) before creating the environment, to enable emulation.

```
CONDA_SUBDIR=osx-64 conda env create -f envs/funkyheatmap.yaml
```

> ⚠️ **CAUTION** Be careful when setting `CONDA_SUBDIR` globally, especially when you decide to update your base environment afterwards.
> You could brick your Conda installation and need to reinstall conda from scratch (I've been there).
> As long as you're using `CONDA_SUBDIR=osx-64` explicitly for the environments that need it, you should be fine.


## FAQs

Below are some scenarios that can occur when starting with the pipeline.
If you have any additional questions or encounter any bugs, please open up a [github issue](https://github.com/HCA-integration/scAtlasTb/issues).
If you want to contribute to improving the pipeline, check out the [contribution guidelines](CONTRIBUTING.md).

### I configured my pipeline and the dry run doesn't fail, but it doesn't want to run the modules I configured. What do I do?

This likely happens when you don't specify which rule you want Snakemake to run. By default, Snakemake will try create a visualisation of the modules you configured. If you want it to run the modules themselves, you will need to add the rule name with your Snakemake command. For each rule, there is a `<module>_all`, but you can view all possible rules through `snakemake -l`