Table of contents

• Disclaimer
• CQcase functionality
• CQcase installation
  • Python installation
  • Install CQcase with uv
  • Install CQcase with pip
• Running CQcase
  • Running CQcase installed with uv or pip
  • Execution with CQmanager
  • Running CQcase 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.

CQcase functionality

Tip

The application hosted by the Institute of Pathology of University Hospital Basel is available here: CQcase
Due to storage space restrictions, the only available preprocessing method is illumina, minimum probes per bin - 20, and the bin size - 50000.

In the app, you can interact with precalculated single-case CN plots generated by CQcalc.

Available graph options:

• Select preprocessing method: Choose between illumina or swan or noob
• Select minimum probes per bin
• Select bin size
• Downsizing target selection: Choose between results with array specific or overlapping probes analysis, whenever the overlapping probes results are available
• Text box with a button to plot CNV graph of pasted Sentrix ID (assuming the case has been successfully analyzed)

After configuring your settings:

• An interactive single-case plot will be displayed below the dropdown selections.

Interaction with the plot:

• Hover over segment points to see details.
• Click on data points to view all genes within that segment.
• Use box or lasso selection to highlight genes in the table below.

Genes selection grid:

• This table lists all data for the selected methylation class, with search and filtering options for ease of use.
• Clicking a gene name opens it on GeneCards in a new tab.

Gene selection:

• Select genes by checking the boxes next to gene names in the table.
• Click "Add selected genes to plotting box" to include selected genes in the text field or paste pre-defined HUGO symbols directly into the gene submission box.
• Use the "Plot genes" button to visualize the genes listed in the text box. Note that the text input persists across changes in methylation classes or settings.

Plot toolbar:

• Features include saving plots as PNG, zooming, panning, box/lasso selection, and resetting the view. Double-clicking the plot also resets the view.

Download options:

• Download the current gene selection or the entire CNV data from the bottom table by clicking "Download selected genes" or "Download case CNV table".
• Save the plot in an interactive HTML format with the "Download plot as html" button.

URL sharing:

• At the bottom of the page, a URL is provided that preserves all current settings. Users can share this URL or save it for later use.

This functionality also supports controlling plot settings via URL parameters, for example:

https://epidip.usb.ch/cqcase/?sentrix_id=10003885067_R03C01?preprocessing_method=illumina?min_probes=20?bin_size=50000?plotgenes=BRCA2

CQcase installation

Note

If you prefer to use CQcase with Docker, skip to the CQmanager repository or the Running CQcase 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 CQcase with uv

1. Install uv if you have not done it yet.
2. Navigate to a directory, where you would like to install CnQuant applications.
3. Initiate a new project called, for example cqcase, and install CQcase

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

Install CQcase with pip

1. Create a directory where you wish to install CQcase 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 CQcase:

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

One-liner

mkdir cqcase \
&& cd cqcase \
&& /usr/bin/python3.11 -m venv .venv \
&& .venv/bin/python3 -m pip install --upgrade pip setuptools \
&& .venv/bin/python3 -m pip install git+https://github.com/neuropathbasel-pub/CQcase \
&& .venv/bin/python3 -c "import cqcase"

Running CQcase

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.

Running CQcase 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. Start CQcase with gunicorn (you can change the IP or port in the --bind argument or the number of workers for the application in --workers):

port="8052"
gunicorn cqcase.app:server --workers=1 --bind=0.0.0.0:$port

4. Access CQcase in your browser, by default:

http://localhost:8052/cqcase/

Execution with CQmanager

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

Running CQcase with Docker compose

Note

This requires a filled-out .env and a data annotation file, as described in the CnQuant repository.

Download the docker-compose.yml to the current directory or adjust its path in the command below.
Following, run the following command in the directory with the docker-compose.yml file:

Note

The GROUP_ID has to match the file permissions group. You might need to adapt it if you are analyzing data with a different user and group.

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 -p cqcase up

4. Access CQcase in your browser (the port depends on your .env file), by default:

http://localhost:8052/cqcase/