{"id":28423849,"url":"https://github.com/bbuchsbaum/fmriparametry","last_synced_at":"2025-06-25T15:31:22.160Z","repository":{"id":296558149,"uuid":"993759690","full_name":"bbuchsbaum/fmriparametry","owner":"bbuchsbaum","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-22T16:02:47.000Z","size":2521,"stargazers_count":0,"open_issues_count":9,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-22T17:19:13.239Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bbuchsbaum.png","metadata":{"files":{"readme":"README.md","changelog":"NEWS.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-31T13:13:33.000Z","updated_at":"2025-06-22T16:02:51.000Z","dependencies_parsed_at":"2025-06-01T02:53:10.014Z","dependency_job_id":"cf971c0d-80f6-41f0-8029-cce5393d70d9","html_url":"https://github.com/bbuchsbaum/fmriparametry","commit_stats":null,"previous_names":["bbuchsbaum/fmriparametry"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/bbuchsbaum/fmriparametry","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbuchsbaum%2Ffmriparametry","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbuchsbaum%2Ffmriparametry/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbuchsbaum%2Ffmriparametry/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbuchsbaum%2Ffmriparametry/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bbuchsbaum","download_url":"https://codeload.github.com/bbuchsbaum/fmriparametry/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbuchsbaum%2Ffmriparametry/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261900874,"owners_count":23227462,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-05T09:09:39.335Z","updated_at":"2025-06-25T15:31:22.152Z","avatar_url":"https://github.com/bbuchsbaum.png","language":"R","readme":"# fmriparametric\n\n\u003c!-- badges: start --\u003e\n[![R-CMD-check](https://github.com/bbuchsbaum/fmriparametry/workflows/R-CMD-check/badge.svg)](https://github.com/bbuchsbaum/fmriparametry/actions)\n[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)\n\u003c!-- badges: end --\u003e\n\n## Overview\n\n`fmriparametric` provides robust and efficient tools for estimating parameters of parametric Hemodynamic Response Function (HRF) models from fMRI data. Using an iterative linear Taylor approximation method, it enables voxel-wise estimation of interpretable HRF parameters with uncertainty quantification.\n\n## Features\n\n- **Fast parameter estimation**: Efficient implementation using sparse matrices and vectorized operations\n- **Flexible HRF models**: Currently supports the Lag-Width-Undershoot (LWU) model with extensible architecture\n- **Robust estimation**: Ridge regularization and parameter bounds enforcement\n- **Uncertainty quantification**: Standard error estimation via delta method\n- **Integration**: Works seamlessly with the `fmrireg` ecosystem\n\n## Installation\n\nYou can install the development version from GitHub:\n\n```r\n# install.packages(\"remotes\")\nremotes::install_github(\"bbuchsbaum/fmriparametry\")\n```\n\n## Quick Start\n\n```r\nlibrary(fmriparametric)\nlibrary(fmrireg)\n\n# Load your fMRI data (timepoints x voxels)\nfmri_data \u003c- matrix(rnorm(200 * 100), nrow = 200, ncol = 100)\n\n# Create event model (e.g., stimulus onsets)\nevent_model \u003c- matrix(0, nrow = 200, ncol = 1)\nevent_model[c(20, 60, 100, 140, 180), 1] \u003c- 1\n\n# Estimate HRF parameters\nfit \u003c- estimate_parametric_hrf(\n  fmri_data = fmri_data,\n  event_model = event_model,\n  parametric_hrf = \"lwu\"\n)\n\n# View results\nprint(fit)\nsummary(fit)\n\n# Extract parameters\nparams \u003c- coef(fit)  # Returns tau, sigma, rho for each voxel\n```\n\n### Single-Voxel Sanity Check\n\nFor quick verification that the estimation machinery is functioning, the\npackage exposes `single_voxel_sanity_check()`. It fits a single time series\nagainst a one-condition design.\n\n```r\ny \u003c- rnorm(40)\nonsets \u003c- rep(0, 40); onsets[c(10, 30)] \u003c- 1\nres \u003c- single_voxel_sanity_check(y, onsets)\n```\n\n## Documentation\n\nFull function reference and articles are available at\n\u003chttps://bbuchsbaum.github.io/fmriparametry\u003e.\n\n## HRF Models\n\n### Lag-Width-Undershoot (LWU) Model\n\nThe LWU model parameterizes the HRF with three interpretable parameters:\n\n- **τ (tau)**: Lag of the peak response (seconds)\n- **σ (sigma)**: Width/duration of the response (seconds)  \n- **ρ (rho)**: Undershoot amplitude ratio\n\nDefault bounds:\n- τ: [0, 20] seconds\n- σ: [0.05, 10] seconds\n- ρ: [0, 1.5]\n\n## Advanced Usage\n\n### Custom Seeds and Bounds\n\n```r\n# Custom parameter seeds\ncustom_seed \u003c- c(tau = 5, sigma = 2, rho = 0.3)\n\n# Custom bounds\ncustom_bounds \u003c- list(\n  lower = c(2, 0.5, 0),\n  upper = c(15, 8, 1.2)\n)\n\nfit \u003c- estimate_parametric_hrf(\n  fmri_data = fmri_data,\n  event_model = event_model,\n  parametric_hrf = \"lwu\",\n  theta_seed = custom_seed,\n  theta_bounds = custom_bounds\n)\n```\n\n### Controlling Global Refinement\n\nBy default, Stage 3 global iterative refinement runs automatically. To disable\nit across all calls, set the package option `fmriparametric.refine_global` to\n`FALSE`:\n\n```r\noptions(fmriparametric.refine_global = FALSE)\n```\n\nRe-enable by setting the option back to `TRUE`.\n\n### Working with fmrireg Objects\n\n```r\n# Using fmrireg data structures\nfmri_dataset \u003c- fmrireg::fmri_dataset(\n  scans = fmri_data,\n  mask = rep(TRUE, 100),\n  TR = 2.0\n)\n\nevent_model \u003c- fmrireg::event_model(\n  onset = c(20, 60, 100, 140, 180),\n  blockids = rep(1, 5),\n  durations = rep(0, 5)\n)\n\nfit \u003c- estimate_parametric_hrf(\n  fmri_data = fmri_dataset,\n  event_model = event_model,\n  parametric_hrf = \"lwu\"\n)\n```\n\n### Using the Ultimate Wrapper\n\nFor convenience, the package also provides\n`estimate_parametric_hrf_ultimate()`. This helper mirrors the main\nfunction but sets sensible defaults for iterative refinement and other\nadvanced options.\n\n```r\nfit \u003c- estimate_parametric_hrf_ultimate(\n  fmri_data = fmri_dataset,\n  event_model = event_model,\n  iterative_recentering = FALSE,\n  verbose = FALSE\n)\n```\n\n## Performance\n\nThe package is optimized for whole-brain analysis with:\n\n- Vectorized operations across voxels\n- Sparse matrix computations\n- Efficient convolution using FFT\n- Optional parallel processing (future releases)\n\nTypical performance:\n- 200 timepoints × 50 voxels: ~0.15 seconds\n- 500 timepoints × 1000 voxels: ~3-5 seconds\n\n## Methods\n\nThe package implements parametric HRF estimation using Taylor approximation:\n\n```\nh(t; θ) ≈ h(t; θ₀) + Σᵢ ∂h/∂θᵢ|θ₀ (θᵢ - θ₀ᵢ)\n```\n\nThis linearization allows efficient parameter estimation through standard linear regression with appropriate regularization.\n\n## Vignettes\n\nDetailed walk-throughs of package features are provided in the package vignettes:\n\n- `vignettes/introduction.Rmd` – getting started and basic concepts\n- `vignettes/advanced-features.Rmd` – advanced options and large-scale analyses\n- `vignettes/performance-guide.Rmd` – benchmarking and tuning tips\n\nUse `browseVignettes(\"fmriparametric\")` within R to view them after installation.\n\n## Contributing\n\nContributions are welcome! Please file bug reports and feature requests as GitHub issues.\n\n## License\n\nMIT © Bradley Buchsbaum\n\n## References\n\n- Glover, G. H. (1999). Deconvolution of impulse response in event-related BOLD fMRI. NeuroImage, 9(4), 416-429.\n- Lindquist, M. A., \u0026 Wager, T. D. (2007). Validity and power in hemodynamic response modeling: A comparison study and a new approach. Human Brain Mapping, 28(8), 764-784.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbuchsbaum%2Ffmriparametry","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbbuchsbaum%2Ffmriparametry","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbuchsbaum%2Ffmriparametry/lists"}