nimare.decode.discrete

Methods for decoding subsets of voxels (e.g., ROIs) or experiments (e.g., from meta-analytic clustering on a database) into text.

Functions

brainmap_decode(coordinates, annotations, ids) Perform image-to-text decoding for discrete image inputs (e.g., regions of interest, significant clusters) according to the BrainMap method [1].
gclda_decode_roi(model, roi[, topic_priors, …]) Perform image-to-text decoding for discrete image inputs (e.g., regions of interest, significant clusters) according to the method described in [1].
neurosynth_decode(coordinates, annotations, ids) Perform discrete functional decoding according to Neurosynth’s meta-analytic method [1].
brainmap_decode(coordinates, annotations, ids, ids2=None, features=None, frequency_threshold=0.001, u=0.05, correction='fdr_bh')[source]

Perform image-to-text decoding for discrete image inputs (e.g., regions of interest, significant clusters) according to the BrainMap method [1].

References

[1](1, 2) Amft, Maren, et al. “Definition and characterization of an extended social-affective default network.” Brain Structure and Function 220.2 (2015): 1031-1049. https://doi.org/10.1007/s00429-013-0698-0
gclda_decode_roi(model, roi, topic_priors=None, prior_weight=1.0)[source]

Perform image-to-text decoding for discrete image inputs (e.g., regions of interest, significant clusters) according to the method described in [1].

Parameters:
  • model (nimare.annotate.topic.GCLDAModel) – Model object needed for decoding.
  • roi (nibabel.nifti1.Nifti1Image or str) – Binary image to decode into text. If string, path to a file with the binary image.
  • topic_priors (numpy.ndarray of float, optional) – A 1d array of size (n_topics) with values for topic weighting. If None, no weighting is done. Default is None.
  • prior_weight (float, optional) – The weight by which the prior will affect the decoding. Default is 1.
Returns:

  • decoded_df (pandas.DataFrame) – A DataFrame with the word-tokens and their associated weights.
  • topic_weights (numpy.ndarray of float) – The weights of the topics used in decoding.

Notes

Notation Meaning
v Voxel
t Topic
w Word type
r Region of interest (ROI)
p(v|t) Probability of topic given voxel (p_topic_g_voxel)
\\tau_{t} Topic weight vector (topic_weights)
p(w|t) Probability of word type given topic (p_word_g_topic)
  1. Compute p(v|t).

    • From gclda.model.Model.get_spatial_probs()
  2. Compute topic weight vector (\\tau_{t}) by adding across voxels within ROI.

    • \\tau_{t} = \sum_{i} {p(t|v_{i})}
  3. Multiply \\tau_{t} by p(w|t).

    • p(w|r) \propto \\tau_{t} \cdot p(w|t)
  4. The resulting vector (word_weights) reflects arbitrarily scaled term weights for the ROI.

References

[1](1, 2) Rubin, Timothy N., et al. “Decoding brain activity using a large-scale probabilistic functional-anatomical atlas of human cognition.” PLoS computational biology 13.10 (2017): e1005649. https://doi.org/10.1371/journal.pcbi.1005649
neurosynth_decode(coordinates, annotations, ids, ids2=None, features=None, frequency_threshold=0.001, prior=0.5, u=0.05, correction='fdr_bh')[source]

Perform discrete functional decoding according to Neurosynth’s meta-analytic method [1]. This does not employ correlations between unthresholded maps, which are the method of choice for decoding within Neurosynth and Neurovault. Metadata (i.e., feature labels) for studies within the selected sample (ids) are compared to the unselected studies remaining in the database (dataset).

References

[1](1, 2) Yarkoni, Tal, et al. “Large-scale automated synthesis of human functional neuroimaging data.” Nature methods 8.8 (2011): 665. https://doi.org/10.1038/nmeth.1635