brisc 0.1.0__tar.gz

brisc-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Wainberg and Keon Arbabi
+
+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.

brisc-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: brisc
+Version: 0.1.0
+Summary: Fast single-cell toolkit
+Author-email: Michael Wainberg <m.wainberg@utoronto.ca>
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anndata
+Requires-Dist: h5py
+Requires-Dist: matplotlib>=3.5.0
+Requires-Dist: numpy>=1.17.0
+Requires-Dist: pandas
+Requires-Dist: polars>=1.41.0
+Requires-Dist: pyarrow>=0.17.0
+Requires-Dist: ryp
+Requires-Dist: scipy>=0.16.0
+Requires-Dist: scikit-misc
+Requires-Dist: threadpoolctl
+Dynamic: license-file
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://brisc.run/_static/images/runner_title_wide_dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://brisc.run/_static/images/runner_title_wide_light.svg">
+    <img alt="brisc" src="https://brisc.run/_static/images/runner_title_wide_light.svg" width="500">
+  </picture>
+</p>
+
+brisc is a high-performance library for analyzing single-cell data at scale. It prioritizes running as fast as possible on multi-core CPU systems, strict reproducibility, and a clean, user-friendly interface. On datasets of 1 to 20 million cells, it cuts the runtime of common workflows from hours to minutes.
+
+Full documentation is available at **[brisc.run](https://brisc.run)**.
+
+## Why brisc?
+
+- **Blazing fast** — ground-up optimization of core algorithms and effective parallelism.
+- **Deterministic** — every step gives floating-point identical results between runs, regardless of the number of threads used.
+- **Complete toolkit** — preprocessing, dimensionality reduction, harmonization, label transfer, clustering, embedding, pseudobulk differential expression, and plotting.
+- **Interoperable** — reads and writes `.h5ad`, `.rds`, `.h5Seurat`, and 10x files, and supports interleaving Python and R analyses via [ryp](https://github.com/Wainberg/ryp) without intermediate writes to disk.
+- **Memory-efficient** — ~2× lower peak memory than Scanpy by tabulating which cells pass QC, instead of subsetting to them.
+- **User-friendly** — sensible defaults, strict type-checking, and solution-focused error messages.
+
+## Installation
+
+brisc supports Linux, macOS, and Windows on Python 3.9+.
+
+**conda (recommended)**
+
+```bash
+conda install -c conda-forge brisc
+```
+
+**pip**
+
+```bash
+pip install brisc
+```
+
+conda is recommended because it sets up the fast MKL BLAS and some of the R packages brisc uses. With pip, you'll need to handle those yourself: see the [installation guide](https://brisc.run/installation.html) for details, including optional R integration (for differential expression, Seurat, and SingleCellExperiment support) via [ryp](https://github.com/Wainberg/ryp).
+
+## Quick start
+
+### Basic workflow
+
+```python
+from brisc import SingleCell
+
+sc = SingleCell('data.h5ad')\
+  .qc()\
+  .hvg(batch_column='donor')\
+  .normalize()\
+  .pca()\
+  .neighbors()\
+  .shared_neighbors()\
+  .cluster(resolution=[0.25, 0.5, 1, 1.5, 2])\
+  .pacmap()
+```
+
+### Label transfer
+
+```python
+from brisc import SingleCell
+
+sc_ref = SingleCell('data_ref.h5ad').qc()
+sc_query = SingleCell('data_query.h5ad').qc()
+sc_ref, sc_query = sc_ref.hvg(sc_query)
+sc_ref = sc_ref.normalize()
+sc_query = sc_query.normalize()
+sc_ref, sc_query = sc_ref.pca(sc_query)
+sc_ref, sc_query = sc_ref.harmonize(sc_query)
+sc_query = sc_query.label_transfer_from(
+  sc_ref, 'cell_type')
+```
+
+### Pseudobulk differential expression
+
+```python
+from brisc import SingleCell
+
+pb = SingleCell('data.h5ad')\
+  .qc()\
+  .pseudobulk('sample', 'cell_type')
+de = pb\
+  .qc('condition')\
+  .library_size()\
+  .de('~ condition + sex + pmi')
+```

brisc-0.1.0/README.md

@@ -0,0 +1,86 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://brisc.run/_static/images/runner_title_wide_dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://brisc.run/_static/images/runner_title_wide_light.svg">
+    <img alt="brisc" src="https://brisc.run/_static/images/runner_title_wide_light.svg" width="500">
+  </picture>
+</p>
+
+brisc is a high-performance library for analyzing single-cell data at scale. It prioritizes running as fast as possible on multi-core CPU systems, strict reproducibility, and a clean, user-friendly interface. On datasets of 1 to 20 million cells, it cuts the runtime of common workflows from hours to minutes.
+
+Full documentation is available at **[brisc.run](https://brisc.run)**.
+
+## Why brisc?
+
+- **Blazing fast** — ground-up optimization of core algorithms and effective parallelism.
+- **Deterministic** — every step gives floating-point identical results between runs, regardless of the number of threads used.
+- **Complete toolkit** — preprocessing, dimensionality reduction, harmonization, label transfer, clustering, embedding, pseudobulk differential expression, and plotting.
+- **Interoperable** — reads and writes `.h5ad`, `.rds`, `.h5Seurat`, and 10x files, and supports interleaving Python and R analyses via [ryp](https://github.com/Wainberg/ryp) without intermediate writes to disk.
+- **Memory-efficient** — ~2× lower peak memory than Scanpy by tabulating which cells pass QC, instead of subsetting to them.
+- **User-friendly** — sensible defaults, strict type-checking, and solution-focused error messages.
+
+## Installation
+
+brisc supports Linux, macOS, and Windows on Python 3.9+.
+
+**conda (recommended)**
+
+```bash
+conda install -c conda-forge brisc
+```
+
+**pip**
+
+```bash
+pip install brisc
+```
+
+conda is recommended because it sets up the fast MKL BLAS and some of the R packages brisc uses. With pip, you'll need to handle those yourself: see the [installation guide](https://brisc.run/installation.html) for details, including optional R integration (for differential expression, Seurat, and SingleCellExperiment support) via [ryp](https://github.com/Wainberg/ryp).
+
+## Quick start
+
+### Basic workflow
+
+```python
+from brisc import SingleCell
+
+sc = SingleCell('data.h5ad')\
+  .qc()\
+  .hvg(batch_column='donor')\
+  .normalize()\
+  .pca()\
+  .neighbors()\
+  .shared_neighbors()\
+  .cluster(resolution=[0.25, 0.5, 1, 1.5, 2])\
+  .pacmap()
+```
+
+### Label transfer
+
+```python
+from brisc import SingleCell
+
+sc_ref = SingleCell('data_ref.h5ad').qc()
+sc_query = SingleCell('data_query.h5ad').qc()
+sc_ref, sc_query = sc_ref.hvg(sc_query)
+sc_ref = sc_ref.normalize()
+sc_query = sc_query.normalize()
+sc_ref, sc_query = sc_ref.pca(sc_query)
+sc_ref, sc_query = sc_ref.harmonize(sc_query)
+sc_query = sc_query.label_transfer_from(
+  sc_ref, 'cell_type')
+```
+
+### Pseudobulk differential expression
+
+```python
+from brisc import SingleCell
+
+pb = SingleCell('data.h5ad')\
+  .qc()\
+  .pseudobulk('sample', 'cell_type')
+de = pb\
+  .qc('condition')\
+  .library_size()\
+  .de('~ condition + sex + pmi')
+```

brisc-0.1.0/brisc/__init__.py

@@ -0,0 +1,64 @@
+import os
+import signal
+import sys
+
+# Disable HDF5 file locking, which can cause issues when loading
+os.environ['HDF5_USE_FILE_LOCKING'] = 'FALSE'
+
+# Python's `logging` module calls `os.register_at_fork()` to handle aspects of
+# its internal locking. Unfortunately, this can cause KeyboardInterrupts to be
+# repeatedly ignored in multiprocessing-based HDF5 loading with errors like:
+# Exception ignored in: <function _releaseLock at 0x7fb85797c5e0>
+# Traceback (most recent call last):
+#   File ".../logging/__init__.py", line 243, in _releaseLock
+#     def _releaseLock():
+# To get around this bug, temporarily monkeypatch `os.register_at_fork()` to be
+# a null-op, then `import logging`. Unfortunately, there's no way to unregister
+# a callback created with `os.register_at_fork()`, so this "fix" only works
+# when the `logging` module has not been imported yet.
+if 'logging' not in sys.modules and hasattr(os, 'register_at_fork'):
+    original_register_at_fork = os.register_at_fork
+    os.register_at_fork = lambda *args, **kwargs: None
+    try:
+        import logging
+    finally:
+        os.register_at_fork = original_register_at_fork
+
+# Ignore Ctrl + C when importing certain modules, to avoid errors due to
+# incomplete imports
+original_sigint_handler = signal.signal(signal.SIGINT, signal.SIG_IGN)
+try:
+    import h5py
+    import numpy as np
+    import polars as pl
+    import pyarrow as pa
+    from scipy import sparse
+    from scipy.sparse._compressed import _cs_matrix
+    from scipy.special import stdtrit
+finally:
+    signal.signal(signal.SIGINT, original_sigint_handler)
+
+# On Linux with thread pinning enabled, MKL BLAS narrows the thread affinity
+# mask to one core when first executed, which would make all of brisc run
+# single-threaded if not fixed. Fix this now by running a BLAS function, then
+# re-expanding the mask to all available cores. (This works even if cgroups
+# limit the available cores, e.g. on Slurm: the OS will take the intersection
+# of what we asked for and what the cgroup allows.)
+if hasattr(os, 'sched_setaffinity'):
+    np.linalg.svd([[0]])
+    os.sched_setaffinity(0, range(os.cpu_count()))
+
+# Ignore harmless warnings about libiomp/libomp mismatch on Windows, which come
+# from compiling with /openmp:llvm but calling BLAS functions compiled with
+# Intel OpenMP
+if sys.platform == 'win32':
+    import warnings
+    warnings.filterwarnings(action='ignore', module='threadpoolctl',
+                            category=RuntimeWarning)
+
+# Expose the public API
+from .single_cell import SingleCell
+from .pseudobulk import Pseudobulk
+from .de import DE
+from .concatenate import concat_obs, concat_var
+__all__ = 'SingleCell', 'Pseudobulk', 'DE', 'concat_obs', 'concat_var'

brisc-0.1.0/brisc/colorspacious.py

@@ -0,0 +1,280 @@
+"""
+A standalone replacement for `colorspacious.cspace_convert()`, covering only
+the conversions used by `generate_palette()`:
+
+    * ('sRGB1',     'CAM02-UCS')
+    * ('sRGB255',   'CAM02-UCS')
+    * ('CAM02-UCS', 'JCh')
+    * ('CAM02-UCS', 'sRGB1')
+
+It is a faithful port of the relevant pieces of colorspacious
+(github.com/njsmith/colorspacious, MIT license, (C) Nathaniel J. Smith),
+using the fixed sRGB viewing conditions and the CAM02-UCS parameters that
+colorspacious uses for these named color spaces. It reproduces colorspacious's
+numeric output for these routes, but does not support any other conversion.
+"""
+
+import numpy as np
+
+__all__ = ['cspace_convert']
+
+# ---------------------------------------------------------------------------
+# sRGB <-> linear-sRGB <-> XYZ100   (from colorspacious/basics.py)
+# ---------------------------------------------------------------------------
+
+# Exact matrix from IEC 61966-2-1:1999
+_XYZ100_to_sRGB1_matrix = np.array([
+    [ 3.2406, -1.5372, -0.4986],
+    [-0.9689,  1.8758,  0.0415],
+    [ 0.0557, -0.2040,  1.0570]])
+_sRGB1_to_XYZ100_matrix = np.linalg.inv(_XYZ100_to_sRGB1_matrix)
+
+
+def _srgb_to_linear(c):
+    c = np.asarray(c, dtype=float)
+    out = np.empty(c.shape, dtype=float)
+    lin = c < 0.04045
+    a = 0.055
+    out[lin] = c[lin] / 12.92
+    out[~lin] = ((c[~lin] + a) / (a + 1)) ** 2.4
+    return out
+
+
+def _linear_to_srgb(c):
+    c = np.asarray(c, dtype=float)
+    out = np.empty(c.shape, dtype=float)
+    lin = c <= 0.0031308
+    a = 0.055
+    out[lin] = c[lin] * 12.92
+    out[~lin] = (1 + a) * c[~lin] ** (1 / 2.4) - a
+    return out
+
+
+def _matvec(mat, vecs):
+    # mat @ each trailing-3 vector of `vecs`
+    return np.einsum('...ij,...j->...i', mat, vecs)
+
+
+def _sRGB1_to_XYZ100(sRGB1):
+    return _matvec(_sRGB1_to_XYZ100_matrix, _srgb_to_linear(sRGB1)) * 100.0
+
+
+def _XYZ100_to_sRGB1(XYZ100):
+    lin = _matvec(_XYZ100_to_sRGB1_matrix, np.asarray(XYZ100, float) / 100.0)
+    return _linear_to_srgb(lin)
+
+
+# ---------------------------------------------------------------------------
+# CIECAM02 viewing conditions (colorspacious's CIECAM02Space.sRGB)
+#   XYZ100_w = D65, Y_b = 20, L_A = (64/pi)/5, average surround
+# ---------------------------------------------------------------------------
+
+_M_CAT02 = np.array([[ 0.7328,  0.4296, -0.1624],
+                     [-0.7036,  1.6975,  0.0061],
+                     [ 0.0030,  0.0136,  0.9834]])
+_M_HPE = np.array([[ 0.38971,  0.68898, -0.07868],
+                   [-0.22981,  1.18340,  0.04641],
+                   [ 0.00000,  0.00000,  1.00000]])
+_M_CAT02_inv = np.linalg.inv(_M_CAT02)
+_M_HPE_M_CAT02_inv = _M_HPE @ _M_CAT02_inv
+_M_CAT02_M_HPE_inv = _M_CAT02 @ np.linalg.inv(_M_HPE)
+
+
+class _VC:
+    """Precomputed CIECAM02 viewing-condition constants (sRGB)."""
+    def __init__(self):
+        XYZ_w = np.array([95.047, 100.0, 108.883])   # D65
+        Y_b = 20.0
+        L_A = (64.0 / np.pi) / 5.0
+        F, c, N_c = 1.0, 0.69, 1.0                    # average surround
+
+        self.c = c
+        self.N_c = N_c
+
+        RGB_w = _M_CAT02 @ XYZ_w
+        D = F * (1 - (1 / 3.6) * np.exp((-L_A - 42) / 92))
+        D = np.clip(D, 0, 1)
+        self.D_RGB = D * XYZ_w[1] / RGB_w + 1 - D
+
+        k = 1 / (5 * L_A + 1)
+        self.F_L = (0.2 * k ** 4 * (5 * L_A)
+                    + 0.1 * (1 - k ** 4) ** 2 * (5 * L_A) ** (1 / 3))
+        self.n = Y_b / XYZ_w[1]
+        self.z = 1.48 + np.sqrt(self.n)
+        self.N_bb = 0.725 * (1 / self.n) ** 0.2
+        self.N_cb = self.N_bb
+
+        RGB_wc = self.D_RGB * RGB_w
+        RGBp_w = _M_HPE_M_CAT02_inv @ RGB_wc
+        tmp = ((self.F_L * RGBp_w) / 100) ** 0.42
+        RGBp_aw = 400 * (tmp / (tmp + 27.13)) + 0.1
+        self.A_w = (np.dot([2, 1, 1 / 20], RGBp_aw) - 0.305) * self.N_bb
+
+
+_VC = _VC()
+
+
+def _XYZ100_to_JCh_M(XYZ100):
+    """Forward CIECAM02. Returns (J, C, h, M)."""
+    vc = _VC
+    XYZ100 = np.asarray(XYZ100, dtype=float)
+
+    RGB = np.inner(XYZ100, _M_CAT02)
+    RGB_C = vc.D_RGB * RGB
+    RGBp = np.inner(RGB_C, _M_HPE_M_CAT02_inv)
+
+    signs = np.sign(RGBp)
+    tmp = (vc.F_L * signs * RGBp / 100) ** 0.42
+    RGBp_a = signs * 400 * (tmp / (tmp + 27.13)) + 0.1
+
+    a = np.inner(RGBp_a, [1, -12 / 11, 1 / 11])
+    b = np.inner(RGBp_a, [1 / 9, 1 / 9, -2 / 9])
+    h_rad = np.arctan2(b, a)
+    h = np.rad2deg(h_rad) % 360
+
+    A = (np.inner(RGBp_a, [2, 1, 1 / 20]) - 0.305) * vc.N_bb
+    if np.any(A < 0):
+        error_message = 'achromatic signal A was negative'
+        raise ValueError(error_message)
+
+    J = 100 * (A / vc.A_w) ** (vc.c * vc.z)
+    e = (12500 / 13) * vc.N_c * vc.N_cb * (np.cos(h_rad + 2) + 3.8)
+    t = (e * np.sqrt(a ** 2 + b ** 2)) / np.inner(RGBp_a, [1, 1, 21 / 20])
+    C = t ** 0.9 * (J / 100) ** 0.5 * (1.64 - 0.29 ** vc.n) ** 0.73
+    M = C * vc.F_L ** 0.25
+    return J, C, h, M
+
+
+def _JMh_to_XYZ100(J, M, h):
+    """Inverse CIECAM02 from (J, M, h). Port of the J/M/h path only."""
+    vc = _VC
+    J = np.asarray(J, dtype=float)
+    M = np.asarray(M, dtype=float)
+    h = np.asarray(h, dtype=float)
+
+    C = M / vc.F_L ** 0.25
+
+    J, C, h = np.broadcast_arrays(J, C, h)
+    target_shape = J.shape
+    if J.ndim == 0:
+        J = np.atleast_1d(J)
+        C = np.atleast_1d(C)
+        h = np.atleast_1d(h)
+
+    t = (C / (np.sqrt(J / 100)
+              * (1.64 - 0.29 ** vc.n) ** 0.73)) ** (1 / 0.9)
+    e_t = 0.25 * (np.cos(np.deg2rad(h) + 2) + 3.8)
+    A = vc.A_w * (J / 100) ** (1 / (vc.c * vc.z))
+
+    with np.errstate(divide='ignore', invalid='ignore'):
+        one_over_t = 1 / t
+    one_over_t = np.select([np.isnan(one_over_t), True],
+                           [np.inf, one_over_t])
+
+    p_1 = (50000 / 13) * vc.N_c * vc.N_cb * e_t * one_over_t
+    p_2 = A / vc.N_bb + 0.305
+    p_3 = 21 / 20
+
+    sin_h = np.sin(np.deg2rad(h))
+    cos_h = np.cos(np.deg2rad(h))
+
+    num = p_2 * (2 + p_3) * (460 / 1403)
+    denom_part2 = (2 + p_3) * (220 / 1403)
+    denom_part3 = (-27 / 1403) + p_3 * (6300 / 1403)
+
+    a = np.empty_like(h)
+    b = np.empty_like(h)
+    small_cos = np.abs(sin_h) >= np.abs(cos_h)
+
+    b[small_cos] = (num[small_cos]
+                    / (p_1[small_cos] / sin_h[small_cos]
+                       + denom_part2 * cos_h[small_cos] / sin_h[small_cos]
+                       + denom_part3))
+    a[small_cos] = b[small_cos] * cos_h[small_cos] / sin_h[small_cos]
+
+    a[~small_cos] = (num[~small_cos]
+                     / (p_1[~small_cos] / cos_h[~small_cos]
+                        + denom_part2
+                        + denom_part3 * sin_h[~small_cos] / cos_h[~small_cos]))
+    b[~small_cos] = a[~small_cos] * sin_h[~small_cos] / cos_h[~small_cos]
+
+    p2ab = np.stack([p_2, a, b], axis=-1)
+    RGBp_a_matrix = (1 / 1403) * np.array([[460,  451,   288],
+                                           [460, -891,  -261],
+                                           [460, -220, -6300]], dtype=float)
+    RGBp_a = np.inner(p2ab, RGBp_a_matrix)
+
+    RGBp = (np.sign(RGBp_a - 0.1)
+            * (100 / vc.F_L)
+            * ((27.13 * np.abs(RGBp_a - 0.1))
+               / (400 - np.abs(RGBp_a - 0.1))) ** (1 / 0.42))
+
+    RGB_C = np.inner(RGBp, _M_CAT02_M_HPE_inv)
+    RGB = RGB_C / vc.D_RGB
+    XYZ100 = np.inner(RGB, _M_CAT02_inv)
+    return XYZ100.reshape(target_shape + (3,))
+
+
+# ---------------------------------------------------------------------------
+# CAM02-UCS (Luo et al. 2006) J'a'b' <-> JMh   (KL=1.00, c1=0.007, c2=0.0228)
+# ---------------------------------------------------------------------------
+
+_UCS_KL, _UCS_C1, _UCS_C2 = 1.00, 0.007, 0.0228
+
+
+def _JMh_to_Jpapbp(JMh):
+    JMh = np.asarray(JMh, dtype=float)
+    J = JMh[..., 0]
+    M = JMh[..., 1]
+    h = JMh[..., 2]
+    Jp = (1 + 100 * _UCS_C1) * J / (1 + _UCS_C1 * J) / _UCS_KL
+    Mp = (1 / _UCS_C2) * np.log(1 + _UCS_C2 * M)
+    h_rad = np.deg2rad(h)
+    ap = Mp * np.cos(h_rad)
+    bp = Mp * np.sin(h_rad)
+    return np.stack([Jp, ap, bp], axis=-1)
+
+
+def _Jpapbp_to_JMh(Jpapbp):
+    Jpapbp = np.asarray(Jpapbp, dtype=float)
+    Jp = Jpapbp[..., 0] * _UCS_KL
+    ap = Jpapbp[..., 1]
+    bp = Jpapbp[..., 2]
+    J = -Jp / (_UCS_C1 * Jp - 100 * _UCS_C1 - 1)
+    Mp = np.hypot(ap, bp)
+    h = np.rad2deg(np.arctan2(bp, ap)) % 360
+    M = (np.exp(_UCS_C2 * Mp) - 1) / _UCS_C2
+    return np.stack([J, M, h], axis=-1)
+
+
+# ---------------------------------------------------------------------------
+# Public entry point
+# ---------------------------------------------------------------------------
+
+def cspace_convert(arr, start, end):
+    """Drop-in replacement for `colorspacious.cspace_convert()`, restricted to
+    the start-end pairs used by `generate_palette()`. Raises for anything
+    else."""
+    route = (start, end)
+
+    if route == ('sRGB1', 'CAM02-UCS'):
+        J, C, h, M = _XYZ100_to_JCh_M(_sRGB1_to_XYZ100(arr))
+        return _JMh_to_Jpapbp(np.stack([J, M, h], axis=-1))
+
+    if route == ('sRGB255', 'CAM02-UCS'):
+        sRGB1 = np.asarray(arr, dtype=float) / 255.0
+        J, C, h, M = _XYZ100_to_JCh_M(_sRGB1_to_XYZ100(sRGB1))
+        return _JMh_to_Jpapbp(np.stack([J, M, h], axis=-1))
+
+    if route == ('CAM02-UCS', 'JCh'):
+        JMh = _Jpapbp_to_JMh(arr)
+        XYZ100 = _JMh_to_XYZ100(JMh[..., 0], JMh[..., 1], JMh[..., 2])
+        J, C, h, M = _XYZ100_to_JCh_M(XYZ100)
+        return np.stack([J, C, h], axis=-1)
+
+    if route == ('CAM02-UCS', 'sRGB1'):
+        JMh = _Jpapbp_to_JMh(arr)
+        XYZ100 = _JMh_to_XYZ100(JMh[..., 0], JMh[..., 1], JMh[..., 2])
+        return _XYZ100_to_sRGB1(XYZ100)
+
+    raise NotImplementedError

brisc-0.1.0/brisc/concatenate.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+from typing import Iterable
+from .single_cell import SingleCell
+from .pseudobulk import Pseudobulk
+from .utils import check_type, to_tuple
+
+
+def concat_obs(datasets: SingleCell | Iterable[SingleCell] |
+                         Pseudobulk | Iterable[Pseudobulk],
+               *more_datasets: SingleCell | Pseudobulk,
+               dataset_column: str | None = None,
+               dataset_labels: Iterable[str] | None = None,
+               flexible: bool = False,
+               num_threads: int | np.integer | None = None) -> \
+        SingleCell | Pseudobulk:
+    """
+    Concatenate multiple SingleCell datasets cell-wise, or multiple Pseudobulk
+    datasets sample-wise.
+
+    Delegates to `SingleCell.concat_obs()` or `Pseudobulk.concat_obs()`,
+    depending on whether the datasets are SingleCell or Pseudobulk.
+
+    Args:
+        datasets: one or more SingleCell or Pseudobulk datasets to concatenate
+        *more_datasets: additional SingleCell or Pseudobulk datasets to
+                        concatenate with this one, specified as positional
+                        arguments
+        dataset_column: the name of an Enum column to be added to the
+                        concatenated dataset's `obs` labeling which dataset
+                        each cell came from. The labels themselves are
+                        determined by the `dataset_labels` argument.
+        dataset_labels: a sequence of labels for each dataset, used to populate
+                        `dataset_column`. There must be one label per dataset
+                        being concatenated. If `dataset_labels` is not
+                        specified, the labels default to `{dataset_column}_0`,
+                        `{dataset_column}_1`, ..., `{dataset_column}_{N - 1}`.
+                        Can only be specified when `dataset_column` is not
+                        `None`.
+        flexible: whether to subset to genes, columns of `obs` and `var`, and
+                  (for SingleCell datasets) keys of `obsm`, `varm` and `uns`
+                  common to all datasets before concatenating, rather than
+                  raising an error on any mismatches
+        num_threads: the number of threads to use when concatenating. Does not
+                     affect the concatenated SingleCell or Pseudobulk dataset's
+                     `num_threads`; this will always be the same as the first
+                     dataset's `num_threads`.
+
+    Returns:
+        The concatenated SingleCell or Pseudobulk dataset.
+    """
+    if isinstance(datasets, (SingleCell, Pseudobulk)):
+        datasets = (datasets,) + more_datasets
+    else:
+        datasets = tuple(datasets) + more_datasets
+        check_type(datasets[0], 'the first dataset', (SingleCell, Pseudobulk),
+                   'a SingleCell or Pseudobulk dataset')
+    if isinstance(datasets[0], SingleCell):
+        return datasets[0].concat_obs(
+            datasets[1:], flexible=flexible, dataset_column=dataset_column,
+            dataset_labels=dataset_labels, num_threads=num_threads)
+    else:
+        return datasets[0].concat_obs(
+            datasets[1:], flexible=flexible, dataset_column=dataset_column,
+            dataset_labels=dataset_labels)
+
+
+def concat_var(datasets: SingleCell | Iterable[SingleCell] |
+                         Pseudobulk | Iterable[Pseudobulk],
+               *more_datasets: SingleCell | Pseudobulk,
+               dataset_column: str | None = None,
+               dataset_labels: Iterable[str] | None = None,
+               flexible: bool = False,
+               num_threads: int | np.integer | None = None) -> \
+        SingleCell | Pseudobulk:
+    """
+    Concatenate multiple SingleCell datasets or multiple Pseudobulk datasets,
+    gene-wise. This is much less common than the cell- or sample-wise
+    concatenation provided by `concat_obs()`.
+
+    Delegates to `SingleCell.concat_var()` or `Pseudobulk.concat_var()`,
+    depending on whether the datasets are SingleCell or Pseudobulk.
+
+    Args:
+        datasets: one or more SingleCell or Pseudobulk datasets to concatenate
+        *more_datasets: additional Pseudobulk datasets to concatenate with this
+                        one, specified as positional arguments
+        dataset_column: the name of an Enum column to be added to the
+                        concatenated dataset's `var` labeling which dataset
+                        each cell came from. The labels themselves are
+                        determined by the `dataset_labels` argument.
+        dataset_labels: a sequence of labels for each dataset, used to populate
+                        `dataset_column`. There must be one label per dataset
+                        being concatenated. If `dataset_labels` is not
+                        specified, the labels default to `{dataset_column}_0`,
+                        `{dataset_column}_1`, ..., `{dataset_column}_{N - 1}`.
+                        Can only be specified when `dataset_column` is not
+                        `None`.
+        flexible: whether to subset to cells/samples, columns of `obs` and
+                  `var`, and (for SingleCell datasets) keys of `obsm`, `varm`
+                  and `uns` common to all datasets before concatenating, rather
+                  than raising an error on any mismatches
+        num_threads: the number of threads to use when concatenating. Does not
+                     affect the concatenated SingleCell/Pseudobulk dataset's
+                     `num_threads`; this will always be the same as the first
+                     dataset's `num_threads`.
+
+    Returns:
+        The concatenated SingleCell or Pseudobulk dataset.
+    """
+    if isinstance(datasets, (SingleCell, Pseudobulk)):
+        datasets = (datasets,) + more_datasets
+    else:
+        datasets = tuple(datasets) + more_datasets
+        check_type(datasets[0], 'the first dataset', (SingleCell, Pseudobulk),
+                   'a SingleCell or Pseudobulk dataset')
+    if isinstance(datasets[0], SingleCell):
+        return datasets[0].concat_var(
+            datasets[1:], flexible=flexible, dataset_column=dataset_column,
+            dataset_labels=dataset_labels, num_threads=num_threads)
+    else:
+        return datasets[0].concat_var(
+            datasets[1:], flexible=flexible, dataset_column=dataset_column,
+            dataset_labels=dataset_labels)