plsdo 0.0.1__tar.gz

plsdo-0.0.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,48 @@
+name: Bug report
+description: Report something that is not working correctly
+labels: ["type: bug"]
+body:
+  - type: textarea
+    id: command
+    attributes:
+      label: Command run
+      description: The exact `plsdo` invocation, including all flags
+      placeholder: "plsdo run --method c --x X.csv --y Y.csv --demographics demo.csv --output results/"
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behaviour
+      description: What should have happened
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behaviour
+      description: What happened instead — include the full error message and traceback if applicable
+    validations:
+      required: true
+
+  - type: textarea
+    id: input
+    attributes:
+      label: Input description
+      description: >
+        Describe the shape and content of your input files (number of subjects, features, groups).
+        Do not attach real data — synthetic or anonymised descriptions are fine.
+      placeholder: "X: 42 subjects × 120 features, Y: 42 subjects × 8 scores, 3 groups"
+    validations:
+      required: false
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Python version, operating system, and plsdo version (found in `log.txt` under `version:`)
+      placeholder: "Python 3.11, macOS 14.4, plsdo 0.1.0"
+    validations:
+      required: true

plsdo-0.0.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

plsdo-0.0.1/.github/ISSUE_TEMPLATE/docs_issue.yml

@@ -0,0 +1,30 @@
+name: Documentation issue
+description: Report missing, incorrect, or unclear documentation — including missing references
+labels: ["type: docs"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: What is missing or incorrect
+      description: Describe the gap or error
+    validations:
+      required: true
+
+  - type: input
+    id: location
+    attributes:
+      label: Location
+      description: Which doc page, CLI help text, log output, or plot label is affected?
+      placeholder: "docs/interpreting-output.md, section on bootstrap ratios"
+    validations:
+      required: false
+
+  - type: textarea
+    id: reference
+    attributes:
+      label: Reference or source
+      description: >
+        Optional. Cite the paper, source, or example that should be referenced or used to correct the docs.
+      placeholder: "McIntosh & Lobaugh (2004), Partial least squares analysis of neuroimaging data, doi:10.1016/j.neuroimage.2004.07.020"
+    validations:
+      required: false

plsdo-0.0.1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,29 @@
+name: Feature request
+description: Propose a new capability or enhancement
+labels: ["type: feature"]
+body:
+  - type: textarea
+    id: motivation
+    attributes:
+      label: Use case and motivation
+      description: What problem does this solve, and for whom?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed behaviour
+      description: How should the feature work? Include proposed CLI flags, output changes, or API behaviour as applicable.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reference
+    attributes:
+      label: Literature reference
+      description: >
+        Optional. If the request relates to a specific PLS variant, statistical method, or published analysis,
+        cite the paper here (author, year, DOI or URL if available).
+    validations:
+      required: false

plsdo-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Install package and dev dependencies
+        run: uv pip install --system -e ".[dev]"
+
+      - name: Run tests
+        run: pytest -v
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Install ruff
+        run: uv pip install --system ruff
+
+      - name: Run ruff
+        run: ruff check plsdo/ tests/

plsdo-0.0.1/.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Virtual environments
+.venv/
+
+# IDE
+.idea/
+.vscode/
+
+# OS
+.DS_Store
+
+# uv
+uv.lock
+
+# Local dev / agentic reference files (not for distribution)
+.dev/

plsdo-0.0.1/CLAUDE.md

@@ -0,0 +1,68 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+# Install for development (from repo root, with .venv active)
+uv pip install -e ".[dev]"
+
+# Run all tests
+.venv/bin/pytest tests/
+
+# Run a single test file
+.venv/bin/pytest tests/test_core.py
+
+# Run a single test by name
+.venv/bin/pytest tests/test_core.py::TestBootstrap::test_seed_reproducibility
+```
+
+## Architecture
+
+The package has a strict separation of concerns across five modules:
+
+- **`io.py`** — everything that touches files or validates inputs: loading CSVs, detecting subject IDs, aligning subjects, checking missing values and variance, z-scoring, parsing YAML group configs, loading feature metadata, and building the dummy-coded design matrix.
+- **`core.py`** — the `PLS` class. Stateful: takes z-scored arrays, runs `fit()` → `permutation_test()` → `bootstrap()` → `filter_lvs()` in sequence. Stores results as instance attributes.
+- **`cross_validate.py`** — `run_cv()` and `permutation_test_cv()`. Uses `sklearn.PLSRegression` (not the SVD-based `PLS` class) because prediction requires `predict()`. Entirely independent of `core.py`.
+- **`plotting.py`** — stateless functions. All take data arrays and an `out_path`, save the figure, return nothing. `meta_colours()` is here too (not in pipeline).
+- **`pipeline.py`** — orchestration only. Calls `io` → `core` → `plotting` in sequence, writes CSVs and `log.txt`. No computation here.
+- **`cli.py`** — argument parsing and validation only. Dispatches to `pipeline.run_pipeline()` or `pipeline.cross_validate_pipeline()`.
+
+### Key design decisions
+
+**One SVD engine for both PLS variants.** Correlational PLS z-scores both X and Y; discriminatory PLS uses a dummy-coded X (not z-scored) and z-scores Y only. The `PLS` class handles both — `pipeline.py` builds the right inputs before calling it.
+
+**Bootstrap uses Procrustes + sign correction.** Each bootstrap SVD is aligned to the reference via `scipy.linalg.orthogonal_procrustes` on Vt, then signs are corrected by dot product with the reference Vt loadings. Both U and Vt loadings are aligned together.
+
+**LV filtering is two-stage.** `filter_lvs()` keeps LVs that are (1) significant by permutation (p < 0.05) and (2) have at least one feature with |bootstrap ratio| > 1.96 on *both* the X and Y sides. Result is a boolean `final_lvs` mask.
+
+**CV flips X and Y.** `cross_validate.py` uses Y (continuous data) as the predictor and dummy-coded groups as the target, so `pls.predict()` gives predicted group scores. This is the opposite convention from `plsdo run`.
+
+## Design philosophy
+
+Four principles, in priority order:
+
+1. **Mathematical validity** — correctness is non-negotiable.
+2. **Lightweight** — no unnecessary dependencies. Every dependency must earn its place.
+3. **Scientific Python standards** — follow community conventions so the package is citable, installable, and maintainable.
+4. **Glass-box and FAIR** — output everything needed to reproduce a result; keep the implementation transparent.
+
+Practical consequences: prefer stdlib over third-party where reasonable (argparse over click, logging over print). Do not add inference or statistical tests beyond PLS itself — plotting scores by group factors is in scope; pairwise post-hoc tests are not. When in doubt, do less.
+
+**Efficiency** is part of correctness. Prefer vectorised NumPy operations over Python loops wherever the maths permits — not for micro-optimisation, but because this code runs on HPCs and environmental cost is real. If a loop can be replaced by array operations without adding complexity or obscuring intent, replace it.
+
+**Robustness** sits inside principle 1, not alongside it. Validate aggressively anywhere a silent failure could propagate — at file boundaries and wherever mathematical assumptions could be violated (zero variance before z-scoring, empty group levels before dummy coding, etc.). Fail loudly with informative errors. Trust internal transformations between already-validated states; defensive checks between modules add noise without catching anything real.
+
+## Conventions
+
+- British English in all prose: docs, commit messages, user-facing strings, comments.
+- Commit messages use conventional prefixes: `feat`, `fix`, `enh`, `ref`, `test`, `docs`, `chore`. User commits with a GPG key — stage files and provide message text only, with attribution for claude, do not run `git commit`.
+- `plsdo/` contains no data. Test data lives in `tests/data/` (synthetic, small).
+- Reference notebooks (`.dev/correlational_pls.ipynb`, `.dev/discriminatory_pls.ipynb`, `.dev/claude_cross_validation.py`) are the source of truth for computational steps and plot styling. Deviations require discussion. These files are gitignored and live only in your local working copy.
+- `.dev/superpowers/specs/` and `.dev/superpowers/plans/` contain the design spec and implementation plan. Consult them before making structural changes. These files are gitignored.
+
+## Before public release / PyPI submission
+- Claim the `plsdo` package name on PyPI before announcing the package publicly — squatting is a real risk once there is any visibility.
+- Update `README.md` and `docs/usage.md` installation instructions from `git clone` to `pip install plsdo` once the package is published.
+- Bump version to `1.0.0` and update the `Development Status` classifier to `4 - Beta` or `5 - Production/Stable` as appropriate.

plsdo-0.0.1/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Eilidh MacNicol
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

plsdo-0.0.1/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: plsdo
+Version: 0.0.1
+Summary: PLS covariance analysis with statistical testing and visualisation
+Project-URL: Repository, https://github.com/braincentrekcl/plsdo
+Project-URL: Issues, https://github.com/braincentrekcl/plsdo/issues
+Author: Eilidh MacNicol
+Maintainer: Eilidh MacNicol
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: PLS,analysis,multivariate,statistics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: scipy>=1.10
+Requires-Dist: seaborn>=0.13
+Provides-Extra: cv
+Requires-Dist: scikit-learn>=1.2; extra == 'cv'
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: scikit-learn; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# plsdo
+
+Partial Least Squares (PLS) covariance analysis with permutation testing, bootstrap reliability, and publication-ready visualisation — from the command line.
+
+(Pronounced: "please do")
+
+`plsdo` was built out of necessity for project-specific neuroscience and neuroimaging pipelines, then generalised to handle flexible, diverse datasets beyond its origins. It implements two PLS variants used in neuroimaging and cognitive neuroscience research:
+
+- **Correlational PLS** — finds latent variables that maximise covariance between two continuous data matrices (e.g. brain measures and behaviour scores).
+- **Discriminatory PLS** — finds latent variables that maximise covariance between a continuous data matrix and a dummy-coded group matrix (i.e. group differences).
+
+Statistical validity is built in: every analysis runs a permutation test on singular values and bootstraps loading stability. Only latent variables that pass both tests appear in the output.
+
+> **Early alpha.** The API and output format may change before the first stable release. Feedback and bug reports are very welcome — please open an issue.
+
+---
+
+## Installation
+
+Requires Python ≥ 3.10.
+
+```bash
+git clone https://github.com/braincentrekcl/plsdo.git
+cd plsdo
+uv venv .venv && source .venv/bin/activate
+uv pip install -e .
+```
+
+For discriminatory PLS with cross-validation (requires scikit-learn):
+```bash
+uv pip install -e ".[cv]"
+```
+
+---
+
+## Quick start
+
+### Correlational PLS
+
+```bash
+plsdo run --method c \
+  --x brain_measures.csv \
+  --y behaviour_scores.csv \
+  --demographics participants.csv \
+  --group-col treatment \
+  --subject-id participant_id \
+  --output results/
+```
+
+### Discriminatory PLS
+
+```bash
+plsdo run --method d \
+  --y mri_features.csv \
+  --demographics participants.csv \
+  --group-col drug_group \
+  --subject-id participant_id \
+  --output results/
+```
+
+### Cross-validation (discriminatory only)
+
+Requires `plsdo[cv]` — see Installation above.
+
+```bash
+plsdo cross-validate \
+  --y mri_features.csv \
+  --demographics participants.csv \
+  --group-col drug_group \
+  --subject-id participant_id \
+  --output cv_results/
+```
+
+---
+
+## Output
+
+Each run writes to the output directory:
+
+```
+results/
+  figures/     cross-correlation heatmap, permutation test, loading bar plots, score plots
+  data/        singular values, p-values, loadings, bootstrap ratios, subject scores (CSV)
+  log.txt      parameters and version stamp
+```
+
+---
+
+## Documentation
+
+| Page | Contents |
+|------|----------|
+| [Usage guide](docs/usage.md) | Full CLI options, multiple grouping variables, all flags |
+| [Input format](docs/input-format.md) | How to structure X, Y, demographics, and metadata files |
+| [Interpreting output](docs/interpreting-output.md) | What each plot and CSV means |
+| [Missing data](docs/missing-data.md) | Why plsdo does not impute, and what to do instead |
+
+---
+
+## Contributing
+
+Issues and pull requests are welcome. Please open an issue before starting significant work.
+
+Contact: eilidh [dot] macnicol [at] kcl [dot] ac [dot] uk
+
+---
+
+## Licence
+
+BSD 3-Clause. See [LICENSE](LICENSE).

plsdo-0.0.1/README.md

@@ -0,0 +1,110 @@
+# plsdo
+
+Partial Least Squares (PLS) covariance analysis with permutation testing, bootstrap reliability, and publication-ready visualisation — from the command line.
+
+(Pronounced: "please do")
+
+`plsdo` was built out of necessity for project-specific neuroscience and neuroimaging pipelines, then generalised to handle flexible, diverse datasets beyond its origins. It implements two PLS variants used in neuroimaging and cognitive neuroscience research:
+
+- **Correlational PLS** — finds latent variables that maximise covariance between two continuous data matrices (e.g. brain measures and behaviour scores).
+- **Discriminatory PLS** — finds latent variables that maximise covariance between a continuous data matrix and a dummy-coded group matrix (i.e. group differences).
+
+Statistical validity is built in: every analysis runs a permutation test on singular values and bootstraps loading stability. Only latent variables that pass both tests appear in the output.
+
+> **Early alpha.** The API and output format may change before the first stable release. Feedback and bug reports are very welcome — please open an issue.
+
+---
+
+## Installation
+
+Requires Python ≥ 3.10.
+
+```bash
+git clone https://github.com/braincentrekcl/plsdo.git
+cd plsdo
+uv venv .venv && source .venv/bin/activate
+uv pip install -e .
+```
+
+For discriminatory PLS with cross-validation (requires scikit-learn):
+```bash
+uv pip install -e ".[cv]"
+```
+
+---
+
+## Quick start
+
+### Correlational PLS
+
+```bash
+plsdo run --method c \
+  --x brain_measures.csv \
+  --y behaviour_scores.csv \
+  --demographics participants.csv \
+  --group-col treatment \
+  --subject-id participant_id \
+  --output results/
+```
+
+### Discriminatory PLS
+
+```bash
+plsdo run --method d \
+  --y mri_features.csv \
+  --demographics participants.csv \
+  --group-col drug_group \
+  --subject-id participant_id \
+  --output results/
+```
+
+### Cross-validation (discriminatory only)
+
+Requires `plsdo[cv]` — see Installation above.
+
+```bash
+plsdo cross-validate \
+  --y mri_features.csv \
+  --demographics participants.csv \
+  --group-col drug_group \
+  --subject-id participant_id \
+  --output cv_results/
+```
+
+---
+
+## Output
+
+Each run writes to the output directory:
+
+```
+results/
+  figures/     cross-correlation heatmap, permutation test, loading bar plots, score plots
+  data/        singular values, p-values, loadings, bootstrap ratios, subject scores (CSV)
+  log.txt      parameters and version stamp
+```
+
+---
+
+## Documentation
+
+| Page | Contents |
+|------|----------|
+| [Usage guide](docs/usage.md) | Full CLI options, multiple grouping variables, all flags |
+| [Input format](docs/input-format.md) | How to structure X, Y, demographics, and metadata files |
+| [Interpreting output](docs/interpreting-output.md) | What each plot and CSV means |
+| [Missing data](docs/missing-data.md) | Why plsdo does not impute, and what to do instead |
+
+---
+
+## Contributing
+
+Issues and pull requests are welcome. Please open an issue before starting significant work.
+
+Contact: eilidh [dot] macnicol [at] kcl [dot] ac [dot] uk
+
+---
+
+## Licence
+
+BSD 3-Clause. See [LICENSE](LICENSE).

plsdo-0.0.1/docs/input-format.md

@@ -0,0 +1,60 @@
+# Input Format
+
+## Required Files
+
+### X Matrix (correlational PLS only)
+
+CSV with subjects as rows and features as columns. The first column must be
+the subject identifier.
+
+```csv
+subject_id,region_A,region_B,region_C
+sub01,1.23,4.56,7.89
+sub02,2.34,5.67,8.90
+```
+
+### Y Matrix
+
+Same format as X. Subject IDs must match across files (order does not matter
+— the pipeline will align them).
+
+### Demographics
+
+CSV with a subject ID column and at least one grouping column.
+
+```csv
+subject_id,group,sex,age
+sub01,control,F,25
+sub02,treatment,M,30
+```
+
+## Optional Files
+
+### Feature Metadata
+
+CSV with a `feature` column matching data column headers, plus category
+columns for plot colour-coding.
+
+```csv
+feature,category
+region_A,frontal
+region_B,frontal
+region_C,temporal
+```
+
+### Groups Configuration
+
+YAML file for multiple grouping variables. See `docs/usage.md` for examples.
+
+## Subject Alignment
+
+The pipeline finds the intersection of subject IDs across all input files.
+Subjects present in some files but not others are excluded with a warning.
+If no subjects are shared, the pipeline errors.
+
+## Missing Data
+
+The pipeline does **not** handle missing data. If any value in X or Y is
+NaN, the pipeline errors and lists which subjects and features are affected.
+
+See `docs/missing-data.md` for guidance on how to address this.

plsdo-0.0.1/docs/interpreting-output.md

@@ -0,0 +1,70 @@
+# Interpreting PLS Output
+
+## Cross-Correlation Heatmap
+
+This matrix shows the Pearson correlation between every feature in X and
+every feature in Y, computed across all subjects. It is the raw input to
+the SVD. Strong positive or negative values indicate features that co-vary
+across subjects.
+
+## Singular Values and Permutation Test
+
+The SVD breaks the cross-correlation matrix into latent variables (LVs),
+ordered by how much covariance they explain. The singular value for each LV
+quantifies its strength.
+
+The permutation test asks: is this singular value larger than we would expect
+if X and Y were unrelated? It shuffles the subject pairing between X and Y
+10,000 times and compares the observed singular value to this null
+distribution.
+
+**How to read the plot:** A red line to the right of the grey histogram
+indicates a singular value that exceeds the null distribution — that LV
+captures real covariance, not noise.
+
+## Loading Bar Plots
+
+For each significant and reliable LV, the loading plots show which features
+contribute most to the pattern. Bars are sorted by absolute loading. The
+red error bars show the bootstrap standard error — they indicate how stable
+each loading is across resampled versions of the data.
+
+**Large bars with small error bars** are the features driving the pattern
+reliably. **Large bars with large error bars** may be driven by a few
+outlier subjects.
+
+## Bootstrap Ratios
+
+The bootstrap ratio is the loading divided by its standard error. It can be
+interpreted like a z-score: values above 1.96 indicate that a feature's
+contribution is reliable at the 95% confidence level.
+
+## Subject Scores
+
+Subject scores show how strongly each subject expresses a given LV pattern.
+The X scores (XU) project each subject onto the X-side pattern; the Y
+scores (YV') project onto the Y-side pattern.
+
+**Box/strip plots** show how scores distribute across groups. If a LV
+captures a group difference, the boxes will separate.
+
+**Score scatter plots** (correlational PLS only) show the relationship
+between X and Y scores. If the PLS pattern is strong, subjects should fall
+along a diagonal. Group-specific linear fits reveal whether the X–Y
+relationship differs by group.
+
+## Cross-Validation (Discriminatory PLS)
+
+Cross-validation tests whether the group discrimination holds on unseen
+subjects. The fold accuracy histogram shows per-fold classification
+accuracy, while the confusion matrix shows which groups are well-separated
+and which are confused.
+
+The permutation test of CV accuracy answers: is the observed accuracy
+significantly better than chance? A p-value below 0.05 indicates that
+the model generalises beyond the training data.
+
+**Important:** do not select the number of components based on `plsdo run`
+results and then feed that into cross-validation. This introduces
+circularity. Use all components (the default) or use nested
+cross-validation.