Metadata-Version: 2.4
Name: fmri-toolkit
Version: 0.1.0
Summary: A comprehensive toolkit for fMRI data analysis and visualization
Author-email: Johnny In <johnnyin@umich.edu>
License: MIT
Keywords: fmri,neuroimaging,brain,neuroscience,analysis,visualization,mri
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: matplotlib>=3.4.0
Requires-Dist: seaborn>=0.11.0
Requires-Dist: plotly>=5.0.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: statsmodels>=0.13.0
Requires-Dist: nibabel>=3.2.0
Requires-Dist: Pillow>=8.0.0
Requires-Dist: tqdm>=4.60.0
Requires-Dist: pyreadr>=0.4.0
Requires-Dist: hotelling>=0.5.0
Requires-Dist: tenacity>=8.0.0
Requires-Dist: requests>=2.25.0
Requires-Dist: plotnine>=0.8.0
Requires-Dist: python-dateutil>=2.8.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: mypy>=0.950; extra == "dev"
Dynamic: license-file

# FMRI Toolkit

A comprehensive Python toolkit for functional Magnetic Resonance Imaging (fMRI) data analysis and visualization.

## Features

### Core Analysis
- **Stimulus Detection**: Multiple statistical tests for detecting brain activation
  - Real-valued tests: t-test, Wilcoxon, on/off difference, HRF GLM
  - Complex-valued tests: Hotelling's T², Wilks-Lambda, generalized LRT
  - Support for 1D-4D data
- **Post-hoc Processing**: FDR correction and spatial clustering (6-, 18-, or 26-connectivity)
- **P-value Adjustment**: Multiple testing correction methods (Bonferroni, Holm, Benjamini-Hochberg)

### Visualization
- **3D Brain Visualization**: Interactive 3D brain maps using Plotly
- **2D Slice Visualization**: Sagittal, axial, and coronal slice views
- **Regional Visualization**: ROI-based 3D visualization
- **Comparison Tools**: Side-by-side comparison of multiple p-value maps (2D and 3D)

### ROI Analysis
- **Phase 1**: Detect activated regions of interest using statistical tests
- **Phase 2**: ROI-based tensor-on-tensor regression analysis

### Time Series Analysis
- **Time Series Visualization**: Interactive time series exploration
- **Forecasting**: Time series forecasting capabilities for fMRI data

### Data Simulation
- Generate synthetic fMRI data with specified activation regions and stimulus timing

## Installation

### From PyPI (when published)
```bash
pip install fmri-toolkit
```

### From source
```bash
git clone https://github.com/yourusername/fmri-toolkit.git
cd fmri-toolkit
pip install -e .
```

## Quick Start

```python
import fmri_toolkit as fmri

# Load fMRI data
data = fmri.fmri_load_mat('path/to/data.mat')

# Perform stimulus detection
result = fmri.fmri_stimulus_detect(
    fmridata=data,
    mask=mask,
    stimulus_idx=stimulus_indices,
    rest_idx=rest_indices,
    method='t-test'
)

# Apply post-hoc correction
processed = fmri.fmri_post_hoc(
    result,
    alpha=0.05,
    method='BH',
    spatial_cluster=True
)

# Visualize results in 3D
fmri.fmri_3dvisual(
    processed,
    title='Brain Activation Map',
    color_scheme='hot'
)
```

## Requirements

- Python >= 3.8
- NumPy >= 1.20.0
- SciPy >= 1.7.0
- Pandas >= 1.3.0
- Matplotlib >= 3.4.0
- Plotly >= 5.0.0
- And other dependencies (see `pyproject.toml`)

## Documentation

For detailed documentation, examples, and API reference, visit the [documentation](https://github.com/yourusername/fmri-toolkit#readme).

## Examples

Check the `examples/` directory for complete usage examples:
- `runall.py`: Full analysis pipeline demonstration

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Citation

If you use this toolkit in your research, please cite:

```bibtex
@software{fmri_toolkit,
  title={FMRI Toolkit: A Python Package for fMRI Data Analysis},
  author={Johnny In},
  year={2024},
  url={https://github.com/yourusername/fmri-toolkit}
}
```

## Support

For issues, questions, or suggestions, please open an issue on [GitHub](https://github.com/yourusername/fmri-toolkit/issues).
