trx.streamlines_ops
===================

.. py:module:: trx.streamlines_ops

.. autoapi-nested-parse::

   Set operations on streamlines with precision-based matching.

   ..
       !! processed by numpydoc !!


Attributes
----------

.. autoapisummary::

   trx.streamlines_ops.MIN_NB_POINTS
   trx.streamlines_ops.KEY_INDEX


Functions
---------

.. autoapisummary::

   trx.streamlines_ops.intersection
   trx.streamlines_ops.difference
   trx.streamlines_ops.union
   trx.streamlines_ops.get_streamline_key
   trx.streamlines_ops.hash_streamlines
   trx.streamlines_ops.perform_streamlines_operation


Module Contents
---------------

.. py:data:: MIN_NB_POINTS
   :value: 5


.. py:data:: KEY_INDEX

.. py:function:: intersection(left, right)

   
   Return the intersection of two streamline hash dictionaries.


   :Parameters:

       **left** : dict
           Hash dictionary returned by :func:`hash_streamlines`.

       **right** : dict
           Hash dictionary returned by :func:`hash_streamlines`.



   :Returns:

       dict
           Dictionary containing only keys present in both inputs.











   ..
       !! processed by numpydoc !!

.. py:function:: difference(left, right)

   
   Return the difference of two streamline hash dictionaries.


   :Parameters:

       **left** : dict
           Hash dictionary returned by :func:`hash_streamlines`.

       **right** : dict
           Hash dictionary returned by :func:`hash_streamlines`.



   :Returns:

       dict
           Dictionary containing keys present in ``left`` but not in ``right``.











   ..
       !! processed by numpydoc !!

.. py:function:: union(left, right)

   
   Return the union of two streamline hash dictionaries.


   :Parameters:

       **left** : dict
           Hash dictionary returned by :func:`hash_streamlines`.

       **right** : dict
           Hash dictionary returned by :func:`hash_streamlines`.



   :Returns:

       dict
           Dictionary containing all keys from both inputs. Values from ``left``
           overwrite those from ``right`` when keys overlap.











   ..
       !! processed by numpydoc !!

.. py:function:: get_streamline_key(streamline, precision=None)

   
   Produce a hash key from a streamline using a few points.


   :Parameters:

       **streamline** : ndarray
           A single streamline (N, 3).

       **precision** : int, optional
           The number of decimals to keep when hashing the points of the
           streamlines. Allows a soft comparison of streamlines. If None, no
           rounding is performed.



   :Returns:

       bytes
           Hash of the first/last MIN_NB_POINTS points of the streamline.











   ..
       !! processed by numpydoc !!

.. py:function:: hash_streamlines(streamlines, start_index=0, precision=None)

   
   Produce a dict from streamlines.

   Produce a dict from streamlines by using the points as keys and the
   indices of the streamlines as values.

   :Parameters:

       **streamlines** : list of ndarray
           The list of streamlines used to produce the dict.

       **start_index** : int, optional
           The index of the first streamline. 0 by default.

       **precision** : int, optional
           The number of decimals to keep when hashing the points of the
           streamlines. Allows a soft comparison of streamlines. If None, no
           rounding is performed.



   :Returns:

       dict
           A dict where the keys are streamline points and the values are
           indices starting at start_index.











   ..
       !! processed by numpydoc !!

.. py:function:: perform_streamlines_operation(operation, streamlines, precision=0)

   
   Perform an operation on a list of list of streamlines.

   Given a list of list of streamlines, this function applies the operation
   to the first two lists of streamlines. The result in then used recursively
   with the third, fourth, etc. lists of streamlines.

   A valid operation is any function that takes two streamlines dict as input
   and produces a new streamlines dict (see hash_streamlines). Union,
   difference, and intersection are valid examples of operations.

   :Parameters:

       **operation** : callable
           A callable that takes two streamlines dicts as inputs and produces a
           new streamline dict.

       **streamlines** : list of list of streamlines
           The streamlines used in the operation.

       **precision** : int, optional
           The number of decimals to keep when hashing the points of the
           streamlines. Allows a soft comparison of streamlines. If None, no
           rounding is performed.



   :Returns:

       **streamlines** : list of `nib.streamline.ArraySequence`
           The streamlines obtained after performing the operation on all the
           input streamlines.

       **indices** : np.ndarray
           The indices of the streamlines that are used in the output.











   ..
       !! processed by numpydoc !!