Skip to content

Commit 1eddba9

Browse files
authored
Merge branch 'main' into ty-typing
2 parents 3d590b4 + 6cd4cfc commit 1eddba9

7 files changed

Lines changed: 105 additions & 124 deletions

File tree

‎.github/workflows/pytest.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,5 +13,7 @@ jobs:
1313
run: uv sync
1414
- name: Run ty check
1515
run: make ty
16+
- name: Run vulture
17+
run: make vulture
1618
- name: Test with pytest
1719
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: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
.PHONY: clean test ty
1+
.PHONY: clean test ty vulture
22

33
all: test
44

@@ -13,3 +13,6 @@ coverage.xml:
1313

1414
clean:
1515
rm -rf coverage.xml
16+
17+
vulture:
18+
uv run vulture

‎pyproject.toml‎

Lines changed: 7 additions & 1 deletion
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
]
@@ -23,6 +22,7 @@ dev = [
2322
"tensordata",
2423
"ty>=0.0.1",
2524
"ruff>=0.6.4",
25+
"vulture>=2.16",
2626
]
2727

2828
[tool.uv.sources]
@@ -39,3 +39,9 @@ packages = ["tensorpack"]
3939

4040
[tool.ty.src]
4141
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/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.

‎uv.lock‎

Lines changed: 11 additions & 11 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)