scibex 0.1.0b3

Python interface to the Ibex BCR embedding R package for scverse single-cell analysis

scibex

scibex brings Ibex BCR embeddings into the scverse ecosystem. It wraps the R Ibex package via rpy2 and stores results directly in AnnData.obsm, making it a drop-in complement to scirpy for B-cell receptor analysis.

Ibex encodes CDR3 (or CDR1+2+3) amino acid sequences from paired heavy and light chains using convolutional/variational autoencoders or a fast geometric transform. The resulting low-dimensional embeddings can be combined with gene expression data for multimodal single-cell analysis.

---

Features

• scirpy-native: reads chain sequences from obsm["chain_indices"]; writes embeddings back to obsm
• Heavy and light chains: embed each independently then combine downstream
• Multiple models: geometric baseline, CNN autoencoder, VAE, and expanded CDR1+2+3 variants
• Multiple encodings: Atchley factors, Kidera factors, Cruciani properties, MSWHIM, tScales, one-hot
• No manual sequence handling: scibex.tl.ibex(mdata, ...) does the full extract → embed → store pipeline

---

Installation

pip install scibex

scibex wraps the Ibex R package via rpy2. Install the R dependency from Python:

import scibex as ib
ib.install_r_deps()                            # into R's default library
ib.install_r_deps(lib_loc="/path/to/my/Rlib")  # into a specific directory
ib.install_r_deps(force=True)                  # force-reinstall everything

Or directly in R:

remotes::install_github("BorchLab/Ibex@devel")

If Ibex is in a non-default R library, call ib.setup(lib_loc=...) once before any embedding call:

ib.setup(lib_loc="/path/to/my/Rlib")

See the Installation docs for R environment troubleshooting (conda ABI mismatches, .Rprofile interference, keras setup).

---

Quick start

import scirpy as ir
import scibex as ib

# Load a scirpy MuData (chain_indices must already be populated)
mdata = ir.datasets.stephenson2021_5k()

# Embed heavy-chain CDR3 sequences → stored in mdata["airr"].obsm["X_ibex_heavy"]
ib.tl.ibex(mdata, chain="Heavy", key_added="X_ibex_heavy")

# Embed light-chain CDR3 sequences → stored in mdata["airr"].obsm["X_ibex_light"]
ib.tl.ibex(mdata, chain="Light", key_added="X_ibex_light")

Switch encoder_input or encoder_model for different representations:

ib.tl.ibex(
    mdata,
    chain="Heavy",
    method="encoder",
    encoder_model="VAE",
    encoder_input="kideraFactors",
    key_added="X_ibex_heavy",
)

If you only have a list of sequences (e.g. from a custom pipeline), use the low-level function directly:

embedding = ib.ibex_matrix(
    ["CARDLVSYGMDVW", "CAKGGQIFHFSSGFYFDFW"],
    chain="Heavy",
    method="encoder",
)  # returns np.ndarray of shape [N, D]

---

Tutorial

A complete end-to-end tutorial on the Stephenson 2021 COVID-19 dataset (5k BCR cells) is available in the Tutorials section (docs/notebooks/tutorial_5k_bcr.ipynb).

It covers:

• Loading a scirpy MuData
• Embedding heavy and light chains with scibex.tl.ibex
• Visualising the embedding space as a UMAP
• Training a logistic-regression classifier to predict patient outcome from paired BCR embeddings

---

API overview

Function	Description
scibex.tl.ibex(adata, ...)	Embed BCR sequences in a scirpy AnnData/MuData; stores result in obsm
scibex.ibex_matrix(seqs, ...)	Low-level: embed a list of CDR3 strings, returns [N, D] numpy array

Key parameters for tl.ibex:

Parameter	Options	Default
chain	"Heavy", "Light"	"Heavy"
method	"encoder", "geometric"	"encoder"
encoder_model	"CNN", "VAE", "CNN.EXP", "VAE.EXP"	"VAE"
encoder_input	"atchleyFactors", "kideraFactors", "crucianiProperties", "MSWHIM", "tScales", "OHE"	"atchleyFactors"
species	"Human", "Mouse"	"Human"
key_added	any string	"X_ibex"

---

Acknowledgements

scibex is a Python interface to the Ibex R package. If you use scibex in your work, please cite the original Ibex publication.

• PyPI: https://pypi.org/project/scibex/
• Documentation: https://scibex.readthedocs.io
• License: MIT