Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
67 commits
Select commit Hold shift + click to select a range
cd7a1f7
Warning and Note Elimination
noahwang1991 Apr 16, 2026
bc96387
Merge pull request #64 from noahwang1991/dev
noahwang1991 Apr 16, 2026
e27eafc
Create R-CMD-check.yaml
noahwang1991 Apr 16, 2026
23a7e06
Update README and Start R-CMD-check
noahwang1991 Apr 16, 2026
f7dfe57
Merge pull request #65 from noahwang1991/dev
noahwang1991 Apr 16, 2026
61ba2f0
Update R-CMD-check.yaml
noahwang1991 Apr 17, 2026
cc95571
Vignette 1
noahwang1991 Apr 20, 2026
6edfce8
Merge pull request #66 from noahwang1991/dev
noahwang1991 Apr 20, 2026
5f0dbbe
Adding Vignettes
noahwang1991 Apr 20, 2026
9ebdf91
Merge pull request #67 from noahwang1991/dev
noahwang1991 Apr 20, 2026
e6fae07
pakagedown update
noahwang1991 Apr 21, 2026
1873439
Merge pull request #68 from noahwang1991/dev
noahwang1991 Apr 21, 2026
0c1ab9d
Start aggregation design - cell centric
noahwang1991 Apr 24, 2026
acd0611
Merge pull request #69 from noahwang1991/dev
noahwang1991 Apr 24, 2026
d0691df
Aggregation functions
noahwang1991 Apr 28, 2026
3055b25
Merge pull request #70 from noahwang1991/dev
noahwang1991 Apr 28, 2026
2ef1969
Aggregation simplification
noahwang1991 Apr 29, 2026
8d06e8b
Merge pull request #71 from noahwang1991/dev
noahwang1991 Apr 29, 2026
5febaf6
Default LRM database change
noahwang1991 May 1, 2026
f256d3e
Merge pull request #72 from noahwang1991/dev
noahwang1991 May 1, 2026
f5f43b4
Distinguish between self.autocrine and other.autocrine
noahwang1991 May 4, 2026
9da5a84
Merge pull request #73 from noahwang1991/dev
noahwang1991 May 4, 2026
c515beb
housekeeping - removing OBS files
msraredon May 6, 2026
313df13
Merge branch 'dev' of https://github.com/msraredon/NICHESv2-msbr into…
msraredon May 6, 2026
99d207c
Merge pull request #74 from msraredon/dev
msraredon May 6, 2026
d9dc35b
Add CLAUDE.md and Xenium PPLR demo script
msraredon May 6, 2026
7992c0a
Merge pull request #75 from msraredon/dev
RaredonLab May 6, 2026
19fcb5a
Add export_to_TissuePlex() and PPLR demo script
msraredon May 6, 2026
07fc7a6
export to tissueplex polishing
msraredon May 6, 2026
c67e44d
Merge pull request #76 from msraredon/dev
msraredon May 6, 2026
32a3164
Update export_TissuePlex_PPLR.R
msraredon May 6, 2026
9bc3fa8
Merge branch 'dev' of https://github.com/msraredon/NICHESv2-msbr into…
msraredon May 7, 2026
c318d68
Merge pull request #77 from msraredon/dev
msraredon May 7, 2026
1c2ddd0
Fixed the R CMD test failure
noahwang1991 May 8, 2026
f43f120
Merge pull request #78 from noahwang1991/dev
noahwang1991 May 8, 2026
e8270fd
Clean my working scripts
noahwang1991 May 8, 2026
ec845d4
Merge pull request #79 from noahwang1991/dev
noahwang1991 May 8, 2026
eb207ac
Fixing the aggregation function
noahwang1991 May 12, 2026
af101ba
Merge pull request #80 from noahwang1991/dev
noahwang1991 May 12, 2026
369b632
Improved the efficiency of aggregation
noahwang1991 Jun 10, 2026
bd412de
Merge pull request #81 from noahwang1991/dev
noahwang1991 Jun 10, 2026
734da97
Update the design files
noahwang1991 Jun 10, 2026
53cea50
Merge pull request #82 from noahwang1991/dev
noahwang1991 Jun 10, 2026
ce61247
deleted the CellToCell_InSitu plot functions
noahwang1991 Jun 11, 2026
2a3365b
Merge pull request #83 from noahwang1991/dev
noahwang1991 Jun 11, 2026
04e41c6
Create TEST.txt
sergio-ibarra-yale Jun 12, 2026
caa54d4
Merge pull request #84 from sergio-ibarra-yale/dev
sergio-ibarra-yale Jun 12, 2026
02e76ee
deleted "smooth" option
noahwang1991 Jun 12, 2026
7c88c27
Merge pull request #85 from noahwang1991/dev
noahwang1991 Jun 12, 2026
3c01cd9
Fix Omnipath issue
noahwang1991 Aug 14, 2026
d3d13fc
Merge pull request #86 from noahwang1991/dev
noahwang1991 Aug 14, 2026
4bf87c9
Fix neighborhood slots when subsetting NICHESObject
noahwang1991 Oct 30, 2026
8089273
Merge pull request #87 from noahwang1991/dev
noahwang1991 Nov 2, 2026
c02bb8c
Fix PDF manual and replace vignettes for 1.0.0
noahwang1991 Nov 2, 2026
269acad
Merge pull request #88 from noahwang1991/dev
noahwang1991 Nov 2, 2026
1da6fc2
Add website publishing workflow and links
noahwang1991 Nov 2, 2026
01622bd
Merge pull request #89 from noahwang1991/dev
noahwang1991 Nov 2, 2026
fe0a35d
ix SeuratData install in website workflow
noahwang1991 Nov 2, 2026
a89aec2
Merge pull request #90 from noahwang1991/dev
noahwang1991 Nov 2, 2026
2538233
Change license from MIT to GNU AGPL v3
noahwang1991 Nov 3, 2026
f0509fc
Merge branch 'dev' of https://github.com/noahwang1991/NICHESv2-NW int…
noahwang1991 Nov 3, 2026
0d6ac78
Merge pull request #91 from noahwang1991/dev
noahwang1991 Nov 3, 2026
1b47f67
Point README badge to main
noahwang1991 Nov 3, 2026
f76e225
Merge pull request #92 from noahwang1991/dev
noahwang1991 Nov 3, 2026
603f400
Stop tracking local settings and OmniPath logs
noahwang1991 Nov 3, 2026
897fcf6
Merge branch 'RaredonLab:dev' into dev
noahwang1991 Nov 3, 2026
afb2881
Merge pull request #93 from noahwang1991/dev
noahwang1991 Nov 3, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
16 changes: 15 additions & 1 deletion .Rbuildignore
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,18 @@
^OBS$
^working-scripts-NW$
^working-scripts-MSBR$
^data-raw$
^data-raw$
^omnipathr-log$
^doc$
^Meta$
^_pkgdown\.yml$
^docs$
^pkgdown$
^\.claude$
^\.github$
^CLAUDE\.md$
^demo-scripts$
^package management$
^LICENSE\.md$
^vignettes/articles$

