Skip to content

Commit 32a61c1

Browse files
committed
Merge remote-tracking branch 'origin/main' into tucker-rank-fix
2 parents dd7736b + dc312d3 commit 32a61c1

10 files changed

Lines changed: 146 additions & 159 deletions

File tree

‎.github/workflows/pytest.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,5 +11,9 @@ jobs:
1111
uses: astral-sh/setup-uv@v10.0.1
1212
- name: Install dependencies
1313
run: uv sync
14+
- name: Run ty check
15+
run: make ty
16+
- name: Run vulture
17+
run: make vulture
1418
- name: Test with pytest
1519
run: make test

‎README.md‎

Lines changed: 80 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,84 @@
11
# tensorpack
2-
A collection of tensor methods from the Meyer lab.
32

4-
To add it to your Python package, add the following line to `requirements.txt` and remake `venv`:
3+
A collection of tensor decomposition methods from the [Meyer lab](https://meyerlab.org), built on [TensorLy](https://tensorly.org) and [xarray](https://xarray.dev). It is aimed at biological data sets that are naturally multi-dimensional (for example subjects × antigens × measurements) and are often incomplete or paired with additional matrices.
4+
5+
## Features
6+
7+
- **CP decomposition with missing data** (`perform_CP`): CANDECOMP/PARAFAC fit by alternating least squares that ignores `NaN` entries instead of requiring imputation.
8+
- **Coupled matrix–tensor factorization** (`perform_CMTF`): jointly factors a tensor and a matrix that share their first mode.
9+
- **Coupled tensor factorization of xarray datasets** (`CoupledTensor`): factors any number of arrays that share named dimensions, with optional non-negativity.
10+
- **Tucker decomposition** (`tucker_decomp`) and a `Decomposition` helper that scans component counts and reports variance explained (R2X) and cross-validated, missing-value-based prediction accuracy (Q2X).
11+
- **Imputation and masking utilities**: an iterative-SVD imputer (`IterativeSVD`) and functions to hold out entries or chords for cross-validation (`tensorpack.impute`).
12+
- **Plotting helpers** for R2X curves and factor heatmaps (`tensorpack.plot`, `tensorpack.xplots`).
13+
14+
## Installation
15+
16+
tensorpack requires Python 3.11 or 3.12. To use it in another project, add it from GitHub:
17+
18+
```bash
19+
uv add git+https://github.com/meyer-lab/tensorpack.git@main
20+
# or, with pip
21+
pip install git+https://github.com/meyer-lab/tensorpack.git@main
522
```
6-
git+https://github.com/meyer-lab/tensorpack.git@main
23+
24+
## Quick start
25+
26+
### CP decomposition of a tensor with missing values
27+
28+
```python
29+
import numpy as np
30+
from tensorpack import perform_CP
31+
32+
rng = np.random.default_rng(0)
33+
tensor = rng.gamma(2, 2, (10, 20, 25))
34+
tensor[rng.random(tensor.shape) < 0.2] = np.nan # 20% missing
35+
36+
cp = perform_CP(tensor, r=3)
37+
cp.R2X # fraction of variance explained
38+
cp.factors # one (size × 3) factor matrix per mode
39+
cp.weights # per-component weights
740
```
41+
42+
### Coupled matrix–tensor factorization
43+
44+
```python
45+
from tensorpack import perform_CMTF
46+
47+
matrix = rng.gamma(2, 2, (10, 15)) # shares its first mode with `tensor`
48+
cmtf = perform_CMTF(tensor, matrix, r=3)
49+
cmtf.factors # tensor factors; factors[0] is shared with the matrix
50+
cmtf.mFactor # factor for the matrix's second mode
51+
```
52+
53+
### Coupled factorization of several xarray arrays
54+
55+
```python
56+
import xarray as xr
57+
from tensorpack import CoupledTensor
58+
59+
data = xr.Dataset(
60+
{
61+
"x": (["a", "b", "c"], rng.random((8, 6, 5))),
62+
"y": (["a", "d"], rng.random((8, 4))),
63+
}
64+
) # dimension "a" is shared
65+
66+
ct = CoupledTensor(data, rank=3)
67+
ct.initialize("svd") # or "nmf" (with fit(nonneg=True)) / "randomized_svd"
68+
ct.fit()
69+
ct.R2X(), ct.R2X("x") # overall and per-array variance explained
70+
```
71+
72+
## Development
73+
74+
The project is managed with [uv](https://docs.astral.sh/uv/).
75+
76+
```bash
77+
uv sync # create the environment
78+
make test # run the test suite
79+
make coverage.xml # tests with coverage
80+
```
81+
82+
## License
83+
84+
MIT. See [LICENSE](LICENSE).

‎makefile‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,18 @@
1-
.PHONY: clean test
1+
.PHONY: clean test ty vulture
22

33
all: test
44

55
test:
66
uv run pytest -s -v -x
77

8+
ty:
9+
uv run ty check
10+
811
coverage.xml:
912
uv run pytest --junitxml=junit.xml --cov=tensorpack --cov-report xml:coverage.xml
1013

1114
clean:
1215
rm -rf coverage.xml
16+
17+
vulture:
18+
uv run vulture

‎pyproject.toml‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,6 @@ dependencies = [
1111
"matplotlib>=3.5.0",
1212
"tqdm>=4.62.3",
1313
"seaborn>=0.11.2",
14-
"drawsvg>=2.4",
1514
"xarray>=2024",
1615
"scikit-learn>=1.1.2",
1716
]
@@ -21,8 +20,9 @@ dev = [
2120
"pytest>=7.0",
2221
"pytest-cov>=3.0.0",
2322
"tensordata",
24-
"pyright>=1.1.379",
23+
"ty>=0.0.1",
2524
"ruff>=0.6.4",
25+
"vulture>=2.16",
2626
]
2727

2828
[tool.uv.sources]
@@ -36,3 +36,12 @@ build-backend = "hatchling.build"
3636

3737
[tool.hatch.build.targets.wheel]
3838
packages = ["tensorpack"]
39+
40+
[tool.ty.src]
41+
include = ["tensorpack"]
42+
43+
[tool.vulture]
44+
paths = ["tensorpack"]
45+
# Everything below 80% is public library API (methods, plotting helpers) that
46+
# has no in-repo callers by design; 80%+ catches unused imports and variables.
47+
min_confidence = 80

‎tensorpack/cmtf.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
import numpy as np
66
from tensorly.tenalg import svd_interface
77
import tensorly as tl
8-
from tensorly.tenalg import khatri_rao
8+
from tensorly.tenalg import khatri_rao # ty: ignore[unresolved-import] # backend-dispatched at runtime
99
from copy import deepcopy
1010
from tensorly.decomposition._cp import initialize_cp
1111
from tqdm import tqdm

‎tensorpack/coupled.py‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
from numpy.linalg import norm
88
from tqdm import tqdm
99
from .SVD_impute import IterativeSVD
10+
from tensorly.tenalg import khatri_rao # ty: ignore[unresolved-import] # backend-dispatched at runtime
1011
from .linalg import mlstsq, calcR2X_TnB
1112
from sklearn.decomposition import NMF
1213
from sklearn.utils.extmath import randomized_svd
@@ -35,8 +36,8 @@ def __init__(self, data: xr.Dataset, rank):
3536

3637
self.data = data
3738
self.rank = rank
38-
self.dvars = list(self.data.data_vars)
39-
self.modes = list(self.data.dims)
39+
self.dvars = [str(v) for v in self.data.data_vars]
40+
self.modes = [str(d) for d in self.data.dims]
4041

4142
ncoords = {}
4243
ndata = {}
@@ -181,7 +182,8 @@ def khatri_rao(self, mode: str):
181182
raise ValueError(f"khatri_rao(): {mode} is not in a mode in this dataset.")
182183
arrs = [] # save kr-ed arrays
183184
for dvar in self.mode_to_dvar[mode]:
184-
recon = tl.tenalg.khatri_rao([self.x["_"+mmode].to_numpy() for mmode in self.dims[dvar] if mmode != mode])
185+
recon = khatri_rao(
186+
[self.x["_"+mmode].to_numpy() for mmode in self.dims[dvar] if mmode != mode])
185187
arrs.append(recon * self.x["_Weight_"].loc[dvar].to_numpy()) # put weights back to kr
186188
concat = np.concatenate(arrs, axis=0)
187189
if np.sum(np.isnan(concat)) > 0:
@@ -284,7 +286,7 @@ def plot_factors(self, dvar=None, reorder=[], sort_comps=True):
284286
ttdim = dat.ndim
285287
assert len(factors) == ttdim
286288
for m in range(ttdim):
287-
no_include = np.all(np.isnan(dat), axis=tuple(np.delete(np.arange(ttdim), m)))
289+
no_include = np.all(np.isnan(dat.to_numpy()), axis=tuple(int(i) for i in np.delete(np.arange(ttdim), m)))
288290
for (ii, val) in enumerate(no_include):
289291
if val:
290292
factors[m].index.values[ii] = f"({factors[m].index.values[ii]})*"

‎tensorpack/decomposition.py‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
from typing import Any, Callable
2+
13
import pickle
24
import numpy as np
35
from .cmtf import perform_CP, calcR2X
@@ -23,7 +25,7 @@ def __init__(self, data, matrix=[0], max_rr=5, method=perform_CP):
2325
other methods include: tucker_decomp
2426
"""
2527
self.data = data
26-
self.method = method
28+
self.method: Callable[..., Any] = method
2729
self.rrs = np.arange(1,max_rr+1)
2830
self.hasMatrix = False
2931
if isinstance(matrix, np.ndarray):

‎tensorpack/plot.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ def tfacr2x(ax, decomp: Decomposition):
1616
Parameters
1717
----------
1818
ax : axis object
19-
Plot information for a subplot of figure f. See getSetup() in tensorpack.test.common.py for more detail.
19+
Plot information for a subplot of figure f.
2020
decomp : Decomposition
2121
Takes a Decomposition object that has successfully run decomp.perform_tfac().
2222
"""

‎tensorpack/test/common.py‎

Lines changed: 0 additions & 107 deletions
This file was deleted.

0 commit comments

Comments
 (0)