HRfunc

Exploring the HRtree



WARNING ⚠️ The HRtree is an experimental community resource that currently contains a limited amount of HRFs contributed by the neuroimaging community. Over time we hope this community resource will grow, however currently functionality listed below is sub-optimal. Estimating your own HRFs or use of a canonical HRF for estimating neural activity may be required.


A core component of the HRfunc tool is the HRtree, a hybrid tree-hash table data structure that efficiently stores HRF estimates with rich detail of their origins. Leveraging this data structure users can filter the HRtree for experimental contexts of interest like age range or experimental task.

Key HRF Contexts


Here are the 10 primary contexts filterable within the HRfunc...

  • method: The deconvolution method employed for estimating the HRF (i.e. 'toeplitz')
  • doi: DOI of paper describing dataset and HRF origin
  • ch_name: Channel name from which the HRF was estimated (i.e. 's1_d1_780')
  • study: Study name HRF was estimated for (i.e. 'p-cat')
  • task: Task name HRF was estimated from (i.e. 'flanker')
  • conditions: Experimental conditions (i.e. 'directional')
  • stimulus: The stimulus type (i.e. 'monitor')
  • intensity: The relative intensity of the stimulus centered around 1 (i.e. 0.5)
  • duration: The duration of the HRF estimate (i.e. 30.0)
  • protocol: The protocol name (i.e. 'gooble')
  • age_range: The age range of the subject pool used to estimate the HRF (i.e. 5.0 or -1.0 for pre-term infants)
  • demographics: The demographics of the subject pool used to estimate the HRF (i.e. ['female', 'black'])


Finding Experimentally Relavent HRFs



There are a number of ways you can filter on these experimental contexts. Each context is inserted into a HRhash table alongside a pointer to it's tree node. The montage.branch() function accepts any of the 10 context items and returns a sub-tree that includes all nodes in the HRtree that matched your requested context. 


import hrfunc as hrf

# Load a hrfunc montage
montage = hrf.montage('study_HRFs.json')
    
# Replace current HRtree with a sub-tree of context specific HRFs
montage.branch(age_range = [5, 6, 7, 8], task = ['stoop', 'n-back', 'tower of hanoi'])


The outputs of this branch call are similar, but may yeild HRFs with suboptimal similarity. It's recommended to then filter the tree which then does a weighted similarity check on each HRF within the tree and deletes any nodes that do not meet a threshold (defaulting too 95%)


# Filter your montage so it only contains HRFs of interest
montage.filter(threshold = 0.95)


You can also leverage the K-D trees data structure to look within regions of interest. The specific k-d tree structure used enables us to quickly group together in uniquely shaped clusters like spheres and boxes.


# Filter your montage so it only contains HRFs of interest
montage.radius_search(optode, maximum_distance = 0.1)


A radius search operation was implemented within the HRtree but easily a custom box search could also be implemented, leveraging the k-d tree structure.