|
1 | 1 | # tensorpack |
2 | | -A collection of tensor methods from the Meyer lab. |
3 | 2 |
|
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 |
5 | 22 | ``` |
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 |
7 | 40 | ``` |
| 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). |
0 commit comments