Table of contents

• Disclaimer
• CQcalc installation
  • Python installation
  • Install CQcalc with uv
  • Install CQcalc with pip
• Running CQcalc
  • Running CQcalc installed with uv or pip
  • Execution with CQmanager
  • Running CQcalc with Docker compose

Disclaimer

Implementation of this software in a diagnostic setting occurs in the sole responsibility of the treating physician. Usage of this software occurs at the risk of the user. The authors may not be held liable for any damage (including hardware) this software might cause. Use is explicitly restricted to academic and non-for-profit organizations.

CQcalc installation

Note

If you prefer to use CQcalc with Docker, skip to the CQmanager repository or the Running CQcalc with Docker compose part of this README

Python installation

Install Python3.11 for your platform (works also with python 3.10 and 3.12). You can find installation guide here or here or here.

The installations depend also on git, which you can install in your terminal (on Ubuntu), if missing, as follows:

sudo apt update && sudo apt install git-all

Install CQcalc with uv

1. Install uv if you did not do it yet.
2. Navigate to a directory, where you would like to install CnQuant applications
3. Initiate a new project called, for example cqcalc, and install CQcalc

uv init cqcalc && cd cqcalc && uv venv --python 3.11 &&  uv pip install "git+https://github.com/neuropathbasel-pub/CQcalc"

Install CQcalc with pip

1. Create a directory where you wish to install CQcalc and enter the directory.
2. Create python3.10 or python3.11 or python3.12 virtual environment (you might need to adjust python path below):

/usr/bin/python3.11 -m venv .venv

or

python3.11 -m venv .venv

3. Activate the virtual environment:

source .venv/bin/activate

4. Install CQcalc:

pip install --upgrade pip setuptools \
&& pip install git+https://github.com/neuropathbasel-pub/CQcalc

Running CQcalc

Note

All of the CnQuant applications require a filled-out .env and a data annotation file as well as Illumina manifests and gaps.csv.gz file, as described in the CnQuant repository. CQcalc requires case-sensitive IDAT suffixes _Red.idat and _Grn.idat. Files like _RED.IDAT or _red.idat will not be processed.

Running CQcalc installed with uv or pip

Steps:

1. Enter the directory where you have installed the app.
2. Activate the virtual environment:

source .venv/bin/activate

3. Run the app in the console:

cqcalc \
--sentrix_ids 'your_sentrix_id1,your_sentrix_id2,your_sentrix_id3'

Additional parameters:

--bin_size 50000 - adjustable integer
--min_probes_per_bin 20 - adjustable integer
--preprocessing_method with one of the following: illumina (default), noob, swan
--downsize_to with one of the following: EPIC_v2_EPIC_v1_to_HM450K, EPIC_v2_EPIC_v1_HM450_to_MSA48, or NO_DOWNSIZING (default)

5. Inspect the results with CQcase

Execution with CQmanager

Instructions on how to use CQmanager for running CnQuant applications are in the CQmanager repository.

Running CQcalc with Docker compose

Note

The calculated files needed for the apps CQall plotter and CQcase will appear in the results_directory you have set up in the .env file.

Download docker-compose.yml either to the current directory or adjust its path in the command below.
Following, adjust the path to your .env file and run the command in the directory with your specified settings (you might adjust the preprocessing_method, bin_size, min_probes_per_bin arguments, and downsize_to):

USER_ID=$(id -u)
GROUP_ID=$(id -g)
path_to_your_env_file="/your_env_file_absolute_path.env"
USER_ID=$USER_ID GROUP_ID=$GROUP_ID docker compose -f docker-compose.yml \
--env-file $path_to_your_env_file run --rm cqcalc cqcalc \
--sentrix_ids 'your_sentrix_id1,your_sentrix_id2,your_sentrix_id3'

Additional parameters:

--bin_size 50000 - adjustable integer
--min_probes_per_bin 20 - adjustable integer
--preprocessing_method with one of the following: illumina, noob, swan, raw
--downsize_to with one of the following: EPIC_v2_EPIC_v1_to_HM450K, EPIC_v2_EPIC_v1_HM450_to_MSA48, or NO_DOWNSIZING (default)