Skip to main content

Build Status

test-posix

test-windows

NCRF

The magnetoencephalography (MEG) response to continuous auditory stimuli, such as speech, is commonly described using a linear filter, the auditory temporal response function (TRF). Though components of the sensor level TRFs have been well characterized, the cortical distributions of the underlying neural responses are not well-understood. In our recent work, we provide a unified framework for determining the TRFs of neural sources directly from the MEG data, by integrating the TRF and distributed forward source models into one, and casting the joint estimation task as a Bayesian optimization problem. Though the resulting problem emerges as non-convex, we propose efficient solutions that leverage recent advances in evidence maximization. For more details please refer to [1], [2].

This repository contains the implementation of our direct TRF estimation algorithm in Python.

For code examples using real datasets, see the Example gallery.

The optimization algorithm is configurable independently of the forward model. For a prepared RegressionData dataset, the lower-level API is:

from ncrf import ChampLasso, NCRFEstimator

estimator = NCRFEstimator.from_lead_field(lead_field, noise_covariance)
solver = ChampLasso(mu='auto', n_iter=30, n_iterc=10, n_iterf=100)
result = estimator.fit(data, solver)

All solvers return a common predictive NCRF in result.model; training explained variance is available as result.scores['explained_variance']. To score other data, result.model.evaluate(data, [explained_variance, l2_error]) predicts once and returns all requested metrics. Solver-specific state is available as result.solver_fit.

How to use:

run

result = fit_ncrf(meg, stim, lead_field, noise_covariance, mu='auto', tstop=1.0, basis_stride=2, n_splits=3, scale='l1')

to perform a 3-fold cross-validation and then construct the model for 1s long TRF with the regularization weight among the given range that gives least generalization error. The signature of the meg and stim could be as follows:

[        megA (case, sensor, time),                       megB (case, sensor, time),               ...]
[[featA1 (case, time), featA2 (case, time), ...], [featB1 (case, time), featB2 (case, time), ...], ...]

For more options, please look at the docstring. The learned TRF, h can be retrieved using:

h = result.model.h

Results

We applied the algorithm on a subset of MEG data collected from 17 adults (aged 18-27 years) under an auditory task described in the papers. In short, during the task, the participants listened to 1 min long segments from an audio-book recording of The Legend of Sleepy Hollow by Washington Irving, narrated by a male speaker. We consider localizing the TRFs using a total of 6 min data from each participant. MNE-python 0.14 was used in pre-processing the raw data to automatically detect and discard flat channels, remove extraneous artifacts, and to band-pass filter the data in the range 1 - 80 Hz. The six 1 min long data epochs were then down-sampled to 200 Hz. As the stimulus variable, we used the speech envelope reflecting the momentary acoustic power, by averaging the auditory spectrogram representation (generated using a model of the auditory periphery) across the frequency bands, sampled at 200 Hz. A volume source space for individual subjects was defined on a 3D regular grid with a resolution of 7 mm in each direction. The lead-field matrix was then computed by placing free orientation virtual dipoles on the resulting 3322 grid points. The consistent components of our estimated 1 s-long 3D TRFs across all 17 subjects looks like following:

Demo

Isn't that cool? Do expect to see something like that with any other source localization method? If you realize you could use this method on your data, please feel free to use the codes. You can reach me at proloy@umd.edu if you have any issues with the codes. And don't forget to go over the papers/ posters before applying the algorithm.

Versioning and releases

The version is derived from git tags by setuptools_scm; it is not stored in the source. A commit tagged v0.5.0 builds as 0.5.0; later commits build as a development version of the next release, e.g. 0.5.1.dev3+g1a2b3c4. The installed version is available as ncrf.__version__.

To release, create a release on GitHub with a new tag of the form v0.5.0. Publishing the release creates the tag and triggers the wheels workflow, which builds and tests the sdist and wheel and publishes them to PyPI. Clones need the tags for the version to resolve (git fetch --tags); pip install -e . must be re-run for ncrf.__version__ to reflect new tags.

The files involved:

  • pyproject.toml: declares the version as dynamic and enables setuptools_scm ([tool.setuptools_scm]), which computes it from git at build time.
  • ncrf/__init__.py: reads the version of the installed package from its metadata into ncrf.__version__.
  • .git_archival.txt and .gitattributes: let GitHub archive downloads (.zip/.tar.gz), which have no git history, still carry the tag information.
  • .github/workflows/wheels.yml: builds, tests and publishes the sdist and wheel; the other workflows check out the full history (fetch-depth: 0) so tags are available.
  • docs/conf.py: takes the documentation version from ncrf.__version__.

References

[1] P. Das, C. Brodbeck, J. Z. Simon, B. Babadi, Direct Cortical Localization of the MEG Auditory Temporal Response Function: a Non-Convex Optimization Approach; Proceedings of the 47th Annual Neuroscience Meeting (SfN 2018), Nov. 2-7, San Diego, CA.

[2] P. Das, C. Brodbeck, J. Z. Simon, B. Babadi, Cortical Localization of the Auditory Temporal Response Function from MEG via Non-Convex Optimization; 2018 Asilomar Conference on Signals, Systems, and Computers, Oct. 28–31, Pacific Grove, CA (invited)

Metadata

Release files for ncrf 0.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ncrf 0.5
File Size Uploaded Provenance Actions
ncrf-0.5.tar.gz 102.4 kB With provenance Details for ncrf-0.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ncrf 0.5
File Interpreter ABI Platform Actions
ncrf-0.5-py3-none-any.whl Python 3 none any Details for ncrf-0.5-py3-none-any.whl

Total release size: 183.2 kB

Release files / ncrf-0.5.tar.gz

Download URL ncrf-0.5.tar.gz
Size 102.4 kB
Tags Source
SHA-256 checksum
How to use checksums
d69273f979610ccb13ebb48590574aff1137cbba3bfb94dcc16221f1e6b43bab
BLAKE2b-256 checksum
How to use checksums
41740ce3cbcf3736af270dc3ac80f393039b15bb1c84f14dfbac63e5a185e286
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Release files / ncrf-0.5-py3-none-any.whl

Download URL ncrf-0.5-py3-none-any.whl
Size 80.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
80e5eda58e956d4c1ee4b152a197b53739cd071303cff079826b7d4a03e313bc
BLAKE2b-256 checksum
How to use checksums
4d641a3ce9098bd0c13fb561a2795c4d28fbc9681d882e3588a276aa5062128f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Security for ncrf 0.5

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ncrf-0.5.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.5 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page