90 changes: 90 additions & 0 deletions .github/workflows/R-CMD-check.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
# .github/workflows/R-CMD-check.yaml
#
# Runs R CMD check on every push to dev/main and on pull requests.
# Runs on macOS (primary dev platform), Windows and Ubuntu with R release, and
# on Ubuntu with R-devel, which CRAN also checks against. The Ubuntu release
# job also builds the PDF manual and validates the HTML manual; the others skip
# these to avoid installing the extra tools. The dependency step installs both
# CRAN and Bioconductor packages (rhdf5, OmnipathR).

on:
push:
branches: [dev, main]
pull_request:
branches: [dev, main]

name: R-CMD-check

jobs:
R-CMD-check:
runs-on: ${{ matrix.config.os }}
name: ${{ matrix.config.os }} (${{ matrix.config.r }})

strategy:
fail-fast: false # if macOS fails, Ubuntu still runs (you see both results)
matrix:
config:
- {os: macos-latest, r: 'release', args: 'c("--no-manual", "--as-cran")'}
- {os: windows-latest, r: 'release', args: 'c("--no-manual", "--as-cran")'}
- {os: ubuntu-latest, r: 'release', args: 'c("--as-cran")', manual-checks: true, extra-packages: 'any::V8'}
- {os: ubuntu-latest, r: 'devel', args: 'c("--no-manual", "--as-cran")', http-user-agent: 'release'}

