From e6bafe2eca4b6efc34071db6864fbd2c4086192d Mon Sep 17 00:00:00 2001 From: theHumanBorch Date: Fri, 3 Apr 2026 08:52:53 -0500 Subject: [PATCH 1/2] Update README.md --- README.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index a67bb8a..6eb54f5 100644 --- a/README.md +++ b/README.md @@ -4,18 +4,20 @@ Using BCR sequences for graph embedding [![R-CMD-check](https://github.com/BorchLab/Ibex/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/BorchLab/Ibex/actions/workflows/R-CMD-check.yaml) [![Codecov test coverage](https://codecov.io/gh/BorchLab/Ibex/graph/badge.svg)](https://app.codecov.io/gh/BorchLab/Ibex?branch=master) [![Documentation](https://img.shields.io/badge/docs-stable-blue.svg)](https://www.borch.dev/uploads/screpertoire/articles/ibex) +[![Bioc Release Build](http://www.bioconductor.org/shields/build/release/bioc/Ibex.svg)](http://www.bioconductor.org/checkResults/release/bioc-LATEST/Ibex) +[![Bioc Devel Build](http://www.bioconductor.org/shields/build/devel/bioc/Ibex.svg)](http://www.bioconductor.org/checkResults/devel/bioc-LATEST/Ibex) +[![Bioc Downloads](http://www.bioconductor.org/shields/downloads/release/Ibex.svg)](http://bioconductor.org/packages/stats/bioc/Ibex/) -## Introduction Single-cell sequencing is an integral tool in immunology and oncology, enabling researchers to measure gene expression and immune cell receptor profiling at the level of individual cells. We developed the [scRepertoire](https://github.com/BorchLab/scRepertoire) R package to facilitate the integration of immune receptor and gene expression data. However, leveraging clonal indices for more complex analyses—such as using clonality in cell embedding—remains challenging. **Ibex** addresses this need by using deep learning to vectorize BCR sequences based on amino acid properties or their underlying order. Ibex is the sister package to [Trex](https://github.com/BorchLab/Trex), which focuses on TCR sequence data. -# System Requirements +### System Requirements Ibex has been tested on R versions >= 4.0. For details on required R packages, refer to the package’s DESCRIPTION file. It is designed to work with single-cell objects containing BCR data generated using [scRepertoire](https://github.com/BorchLab/scRepertoire). Ibex has been tested on macOS and Linux. -# Installation +### Installation Ibex relies on the [immApex](https://github.com/BorchLab/immApex) API can be installed directly from GitHub: @@ -46,7 +48,7 @@ BiocManager::install("Ibex") The main version of Ibex is submitted to Bioconductor (installation instructions will be updated after review). By default, Ibex will automatically pull deep learning models from a [Zenodo repository](https://zenodo.org/records/14919286) and cache them locally. -# Usage/Demos +### Usage/Demos Ibex integrates smoothly into most popular R-based single-cell workflows, including **Seurat** and **Bioconductor/SingleCellExperiment.** @@ -56,7 +58,7 @@ See the [vignette](https://www.borch.dev/uploads/screpertoire/articles/ibex) for -## Autoencoded Matrix +#### Autoencoded Matrix The Ibex algorithm allows users to select BCR-based metrics to return autoencoded values to be used in dimensional reduction. If single-cell objects are not filtered for B cells with BCR, `Ibex_matrix()` will still return values, however IBEX_1 will be based on the disparity of BCR-containing and BCR-non-containing cells based on the Ibex algorithm. @@ -65,7 +67,7 @@ library(Ibex) my_ibex <- Ibex_matrix(singleObject) ``` -## Seurat or Single-Cell Experiment +#### Seurat or Single-Cell Experiment You can run Ibex within your Seurat or Single-Cell Experiemt workflow. **Importantly** `runIbex()` will automatically filter single-cells that do not contain BCR information in the meta data of the single-cell object. @@ -82,7 +84,7 @@ seuratObj_Bonly <- runIbex(seuratObj, #The single cell object seuratObj_Bonly <- runIbex(seuratObj, reduction.name = "Ibex") ``` -## After Running Ibex +#### After Running Ibex Once the Ibex embeddings are part of your Seurat object, you can use these embeddings to generate a t-SNE or UMAP: @@ -99,7 +101,7 @@ seuratObj <- quietBCRgenes(seuratObj) seuratObj <- RunPCA(seuratObj) ``` -### Running WNN approach +#### Running WNN approach ```r seuratObj <- FindMultiModalNeighbors(seuratObj, reduction.list = list("pca", "Ibex"), From 998beda0485d128f5ff1518cd2ad16c3159c83ac Mon Sep 17 00:00:00 2001 From: theHumanBorch Date: Fri, 3 Apr 2026 09:16:27 -0500 Subject: [PATCH 2/2] syncing with Bioconductor --- .github/workflows/R-CMD-check.yaml | 4 +- .github/workflows/release.yaml | 45 ++++++++++ .github/workflows/test-coverage.yaml | 4 +- DESCRIPTION | 2 +- NEWS | 124 --------------------------- NEWS.md | 46 ++++++++++ 6 files changed, 96 insertions(+), 129 deletions(-) create mode 100644 .github/workflows/release.yaml delete mode 100644 NEWS create mode 100644 NEWS.md diff --git a/.github/workflows/R-CMD-check.yaml b/.github/workflows/R-CMD-check.yaml index 32c3e56..7fe222a 100644 --- a/.github/workflows/R-CMD-check.yaml +++ b/.github/workflows/R-CMD-check.yaml @@ -2,9 +2,9 @@ # Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help on: push: - branches: [main, master] + branches: [devel] pull_request: - branches: [main, master] + branches: [devel] name: R-CMD-check diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml new file mode 100644 index 0000000..e2ca1b3 --- /dev/null +++ b/.github/workflows/release.yaml @@ -0,0 +1,45 @@ +on: + push: + tags: + - 'v*' + +name: Create Release + +permissions: + contents: write + +jobs: + release: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Validate tag matches DESCRIPTION version + run: | + TAG_VERSION="${GITHUB_REF_NAME#v}" + PKG_VERSION=$(grep '^Version:' DESCRIPTION | sed 's/Version: //') + if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then + echo "::error::Tag version ($TAG_VERSION) does not match DESCRIPTION version ($PKG_VERSION)" + exit 1 + fi + + - name: Extract release notes from NEWS.md + id: notes + run: | + TAG_VERSION="${GITHUB_REF_NAME#v}" + # Extract section between this version header and the next version header + awk "/^## v${TAG_VERSION}$/,/^## /" NEWS.md | head -n -1 | tail -n +2 > release_notes.txt + if [ ! -s release_notes.txt ]; then + echo "::error::No release notes found for v${TAG_VERSION} in NEWS.md" + exit 1 + fi + echo "Release notes:" + cat release_notes.txt + + - name: Create GitHub Release + uses: softprops/action-gh-release@v2 + with: + body_path: release_notes.txt + generate_release_notes: false + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/test-coverage.yaml b/.github/workflows/test-coverage.yaml index 9ee1f3d..39f4ae2 100644 --- a/.github/workflows/test-coverage.yaml +++ b/.github/workflows/test-coverage.yaml @@ -2,9 +2,9 @@ # Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help on: push: - branches: [main, master] + branches: [devel] pull_request: - branches: [main, master] + branches: [devel] name: test-coverage diff --git a/DESCRIPTION b/DESCRIPTION index e7ce92e..91bdb6d 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: Ibex Title: Methods for BCR single-cell embedding -Version: 1.0.0 +Version: 1.1.1 Authors@R: c( person(given = "Nick", family = "Borcherding", role = c("aut", "cre"), email = "ncborch@gmail.com")) Description: Implementation of the Ibex algorithm for single-cell embedding based on BCR sequences. The package includes a standalone function to encode BCR sequence information by amino acid properties or sequence order using tensorflow-based autoencoder. In addition, the package interacts with SingleCellExperiment or Seurat data objects. diff --git a/NEWS b/NEWS deleted file mode 100644 index 82536fc..0000000 --- a/NEWS +++ /dev/null @@ -1,124 +0,0 @@ -CHANGES IN VERSION 0.99.31 ------------------------- -* ibex_ensure_basilisk_external_dir no longer importsFrom basilisk.utils directly - -CHANGES IN VERSION 0.99.30 ------------------------- -* Moved data processing script out of vignette to inst/scripts -* Added ibex_ensure_basilisk_external_dir with basilisk.utils - -CHANGES IN VERSION 0.99.29 ------------------------- -* Adding internal .OnLoad() function to handle basilisk lock dir issue - -CHANGES IN VERSION 0.99.28 ------------------------- -* Deprecated `quietBCRgenes()` -* Converted `Ibex.matrix()` to `Ibex_matrix()` -* Added Install Instructions for BioCondcutor on README and Vignette -* Removed references to Keras3 Installation -* Removed LazyData TRUE statement - -CHANGES IN VERSION 0.99.10 ------------------------- -* Added information to example data - -CHANGES IN VERSION 0.99.9 ------------------------- -* Examples now check if python is installed and running - -CHANGES IN VERSION 0.99.8 ------------------------- -* Updated example data to 2k HEL BEAM-Ab from 10x -* Converted ibex_example into SCE object for compliance -* Large revision of vignette to fit new data/format -* Added species argument to runIbex -* Updated CoNGA handling of assay for Seurat and Single-Cell Objects. - -CHANGES IN VERSION 0.99.7 ------------------------- -* Integration of Ibex with immApex -* Updated Seurat object to v5 -* Updated support for SCE format for ```runIbex()``` -* Update ```CoNGAfy()``` to function with all versions of Seurat -* Updated ```quietBCRgenes()``` to use VariableFeatures() call for SeuratV5 and backward compatibility. -* Add ```getHumanIgPseudoGenes()``` to return a list of human Immunoglobulin Pseudo genes that are kept by ```quietBCRgenes()``` - -## New Models -* Added New Light and Heavy Chain Models -* Encoding methods now accepted: "OHE", "atchleyFactors", "crucianiProperties", "kideraFactors", "MSWHIM","tScales", "zScales" -* Sequence input: - - Human Heavy: 10000000 - - Human Light: 5000000 - - Human Heavy-Expanded: 5000000 - - Human Light-Expanded: 2500000 - - Mouse Heavy: 5000000 - - Mouse Heavy-Expanded: 5000000 -* Trained convolutional and variational autoencoders for Heavy/Light chains - - Architecture: 512-256-128-256-512 - - Parameters: - Batch Size = 128 - Latent Dimensions = 128 - Epochs = 100 - Loss = Mean Squared Error (CNN) & KL Divergence (VAE) - Activation = relu - Learning rate = 1e-6 - - Optimizers: Adam - - Early stopping was set to patients of 10 for minimal validation loss and restoration of best weights - - CNN autoencoders have batch normalization layers between the dense layers. - -CHANGES IN VERSION 0.99.6 ------------------------- -* Implementing GitHub action workflows -* Adding testthat framework -* Deprecating clonalCommunity - -CHANGES IN VERSION 0.99.5 ------------------------- -* Added geometric encoding using the BLOSUM62 matrix -* Trained classical and variational autoencoders for light/heavy chains with 1.5 million cdr sequences - - Architecture: 256-128-30-128-256 - - Parameters: - Batch Size = 64 - Latent Dimensions = 30 - Epochs = 100 - Loss = Mean Squared Error - - Optimizers: Adam - - Early stopping was set to patients of 10 for minimal validation loss and restoration of best weights - - learn rate varied by models - - classical auto encoders have batch normalization layers between the dense layers. - -CHANGES IN VERSION 0.99.4 ------------------------- -* Added chain.checker() function to allow for uncapitlized chain calls - -CHANGES IN VERSION 0.99.3 ------------------------- -* Updated models for manuscript revision - - Architecture: 256-128-30-128-256 - - Parameters: - Batch Size = 64 - Learning Rate = 0.001 - Latent Dimensions = 30 - Epochs = 50 - Loss = Mean Squared Error - - Optimizers: RAdam (for amino acid properties) and RMSprop (for OHE) - - Early stopping was set to patients of 10 for minimal validation loss and restoration of best weights - - -CHANGES IN VERSION 0.99.2 ------------------------- -* Updated models to include radam optimization, early stop for min 10 epochs, and all trained on 800,000 unique cdr3s -* quietBCRgenes() now does not remove human Ig pseudogenes - - -CHANGES IN VERSION 0.99.1 ------------------------- -* Added detection of chain length to function call -* Added support for direct output of combineBCR() -* Modified quietBCR() to include constant regions and J-chains - - -CHANGES IN VERSION 0.99.0 ------------------------- -* Initial commit \ No newline at end of file diff --git a/NEWS.md b/NEWS.md new file mode 100644 index 0000000..78d4c06 --- /dev/null +++ b/NEWS.md @@ -0,0 +1,46 @@ +# Ibex - Change Log + +## v1.1.1 +* Aligned version with Bioconductor release +* Switched default branch to `devel` for Bioconductor compatibility +* Updated CI workflows to target `devel` branch +* Converted NEWS to NEWS.md format +* Added automated GitHub Release workflow via tags + +## v1.0.0 +* Integration of Ibex with immApex +* Updated Seurat object to v5 +* Updated support for SCE format for `runIbex()` +* Update `CoNGAfy()` to function with all versions of Seurat +* Updated `quietBCRgenes()` to use VariableFeatures() call for SeuratV5 and backward compatibility +* Added `getHumanIgPseudoGenes()` to return a list of human Immunoglobulin Pseudo genes +* Added new light and heavy chain models with encoding methods: OHE, atchleyFactors, crucianiProperties, kideraFactors, MSWHIM, tScales, zScales +* Trained convolutional and variational autoencoders (architecture: 512-256-128-256-512) +* Implementing GitHub action workflows +* Adding testthat framework +* Deprecated clonalCommunity +* Added geometric encoding using the BLOSUM62 matrix +* Added information to example data +* Examples now check if python is installed and running +* Updated example data to 2k HEL BEAM-Ab from 10x +* Converted ibex_example into SCE object for compliance +* Large revision of vignette to fit new data/format +* Added species argument to runIbex +* Deprecated `quietBCRgenes()` +* Converted `Ibex.matrix()` to `Ibex_matrix()` +* Added Install Instructions for Bioconductor on README and Vignette +* Removed references to Keras3 Installation +* Moved data processing script out of vignette to inst/scripts +* Added ibex_ensure_basilisk_external_dir with basilisk.utils +* Adding internal .OnLoad() function to handle basilisk lock dir issue + +## Pre-release Development (v0.99.0 - v0.99.5) +* Initial commit and early development +* Added detection of chain length to function call +* Added support for direct output of combineBCR() +* Modified quietBCR() to include constant regions and J-chains +* Updated models to include radam optimization, early stop, trained on 800,000 unique cdr3s +* quietBCRgenes() now does not remove human Ig pseudogenes +* Updated models for manuscript revision +* Added chain.checker() function to allow for uncapitalized chain calls +* Trained classical and variational autoencoders for light/heavy chains (architecture: 256-128-30-128-256)