nimare.decode.discrete.gclda_decode_roi

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]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