env:
GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} # auto-generated per run; lets
# the runner read private repos
R_KEEP_PKG_SOURCE: yes # improves error messages
OMP_THREAD_LIMIT: 2 # same two-thread limit as CRAN

steps:
# Step 1: clone the repository onto the runner machine
- uses: actions/checkout@v4

# Step 2: install R (version comes from the matrix above)
# use-public-rspm: true → Posit's binary package mirror; Linux
# packages install in seconds instead of compiling from source
# http-user-agent → lets R-devel use the same binary packages
- uses: r-lib/actions/setup-r@v2
with:
r-version: ${{ matrix.config.r }}
http-user-agent: ${{ matrix.config.http-user-agent }}
use-public-rspm: true

# Pandoc builds the vignettes
- uses: r-lib/actions/setup-pandoc@v2

# Step 3: install tools for the PDF and HTML manual checks (one job only)
# LaTeX builds the PDF manual; tidy validates the HTML one
- uses: r-lib/actions/setup-tinytex@v2
if: matrix.config.manual-checks

- name: Install HTML Tidy
if: matrix.config.manual-checks
run: |
sudo apt-get update
sudo apt-get install -y tidy

# Step 4: install all packages listed in DESCRIPTION
# extra-packages: any::rcmdcheck → adds rcmdcheck (used in Step 5);
# the matrix adds V8 for math checks
# needs: check → reads DESCRIPTION; installs Imports
# and Suggests needed for R CMD check,
# from CRAN and Bioconductor
- uses: r-lib/actions/setup-r-dependencies@v2
with:
extra-packages: |
any::rcmdcheck
${{ matrix.config.extra-packages }}
needs: check

# Step 5: run R CMD check
# args (from the matrix above):
# --no-manual → skip PDF manual (requires LaTeX; slow on CI)
# --as-cran → apply CRAN-level strictness
# error-on: '"warning"' → fail the workflow on any warning, not just errors
# upload-snapshots: true → save check output as a downloadable artifact
# so you can read failures in the Actions tab
- uses: r-lib/actions/check-r-package@v2
with:
args: ${{ matrix.config.args }}
error-on: '"warning"'
upload-snapshots: true
75 changes: 75 additions & 0 deletions .github/workflows/pkgdown.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
# .github/workflows/pkgdown.yaml
#
# Builds the website and publishes it to the gh-pages branch on every push to
# main. The tutorials really run here, so each build installs SeuratData and
# downloads both public test datasets. A failed build publishes nothing, and the
# live site stays as it was.
#
# To test a build without publishing it, start this workflow by hand from the
# Actions tab on any other branch.

on:
push:
branches: [main]
workflow_dispatch:

name: pkgdown

jobs:
pkgdown:
runs-on: ubuntu-latest

env:
GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} # auto-generated per run

permissions:
contents: write # lets the last step publish

steps:
# Step 1: clone the repository onto the runner machine
- uses: actions/checkout@v4

# Step 2: install Pandoc (builds the pages) and R
- uses: r-lib/actions/setup-pandoc@v2

- uses: r-lib/actions/setup-r@v2
with:
use-public-rspm: true

# Step 3: install this package, everything in DESCRIPTION, and the tools
# the website needs
- uses: r-lib/actions/setup-r-dependencies@v2
with:
extra-packages: |
any::pkgdown
any::remotes
any::Seurat
local::.

# Step 4: install SeuratData and download the test datasets
# SeuratData isn't on CRAN, so it comes from GitHub. It gets its own step
# because Step 3 would also require Azimuth, an optional SeuratData
# package that isn't on CRAN or Bioconductor.
- name: Install SeuratData and test datasets
run: |
remotes::install_github("satijalab/seurat-data", upgrade = "never")
SeuratData::InstallData(c("stxBrain", "ifnb"))
shell: Rscript {0}

