scibex 0.1.0b1__tar.gz

scibex-0.1.0b1/CONTRIBUTING.md

@@ -0,0 +1,119 @@
+# Contributing
+
+Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.
+
+You can contribute in many ways:
+
+## Types of Contributions
+
+### Report Bugs
+
+Report bugs at https://github.com/Qile0317/scibex/issues.
+
+If you are reporting a bug, please include:
+
+- Your operating system name and version.
+- Any details about your local setup that might be helpful in troubleshooting.
+- Detailed steps to reproduce the bug.
+
+### Fix Bugs
+
+Look through the GitHub issues for bugs. Anything tagged with "bug" and "help wanted" is open to whoever wants to implement it.
+
+### Implement Features
+
+Look through the GitHub issues for features. Anything tagged with "enhancement" and "help wanted" is open to whoever wants to implement it.
+
+### Write Documentation
+
+scibex could always use more documentation, whether as part of the official docs, in docstrings, or even on the web in blog posts, articles, and such.
+
+### Submit Feedback
+
+The best way to send feedback is to file an issue at https://github.com/Qile0317/scibex/issues.
+
+If you are proposing a feature:
+
+- Explain in detail how it would work.
+- Keep the scope as narrow as possible, to make it easier to implement.
+- Remember that this is a volunteer-driven project, and that contributions are welcome :)
+
+## Get Started!
+
+Ready to contribute? Here's how to set up `scibex` for local development.
+
+1. Fork the `scibex` repo on GitHub.
+2. Clone your fork locally:
+
+   ```sh
+   git clone git@github.com:your_name_here/scibex.git
+   ```
+
+3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:
+
+   ```sh
+   mkvirtualenv scibex
+   cd scibex/
+   python setup.py develop
+   ```
+
+4. Create a branch for local development:
+
+   ```sh
+   git checkout -b name-of-your-bugfix-or-feature
+   ```
+
+   Now you can make your changes locally.
+
+5. When you're done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:
+
+   ```sh
+   make lint
+   make test
+   # Or
+   make test-all
+   ```
+
+   To get flake8 and tox, just pip install them into your virtualenv.
+
+6. Commit your changes and push your branch to GitHub:
+
+   ```sh
+   git add .
+   git commit -m "Your detailed description of your changes."
+   git push origin name-of-your-bugfix-or-feature
+   ```
+
+7. Submit a pull request through the GitHub website.
+
+## Pull Request Guidelines
+
+Before you submit a pull request, check that it meets these guidelines:
+
+1. The pull request should include tests.
+2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.md.
+3. The pull request should work for Python 3.12 and 3.13. Tests run in GitHub Actions on every pull request to the main branch, make sure that the tests pass for all supported Python versions.
+
+## Tips
+
+To run a subset of tests:
+
+```sh
+pytest tests.test_scibex
+```
+
+## Deploying
+
+A reminder for the maintainers on how to deploy. Make sure all your changes are committed (including an entry in HISTORY.md). Then run:
+
+```sh
+uv version patch  # or: minor, major
+git commit -am "Release X.Y.Z"
+just tag
+```
+
+GitHub Actions will automatically publish to PyPI when the tag is pushed. See `.github/workflows/publish.yml` for details.
+
+## Code of Conduct
+
+Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.

scibex-0.1.0b1/HISTORY.md

@@ -0,0 +1,13 @@
+# History
+
+## 0.1.0b1 (2026-06-12)
+
+* First public pre-release on PyPI.
+* Python interface to the Ibex BCR embedding R package for scverse single-cell analysis.
+* `scibex.tl.ibex` — embed BCR sequences from scirpy `AnnData`/`MuData` into `obsm`.
+* `scibex.ibex_matrix` — low-level embedding of a plain sequence list.
+* Supports geometric, CNN, and VAE encoders; CDR3-only and expanded CDR1+2+3 (EXP) variants.
+* `strategy` parameter (`"lenient"` / `"strict"`) for handling partial CDR missingness in EXP models.
+* `fill_value` and `verbose` options for missing-sequence handling.
+* Central type aliases (`_types.py`) for all shared `Literal` annotations.
+* Zensical documentation site; ReadTheDocs integration.

