Updates#8
Open
AdrianCurtin wants to merge 4 commits into
Open
Conversation
Introduce an authoritative test-suite builder plus `runCI` so headless, UI, clean-process, and quick lanes can be gated correctly, including incomplete-test failures. Add a manual GitHub Actions workflow for the quick lane. Also add shipped Takizawa oxy seed methods, update examples/docs to use `OD_TDDR` and the public `pf2.ProcessingContext`, and document how to drive processFNIRS2 through the MATLAB MCP Server.
Introduces a new `+pf2_base/+identity` package with deterministic canonical encoding, domain-separated hashing, JSON transport encode/decode, source/imported fingerprinting, and fail-closed expected-digest verification, plus preflight import gating around importers. Adds comprehensive identity-focused unit tests/fixtures and wires them into a dedicated `identity` test lane in `buildSuite`, `runCI`, and GitHub Actions (including cross-platform/release matrix jobs). Also removes the public `pf2.ProcessingContext.fromRecipe` path and related examples/tests, keeping context struct round-trip coverage in the base class tests, updates `processFNIRS2` function signature metadata to require `pf2.ProcessingContext`, and refreshes docs wording to clarify `pf2_base` as an advanced+internal package.
There was a problem hiding this comment.
Pull request overview
This PR updates processFNIRS2 to the 1.0.1 release, expanding the testing/CI story (lane-based gating and durable semantic-identity contracts), adding MCP guidance for agent-driven MATLAB sessions, and refreshing docs/examples to match updated method registries.
Changes:
- Version/release metadata bumped to 1.0.1 across README/CITATION/changelog and
pf2_base.pf2version. - Added lane-based test orchestration (
buildSuite,runCI) plus a new semantic-identity subsystem (+pf2_base/+identity/*) with extensive unit tests. - Added/updated method seed factories (new oxy seeds
HPF,BPF,takizawa_*; new raw seedOD_SMAR; removedOD_TDDR_lpf) and updated documentation/examples accordingly.
Reviewed changes
Copilot reviewed 59 out of 64 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/golden/README.md | Adds documentation for golden-file regression testing workflow. |
| README.md | Updates version badge/citation and refreshes usage examples (methods + pf2.ProcessingContext). |
| mcp/TOOL_CARD.md | Adds MCP session operational guidance for headless MATLAB usage and pf2 idioms. |
| mcp/README.md | Documents how to configure MATLAB MCP server across common clients. |
| functionSignatures.json | Updates processFNIRS2 signature metadata for public pf2.ProcessingContext. |
| examples/scripts/tutorial_end_to_end.m | Updates raw method example naming. |
| docs/USAGE_EXAMPLES.md | Refreshes examples for new method names and pf2.ProcessingContext usage. |
| docs/PROCESSING_PIPELINE.md | Refreshes method reference tables and recommendations (needs corrections per review). |
| docs/CLI_UX_GUIDE.md | Updates CLI UX documentation and examples (needs corrections per review). |
| docs/ARCHITECTURE.md | Clarifies positioning of +pf2_base as advanced/internal. |
| docs/API_REFERENCE.md | Updates API reference headings/description for +pf2_base. |
| CONTRIBUTING.md | Updates test-running guidance and introduces runCI lanes. |
| CITATION.cff | Updates version and release date to 1.0.1 / 2026-07-14. |
| CHANGELOG.md | Notes new oxy seeds and toolbox-free signal-processing additions. |
| +pf2/ProcessingContext.m | Updates docs/examples and removes the fromRecipe helper from the public context class. |
| +pf2/+process/processRaw.m | Updates method example naming. |
| +pf2/+methods/Editor.m | Updates seed-install confirmation text to reflect current raw seed set. |
| +pf2/+methods/+seeds/+raw/OD_TDDR.m | Updates “See also” after raw seed set change. |
| +pf2/+methods/+seeds/+raw/OD_TDDR_lpf.m | Removes the old OD_TDDR_lpf raw seed factory. |
| +pf2/+methods/+seeds/+raw/OD_SMAR.m | Adds new raw seed factory for SMAR motion rejection on OD. |
| +pf2/+methods/+seeds/+oxy/HPF.m | Adds new oxy seed factory for 0.01 Hz HPF. |
| +pf2/+methods/+seeds/+oxy/BPF.m | Adds new oxy seed factory for 0.01–0.1 Hz BPF. |
| +pf2/+methods/+seeds/+oxy/takizawa_easy.m | Adds new lenient Takizawa rejection oxy seed. |
| +pf2/+methods/+seeds/+oxy/takizawa_hard.m | Adds new strict Takizawa rejection oxy seed. |
| +pf2/+methods/+raw/setMethod.m | Updates raw-method example naming. |
| +pf2/+methods/+raw/describeMethod.m | Updates raw-method example naming. |
| +pf2_base/RawPipeline.m | Updates documentation example naming. |
| +pf2_base/ProcessingContext.m | Updates documentation example naming. |
| +pf2_base/Pipeline.m | Updates documentation example naming. |
| +pf2_base/pf2version.m | Updates internal version/date strings to v1.0.1 / July 14 2026. |
| +pf2_base/+tests/runQuickTests.m | Makes quick tests gateable (returns ok, errors when failures and no output captured). |
| +pf2_base/+tests/runCI.m | Adds a lane-based CI gate that fails on Failed or Incomplete tests. |
| +pf2_base/+tests/runAllTests.m | Rebuilds suite via buildSuite('full') and points users to runCI for gating. |
| +pf2_base/+tests/generateGoldenFiles.m | Removes temp-method creation; uses the registered OD_TDDR method name. |
| +pf2_base/+tests/buildSuite.m | Adds authoritative suite discovery and lane filtering registries. |
| +pf2_base/+tests/+unit/SourceFingerprintTest.m | Adds contract tests for exact source-byte identity and manifest semantics. |
| +pf2_base/+tests/+unit/PublicProcessingContextTest.m | Removes recipe round-trip tests; keeps public-context contracts. |
| +pf2_base/+tests/+unit/InputIdentityPreflightTest.m | Adds fail-closed import preflight identity tests. |
| +pf2_base/+tests/+unit/IdentityTransportRoundtripTest.m | Adds JSON/MAT transport proof tests for canonical value language. |
| +pf2_base/+tests/+unit/IdentityNamedHashTest.m | Adds contract tests for SHA-256/named hash domains and wire format. |
| +pf2_base/+tests/+unit/IdentityCanonicalEncodingTest.m | Adds contract tests for canonical semantic encoding. |
| +pf2_base/+tests/+unit/CharacterizationTest.m | Updates characterization matrix to remove OD_TDDR_lpf dependency. |
| +pf2_base/+tests/+integration/PipelineEditorWorkflowTest.m | Updates seed expectations (raw now includes OD_SMAR instead of OD_TDDR_lpf). |
| +pf2_base/+tests/+fixtures/identityRecipeSpike.m | Adds a representative identity fixture for transport/hash tests. |
| +pf2_base/+tests/+fixtures/IdentityImportSpy.m | Adds a spy fixture for preflight gating tests. |
| +pf2_base/+identity/verifyExpected.m | Adds fail-closed expected-vs-observed identity enforcement. |
| +pf2_base/+identity/sourceFingerprint.m | Adds portable multi-file source manifest fingerprinting. |
| +pf2_base/+identity/sha256File.m | Adds chunked file hashing with stable error identifiers. |
| +pf2_base/+identity/sha256Bytes.m | Adds byte hashing helper with strict input validation. |
| +pf2_base/+identity/preflightImport.m | Adds import preflight gate: source → importer → source stability → imported identity. |
| +pf2_base/+identity/normalizeText.m | Adds Unicode NFC + UTF-8 normalization with invalid UTF-16 rejection. |
| +pf2_base/+identity/importedContentFingerprint.m | Adds imported-content fingerprinting via domain-separated projection hashing. |
| +pf2_base/+identity/hashProjection.m | Adds domain-separated hashing of canonical values. |
| +pf2_base/+identity/encodeJsonTransport.m | Adds a lossless tagged JSON transport for canonical value language. |
| +pf2_base/+identity/decodeJsonTransport.m | Adds strict decoder for the tagged JSON transport format. |
| +pf2_base/+identity/canonicalBytes.m | Adds deterministic canonical semantic encoding for supported MATLAB value types. |
| +pf2_base/+identity/Contents.m | Adds package Contents for identity primitives. |
| +exploreFNIRS/processMethods.m | Updates example method naming. |
| .gitignore | Ensures new markdown docs under mcp/ and golden README are not ignored. |
| .github/workflows/tests.yml | Adds manual workflow_dispatch MATLAB test workflow (quick + identity lanes). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
43
to
47
| % Load → Configure → Process → Visualize → Export | ||
| data = pf2.import.importNIR('subject01.nir'); | ||
| pf2.methods.raw.setMethod('x2_lpf_smar'); % Motion correction + filtering | ||
| pf2.methods.raw.setMethod('OD_TDDR_BPF'); % Motion correction + filtering | ||
| processed = processFNIRS2(data); | ||
| pf2.data.plot.oxy(processed); % Time series plot |
Comment on lines
457
to
468
| @@ -464,7 +464,7 @@ pf2.methods.oxy.setMethod(2) | |||
| pf2.methods.oxy.setMethod() | |||
|
|
|||
| % Method information | |||
| pf2.methods.raw.describeMethod('x2_lpf_smar') | |||
| pf2.methods.raw.describeMethod('OD_TDDR_BPF') | |||
| pf2.methods.oxy.describeMethod('takizawa_easy') | |||
Comment on lines
+104
to
+120
| Methods for Stage 1 processing (Raw → Optical Density). Each `OD_` method first | ||
| converts raw intensity to optical density, then applies the named motion | ||
| correction and/or filtering. Run `pf2.methods.raw.list()` for the authoritative | ||
| live set (a few internal test/demo methods are omitted here). | ||
|
|
||
| | Method | Pipeline | | ||
| |--------|----------| | ||
| | `None` | Optical-density conversion only (no motion/filter step) | | ||
| | `OD_TDDR` | TDDR motion correction | | ||
| | `OD_TDDR_BPF` | TDDR motion correction + band-pass filter | | ||
| | `OD_SMAR` | SMAR sliding-window motion artifact rejection | | ||
| | `OD_Spline` | Spline-interpolation motion correction | | ||
| | `OD_Spline_BPF` | Spline motion correction + band-pass filter | | ||
| | `OD_SplineSG_BPF` | Spline + Savitzky-Golay motion correction + band-pass filter | | ||
| | `OD_Spline_Wavelet` | Spline + wavelet motion correction | | ||
| | `OD_Wavelet_BPF` | Wavelet motion correction + band-pass filter | | ||
| | `OD_sSMART` | sSMART motion correction | |
Comment on lines
232
to
236
| **For motion-prone data (head movement):** | ||
| ```matlab | ||
| % Raw stage: Motion correction + filtering | ||
| pf2.methods.raw.setMethod('x2_lpf_smar'); % LPF + SMAR | ||
| pf2.methods.raw.setMethod('OD_TDDR_BPF'); % TDDR + band-pass filter | ||
| % or |
Separate negative zero from the non-finite JSON transport test and add explicit coverage that it round-trips canonically as +0 through default JSON encoding. Also fix `getTakizawaRejection` to use the first FFT bin above 1 Hz as a scalar index instead of the full index vector.
Add proper references to the sSMART function header (Curtin & Ayaz 2019 for sSMART; Ayaz et al. 2010 for the SMAR detection stage). Expand the Notes section with a detailed explanation of the DC-offset correction (ShiftCorrect) and its caveats. Update pf2_functions_default.cfg: correct the Arguments list to match actual function signature, add Role='motion', fix default parameter values, and add full type/range/description metadata for all parameters.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.