DeepTCR Integration - Dependency Conflict

[ncborcherding]

Summary

DeepTCR support has been temporarily removed from immLynx due to incompatible Python dependency requirements. This issue tracks the status and potential solutions for re-integrating DeepTCR functionality.

Problem

The DeepTCR Python package (v2.1.1) has strict, pinned dependencies that conflict with other packages in the immLynx basilisk environment:

DeepTCR Requirements (incompatible)

• numpy==1.18.0 (requires ancient version)
• matplotlib==3.3.3
• h5py==2.10.0
• grpcio==1.34.0
• llvmlite==0.36.0
• numba==0.53.1 (pinned)

immLynx Environment Requirements

• numpy>=1.23.4 (needed by clustcr, tcrdist3, etc.)
• scipy==1.8.0 (required by clustcr)
• matplotlib>=3.5.3

When pip tries to install DeepTCR, it attempts to downgrade numpy to 1.18.0, which breaks all other packages and fails to build on modern systems (Python 3.9+ with current setuptools).

Error Message

error: metadata-generation-failed
× Preparing metadata (pyproject.toml) did not run successfully.
NameError: name 'CCompiler' is not defined

This occurs because numpy 1.18.0 is incompatible with modern Python build tools.

Potential Solutions

Option 1: Separate Basilisk Environment

Create a dedicated basilisk environment specifically for DeepTCR with its legacy dependencies:

deepTCREnv <- basilisk::BasiliskEnvironment(
    envname = "deepTCREnv",
    pkgname = "immLynx",
    packages = c(
        "python=3.8",  # Older Python may help
        "numpy=1.18.5",
        "tensorflow=2.4.0",
        ...
    )
)

Pros: Would work without modifying DeepTCR
Cons: Requires maintaining two environments, increases package size

Option 2: Wait for DeepTCR Update

Monitor the DeepTCR repository for updates that relax dependency constraints:

• Repository: https://github.com/sidhomj/DeepTCR

Pros: Clean solution
Cons: No timeline, may never happen

Option 3: Fork and Patch DeepTCR

Create a fork of DeepTCR with relaxed dependencies:

• Update setup.py to use version ranges instead of pinned versions
• Test compatibility with modern numpy/tensorflow

Pros: Could contribute back to upstream
Cons: Maintenance burden

Option 4: Alternative Deep Learning Approach

Consider alternative approaches for TCR deep learning:

• Use ESM-2 embeddings (already implemented via runEmbeddings())
• Integrate other tools like TCR-BERT or TITAN

Pros: More modern approaches available
Cons: Different methodology than DeepTCR VAE

Workaround for Users

Users who need DeepTCR functionality can:

1. Install DeepTCR in a separate Python environment
2. Use reticulate to connect to that environment
3. Run DeepTCR analysis manually

# Create separate conda environment
reticulate::conda_create("deeptcr_env", python_version = "3.8")
reticulate::conda_install("deeptcr_env", "DeepTCR", pip = TRUE)

# Use the environment
reticulate::use_condaenv("deeptcr_env")
DeepTCR <- reticulate::import("DeepTCR")