# Installation Instructions

Start by cloning the CryoBench git repository; note that we also have to fetch the codebases for some of the example methods through their git submodules:

```bash
git clone --recurse-submodules git@github.com:ml-struct-bio/CryoBench.git
```

You will also have to install ChimeraX, which can be done by downloading the correct version for your operating system from [their website](https://www.cgl.ucsf.edu/chimerax/download.html). For CryoBench to find your installation, create an environment variable pointing to its location:

```bash
export CHIMERAX_PATH="/myhome/software/chimerax-1.6.1/bin/ChimeraX"
```

{% hint style="info" %}
To avoid having to specify this environment variable every time you load these environments, save the above `export` expression in your `.bashrc` file!\
\
More info on .bashrc files can be found [here](https://www.digitalocean.com/community/tutorials/bashrc-file-in-linux).
{% endhint %}

## Method-specific instructions

We developed CryoBench as a tool for quantitatively evaluating a set of reconstruction methods. Shown here are instructions for creating a conda environment for running each of these example methods, as well as for measuring the quality of the reconstructions.

{% hint style="info" %}
For each reconstruction method, **we recommend using a separate conda environment for running the method itself and for using CryoBench** on its outputs. This is because many methods — especially those related to cryoDRGN — have package dependencies whose required versions conflict with one another, or with those required by CryoBench!
{% endhint %}

Installing each method generally means following the instructions provided by the developers, while creating the corresponding CryoBench environment entails repeating the steps of the method installation as necessary and then installing CryoBench dependencies using the repository's `requirements.txt` file along with a compatible version of cryoDRGN.

The scripts we have provided for each method are generally designed to work with the output of a range of versions of the method, and to have a specific version of the method installed for CryoBench:

### CryoDRGN

Create an environment for running cryoDRGN models. Here we specify a recent version; CryoBench is compatible with cryoDRGN v3.x outputs:

```bash
$ conda create --name cryodrgn_model python=3.10
$ conda activate cryodrgn_model
(cryodrgn_model)$ pip install 'cryodrgn==3.4.2'
```

Next, create an environment for running CryoBench analyses on cryoDRGN output using the `requirements.txt` and an older version of cryoDRGN compatible with CryoBench code:

<pre class="language-bash"><code class="lang-bash">$ conda create --name cryodrgn_bench python=3.10
$ conda activate cryodrgn_bench
(cryodrgn_bench)$ pip install -r CryoBench/requirements.txt
<strong>(cryodrgn_bench)$ pip install git+https://github.com/ml-struct-bio/cryodrgn.git@2.0.0-beta
</strong></code></pre>

### DRGN-AI

For running DRGN-AI reconstruction we use the latest version available through Git. CryoBench supports handling DRGN-AI output up to v0.3.1:

```bash
$ conda create --name drgnai_model python=3.10
$ conda activate drgnai_model
(drgnai_model)$ pip install git+https://github.com/ml-struct-bio/drgnai.git
```

For running CryoBench analyses on DRGN-AI output we use a specific version of DRGN-AI, along with the necessary CryoBench dependencies as described above:

```bash
$ conda create --name drgnai_bench python=3.10
$ conda activate drgnai_bench
(drgnai_bench)$ pip install git+https://github.com/ml-struct-bio/drgnai.git@0.3.1
(drgnai_bench)$ pip install -r CryoBench/requirements.txt
(drgnai_bench)$ pip install git+https://github.com/ml-struct-bio/cryodrgn.git@2.0.0-beta
```

### OPUS-DSD

For this package we have to use their custom dependency list, and then install the package from the cloned submodule using `pip install -e` (non-developer mode does not work). CryoBench has been tested with [OPUS-DSD v1.0.0](https://github.com/alncat/opusDSD/tree/1.0.0); this is the version that is attached as a submodule under `metrics/methods/opusDSD`:

```bash
$ conda env create --name opusdsd_model -f CryoBench/metrics/methods/opusDSD/environmentcu11torch11.yml
$ conda activate opusdsd_model
(opusdsd_model)$ pip install -e CryoBench/metrics/methods/opusDSD/
```

We repeat the same steps for CryoBench analyses, also installing CryoBench dependencies at the end. In this case we can use the version of cryoDRGN installed with OPUS-DSD itself for CryoBench as well:

```bash
$ conda env create --name opusdsd_bench -f CryoBench/metrics/methods/opusDSD/environmentcu11torch11.yml
$ conda activate opusdsd_bench
(opusdsd_bench)$ pip install -e CryoBench/metrics/methods/opusDSD/
(opusdsd_bench)$ pip install -r CryoBench/requirements.txt
```

### RECOVAR

In the case of RECOVAR, as per their instructions, we have to install a specific version of `jax` on top of their custom requirements list, along with setting some bash environment variables and creating a special `ipykernel` installation. You may find it necessary to install a different version of `jax` that is compatible with your version of CUDA:

<pre class="language-bash"><code class="lang-bash">$ conda create --name recovar_model python=3.11
$ conda activate recovar_model
<strong>(recovar_model)$ pip install -U "jax[cuda12_pip]"==0.4.23 -f https://storage.googleapis.com/jax-releases/jax_cuda_releases.html
</strong>(recovar_model)$ pip install --no-deps -r CryoBench/metrics/methods/recovar/recovar_install_requirements.txt
(recovar_model)$ python -m ipykernel install --user --name=recovar

# can also be added to .bashrc — you may have to change the CUDA version path as necessary for your system
(recovar_model)$ export PATH=/usr/local/cuda-12.6/bin:$PATH
(recovar_model)$ export LD_LIBRARY_PATH=/usr/local/cuda-12.6/lib64:$LD_LIBRARY_PATH
</code></pre>

{% hint style="info" %}
These environment variables have to be redefined every time the environment is loaded if they are not specified in e.g. your `~/.bashrc` file!
{% endhint %}

CryoBench has been tested with [a specific commit](https://github.com/ma-gilles/recovar/commit/76ea7a3bfcf05b1b296e4a2903fe0650368fe0bd) of the RECOVAR repository, which is also the commit used by the RECOVAR submodule within the CryoBench repo.

For running CryoBench we can avoid redefining the environment variables if creating the environment in the same session. Note that for installation to work correctly, the `CryoBench/requirements.txt` dependencies **must be installed before** the remaining RECOVAR dependencies:

```bash
$ conda create --name recovar_bench python=3.11
$ conda activate recovar_bench
(recovar_bench)$ pip install -r CryoBench/requirements.txt
(recovar_bench)$ pip install -U "jax[cuda12_pip]"==0.4.23 -f https://storage.googleapis.com/jax-releases/jax_cuda_releases.html
(recovar_bench)$ pip install --no-deps -r CryoBench/metrics/methods/recovar/recovar_install_requirements.txt
(recovar_bench)$ python -m ipykernel install --user --name=recovar
```

{% hint style="info" %}
`conda install "jaxlib=*=cuda" jax cuda-nvcc -c conda-forge -c nvidia` is an alternative method of installing `jax` that should correctly detect the version compatible with your CUDA installation
{% endhint %}

### CryoSPARC

CryoSPARC is typically accessed through a graphical interface installed by your system administrator, and not through a command-line interface as with the other example methods. We hence assume that such a GUI will be used to generate reconstruction output for subsequent examples.

For running CryoBench on outputs generated by CryoSparc, we create an environment similar to `cryodrgn_bench`above — you can also instead use the same environment for both sets of analyses:

```bash
$ conda create --name csparc_bench python=3.10
$ conda activate csparc_bench
(cryodrgn_bench)$ pip install -r CryoBench/requirements.txt
(cryodrgn_bench)$ pip install git+https://github.com/ml-struct-bio/cryodrgn.git@2.0.0-beta
(cryodrgn_bench)$ pip install cryosparc-tools
```

You will also need to replace lines in `cryosparc_3dflex.py`if doing analyses on 3D Flex outputs:

<pre><code>$ vim ~/dev/CryoBench/metrics/fsc/old/per_conf/cryosparc_3dflex.py

<strong>    23 # replace these as necessary with your CryoSPARC credentials
</strong>    24 license_id = None
    25 email = None
    26 password = None
    27 host = None
    28 run_lane = None
</code></pre>

CryoBench has been tested using the output of CryoSPARC v4.6.0.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ez-lab.gitbook.io/cryobench/getting-started/installation-instructions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.