# Step 5: build the site
# pkgdown turns every Markdown file in the top folder into a page, so
# the project notes in CLAUDE.md are removed from this checkout first.
- name: Build site
run: |
file.remove("CLAUDE.md")
pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE)
shell: Rscript {0}

# Step 6: publish, from main only
- name: Publish to gh-pages
if: github.ref == 'refs/heads/main'
uses: JamesIves/github-pages-deploy-action@v4
with:
clean: false
branch: gh-pages
folder: docs
7 changes: 7 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -48,3 +48,10 @@ po/*~

# RStudio Connect folder
rsconnect/
/doc/
/Meta/
docs

# Local Claude Code settings and OmniPath download logs
.claude/settings.local.json
omnipathr-log/
125 changes: 125 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,125 @@
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Package overview

NICHESv2 is an R package for spatial cell-to-cell ligand-receptor communication analysis. It computes LR signaling scores between pairs of cells in spatial and non-spatial single-cell transcriptomics data and organizes results in a memory-efficient S3 object (`NICHESObject`). Version 1.0.0 is being prepared for CRAN, alongside the methods paper. `working-scripts-NW/v1_facts_sheet.md` holds the verified facts that all documents copy.

## Development commands

All standard package development goes through `devtools`:

```r
devtools::load_all() # load package in-session during development
devtools::document() # regenerate NAMESPACE and man/ from roxygen2 comments
devtools::test() # run full test suite
devtools::check() # R CMD CHECK (includes tests, examples, vignettes)
devtools::build() # build source tarball
```

Run a single test file:
```r
testthat::test_file("tests/testthat/test-create_NICHESObject.R")
```

Tests auto-generate fixtures on first run via `tests/testthat.R`.

## Architecture

### NICHESObject — 15-slot S3 class

The central data structure is defined in `R/NICHESObject_class.R`. It is a plain S3 list (not R6/Reference), so **it is copied on every assignment** — always reassign the result of any mutating function (`obj <- add_meta_column(obj, ...)`).

The 15 slots split into five groups:

- **Cell level**: `$cell.list`, `$cell.data`, `$cell.meta`
- **Edge level**: `$edge.list`, `$edge.data`, `$edge.meta`
- **Neighborhood level**: `$neighborhood.cell.list`, `$neighborhood.edge.list`, `$neighborhood.meta`
- **LRM / gene level**: `$gene.list`, `$gene.meta`, `$LRM.list`, `$LRM.meta`
- **Extras**: `$segmentation` (sf polygons), `$aggregations` (named list, empty at construction)

Two object attributes (not slots) track mode: `attr(obj, "mode")` (`"spatial"` or `"nonspatial"`) and `attr(obj, "sample.col")`.

### Sparse long-format storage

`$cell.data` and `$edge.data` are **keyed `data.table` objects in long format** — one row per (cell, gene) or (edge, LRM). This scales with interaction density rather than total dimensions and is fundamental to the package's memory model. Do not convert these to wide matrices without an explicit reason.

Key string separators (used throughout):
- Edge IDs: `"SendingCell|ReceivingCell"`
- LRM IDs: `"ligand|receptor"`
- Gene complexes: `"GeneA_GeneB"` (underscore; handled automatically in `compute_LRM_Score()`)

### Construction pipeline

`create_NICHESObject()` (`R/create_NICHESObject.R`) is the public entry point. It dispatches to:

- `create_NICHESObject_single()` — one sample or no `sample.col`
- `create_NICHESObject_by_sample()` — splits by `sample.col`, processes each partition independently, merges via `merge_NICHESObjects()`

**Barcodes must be globally unique across all samples** when using `sample.col`.

The single-partition pipeline (in order): validate inputs → build edge list → score LR pairs via `compute_CellToCell()` → assemble slots → extract neighborhoods.

Edge list construction:
- **Spatial kNN** (`k=`): `RANN::nn2`; only mutual edges are kept
- **Spatial radius** (`rad=`): `dbscan::frNN`; inherently symmetric
- Both modes add autocrine self-loop edges for every cell

LR scoring (`compute_CellToCell()` → `compute_LRM_Score()`): supports `"product"` (L×R) and `"minimum"` (min(L,R)) methods. Gene complexes take the product or minimum across all component genes.

### Aggregation framework

`$aggregations` starts as an empty list. Aggregations are populated on demand:

- `add_neighborhood_edge_agg()` — adds `$aggregations$neighborhood.edge.agg`: 27-column table with directional per-(cell, LRM) scores (in, out, cross, self.autocrine, other.autocrine; sum/mean/cmean variants and in/out ratio). Uses sparse matrix multiplication internally: five binary A matrices (cells × edges) are built once and multiplied by the score matrix B (edges × LRMs) in batches of `chunk.size` LRMs (default 50). This bounds peak memory while reducing iterations from n.lrms to ceil(n.lrms / chunk.size).
- `add_neighborhood_composition()` — adds `$aggregations$neighborhood.composition`: per-cell neighbor cell-type proportions
- `aggregate_NICHESObject()` calls both as a convenience wrapper; accepts `chunk.size` and passes it through to `add_neighborhood_edge_agg()`

### Neighborhood filtering

`add_neighborhoods()` (called internally at construction) supports three `edge.filter.mode` values: `"both_in_neighborhood"` (default at construction), `"any_in_neighborhood"`, and `"central_cell_only"`. The mode set at construction is stored in the object.

### Subsetting

`[.NICHESObject` filters neighborhood slots and aggregation tables by cell, leaving each retained cell's entries unchanged, so they still describe its whole neighborhood in the full tissue. Edge slots keep only edges between retained cells, so a subset's neighborhood lists can name edges that are absent from `$edge.list`. `add_neighborhood_edge_agg()` and `add_neighborhood_composition()` therefore stop on such a subset through `.stop_if_neighborhood_edges_missing()`, because recomputing would divide partial sums by full edge counts. The workflow is to aggregate first, then subset. `add_neighborhoods(obj, overwrite = TRUE)` treats a subset as a separate tissue and clears the carried-over aggregations.

### Metadata operations — important distinction

- `add_cell_meta()` **fully replaces** `$cell.meta` and rebuilds `$edge.meta` from scratch. Use only when replacing the entire metadata table.
- `add_meta_column()` appends or overwrites a single column without touching anything else.

### Parallelism

Always use `parallel::makeCluster()` (socket clusters). **Never use `mclapply`** — it is not cross-platform. The `n.cores` parameter in user-facing functions wires directly to socket clusters. Workers call `data.table::setDTthreads(1)`. The package must not change `data.table`'s thread setting on load, because each worker loads the namespace and would lose that limit.

**Exception**: `add_neighborhood_edge_agg()` uses sparse matrix multiplication (Matrix package) instead of socket clusters. Its `n.cores` parameter is retained for API compatibility only and is not used. New functions that adopt a similar matrix-based approach should follow the same pattern: keep `n.cores` in the signature, validate it, but skip cluster creation.

### LR databases

Three built-in options via `load_LRM_database()`:
- `"connectomedb2025"` (default) — bundled `.rda` files, human/mouse/rat/pig, no internet required
- `"fantom5"` — bundled `.rda` files, same four species
- `"omnipath"` — requires internet access; uses `OmnipathR` (Suggests) when available, with a base-R REST fallback

Custom data frames are also accepted; must have `ligand` and `receptor` columns (configurable via `ligand.col`/`receptor.col`).

**OmniPath resilient loading** (ported from NICHESv1 PR #72 / issue #70): newer OmnipathR (≥ ~3.17, incl. 4.1.0) resolves the `organism` argument via `ncbi_taxid()`, which downloads/coalesces species tables from Ensembl, OMA, and UniProt — when any of those ancillary services is unreachable the call aborts with `"Can't combine ..1 and ..3"` even though the OmniPath interaction server is fine. `.load_omnipath()` therefore delegates to `.niches_fetch_omnipath_ligrec()`, which (1) tries the standard OmnipathR path with its logger muted, (2) falls back to a direct OmniPath REST query (`omnipathdb.org/interactions?datasets=ligrecextra&organisms=<taxid>`) using the already-known NCBI taxon id, bypassing the organism-name lookup, and (3) raises an informative network error only if both fail. Fallback is base-R only (`utils::download.file`/`read.delim`), no new dependencies. All four OmniPath helpers live in `R/load_LRM_database.R`.

### Data ingest

- `extract_NICHESInputs_Seurat()` — supports Seurat V4 and V5; detects assay class automatically; **spatial coordinates must be extracted manually** and added to the returned metadata before calling `create_NICHESObject()`
- `extract_NICHESInputs_AnnData()` — reads `.h5ad` via `rhdf5` only; no Python required

## Repository layout notes

- `R/` — all package source; every exported function has its own file
- `data/` — bundled `.rda` files (count matrix, example object, LR databases for 4 species)
- `inst/extdata/` — `NICHESv2_example.h5ad`, a small synthetic file used by the AnnData example
- `data-raw/` — scripts that build the bundled data files; excluded from package build
- `tests/testthat/` — one test file per source file; `helper-testutils.R` provides shared fixtures
- `vignettes/` — one vignette, `NICHESv2.Rmd`, which runs on bundled data; `vignettes/articles/` holds the website pages and is excluded from the package build
- `.github/workflows/` — `R-CMD-check.yaml` runs the checks; `pkgdown.yaml` builds the website and publishes it from `main`, removing this file first because pkgdown turns top-level Markdown files into pages
- `demo-scripts/` — standalone R scripts demonstrating real-dataset usage (not part of the package build)
- `working-scripts-MSBR/` and `working-scripts-NW/` — exploratory and prototyping scripts; not part of the package
- `package management/` — design documents
40 changes: 27 additions & 13 deletions DESCRIPTION
Original file line number Diff line number Diff line change
@@ -1,33 +1,47 @@
Package: NICHESv2
Type: Package
Title: Spatial Cell-to-Cell Ligand-Receptor Communication Analysis
Version: 0.1.0
Authors@R: person(given="NICHESv2", family="Authors", role=c("aut","cre"), email="niches@example.com")
Description: Computes ligand-receptor (LR) signalling scores between spatially
neighbouring cells in single-cell spatial transcriptomics data. Returns a
NICHESObject (13-slot S3 class) with per-cell aggregation, batch in situ
visualisation, and flexible downstream analysis. Supports single-gene and
multi-gene complex ligands/receptors (underscore-delimited). Built-in
loaders for FANTOM5 and OmniPath LR databases.
License: MIT + file LICENSE
Version: 1.0.0
Authors@R: c(
person("Nuoya", "Wang",
email = "nuoya.wang@yale.edu",
role = c("aut", "cre", "cph")),
person("Micha Sam Brickman", "Raredon",
role = c("aut", "cph")))
Description: Computes ligand-receptor (LR) signaling scores between pairs of
cells in spatial and non-spatial single-cell transcriptomics data. Results
are held in a memory-efficient, sparse long-format S3 class with per-cell
neighborhood aggregation for downstream analysis. Supports single-gene and
multi-gene complex ligands and receptors. Built-in loaders are provided for
the ConnectomeDB2025 (default), FANTOM5, and OmniPath LR databases.
License: AGPL-3
URL: https://raredonlab.github.io/NICHESv2/,
https://github.com/RaredonLab/NICHESv2
BugReports: https://github.com/RaredonLab/NICHESv2/issues
Encoding: UTF-8
Language: en-US
VignetteBuilder: knitr
LazyData: false
RoxygenNote: 7.3.2
Depends: R (>= 4.1.0)
Imports:
data.table (>= 1.14.0),
Matrix (>= 1.5.0),
methods,
RANN (>= 2.6.1),
dbscan (>= 1.1.0),
ggplot2 (>= 3.4.0),
irlba (>= 2.3.0),
parallel
parallel,
stats,
utils
Suggests:
SeuratObject,
rhdf5,
OmnipathR,
arrow,
testthat (>= 3.0.0),
withr,
devtools,
sf
sf,
knitr,
rmarkdown
Config/testthat/edition: 3
Loading
Loading