scibex-0.1.0b1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026, Qile Yang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

scibex-0.1.0b1/MANIFEST.in

@@ -0,0 +1,10 @@
+include CONTRIBUTING.md
+include HISTORY.md
+include LICENSE
+include README.md
+
+recursive-include tests *
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+
+recursive-include docs *.md Makefile *.jpg *.png *.gif

scibex-0.1.0b1/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: scibex
+Version: 0.1.0b1
+Summary: Python interface to the Ibex BCR embedding R package for scverse single-cell analysis
+Author-email: Qile Yang <qile.yang@berkeley.edu>
+Maintainer-email: Qile Yang <qile.yang@berkeley.edu>
+License: MIT
+Project-URL: bugs, https://github.com/Qile0317/scibex/issues
+Project-URL: changelog, https://github.com/Qile0317/scibex/blob/main/changelog.md
+Project-URL: homepage, https://github.com/Qile0317/scibex
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rpy2
+Requires-Dist: anndata
+Requires-Dist: scirpy
+Requires-Dist: muon
+Provides-Extra: docs
+Requires-Dist: zensical; extra == "docs"
+Provides-Extra: test
+Requires-Dist: coverage; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: ruff; extra == "test"
+Requires-Dist: ty; extra == "test"
+Requires-Dist: ipdb; extra == "test"
+Dynamic: license-file
+
+# scibex
+
+[![PyPI version](https://img.shields.io/pypi/v/scibex.svg)](https://pypi.org/project/scibex/)
+[![Documentation Status](https://readthedocs.org/projects/scibex/badge/?version=latest)](https://scibex.readthedocs.io/en/latest/?version=latest)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**scibex** brings [Ibex](https://github.com/BorchLab/Ibex) BCR embeddings into the [scverse](https://scverse.org) ecosystem. It wraps the R Ibex package via rpy2 and stores results directly in `AnnData.obsm`, making it a drop-in complement to [scirpy](https://scirpy.scverse.org) 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
+
+```bash
+pip install scibex
+```
+
+scibex wraps the [Ibex R package](https://github.com/BorchLab/Ibex) via rpy2.
+Install the R dependency from Python:
+
+```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
+```
+
+<!-- This also installs `callr`, which basilisk needs to run the encoder in an
+isolated subprocess (required when calling scibex from a Jupyter notebook). -->
+
+Or directly in R:
+
+```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:
+
+```python
+ib.setup(lib_loc="/path/to/my/Rlib")
+```
+
+See the [Installation docs](docs/installation.md) for R environment
+troubleshooting (conda ABI mismatches, `.Rprofile` interference, keras setup).
+
+---
+
+## Quick start
+
+```python
+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:
+
+```python
+ib.tl.ibex(
+    mdata,
+    chain="Heavy",
+    method="encoder",
+    encoder_model="VAE",
+    encoder_input="kideraFactors",
+    key_added="X_ibex_heavy",
+)
+```
+
+<!-- For a fast geometric baseline (no model download needed):
+
+```python
+ib.tl.ibex(mdata, chain="Heavy", method="geometric", 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:
+
+```python
+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
+[`docs/notebooks/tutorial_5k_bcr.ipynb`](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](https://github.com/BorchLab/Ibex). 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

scibex-0.1.0b1/README.md

@@ -0,0 +1,147 @@
+# scibex
+
+[![PyPI version](https://img.shields.io/pypi/v/scibex.svg)](https://pypi.org/project/scibex/)
+[![Documentation Status](https://readthedocs.org/projects/scibex/badge/?version=latest)](https://scibex.readthedocs.io/en/latest/?version=latest)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**scibex** brings [Ibex](https://github.com/BorchLab/Ibex) BCR embeddings into the [scverse](https://scverse.org) ecosystem. It wraps the R Ibex package via rpy2 and stores results directly in `AnnData.obsm`, making it a drop-in complement to [scirpy](https://scirpy.scverse.org) 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
+
+```bash
+pip install scibex
+```
+
+scibex wraps the [Ibex R package](https://github.com/BorchLab/Ibex) via rpy2.
+Install the R dependency from Python:
+
+```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
+```
+
+<!-- This also installs `callr`, which basilisk needs to run the encoder in an
+isolated subprocess (required when calling scibex from a Jupyter notebook). -->
+
+Or directly in R:
+
+```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:
+
+```python
+ib.setup(lib_loc="/path/to/my/Rlib")
+```
+
+See the [Installation docs](docs/installation.md) for R environment
+troubleshooting (conda ABI mismatches, `.Rprofile` interference, keras setup).
+
+---
+
+## Quick start
+
+```python
+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:
+
+```python
+ib.tl.ibex(
+    mdata,
+    chain="Heavy",
+    method="encoder",
+    encoder_model="VAE",
+    encoder_input="kideraFactors",
+    key_added="X_ibex_heavy",
+)
+```
+
+<!-- For a fast geometric baseline (no model download needed):
+
+```python
+ib.tl.ibex(mdata, chain="Heavy", method="geometric", 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:
+
+```python
+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
+[`docs/notebooks/tutorial_5k_bcr.ipynb`](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](https://github.com/BorchLab/Ibex). 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

scibex-0.1.0b1/docs/index.md

@@ -0,0 +1 @@
+--8<-- "README.md"

scibex-0.1.0b1/docs/installation.md

@@ -0,0 +1,175 @@
+# Installation
+
+## Python package
+
+```sh
+pip install scibex
+# or with uv
+uv add scibex
+```
+
+## R dependency
+
+scibex is a Python wrapper around the [Ibex R package](https://github.com/BorchLab/Ibex).
+The R package must be installed and visible to the R runtime that rpy2 uses before
+calling any `scibex` function.
+
+### Option A — install from Python (recommended)
+
+```python
+import scibex as ib
+
+ib.install_r_deps()                           # installs into R's default .libPaths()
+ib.install_r_deps(lib_loc="/path/to/my/Rlib") # install into a specific directory
+ib.install_r_deps(force=True)                 # force-reinstall everything
+```
+
+This installs Ibex, `remotes`, and `callr`.  Packages already present are
+skipped, so repeated calls return quickly.  `callr` is required for the
+encoder (`method="encoder"`) to work from a Jupyter notebook: without it,
+basilisk runs inline and conflicts with rpy2's pre-initialized Python.
+
+If the target directory is non-standard, tell scibex where to find it at runtime:
+
+```python
+ib.setup(lib_loc="/path/to/my/Rlib")
+```
+
+`setup()` must be called **before** the first `ib.tl.ibex(...)` or `ib.ibex_matrix(...)` call.
+
+### Option B — install directly in R
+
+```r
+remotes::install_github("BorchLab/Ibex@devel")
+```
+
+## Troubleshooting R environments
+
+### rpy2 / conda: base packages not found at startup
+
+```text
+During startup - Warning messages:
+1: package 'grDevices' in options("defaultPackages") was not found
+2: package 'graphics' in options("defaultPackages") was not found
+3: package 'stats' in options("defaultPackages") was not found
+```
+
+This means rpy2's C extension was compiled against a different `libR.so` than the
+one in your conda environment. It happens when rpy2 is installed from PyPI inside a
+conda env — the PyPI wheel is not compiled with the `-rpath` flag pointing at
+conda's R library.
+
+**Fix (option A) — recompile from source in the conda env:**
+
+```bash
+conda activate ibex   # or your env name
+LDFLAGS="-Wl,-rpath,$CONDA_PREFIX/lib/R/lib" \
+    pip install --force-reinstall --no-binary rpy2 rpy2
+```
+
+**Fix (option B) — use the conda-forge build (pre-patched):**
+
+```bash
+conda install -n ibex -c conda-forge rpy2
+```
+
+### rpy2 picks up the wrong R installation
+
+rpy2 uses whichever `R` binary appears first on `PATH`. Check which one it will use:
+
+```bash
+R --version        # should match your intended R installation
+Rscript -e "R.home()"
+```
+
+If you are using conda, activate the correct environment before starting Python.
+
+### `list.files` arity error (R ABI mismatch)
+
+```text
+RRuntimeError: Error in list.files(...) :
+  8 arguments passed to .Internal(list.files) which requires 9
+```
+
+R 4.5+ changed `.Internal(list.files)` from 8 to 9 arguments.  This error means
+the C runtime (the `libR.so` loaded by rpy2) is R 4.5+ but the R bytecode being
+executed was compiled for R ≤ 4.4.
+
+**Case A — conda R only (partial upgrade).** After `conda update r-base`, the
+base package bytecode may lag the C library.  Fix:
+
+```bash
+conda install -n <env> -c conda-forge r-base --force-reinstall
+```
+
+Then reinstall any R packages that depend on compiled C/C++/Fortran code.
+
+**Case B — conda R 4.5.x + system R 4.6+.** If your machine has both a conda R
+(e.g. 4.5.1) and a system R (e.g. 4.6.0), rpy2's compiled CFFI extension may
+load the *system* `libR.so` via its rpath, while `R_HOME` points to the conda
+install.  The result is an ABI mismatch between the system R 4.6 C code and the
+conda R 4.5 bytecode.
+
+Fix — recompile rpy2 and patch the binary's rpath:
+
+```bash
+conda activate <env>
+# Install patchelf if not already present:
+conda install -c conda-forge patchelf
+# Recompile rpy2 and patch the CFFI extension in one step:
+just setup-r
+```
+
+If you are not using `just`, the equivalent manual steps are:
+
+```bash
+LDFLAGS="-Wl,-rpath,$CONDA_PREFIX/lib/R/lib" \
+    pip install --force-reinstall --no-binary rpy2 rpy2
+
+CFFI_SO=$(find $VIRTUAL_ENV/lib -name "_rinterface_cffi_api*.so" | head -1)
+patchelf --force-rpath \
+    --set-rpath "$CONDA_PREFIX/lib/R/lib:$CONDA_PREFIX/lib" "$CFFI_SO"
+```
+
+Without patchelf you can use `LD_PRELOAD` as a per-process workaround:
+
+```bash
+LD_PRELOAD="$CONDA_PREFIX/lib/R/lib/libR.so" python my_script.py
+```
+
+### `.Rprofile` interference
+
+If an ancestor directory contains an `.Rprofile` (e.g. a sibling project's
+`renv/activate.R`), R will source it at startup, potentially modifying
+`.libPaths()` in unexpected ways. Disable `.Rprofile` loading when running tests
+or one-off scripts:
+
+```bash
+R_PROFILE_USER=/dev/null python my_script.py
+```
+
+To inject a custom R library path without touching `.Rprofile`:
+
+```bash
+R_LIBS_USER=/path/to/my/Rlib python my_script.py
+# or equivalently via scibex:
+python -c "import scibex as ib; ib.setup(lib_loc='/path/to/my/Rlib'); ..."
+```
+
+### Encoder models require keras / tensorflow
+
+`method="encoder"` (the default) downloads model weights on first use via the
+`basilisk`-managed Python environment inside the Ibex R package. If keras is not
+available, use the fast geometric baseline instead:
+
+```python
+ib.tl.ibex(mdata, chain="Heavy", method="geometric")
+```
+
+## From source
+
+```bash
+git clone https://github.com/Qile0317/scibex
+cd scibex
+uv pip install -e ".[dev]"
+```