rapidtide 3.0.10__tar.gz → 3.1__tar.gz

{rapidtide-3.0.10 → rapidtide-3.1}/CHANGELOG.md

@@ -1,7 +1,29 @@
 # Release history
 
+## Version 3.1 (11/8/25)
+* (happy) Moved to a pytorch implementation of the deep learning filter, as tensorflow seems to be barely maintained these days.  The pytorch filter is now the default, and performance seems indistinguishable.  I'll keep the tensorflow version around until it becomes (more) cumbersome to do so.  Use ``--usetensorflow`` to get the old filter.
+* (happy) Added "pulsatility" map output - the percentage pulsatile cardiac variation around the mean in each voxel.
+* (happy) Made pass labelling consistent for output files.
+* (happy) Switched nifti file output to use maplist (jsons have description fields now).
+* (rapidtide) Output some timecourse statistics before and after sLFO regression.
+* (atlasaverage) Fixed label output when extracting data from 3D files.
+* (package) Added type hints to all core routines (thanks Claude!).  Everything works, but I'll probably be finetuning the type hints for a while to make them more specific (and I'll be resolving sloppy type handling that I'm now aware of due to mypy).
+* (package) Added docstrings to all core routines (thanks script I wrote that calls qwen3-coder locally so I don't run out of Claude tokens!).
+* (package) Added support for python 3.13 (now that tensorflow is FINALLY available for 3.13).
+* (package) Dropped support for python 3.9 (it doesn't support modern type hint formats).
+* (package) More dependabot PRs.
+
+## Version 3.0.11 (8/27/25)
+* (Docker) Fixed a critical bug in building the container.
+* (happy) Added the ability to specify an overall processing mask.
+* (docs) Revised the singularity/apptainer installation section.
+* (reference) Added MNI152NLin2009cAsym versions of the JHU atlases.
+* (package) Miscellaneous code cleanups.
+* (package) More dependabot PRs.
+
 ## Version 3.0.10 (8/18/25)
 * (tidepool) Do better checking on which required files exist so it's more clear why a dataset won't load.
+* (tidepool) Add support for PySide6 (in addition to PyQt5 and PyQt6).
 * (docs) Clarified that the sLFO filtered output of rapidtide has NO other filtering applied to is - the temporal, spatial, and confound filtering is all discarded prior to the final sLFO filtering step.
 * (package) Played with some coding models (qwen3-coder, Claude) to write some docstrings and check a few routines for bugs.  It generally worked well, but you definitely have to check their work.
 * (package) Adjusted coverage calculation.

rapidtide-3.1/CLAUDE.md

@@ -0,0 +1,191 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Rapidtide is a Python package for modeling, characterizing, visualizing, and removing time-varying physiological blood signals from fMRI and fNIRS datasets. The package has two primary workhorses:
+
+- **rapidtide**: Characterizes bulk blood flow through time delay analysis on functional imaging data, finding time-lagged correlations between voxelwise time series in the low-frequency oscillation (LFO) band
+- **happy**: Extracts and analyzes cardiac signals from fMRI data using hypersampling techniques, even when TR is too long to properly sample cardiac waveforms
+
+## Architecture
+
+### Code Organization
+
+```
+rapidtide/
+├── scripts/          # Command-line entry points (~65 utilities)
+├── workflows/        # Main processing pipelines (rapidtide, happy, and various utilities)
+├── tests/            # Pytest test suite (~44 test files)
+├── candidatetests/   # Work-in-progress tests (not run in CI)
+├── data/             # Reference data, models, and examples
+└── [modules]         # Core processing modules (see below)
+```
+
+### Key Modules
+
+- **io.py**: NIFTI/text file I/O operations
+- **filter.py**: Signal filtering and preprocessing
+- **correlate.py**: Cross-correlation and time-lag analysis
+- **fit.py**: Peak fitting and parameter estimation
+- **resample.py**: Time series resampling utilities
+- **stats.py**: Statistical analysis functions
+- **multiproc.py**: Parallel processing infrastructure
+- **happy_supportfuncs.py**: Cardiac signal processing for happy workflow
+- **dlfilter.py / dlfiltertorch.py**: Deep learning filters for signal cleaning
+- **RapidtideDataset.py**: Dataset class for tidepool GUI
+- **OrthoImageItem.py**: Orthogonal image display for tidepool GUI
+
+### Script/Workflow Architecture
+
+All command-line tools follow a consistent pattern:
+1. `rapidtide/scripts/<name>.py` - Minimal entry point that imports from workflows
+2. `rapidtide/workflows/<name>.py` - Main processing logic
+3. `rapidtide/workflows/<name>_parser.py` - Argument parsing (for complex tools)
+
+Entry points are registered in `pyproject.toml` under `[project.scripts]`.
+
+### Main Workflows
+
+**rapidtide workflow** (`rapidtide/workflows/rapidtide.py`):
+- Performs voxel-wise time delay analysis on fMRI data
+- Generates multiple 3D NIFTI maps (lag time, correlation values, masks, etc.)
+- Outputs text files with significance thresholds and processing parameters
+
+**happy workflow** (`rapidtide/workflows/happy.py`):
+- Extracts cardiac waveforms from fMRI using slice-selective averaging
+- Cleans estimates using deep learning filters
+- Constructs cardiac pulsation maps over a single cardiac cycle
+
+## Development Commands
+
+### Setup and Installation
+
+```bash
+# Install package in development mode with all dependencies
+pip install -e .[tests,doc]
+
+# Or for all optional dependencies
+pip install -e .[all]
+```
+
+### Testing
+
+```bash
+# Run full test suite
+pytest rapidtide/tests/
+
+# Run specific test file
+pytest rapidtide/tests/test_filter.py
+
+# Run with coverage
+pytest --cov=rapidtide rapidtide/tests/
+
+# Run specific test function
+pytest rapidtide/tests/test_filter.py::test_function_name -v
+```
+
+Note: Tests are run in CI via CircleCI for Python 3.9, 3.10, 3.11, and 3.12.
+
+### Code Formatting
+
+```bash
+# Format code with black (line length: 99)
+black rapidtide/
+
+# Check specific file
+black --check rapidtide/filter.py
+```
+
+Black configuration in `pyproject.toml`:
+- Line length: 99
+- Target: Python 3.9+
+- Excludes: versioneer files, candidatetests, disabledtests, data/examples
+
+### Building and Distribution
+
+```bash
+# Build package
+python -m build
+
+# Install locally
+pip install .
+
+# Build Docker container
+./builddocker.sh
+
+# Test Docker container
+./testdocker.sh
+```
+
+### Running Main Tools
+
+```bash
+# Run rapidtide analysis
+rapidtide <input_4d_nifti> <output_root> [options]
+
+# Run happy analysis
+happy <input_4d_nifti> <output_root> [options]
+
+# View results in GUI
+tidepool  # Then select a lag time map file
+
+# Quick timecourse visualization
+showtc <textfile>
+
+# Cross-correlation between two timecourses
+showxcorrx <file1> <file2>
+```
+
+## Important Constraints
+
+### Python Version
+- **Minimum**: Python 3.9
+- **Maximum**: Python 3.12 (tensorflow limitation)
+- Uses modern Python features (f-strings, type hints)
+
+### Data Formats
+- Input: 4D NIFTI files for fMRI data
+- Output: 3D NIFTI maps, text files with timecourses/parameters
+- Timecourses: Whitespace-separated text files
+
+### FSL Dependency
+Some tools (rapidtide2std, happy2std) require a working FSL installation for registration to MNI152 space.
+
+## Key Design Patterns
+
+### Versioning
+Uses versioneer for automatic version management from git tags:
+- Version set in `rapidtide/_version.py` (auto-generated)
+- Tag prefix: `v` (e.g., v2.9.0)
+
+### Testing Philosophy
+- Main tests in `rapidtide/tests/` are run in CI
+- Experimental/incomplete tests in `rapidtide/candidatetests/`
+- Many tests use synthetic data and compare against reference outputs
+- Full workflow tests: `test_fullrunrapidtide_v*.py`, `test_fullrunhappy_v*.py`
+
+### Multiprocessing
+Many operations support parallel processing:
+- Uses `rapidtide/multiproc.py` and `rapidtide/genericmultiproc.py`
+- Configurable number of worker processes
+- Shared memory for efficiency
+
+## Special Notes
+
+- The codebase uses extensive command-line argument parsing with validation in `workflows/parser_funcs.py`
+- Deep learning models for signal filtering are in `rapidtide/data/models/`
+- The package includes a GUI tool (tidepool) built with PyQt6 for visualizing results
+- Reference data and example datasets are in `rapidtide/data/`
+- Documentation is built with Sphinx and hosted on ReadTheDocs
+
+## Style Conventions
+
+See the contributing guide at http://rapidtide.readthedocs.io/en/latest/contributing.html for full style guidelines.
+
+Key points:
+- Use Black formatter with 99-character line length
+- Follow NumPy docstring format
+- Keep changes focused on specific issues/features
+- Work on feature branches, not main

{rapidtide-3.0.10 → rapidtide-3.1}/INSTALL.rst

@@ -65,7 +65,7 @@ source code, and type:
 
    git clone https://github.com/bbfrederick/rapidtide.git
    cd rapidtide
-   refresh
+   ./refresh
 
 
 to install all of the tools in the package. You should be able to run
@@ -74,11 +74,11 @@ subdirectories).
 
 If you’ve made edits to the code, or want to sync up with the current version on Github,
 cd into the
-package directory and type ``refresh``:
+package directory and type ``./refresh``:
 
 ::
 
-   refresh
+   ./refresh
 
 
 This will uninstall the current version, sync up to github, and reinstall
@@ -190,22 +190,23 @@ Then the following command will work (you can replace 'tidepool' with any of the
 Singularity installation
 ------------------------
 
-Many times you can't use Docker, because of security concerns.  Singularity, from LBL, offers containerized computing
-that runs entirely in user space, so the amount of mischief you can get up to is significantly less.  Singularity
+Many times you can't use Docker, because of security concerns.  Apptainer (formerly singularity), from LBL, offers containerized computing
+that runs entirely in user space, so the amount of mischief you can get up to is significantly less.  Apptainer
 containers can be created from Docker containers as follows (stealing from the fMRIprep documentation):
 ::
 
-    singularity build /my_images/rapidtide.simg docker://fredericklab/rapidtide:latest-release
+    apptainer build \
+        /my_image_directory/rapidtide.sif \
+        docker://fredericklab/rapidtide:latest-release
 
 
 Running the container is similar to Docker.  The "-B" option is used to bind filesystems to mountpoints in the container.
-For example, to run the simple rapidtide2x analysis above, type the following:
+For example, to run the simple rapidtide analysis above, type the following:
 ::
 
-    singularity run \
-        --cleanenv \
+    apptainer run \
         -B INPUTDIRECTORY:/data_in,OUTPUTDIRECTORY:/data_out \
-        rapidtide.simg \
+        rapidtide.sif \
             rapidtide \
                 /data_in/YOURNIFTIFILE.nii.gz \
                 /data_out/outputname \

{rapidtide-3.0.10/rapidtide.egg-info → rapidtide-3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rapidtide
-Version: 3.0.10
+Version: 3.1
 Summary: Tools for performing correlation analysis on fMRI data.
 Author: Taylor Salo, Daniel M. Drucker, Ph.D., Jeffrey N Stout, Yaroslav O. Halchenko, Derek Monroe
 Author-email: "Blaise deB. Frederick" <blaise.frederick@gmail.com>
@@ -16,10 +16,10 @@ Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Science/Research
 Classifier: Topic :: Scientific/Engineering :: Image Recognition
 Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.9
 Description-Content-Type: text/x-rst
 License-File: LICENSE
@@ -40,15 +40,16 @@ Requires-Dist: statsmodels
 Requires-Dist: pywavelets
 Requires-Dist: tensorflow>=2.18.0
 Requires-Dist: tf-keras>=2.18.0
+Requires-Dist: torch
 Requires-Dist: tqdm
 Requires-Dist: versioneer
-Provides-Extra: tests
-Requires-Dist: codecov; extra == "tests"
-Requires-Dist: coverage; extra == "tests"
-Requires-Dist: coveralls; extra == "tests"
-Requires-Dist: flake8-black; extra == "tests"
-Requires-Dist: pytest; extra == "tests"
-Requires-Dist: pytest-cov; extra == "tests"
+Provides-Extra: test
+Requires-Dist: codecov; extra == "test"
+Requires-Dist: coverage; extra == "test"
+Requires-Dist: coveralls; extra == "test"
+Requires-Dist: flake8-black; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
 Provides-Extra: doc
 Requires-Dist: sphinx; extra == "doc"
 Requires-Dist: sphinx_rtd_theme; extra == "doc"

{rapidtide-3.0.10 → rapidtide-3.1}/pyproject.toml

@@ -14,10 +14,10 @@ classifiers = [
     'Intended Audience :: Science/Research',
     'Topic :: Scientific/Engineering :: Image Recognition',
     'License :: OSI Approved :: Apache Software License',
-    'Programming Language :: Python :: 3.9',
     'Programming Language :: Python :: 3.10',
     'Programming Language :: Python :: 3.11',
     'Programming Language :: Python :: 3.12',
+    'Programming Language :: Python :: 3.13',
 ]
 requires-python = '>=3.9'
 dependencies = [
@@ -38,6 +38,7 @@ dependencies = [
   'pywavelets',
   'tensorflow >= 2.18.0',
   'tf-keras >= 2.18.0',
+  'torch',
   'tqdm',
   'versioneer',
 ]
@@ -59,7 +60,7 @@ authors = [
 'Changelog' = 'https://github.com/bbfrederick/rapidtide/blob/main/CHANGELOG.md'
 
 [project.optional-dependencies]
-tests = [
+test = [
   'codecov',
   'coverage',
   'coveralls',
@@ -82,6 +83,7 @@ doc = [
 adjustoffset = 'rapidtide.scripts.adjustoffset:entrypoint'
 aligntcs = 'rapidtide.scripts.aligntcs:entrypoint'
 applydlfilter = 'rapidtide.scripts.applydlfilter:entrypoint'
+applyppgproc = 'rapidtide.scripts.applyppgproc:entrypoint'
 atlasaverage = 'rapidtide.scripts.atlasaverage:entrypoint'
 atlastool = 'rapidtide.scripts.atlastool:entrypoint'
 calcicc = 'rapidtide.scripts.calcicc:entrypoint'
@@ -161,11 +163,11 @@ rapidtide = ['.eggs', '.git', '.github', '.pytest_cache', 'rapidtide/candidatete
 # Aliases
 docs = ['rapidtide[doc]']
 tests = ['rapidtide[test]']
-all = ['rapidtide[docs,tests]']
+all = ['rapidtide[doc,test]']
 
 [tool.black]
 line-length = 99
-target-version = ['py39']
+target-version = ['py310']
 include = '\.pyi?$'
 exclude = '''
 (