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

.. py:module:: cubnm.datasets

.. autoapi-nested-parse::

   Example datasets




.. autoapisummary::

   cubnm.datasets.load_sc
   cubnm.datasets.load_bold
   cubnm.datasets.load_fc
   cubnm.datasets.load_fcd
   cubnm.datasets.load_maps



.. py:function:: load_sc(measure, parc='schaefer-100', sub='group-train706', norm='mean')

   Load example structural connectivity matrix from HCP-YA dataset

   Parameters
   ----------
   measure: {'strength', 'length'}
       Structural connectivity measure.

       - ``'strength'``: SC strength (tract counts)
       - ``'length'``: SC tracts length

   parc: :obj:`str`
       Parcellation. Currently only ``'schaefer-100'`` is supported.
   sub: :obj:`str`
       Subject or group ID. Two subjects and two group-averaged 
       matrices are currently included:

       - ``'100206'``
       - ``'100307'``
       - ``'group-train706'``
       - ``'group-test303'``

   norm: {'mean', None}
       SC strength normalization method.
       Only used when ``measure`` is ``'strength'``.

       - ``'mean'``: normalize to mean 0.01. Default
       - ``None``: no normalization

   Returns
   -------
   :obj:`np.ndarray`
       Structural connectivity matrix. Shape: (nodes, nodes)


.. py:function:: load_bold(parc='schaefer-100', sub='100206', ses='REST1_LR')

   Load example BOLD data from the HCP-YA dataset

   Parameters
   --------
   parc: :obj:`str`
       Parcellation. Currently only ``'schaefer-100'`` is available.
   sub: :obj:`str`
       Subject ID. Currently two subjects are included:

       - ``'100206'``
       - ``'100307'``

   ses: {'REST1_LR', 'REST2_LR'}
       Imaging session.

   Returns
   --------
   :obj:`np.ndarray`
       The BOLD signal. Shape: (nodes, volumes)


.. py:function:: load_fc(parc='schaefer-100', sub='group-train706', ses='REST', exc_interhemispheric=False, return_tril=True)

   Load example FC from the HCP-YA dataset

   Parameters
   --------
   parc: :obj:`str`
       Parcellation. Currently only ``'schaefer-100'`` is available.
   sub: :obj:`str`
       Subject or group ID. Two subjects and two group-averaged 
       matrices are currently included:

       - ``'100206'``
       - ``'100307'``
       - ``'group-train706'``
       - ``'group-test303'``

   ses: {'REST1_LR', 'REST2_LR', 'REST'}
       Imaging session. For subject-level data currently
       only ``'REST1_LR'``, and ``'REST2_LR'`` are included and
       for group-level data only ``'REST'`` is included.
       ``'REST'`` includes the data averaged across
       all sessions.
   exc_interhemispheric: :obj:`bool`
       Whether to exclude interhemispheric connections. Default: False
   return_tril: :obj:`bool`
       Whether to return the lower triangular part of the FC matrix.

   Returns
   --------
   :obj:`np.ndarray`
       Functional connectivity matrix or its lower triangular part.
       Shape: (nodes, nodes) or (node_pairs,)


.. py:function:: load_fcd(parc='schaefer-100', sub='group-train706', ses='REST', window_size=30, window_step=5, drop_edges=True, exc_interhemispheric=False, return_tril=True)

   Load example FCD from the HCP-YA dataset

   Parameters
   --------
   parc: :obj:`str`
       Parcellation. Currently only ``'schaefer-100'`` is available.
   sub: :obj:`str`
       Subject or group ID. Two subjects and two group-averaged 
       matrices are currently included:

       - ``'100206'``
       - ``'100307'``
       - ``'group-train706'``
       - ``'group-test303'``

   ses: {'REST1_LR', 'REST2_LR', 'REST'}
       Imaging session. For subject-level data currently
       only ``'REST1_LR'``, and ``'REST2_LR'`` are included and
       for group-level data only ``'REST'`` is included.
       ``'REST'`` includes the data pooled across
       all sessions.
   window_size: :obj:`int`
       dynamic FC window size (in seconds)
       will be converted to N TRs (nearest even number)
       The actual window size is number of TRs + 1 (including center)
   window_step: :obj:`int`
       dynamic FC window step (in seconds)
       will be converted to N TRs
   drop_edges: :obj:`bool`
       drop edge windows which have less than window_size volumes
   exc_interhemispheric: :obj:`bool`
       Whether to exclude interhemispheric connections. Default: False
   return_tril: :obj:`bool`
       Whether to return the lower triangular part of the FCD matrix.
       Ignored when ``sub`` is a group (in this case
       the return matrix is pooled from FCD lower triangles of
       individual subjects).

   Returns
   --------
   :obj:`np.ndarray`
       Functional connectivity dynamics matrix or its lower triangular part.
       Shape: (nodes, nodes) or (node_pairs,)


.. py:function:: load_maps(names, parc='schaefer-100', 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: :obj:`str`
       Parcellation. Currently only ``'schaefer-100'`` is supported.
   norm: {'zscore', 'minmax', None}
       Map normalization method applied across nodes.

       - ``'zscore'``: maps are z-score normalized
       - ``'minmax'``: maps are min-max normalized to [0, 1]
       - ``None``: no normalization

   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.