:py:mod:`cubnm.datasets`
#######################

.. py:module:: cubnm.datasets

.. autoapi-nested-parse::

   Example datasets




.. autoapisummary::

   cubnm.datasets._get_lut_full
   cubnm.datasets._clean_micamics_sc
   cubnm.datasets._clean_micamics_bold
   cubnm.datasets.load_sc
   cubnm.datasets.load_bold
   cubnm.datasets.load_maps



.. py:function:: _get_lut_full(parc)

   Load the full (cortical+subcortical) lookup table for the given parcellation

   Parameters
   ----------
   parc: {'schaefer-[100, 200, ... 1000]', 'aparc', 'glasser-360'}
       Parcellation

   Returns
   -------
   :obj:`pandas.DataFrame`
       Full lookup table


.. py:function:: _clean_micamics_sc(micamics_dir, measure, parc, sub, exc_subcortex=True, norm='mean001', out_dir=None)

   Clean SC matrix of the given subject and parcellation

   Parameters
   ----------
   micamics_dir: :obj:`str`
       Path to the directory containing the micapipe outputs of micamics
       (https://osf.io/x7qr2 unzipped)
   measure: {'strength', 'length'}
       - 'strength': SC strength (normalized tract counts)
       - 'length': SC tracts length
   parc: {'schaefer-[100, 200, ... 1000]', 'aparc', 'glasser-360'}
       Parcellation
   sub: :obj:`str`
       Subject ID, e.g. "sub-HC001"
   exc_subcortex: :obj:`bool`, optional
       Whether to exclude subcortical regions. Default: True
   norm: {'mean001', 'none'}
       SC strength normalization method
       - 'mean001': normalize to mean 0.01. Default
       - 'none': no normalization
   out_dir: :obj:`str`, optional
       Path to save the cleaned SC matrix


.. py:function:: _clean_micamics_bold(micamics_dir, parc, sub, exc_subcortex=True, out_dir=None)

   Clean BOLD time series of the given subject and parcellation

   Parameters
   ----------
   micamics_dir: :obj:`str`
       Path to the directory containing the micapipe outputs of micamics
       (https://osf.io/x7qr2 unzipped)
   parc: {'schaefer-[100, 200, ... 1000]', 'aparc', 'glasser-360'}
       Parcellation
   sub: :obj:`str`
       Subject ID, e.g. "sub-HC001"
   exc_subcortex: :obj:`bool`, optional
       Whether to exclude subcortical regions. Default: True
   out_dir: :obj:`str`, optional
       Path to save the cleaned BOLD time series


.. py:function:: load_sc(measure, parc, sub='sub-HC001', exc_subcortex=True, norm='mean001', micamics_dir=None)

   Load example structural connectivity matrix from MICA-MICs dataset
   (https://www.nature.com/articles/s41597-022-01682-y)

   Parameters
   ----------
   measure: {'strength', 'length'}
       - 'strength': SC strength (normalized tract counts)
       - 'length': SC tracts length
   parc: {'schaefer-[100, 200, ... 1000]', 'aparc', 'glasser-360'}
       Parcellation
   sub: :obj:`str`
       Subject ID, e.g. "sub-HC001"
   exc_subcortex: :obj:`bool`, optional
       Whether to exclude subcortical regions. Default: True
   norm: {'mean001', 'none'}
       SC strength normalization method
       - 'mean001': normalize to mean 0.01. Default
       - 'none': no normalization
   micamics_dir: :obj:`str`, optional
       Path to the directory containing the micapipe outputs of micamics
       (https://osf.io/x7qr2 unzipped). Required if subjects other than 
       'sub-HC001' are requested and/or exc_subcortex is False and/or
       norm is 'none'.

   Returns
   -------
   :obj:`np.ndarray` or :obj:`str`
       Structural connectivity matrix or path to its
       text file. Shape: (nodes, nodes)


.. py:function:: load_bold(parc, sub='sub-HC001', exc_subcortex=True, micamics_dir=None)

   Load example BOLD data from the MICA-MICs dataset
   (https://www.nature.com/articles/s41597-022-01682-y)

   Parameters
   --------
   parc: 'schaefer-100'
       parcellation
   sub: :obj:`str`
       Subject ID, e.g. "sub-HC001"
   exc_subcortex: :obj:`bool`, optional
       Whether to exclude subcortical regions. Default: True
   micamics_dir: :obj:`str`, optional
       Path to the directory containing the micapipe outputs of micamics
       (https://osf.io/x7qr2 unzipped). Required if subjects other than 
       'sub-HC001' are requested and/or exc_subcortex is False.

   Returns
   --------
   :obj:`np.ndarray` or :obj:`str`
       Path to a text file or numpy array including
       the BOLD signal. Shape: (nodes, volumes)


.. py:function:: load_maps(names, parc, norm='minmax')

   Loads example heterogeneity maps

   Parameters
   ----------
   names: :obj:`str` or :obj:`list`
       One or more maps selected from this list:
       - 'myelinmap'
       - 'thickness'
       - 'fcgradient01'
       - 'genepc1'
       - 'nmda'
       - 'gabaa'
       - 'yeo7'
   parc: {'schaefer-100'}
       parcellation
   norm: {'zscore', 'minmax', None}
       - 'zscore': maps are z-score normalized
       - 'minmax': maps are min-max normalized to [0, 1]

   Returns
   --------
   :obj:`np.ndarray` or :obj:`str`
       Maps arrays or path to their
       text file. Shape: (maps, nodes)

   Notes
   -----
   For more information and code on how these maps were
   obtained and parcellated see `utils.datasets.load_maps`
   in https://github.com/amnsbr/eidev. The set of maps included
   here are limited and provided just as examples. We recommend 
   users to use `neuromaps` and similar tools to obtain and 
   parcellate further maps.