API Reference¶
parafac2
¶
Main exports.
CSRMatrix
¶
Bases: Matrix
A SciPy CSR array with optional implicit mean-centering.
The norms expand ||X - 1 mu^T||^2 into sum-of-squares and cross terms
over the stored nonzeros, so a centered norm never densifies X.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mat
|
csr_array
|
The sparse data matrix of shape |
required |
means
|
ndarray | None
|
Per-column means to subtract implicitly. |
None
|
Source code in parafac2/matrix.py
CompressedData
dataclass
¶
Compressed representation of a multi-condition single-cell dataset.
Stores the small dense per-condition cores and the orthonormal bases for
the gene mode (Q) and cell mode (Q_k), enabling fast rank sweeps
without touching the raw data again.
Source code in parafac2/compress.py
L_g
property
¶
Gene compression dimension.
Q
instance-attribute
¶
Gene projection basis of shape (n_genes, L_g) with orthonormal columns.
Q_k
instance-attribute
¶
Per-condition cell projection bases (n_cells_k, L_c_k) or None.
adata = None
class-attribute
instance-attribute
¶
Reference to original AnnData object if available.
condition_unique_idxs
instance-attribute
¶
Integer condition indices for each cell.
cores
instance-attribute
¶
List of length n_cond with dense cores Y_k of shape (L_c_k, L_g).
lost_var
instance-attribute
¶
Variance discarded by the compression projectors.
max_cell_dim
property
¶
Maximum cell dimension across cores.
means = None
class-attribute
instance-attribute
¶
Per-gene means subtracted during compression.
n_cond
instance-attribute
¶
Number of conditions.
n_genes
instance-attribute
¶
Number of genes in the uncompressed dataset.
norm_tensor
instance-attribute
¶
Total squared Frobenius norm of the original mean-centered dataset.
norm_weighted = None
class-attribute
instance-attribute
¶
Squared norm of the weighted slices w_k X_k, set with slice_weights.
slice_weights = None
class-attribute
instance-attribute
¶
Optional per-condition slice weights for normalized ALS.
total_cells
instance-attribute
¶
Total number of cells across all conditions.
DenseMatrix
¶
Bases: Matrix
A dense NumPy array with optional implicit mean-centering.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mat
|
ndarray
|
The dense data matrix of shape |
required |
means
|
ndarray | None
|
Per-column means to subtract implicitly. |
None
|
Source code in parafac2/matrix.py
Matrix
¶
Bases: ABC
Base class implementing the duck-typed matrix contract.
Subclasses supply the raw products (:meth:_matmul/:meth:_rmatmul,
which receive an operand already cast to self.dtype and made
C-contiguous) and the two norms. This class layers the shared parts on
top: operand coercion, the float64 result contract, and the implicit
mean-centering, which is applied as a rank-1 correction to the (small)
product rather than by materializing X - 1 mu^T.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
shape
|
tuple[int, int]
|
The matrix's |
required |
dtype
|
dtype
|
The dtype products are taken in. |
required |
means
|
ndarray | None
|
Per-column means to subtract implicitly. |
None
|
Source code in parafac2/matrix.py
85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 | |
__matmul__(rhs)
¶
Compute (self - 1 mu^T) @ rhs as a float64 NumPy array.
Source code in parafac2/matrix.py
__rmatmul__(lhs)
¶
Compute lhs @ (self - 1 mu^T) as a float64 NumPy array.
Source code in parafac2/matrix.py
norm_sq()
abstractmethod
¶
slice_norms(condition_idxs, n_cond)
abstractmethod
¶
Return the per-condition Frobenius norms of the (centered) rows.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
condition_idxs
|
ndarray
|
Integer array assigning each row to a condition in |
required |
n_cond
|
int
|
The total number of conditions. |
required |
Source code in parafac2/matrix.py
GPUMatrix(mat, backend=None, means=None)
¶
Deprecated alias for :func:to_gpu, kept for backwards compatibility.
The GPU-resident matrix is now just another implementation of the
duck-typed contract (see :class:DeviceMatrix) rather than a separate
wrapper class.
Source code in parafac2/matrix.py
as_linear_operator(mat, means=None)
¶
Return mat as a SciPy :class:~scipy.sparse.linalg.LinearOperator.
This is how the data is handed to SciPy's decompositions (see
:func:~parafac2.utils.randomized_svd_right): anything :func:as_matrix
accepts becomes an operator without the decomposition ever learning what
the data actually is or where it lives.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mat
|
Any
|
Anything :func: |
required |
means
|
ndarray | None
|
Per-column means to center by, as accepted by :func: |
None
|
Returns:
| Type | Description |
|---|---|
LinearOperator
|
An |
Source code in parafac2/matrix.py
as_matrix(mat, means=None)
¶
Return mat as something satisfying the duck-typed matrix contract.
This is the single place in the package that looks at the data's type: a NumPy array or SciPy sparse matrix is wrapped, and anything else is assumed to implement the contract itself and passed through untouched.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mat
|
Any
|
A NumPy array, a SciPy sparse matrix, or an object already
implementing the contract (including a :class: |
required |
means
|
ndarray | None
|
Per-column means to center by. Only meaningful for a plain NumPy or SciPy input: a type that implements the contract itself already accounts for its own centering. |
None
|
Returns:
| Type | Description |
|---|---|
Any
|
A :class: |
Raises:
| Type | Description |
|---|---|
ValueError
|
If a nonzero |
Source code in parafac2/matrix.py
compress_dataset(X_in, L='auto', rank=None, n_power_iter=20, random_state=None, normalize_slices=False, backend=None)
¶
Compress an AnnData dataset in gene and cell modes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
X_in
|
AnnData
|
Input dataset with data in |
required |
L
|
int | tuple[int, int | None] | str | bool
|
Compression dimension(s). If |
"auto"
|
rank
|
int | None
|
Expected maximum rank to fit on the compressed data. Used when
|
None
|
n_power_iter
|
int
|
Maximum number of refinement iterations for the randomized SVD
(see :func: |
20
|
random_state
|
int | Generator | None
|
Random seed or generator. |
None
|
normalize_slices
|
bool
|
Whether to precalculate slice weights for normalized ALS. |
False
|
backend
|
str | None
|
Compute backend for raw matrix products. |
None
|
Returns:
| Type | Description |
|---|---|
CompressedData
|
The compressed dataset ready for fast PARAFAC2 fitting. |
Source code in parafac2/compress.py
191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 | |
get_backend(backend=None)
¶
Return the requested backend, or auto-detect the first available one.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
backend
|
str
|
One of |
None
|
Returns:
| Type | Description |
|---|---|
str
|
The resolved backend name: |
Source code in parafac2/backend.py
parafac2_init(X, condition_unique_idxs, rank=3, means=None, random_state=None, n_oversamples=10, n_iter=20, norm_tensor=None, row_weights=None)
¶
Compute initial factors using randomized SVD.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
X
|
Any
|
The data matrix, stacked across all conditions, with shape
|
required |
condition_unique_idxs
|
ndarray
|
Integer array of length |
required |
rank
|
int
|
The number of components to compute. |
3
|
means
|
ndarray | None
|
Per-gene means to mean-center |
None
|
random_state
|
int | Generator | None
|
Seed or generator controlling the random projection used by the randomized SVD. |
None
|
n_oversamples
|
int
|
Extra dimensions added to |
10
|
n_iter
|
int
|
Maximum number of LOBPCG refinement iterations applied to the randomized SVD's subspace. |
20
|
norm_tensor
|
float | None
|
Precomputed squared Frobenius norm of the mean-centered |
None
|
row_weights
|
ndarray | None
|
Per-row weights; if given, |
None
|
Returns:
| Type | Description |
|---|---|
tuple[list[ndarray], float]
|
The initial |
Source code in parafac2/parafac2.py
parafac2_nd(X_in, rank, n_iter_max=100, tol=1e-06, random_state=None, callback=None, backend=None, normalize_slices=False, n_inner=1, compress=None, n_power_iter=20, fix_B_identity=False)
¶
The same interface as regular PARAFAC2 with optional CANDELINC compression.
If compress is specified (or if X_in is already a
:class:~parafac2.compress.CompressedData), PARAFAC2 is fit in the
compressed subspace (Bro's "compress-then-fit"), eliminating per-sweep raw
data passes.
If normalize_slices is True, each condition is weighted by the
inverse of its (mean-centered) Frobenius norm, so every condition counts
equally in the fit regardless of its cell count or variance. The fit is
that of the rescaled slices X_k / ||X_k|| (X itself is never
copied or modified), so tol and callback follow their error. The
returned A is in data units and R2X is the unweighted fraction of
variance explained, comparable to an unweighted fit.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
X_in
|
AnnData | CompressedData
|
Input dataset with the (optionally sparse) data matrix in |
required |
rank
|
int
|
The number of components to fit. |
required |
n_iter_max
|
int
|
Maximum number of ALS iterations. |
100
|
tol
|
float
|
Convergence tolerance: iteration stops once the (non-negative) decrease in relative error between successive iterations drops below this value. |
1e-6
|
random_state
|
int | None
|
Seed controlling the randomized SVD initialization. |
None
|
callback
|
Callable[[int, float, list[ndarray]], None] | None
|
Optional callback invoked after each iteration with the iteration index, the relative error, and the current factor matrices. |
None
|
backend
|
str | None
|
Compute backend to run matrix products on: one of |
None
|
normalize_slices
|
bool
|
Whether to weight each condition by the inverse of its Frobenius norm, as described above. |
False
|
n_inner
|
int
|
Number of |
1
|
compress
|
int | tuple[int, int | None] | str | bool | None
|
Compression mode. If |
None
|
n_power_iter
|
int
|
Maximum number of refinement iterations for the randomized SVD in the
compression step (see :func: |
20
|
fix_B_identity
|
bool
|
Whether to hold the |
False
|
Returns:
| Type | Description |
|---|---|
tuple[tuple[ndarray, list[ndarray], list[ndarray]], float]
|
A |
Source code in parafac2/parafac2.py
276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 | |
prepare_dataset(X, condition_name, geneThreshold)
¶
Preprocess and normalize an AnnData dataset for PARAFAC2 factorization.
Performs quality control filtering of low-count cells and low-expression genes, normalizes total cell counts and gene sums, applies a log10 transformation, and computes metadata required by PARAFAC2 (condition indices and gene means).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
X
|
AnnData
|
Input single-cell dataset with raw count matrix stored in |
required |
condition_name
|
str
|
Column name in |
required |
geneThreshold
|
float
|
Minimum threshold fraction for gene inclusion. Genes with total counts
less than |
required |
Returns:
| Type | Description |
|---|---|
AnnData
|
A filtered and normalized copy of the AnnData object. Contains the
log-transformed normalized counts in |
Source code in parafac2/normalize.py
store_pf2(X, parafac2_output)
¶
Store the Pf2 results into the anndata object.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
X
|
AnnData | CompressedData
|
The dataset the factorization was fit on. Must have
|
required |
parafac2_output
|
tuple[ndarray, list[ndarray], list[ndarray]]
|
The |
required |
Returns:
| Type | Description |
|---|---|
AnnData
|
The target AnnData object, mutated in place, with the weights in
|
Source code in parafac2/parafac2.py
to_gpu(mat, backend=None, means=None)
¶
Wrap mat for the fit and move it to the resolved backend's device.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mat
|
Any
|
The matrix to (optionally) transfer, as accepted by :func: |
required |
backend
|
str
|
One of |
None
|
means
|
ndarray | None
|
Per-column means to center by, as accepted by :func: |
None
|
Returns:
| Type | Description |
|---|---|
Any
|
The device-resident matrix on a GPU backend, otherwise the CPU-resident one. |
Raises:
| Type | Description |
|---|---|
TypeError
|
If a GPU backend is selected for a duck-typed matrix that does not
implement |
Source code in parafac2/matrix.py
parafac2.parafac2¶
parafac2.parafac2
¶
Core PARAFAC2 decomposition routines.
Implements PARAFAC2 initialization (randomized SVD), the alternating-least- squares fitting loop, CANDELINC-style compression, and standardization/storage of the fitted factors and per-condition projections. Operates directly on a single (optionally sparse) data matrix held in an AnnData object, avoiding per-condition copies.
parafac2_init(X, condition_unique_idxs, rank=3, means=None, random_state=None, n_oversamples=10, n_iter=20, norm_tensor=None, row_weights=None)
¶
Compute initial factors using randomized SVD.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
X
|
Any
|
The data matrix, stacked across all conditions, with shape
|
required |
condition_unique_idxs
|
ndarray
|
Integer array of length |
required |
rank
|
int
|
The number of components to compute. |
3
|
means
|
ndarray | None
|
Per-gene means to mean-center |
None
|
random_state
|
int | Generator | None
|
Seed or generator controlling the random projection used by the randomized SVD. |
None
|
n_oversamples
|
int
|
Extra dimensions added to |
10
|
n_iter
|
int
|
Maximum number of LOBPCG refinement iterations applied to the randomized SVD's subspace. |
20
|
norm_tensor
|
float | None
|
Precomputed squared Frobenius norm of the mean-centered |
None
|
row_weights
|
ndarray | None
|
Per-row weights; if given, |
None
|
Returns:
| Type | Description |
|---|---|
tuple[list[ndarray], float]
|
The initial |
Source code in parafac2/parafac2.py
parafac2_nd(X_in, rank, n_iter_max=100, tol=1e-06, random_state=None, callback=None, backend=None, normalize_slices=False, n_inner=1, compress=None, n_power_iter=20, fix_B_identity=False)
¶
The same interface as regular PARAFAC2 with optional CANDELINC compression.
If compress is specified (or if X_in is already a
:class:~parafac2.compress.CompressedData), PARAFAC2 is fit in the
compressed subspace (Bro's "compress-then-fit"), eliminating per-sweep raw
data passes.
If normalize_slices is True, each condition is weighted by the
inverse of its (mean-centered) Frobenius norm, so every condition counts
equally in the fit regardless of its cell count or variance. The fit is
that of the rescaled slices X_k / ||X_k|| (X itself is never
copied or modified), so tol and callback follow their error. The
returned A is in data units and R2X is the unweighted fraction of
variance explained, comparable to an unweighted fit.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
X_in
|
AnnData | CompressedData
|
Input dataset with the (optionally sparse) data matrix in |
required |
rank
|
int
|
The number of components to fit. |
required |
n_iter_max
|
int
|
Maximum number of ALS iterations. |
100
|
tol
|
float
|
Convergence tolerance: iteration stops once the (non-negative) decrease in relative error between successive iterations drops below this value. |
1e-6
|
random_state
|
int | None
|
Seed controlling the randomized SVD initialization. |
None
|
callback
|
Callable[[int, float, list[ndarray]], None] | None
|
Optional callback invoked after each iteration with the iteration index, the relative error, and the current factor matrices. |
None
|
backend
|
str | None
|
Compute backend to run matrix products on: one of |
None
|
normalize_slices
|
bool
|
Whether to weight each condition by the inverse of its Frobenius norm, as described above. |
False
|
n_inner
|
int
|
Number of |
1
|
compress
|
int | tuple[int, int | None] | str | bool | None
|
Compression mode. If |
None
|
n_power_iter
|
int
|
Maximum number of refinement iterations for the randomized SVD in the
compression step (see :func: |
20
|
fix_B_identity
|
bool
|
Whether to hold the |
False
|
Returns:
| Type | Description |
|---|---|
tuple[tuple[ndarray, list[ndarray], list[ndarray]], float]
|
A |
Source code in parafac2/parafac2.py
276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 | |
store_pf2(X, parafac2_output)
¶
Store the Pf2 results into the anndata object.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
X
|
AnnData | CompressedData
|
The dataset the factorization was fit on. Must have
|
required |
parafac2_output
|
tuple[ndarray, list[ndarray], list[ndarray]]
|
The |
required |
Returns:
| Type | Description |
|---|---|
AnnData
|
The target AnnData object, mutated in place, with the weights in
|
Source code in parafac2/parafac2.py
parafac2.normalize¶
parafac2.normalize
¶
Dataset preprocessing and normalization utilities for PARAFAC2 analysis.
This module provides functions to filter, normalize, and annotate single-cell gene expression datasets stored in AnnData objects prior to PARAFAC2 matrix factorization.
prepare_dataset(X, condition_name, geneThreshold)
¶
Preprocess and normalize an AnnData dataset for PARAFAC2 factorization.
Performs quality control filtering of low-count cells and low-expression genes, normalizes total cell counts and gene sums, applies a log10 transformation, and computes metadata required by PARAFAC2 (condition indices and gene means).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
X
|
AnnData
|
Input single-cell dataset with raw count matrix stored in |
required |
condition_name
|
str
|
Column name in |
required |
geneThreshold
|
float
|
Minimum threshold fraction for gene inclusion. Genes with total counts
less than |
required |
Returns:
| Type | Description |
|---|---|
AnnData
|
A filtered and normalized copy of the AnnData object. Contains the
log-transformed normalized counts in |
Source code in parafac2/normalize.py
parafac2.compress¶
parafac2.compress
¶
CANDELINC compression for PARAFAC2.
Compresses the gene and cell modes of single-cell datasets prior to PARAFAC2 factorization, collapsing the problem to small dense per-condition cores.
CompressedData
dataclass
¶
Compressed representation of a multi-condition single-cell dataset.
Stores the small dense per-condition cores and the orthonormal bases for
the gene mode (Q) and cell mode (Q_k), enabling fast rank sweeps
without touching the raw data again.
Source code in parafac2/compress.py
L_g
property
¶
Gene compression dimension.
Q
instance-attribute
¶
Gene projection basis of shape (n_genes, L_g) with orthonormal columns.
Q_k
instance-attribute
¶
Per-condition cell projection bases (n_cells_k, L_c_k) or None.
adata = None
class-attribute
instance-attribute
¶
Reference to original AnnData object if available.
condition_unique_idxs
instance-attribute
¶
Integer condition indices for each cell.
cores
instance-attribute
¶
List of length n_cond with dense cores Y_k of shape (L_c_k, L_g).
lost_var
instance-attribute
¶
Variance discarded by the compression projectors.
max_cell_dim
property
¶
Maximum cell dimension across cores.
means = None
class-attribute
instance-attribute
¶
Per-gene means subtracted during compression.
n_cond
instance-attribute
¶
Number of conditions.
n_genes
instance-attribute
¶
Number of genes in the uncompressed dataset.
norm_tensor
instance-attribute
¶
Total squared Frobenius norm of the original mean-centered dataset.
norm_weighted = None
class-attribute
instance-attribute
¶
Squared norm of the weighted slices w_k X_k, set with slice_weights.
slice_weights = None
class-attribute
instance-attribute
¶
Optional per-condition slice weights for normalized ALS.
total_cells
instance-attribute
¶
Total number of cells across all conditions.
compress_cells(X_c, condition_unique_idxs, L_c=None)
¶
Compute per-condition cell-mode compression projectors Q_k and cores Y_k.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
X_c
|
ndarray
|
Gene-compressed data matrix of shape |
required |
condition_unique_idxs
|
ndarray
|
Integer condition index for each cell. |
required |
L_c
|
int | None
|
Target cell subspace dimension per condition. If |
None
|
Returns:
| Type | Description |
|---|---|
tuple[list[ndarray], list[ndarray | None] | None, float]
|
|
Source code in parafac2/compress.py
compress_dataset(X_in, L='auto', rank=None, n_power_iter=20, random_state=None, normalize_slices=False, backend=None)
¶
Compress an AnnData dataset in gene and cell modes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
X_in
|
AnnData
|
Input dataset with data in |
required |
L
|
int | tuple[int, int | None] | str | bool
|
Compression dimension(s). If |
"auto"
|
rank
|
int | None
|
Expected maximum rank to fit on the compressed data. Used when
|
None
|
n_power_iter
|
int
|
Maximum number of refinement iterations for the randomized SVD
(see :func: |
20
|
random_state
|
int | Generator | None
|
Random seed or generator. |
None
|
normalize_slices
|
bool
|
Whether to precalculate slice weights for normalized ALS. |
False
|
backend
|
str | None
|
Compute backend for raw matrix products. |
None
|
Returns:
| Type | Description |
|---|---|
CompressedData
|
The compressed dataset ready for fast PARAFAC2 fitting. |
Source code in parafac2/compress.py
191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 | |
compress_genes(X, L_g, n_power_iter=20, random_state=None, row_weights=None)
¶
Compute gene-mode compression projector Q and compressed matrix Xc.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
X
|
Any
|
Stacked data matrix of shape |
required |
L_g
|
int
|
Target gene subspace dimension. |
required |
n_power_iter
|
int
|
Maximum number of refinement iterations for the randomized SVD
(see :func: |
20
|
random_state
|
int | Generator | None
|
Random seed or generator. |
None
|
row_weights
|
ndarray | None
|
Per-row weights; if given, |
None
|
Returns:
| Type | Description |
|---|---|
tuple[ndarray, ndarray, float]
|
|
Source code in parafac2/compress.py
init_compressed_factors(cores, rank, random_state=None, slice_weights=None)
¶
Initialize factor matrices [A, B, C_L] directly on compressed cores.
Source code in parafac2/compress.py
project_data_compressed(cores, factors, norm_tensor, mode, return_projections=False, slice_weights=None)
¶
Project compressed per-condition cores and accumulate MTTKRP and error.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cores
|
list[ndarray]
|
List of per-condition core matrices |
required |
factors
|
list[ndarray]
|
Current factor matrices |
required |
norm_tensor
|
float
|
Squared Frobenius norm of the original mean-centered tensor, or of
its weighted slices when |
required |
mode
|
int
|
Mode to update (0, 1, or 2). |
required |
return_projections
|
bool
|
Whether to return the list of projection matrices |
False
|
slice_weights
|
ndarray | None
|
Optional per-condition weights |
None
|
Returns:
| Type | Description |
|---|---|
tuple[ndarray, float] | list[ndarray]
|
|
Source code in parafac2/compress.py
parafac2.matrix¶
parafac2.matrix
¶
The duck-typed matrix contract the PARAFAC2 fit talks to, and the wrappers that give NumPy arrays and SciPy CSR arrays that interface.
Everything downstream of :func:as_matrix -- :mod:parafac2.utils,
:mod:parafac2.compress, :mod:parafac2.parafac2 -- reaches the raw data
only through this contract. Nothing there branches on the data's type.
The contract
An object usable as X must provide:
shape
The (n_rows, n_cols) tuple.
dtype
The NumPy dtype products should be taken in. Callers build their dense
operands in this dtype so the product never has to upcast the (possibly
enormous) data matrix.
X @ rhs and lhs @ X
Matrix products against a 1-D or 2-D NumPy array, returning a float64
NumPy array. Any mean-centering the matrix represents must already be
applied -- X @ rhs means (X_raw - 1 mu^T) @ rhs.
norm_sq()
The squared Frobenius norm of the (centered) matrix, as a float.
slice_norms(condition_idxs, n_cond)
Per-condition Frobenius norms of the (centered) rows, as a length
n_cond array.
to_device(backend)
Return an object satisfying this same contract with its data resident on
backend ('cupy' or 'mlx'). Only needed to run on a GPU
backend; parafac2 has no transfer logic of its own for a third-party
storage format.
__array_ufunc__ = None
Required, so that lhs @ X for a plain NumPy lhs defers to X's
own __rmatmul__ instead of NumPy trying to broadcast X into an
ndarray (which fails outright for a type that cannot be converted to
one, as most duck-typed backends cannot).
:func:as_linear_operator adapts any of these to a SciPy
:class:~scipy.sparse.linalg.LinearOperator, which is how the data reaches
SciPy's decompositions (the randomized SVD in :mod:parafac2.utils) without
those ever learning what the data is or where it lives.
:class:Matrix implements everything but the two products and the two norms,
so subclassing it is the easy way to satisfy the contract; vsparse-style
types that implement it structurally work just as well and are passed through
:func:as_matrix untouched.
CSRMatrix
¶
Bases: Matrix
A SciPy CSR array with optional implicit mean-centering.
The norms expand ||X - 1 mu^T||^2 into sum-of-squares and cross terms
over the stored nonzeros, so a centered norm never densifies X.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mat
|
csr_array
|
The sparse data matrix of shape |
required |
means
|
ndarray | None
|
Per-column means to subtract implicitly. |
None
|
Source code in parafac2/matrix.py
DenseMatrix
¶
Bases: Matrix
A dense NumPy array with optional implicit mean-centering.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mat
|
ndarray
|
The dense data matrix of shape |
required |
means
|
ndarray | None
|
Per-column means to subtract implicitly. |
None
|
Source code in parafac2/matrix.py
DeviceMatrix
¶
Bases: Matrix
A host matrix whose data has been transferred to an accelerator.
Holds the device-resident payload plus the product routines that understand it, and delegates the norms back to the host matrix (they are computed once at setup, from data the host object already owns).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
host
|
Matrix
|
The CPU-resident matrix this was transferred from. |
required |
device_mat
|
Any
|
The device-resident payload (a CuPy array or sparse matrix, an MLX
array, or the |
required |
matmul_fn
|
callable
|
The backend routines computing |
required |
rmatmul_fn
|
callable
|
The backend routines computing |
required |
Source code in parafac2/matrix.py
Matrix
¶
Bases: ABC
Base class implementing the duck-typed matrix contract.
Subclasses supply the raw products (:meth:_matmul/:meth:_rmatmul,
which receive an operand already cast to self.dtype and made
C-contiguous) and the two norms. This class layers the shared parts on
top: operand coercion, the float64 result contract, and the implicit
mean-centering, which is applied as a rank-1 correction to the (small)
product rather than by materializing X - 1 mu^T.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
shape
|
tuple[int, int]
|
The matrix's |
required |
dtype
|
dtype
|
The dtype products are taken in. |
required |
means
|
ndarray | None
|
Per-column means to subtract implicitly. |
None
|
Source code in parafac2/matrix.py
85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 | |
__matmul__(rhs)
¶
Compute (self - 1 mu^T) @ rhs as a float64 NumPy array.
Source code in parafac2/matrix.py
__rmatmul__(lhs)
¶
Compute lhs @ (self - 1 mu^T) as a float64 NumPy array.
Source code in parafac2/matrix.py
norm_sq()
abstractmethod
¶
slice_norms(condition_idxs, n_cond)
abstractmethod
¶
Return the per-condition Frobenius norms of the (centered) rows.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
condition_idxs
|
ndarray
|
Integer array assigning each row to a condition in |
required |
n_cond
|
int
|
The total number of conditions. |
required |
Source code in parafac2/matrix.py
GPUMatrix(mat, backend=None, means=None)
¶
Deprecated alias for :func:to_gpu, kept for backwards compatibility.
The GPU-resident matrix is now just another implementation of the
duck-typed contract (see :class:DeviceMatrix) rather than a separate
wrapper class.
Source code in parafac2/matrix.py
as_linear_operator(mat, means=None)
¶
Return mat as a SciPy :class:~scipy.sparse.linalg.LinearOperator.
This is how the data is handed to SciPy's decompositions (see
:func:~parafac2.utils.randomized_svd_right): anything :func:as_matrix
accepts becomes an operator without the decomposition ever learning what
the data actually is or where it lives.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mat
|
Any
|
Anything :func: |
required |
means
|
ndarray | None
|
Per-column means to center by, as accepted by :func: |
None
|
Returns:
| Type | Description |
|---|---|
LinearOperator
|
An |
Source code in parafac2/matrix.py
as_matrix(mat, means=None)
¶
Return mat as something satisfying the duck-typed matrix contract.
This is the single place in the package that looks at the data's type: a NumPy array or SciPy sparse matrix is wrapped, and anything else is assumed to implement the contract itself and passed through untouched.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mat
|
Any
|
A NumPy array, a SciPy sparse matrix, or an object already
implementing the contract (including a :class: |
required |
means
|
ndarray | None
|
Per-column means to center by. Only meaningful for a plain NumPy or SciPy input: a type that implements the contract itself already accounts for its own centering. |
None
|
Returns:
| Type | Description |
|---|---|
Any
|
A :class: |
Raises:
| Type | Description |
|---|---|
ValueError
|
If a nonzero |
Source code in parafac2/matrix.py
to_gpu(mat, backend=None, means=None)
¶
Wrap mat for the fit and move it to the resolved backend's device.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mat
|
Any
|
The matrix to (optionally) transfer, as accepted by :func: |
required |
backend
|
str
|
One of |
None
|
means
|
ndarray | None
|
Per-column means to center by, as accepted by :func: |
None
|
Returns:
| Type | Description |
|---|---|
Any
|
The device-resident matrix on a GPU backend, otherwise the CPU-resident one. |
Raises:
| Type | Description |
|---|---|
TypeError
|
If a GPU backend is selected for a duck-typed matrix that does not
implement |
Source code in parafac2/matrix.py
parafac2.utils¶
parafac2.utils
¶
Low-level numerical routines supporting the PARAFAC2 fit.
Provides the per-condition projection step, the per-mode ALS factor update (which forms its own MTTKRP), the randomized SVD used for initialization and gene compression (SciPy's, driven through a linear operator over the data), and post-fit standardization of the factors and projections.
The fit touches the raw data through exactly two products, which together dominate runtime on single-cell-sized inputs:
W = (X - 1 mu^T) @ C(:func:calc_W), which depends only onC.X^T @ Hfor the mode-2 MTTKRP (inside :func:parafac_update).
Everything else flows through the compressed per-condition slices
S_k = P_k^T W_k, an (n_cond, rank, rank) array small enough to keep
resident. In particular the mode-0 and mode-1 MTTKRPs and the reconstruction
error are all functions of S alone, so the projections and both of those
factor updates can be recomputed from a cached W without re-reading the
data.
Nothing here inspects X's type. X is any object satisfying the
duck-typed matrix contract in :mod:parafac2.matrix -- a NumPy array or
SciPy CSR array wrapped by :func:~parafac2.matrix.as_matrix, or a
third-party type (e.g. one of vsparse's normalized views) implementing
it directly. In particular the matrix carries its own mean-centering, so
X @ C already means (X - 1 mu^T) @ C and no means argument is
threaded through these routines.
calc_W(X, C)
¶
Compute W = (X - 1 mu^T) @ C, the first of the two raw-data products.
W depends only on C, so it stays valid across the A and B
updates and only has to be recomputed once C changes. Any centering
and dtype handling belongs to X itself (see :mod:parafac2.matrix).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
X
|
Any
|
The data matrix, stacked across all conditions, with shape
|
required |
C
|
ndarray
|
The current gene factor matrix, shape |
required |
Returns:
| Type | Description |
|---|---|
ndarray
|
The float64 array |
Source code in parafac2/utils.py
calc_err(S, factors, norm_X_sq)
¶
Return the squared reconstruction error from the compressed slices.
Uses the expansion ||X||^2 + Tr(A^T A * B^T B * C^T C) - 2 <A, diag(B^T
S_k)>, so no raw-data pass is needed and the error is free to evaluate
as often as desired (e.g. to monitor an inner iteration).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
S
|
ndarray
|
The stacked compressed slices from :func: |
required |
factors
|
list[ndarray]
|
The current |
required |
norm_X_sq
|
float
|
The squared Frobenius norm of the mean-centered |
required |
Returns:
| Type | Description |
|---|---|
float
|
The squared reconstruction error. |
Source code in parafac2/utils.py
condition_slices(condition_unique_idxs, n_cond)
¶
Return a per-condition row selector for each condition.
Computing condition_unique_idxs == i inside the per-condition loop
costs O(n_cells) per condition, i.e. O(n_cells * n_cond) per pass
over the data, plus a fancy-indexed copy each time. Precomputing the
selectors once drops that to O(n_cells), and when the rows are
already grouped by condition (the usual case, since conditions are
concatenated) the selectors are plain slice objects, making
W[sel] a zero-copy view.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
condition_unique_idxs
|
ndarray
|
Integer array assigning each row to a condition in |
required |
n_cond
|
int
|
The total number of conditions. |
required |
Returns:
| Type | Description |
|---|---|
list[slice | ndarray]
|
One selector per condition: a |
Source code in parafac2/utils.py
extract_dataset_info(X_in, normalize_slices=False)
¶
Wrap an AnnData's matrix and summarize what the fit needs up front.
This is the boundary where a dataset stops being a specific storage type
and becomes an opaque duck-typed matrix: X_in.X is handed to
:func:~parafac2.matrix.as_matrix together with any per-gene means, and
everything downstream works through that object alone.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
X_in
|
AnnData
|
Input single-cell AnnData dataset. |
required |
normalize_slices
|
bool
|
Whether to calculate per-condition slice inverse-norm weights. |
False
|
Returns:
| Type | Description |
|---|---|
tuple[Any, ndarray, ndarray, float, ndarray | None, float | None]
|
The |
Source code in parafac2/utils.py
parafac_update(factors, mode, S, projections=None, *, X=None, cond_slices=None, slice_weights=None)
¶
Form the MTTKRP for the requested mode and update that factor.
Modes 0 and 1 are built from the compressed slices S alone and cost
O(n_cond * rank^2). Mode 2 is the only update that has to revisit the
raw data, via X^T @ H with H_k = P_k B diag(a_k).
slice_weights, if given, scales each condition's MTTKRP contribution,
so the update fits the weighted slices w_k X_k without copying X.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
factors
|
list[ndarray]
|
The current |
required |
mode
|
int
|
Which factor to update (index into |
required |
S
|
ndarray
|
The stacked compressed slices from :func: |
required |
projections
|
list[ndarray] | None
|
The per-condition projections. Required for |
None
|
X
|
(Any, keyword - only)
|
The raw data matrix. Required for |
None
|
cond_slices
|
(list[slice | ndarray] | None, keyword - only)
|
Per-condition row selectors from :func: |
None
|
slice_weights
|
(ndarray | None, keyword - only)
|
Optional per-condition scalar weights, as described above. |
None
|
Returns:
| Type | Description |
|---|---|
list[ndarray]
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Source code in parafac2/utils.py
238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 | |
polar_factor(M)
¶
Compute the nearest matrix with orthonormal columns to M.
Uses the thin SVD M = U S V^T, whose orthonormal factor U @ V^T
is the (Frobenius-norm) nearest matrix with orthonormal columns to M --
unlike a näive M @ V / diag(S) reconstruction, this stays exactly
orthonormal even when M is column-rank-deficient (some singular values
are zero), since LAPACK's SVD always returns a fully orthonormal U
regardless of M's rank, filling in arbitrary-but-orthonormal directions
for the zero-singular-value columns.
Raises:
| Type | Description |
|---|---|
ValueError
|
If M has fewer rows than columns: no matrix of that shape can have orthonormal columns (there is no room for that many independent unit vectors), so this is a genuine shape mismatch upstream (e.g. a PARAFAC2 condition with fewer cells than the fit rank) rather than something this function can paper over. |
Source code in parafac2/utils.py
project_data(W, factors, cond_slices)
¶
Compute each condition's projection matrix and compressed slice.
For condition k the projection P_k is the orthonormal polar
factor of W_k diag(a_k) B^T, and the compressed slice is
S_k = P_k^T W_k. Costs O(n_cells * rank^2) and touches no raw
data, so it is roughly two orders of magnitude cheaper than
:func:calc_W and can be repeated freely while W is cached.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
W
|
ndarray
|
The cached |
required |
factors
|
list[ndarray]
|
The current |
required |
cond_slices
|
list[slice | ndarray]
|
Per-condition row selectors from :func: |
required |
Returns:
| Type | Description |
|---|---|
tuple[list[ndarray], ndarray]
|
The per-condition projections |
Source code in parafac2/utils.py
randomized_svd_right(X, n_components, n_oversamples=0, n_power_iter=20, random_state=None, row_weights=None)
¶
Compute the top right-singular vectors of the mean-centered matrix (X - 1 mu^T).
The data is wrapped as a linear operator
(:func:~parafac2.matrix.as_linear_operator) and handed to
:func:scipy.sparse.linalg.lobpcg, which is run against the Gram
operator X^T X -- whose top eigenvectors are exactly the
right-singular vectors being sought -- from a random orthonormal start.
LOBPCG applies the operator to the whole block at once, so an iteration
costs one pass over the data in each direction, the same as a power
iteration, with a Rayleigh-Ritz step and a conjugate search direction on
top. Its Rayleigh-Ritz step is also why the starting subspace barely
matters: warm-starting it from a randomized decomposition was measured to
reach the same answer as a random start at the same iteration count,
while costing the decomposition on top.
Below 5 * n_components columns LOBPCG cannot run (it would fall back
to densifying the operator, which for a data matrix is the one thing this
may not do), so that case is solved exactly instead, via
:func:_exact_right_vectors.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
X
|
Any
|
The data matrix of shape |
required |
n_components
|
int
|
Number of right-singular vectors to return. |
required |
n_oversamples
|
int
|
Extra directions to carry through the refinement before truncating
to |
0
|
n_power_iter
|
int
|
Maximum number of LOBPCG iterations; it stops early once the subspace has converged. Must be at least 1: unlike a randomized decomposition, the starting subspace here carries no information of its own, so there is no meaningful zero-iteration answer. |
20
|
random_state
|
int | Generator | None
|
Random seed or NumPy generator for the starting subspace. |
None
|
row_weights
|
ndarray | None
|
Per-row weights |
None
|
Returns:
| Type | Description |
|---|---|
ndarray
|
Array of shape |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Source code in parafac2/utils.py
391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 | |
solve_factors(factors, mttkrp, mode)
¶
ALS factor update for a single mode using its precomputed MTTKRP.
Source code in parafac2/utils.py
standardize_pf2(factors, projections)
¶
Put a fitted PARAFAC2 model into a canonical, comparable form.
Reorders components by condition variance-to-mean ratio, normalizes and
sign-flips the factors (via TensorLy's cp_normalize/cp_flip_sign),
permutes components to maximize the diagonal of B (via linear-sum
assignment), and flips signs so that B's diagonal is non-negative.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
factors
|
list[ndarray]
|
The fitted |
required |
projections
|
list[ndarray]
|
The fitted per-condition projection matrices |
required |
Returns:
| Type | Description |
|---|---|
tuple[ndarray, list[ndarray], list[ndarray]]
|
The |
Source code in parafac2/utils.py
parafac2.backend¶
parafac2.backend
¶
Low-level device primitives for CPU, Apple GPU (MLX), and NVIDIA GPU (CuPy).
This module knows about devices, not about matrices: it resolves which backend to run on, accounts for device memory, and provides the transfer and kernel routines for dense and CSR operands on each backend. Nothing here inspects the type of the user's data.
The matrix types that consume these primitives -- and the duck-typed contract
the rest of the package talks to -- live in :mod:parafac2.matrix.
csr_device_bytes(mat_csr)
¶
Bytes a SciPy CSR array will occupy on a CuPy device.
cupyx stores indices and indptr in one shared index dtype, so
a nonzero count past the int32 limit widens both to 8 bytes per entry.
Source code in parafac2/backend.py
cupy_csr_matmul(device_mat, rhs, shape)
¶
Compute device_mat @ rhs (sparse CSR @ dense) via nvmath-python.
CuPy's own @ for a CSR-by-dense product prefers cuSPARSE's legacy
csrmm2 routine, which only understands 32-bit indices: it hands the
raw indices/indptr device pointers straight to that int32-only
API with no dtype check, so once a matrix has more than 2**31 - 1
nonzeros (and therefore int64 indices), the call reads those buffers as
the wrong width and silently corrupts the result. nvmath-python's
nvmath.sparse.matmul goes through cuSPARSE's generic SpMM API
instead, which is told the operands' actual index type
(CUSPARSE_INDEX_64I when needed), so it stays correct at any nnz.
Source code in parafac2/backend.py
cupy_csr_rmatmul(lhs, device_mat, shape)
¶
Compute lhs @ device_mat (dense @ sparse CSR) via nvmath-python.
nvmath's SpMM always takes the sparse operand first, so this computes
the equivalent (device_mat.T @ lhs.T).T using the is_transpose
matrix qualifier rather than materializing a transposed copy of
device_mat. See :func:cupy_csr_matmul for why cuSPARSE's legacy
routines (which CuPy's own @ would otherwise use here) are unsafe
for int64-indexed matrices.
Source code in parafac2/backend.py
cupy_dense_matmul(device_mat, rhs, shape)
¶
Compute device_mat @ rhs for a dense CuPy-resident matrix.
Dense products go through cuBLAS's plain @, which has no int32 index
limitation to work around.
Source code in parafac2/backend.py
cupy_dense_rmatmul(lhs, device_mat, shape)
¶
Compute lhs @ device_mat for a dense CuPy-resident matrix.
Source code in parafac2/backend.py
ensure_device_capacity(nbytes, what='matrix')
¶
Install the managed-memory allocator if nbytes will not fit.
Raises:
| Type | Description |
|---|---|
MemoryError
|
If the transfer does not fit and the device cannot oversubscribe, with
the sizes involved and a pointer at |
Source code in parafac2/backend.py
get_backend(backend=None)
¶
Return the requested backend, or auto-detect the first available one.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
backend
|
str
|
One of |
None
|
Returns:
| Type | Description |
|---|---|
str
|
The resolved backend name: |
Source code in parafac2/backend.py
mkl_dot()
¶
Return sparse_dot_mkl.dot_product_mkl if importable, else None.
SciPy's sparse-times-dense kernels are single-threaded, which dominates
the PARAFAC2 fit on large datasets. When the optional sparse-dot-mkl
package is installed (pip install 'parafac2[mkl]') its multithreaded
MKL kernels are used instead. The lookup is cached in the module-level
_MKL_DOT global.
Source code in parafac2/backend.py
mlx_csr_matmul(device_mat, rhs, shape)
¶
Compute device_mat @ rhs via the MLX CSR sparse-matmul kernel.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
device_mat
|
tuple[Any, Any, Any]
|
The |
required |
rhs
|
ndarray
|
The right-hand operand (1-D or 2-D NumPy array). |
required |
shape
|
tuple[int, int]
|
The logical |
required |
Source code in parafac2/backend.py
mlx_csr_rmatmul(lhs, device_mat, shape)
¶
Compute lhs @ device_mat via the atomic MLX CSR sparse-matmul kernel.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
lhs
|
ndarray
|
The left-hand operand (1-D or 2-D NumPy array). |
required |
device_mat
|
tuple[Any, Any, Any]
|
The |
required |
shape
|
tuple[int, int]
|
The logical |
required |
Source code in parafac2/backend.py
mlx_dense_matmul(device_mat, rhs, shape)
¶
Compute device_mat @ rhs for a dense MLX-resident matrix.
Source code in parafac2/backend.py
mlx_dense_rmatmul(lhs, device_mat, shape)
¶
Compute lhs @ device_mat for a dense MLX-resident matrix.
Source code in parafac2/backend.py
to_cupy_csr(mat_csr)
¶
Move a SciPy CSR array onto the CuPy device.
Switches to managed memory first when the matrix is larger than free device memory, so a dataset bigger than the card is paged rather than refused.
Source code in parafac2/backend.py
to_cupy_dense(mat)
¶
Move a dense matrix onto the CuPy device.
to_mlx_csr(mat_csr)
¶
Move a SciPy CSR array's components onto the MLX device.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mat_csr
|
csr_array
|
The sparse matrix to transfer. |
required |
Returns:
| Type | Description |
|---|---|
tuple[Any, Any, Any]
|
The |