:py:mod:`cddm.map`
==================

.. py:module:: cddm.map

.. autoapi-nested-parse::

   Data mapping and k-averaging functions.



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

.. py:function:: sector_indexmap(kmap, anglemap, angle=0.0, sector=30.0, kstep=1.0)

   Builds indexmap array of integers ranging from -1 (invalid data)
   and positive integers. Each non-negative integer is a valid k-index computed
   from sector parameters.

   :param kmap: Size of wavevector at each (i,j) indices in the rfft2 ouptut data.
   :type kmap: ndarray
   :param anglemap: Angle of the wavevector at each (i,j) indices in the rfft2 ouptut data.
   :type anglemap: ndarray
   :param angle: Mean angle of the sector in degrees (-90 to 90).
   :type angle: float
   :param sector: Width of the sector in degrees (between 0 and 180)
   :type sector: float
   :param kstep: k resolution in units of minimum step size.
   :type kstep: float, optional

   :returns: **map** -- Ouput array of non-zero valued k-indices where data is valid, -1 elsewhere.
   :rtype: ndarray


.. py:function:: fft2_sector_indexmap(kmap, anglemap, angle=0.0, sector=30.0, kstep=1.0)

   Builds indexmap array of integers ranging from -1 (invalid data)
   and positive integers. Each non-negative integer is a valid k-index computed
   from sector parameters.

   :param kmap: Size of wavevector at each (i,j) indices in the rfft2 ouptut data.
   :type kmap: ndarray
   :param anglemap: Angle of the wavevector at each (i,j) indices in the rfft2 ouptut data.
   :type anglemap: ndarray
   :param angle: Mean angle of the sector in degrees (-180 to 180).
   :type angle: float
   :param sector: Width of the sector in degrees (between 0 and 180)
   :type sector: float
   :param kstep: k resolution in units of minimum step size.
   :type kstep: float, optional

   :returns: **map** -- Ouput array of non-zero valued k-indices where data is valid, -1 elsewhere.
   :rtype: ndarray


.. py:function:: rfft2_kangle(kisize=None, kjsize=None, shape=None)

   Build k,angle arrays based on the size of the rfft2 data.

   :param kisize: i-size of the cropped rfft2 data.
   :type kisize: int
   :param kjsize: j-size of the cropped rfft2 data
   :type kjsize: int
   :param shape: Shape of the original data. This is used to calculate step size. If not
                 given, rectangular data is assumed (equal steps).
   :type shape: (int,int)

   :returns: **k, angle** -- k, angle arrays
   :rtype: ndarray, ndarray


.. py:function:: fft2_kangle(kisize=None, kjsize=None, shape=None)

   Build k,angle arrays based on the size of the fft2 data.

   :param kisize: i-size of the cropped fft2 data.
   :type kisize: int
   :param kjsize: j-size of the cropped fft2 data
   :type kjsize: int
   :param shape: Shape of the original data. This is used to calculate step size. If not
                 given, rectangular data is assumed (equal steps).
   :type shape: (int,int)

   :returns: k, angle arrays
   :rtype: k, angle, ndarray, ndarray


.. py:function:: rfft2_grid(kisize=None, kjsize=None, shape=None)

   Build ki,kj coordinate arrays based on the size of the rfft2.

   :param kisize: i-size of the cropped rfft2 data.
   :type kisize: int
   :param kjsize: j-size of the cropped rfft2 data
   :type kjsize: int
   :param shape: Shape of the original data. This is used to calculate step size. If not
                 given, rectangular data is assumed (equal steps).
   :type shape: (int,int)

   :returns: ki,kj coordinate arrays
   :rtype: ki, kj, ndarray, ndarray


.. py:function:: fft2_grid(kisize=None, kjsize=None, shape=None)

   Build ki,kj coordinate arrays based on the size of the fft2.

   :param kisize: i-size of the cropped fft2 data.
   :type kisize: int
   :param kjsize: j-size of the cropped fft2 data
   :type kjsize: int
   :param shape: Shape of the original data. This is used to calculate step size. If not
                 given, rectangular data is assumed (equal steps).
   :type shape: (int,int)

   :returns: ki,kj coordinate arrays
   :rtype: ki, kj, ndarray, ndarray


.. py:function:: k_indexmap(kisize, kjsize, angle=0, sector=5, kstep=1.0, shape=None)

   Builds indexmap array of integers ranging from -1 (invalid data)
   and positive integers. Each non-negative integer is a valid k-index computed
   from sector parameters.

   :param kisize: Height of the fft data
   :type kisize: int
   :param kjsize: Width of the fft data
   :type kjsize: int
   :param angle: Mean angle of the sector in degrees (-90 to 90).
   :type angle: float
   :param sector: Width of the sector in degrees (between 0 and 180)
   :type sector: float
   :param kstep: k resolution in units of minimum step size.
   :type kstep: float, optional
   :param shape: Shape of the original data. This is used to calculate step size. If not
                 given, rectangular data is assumed (equal steps).
   :type shape: (int,int), optional

   :returns: **map** -- Ouput array of non-zero valued k-indices where data is valid, -1 elsewhere.
   :rtype: ndarray


.. py:function:: as_rfft2_mask(a, axes=(-2, -1))

   Converts fft2 (boolean) mask array into rfft2 (boolean) mask array.



.. py:function:: as_rfft2_conj(a, axes=(-2, -1))

   Converts data from `fft2 space` to `rfft2 conjugate half space`.

   It stores the missing part in the rfft2 data from the full fft2 data.
   The shape of the ouptut is the same as that of the as_rfft2_data. Note that
   you should only access non-zero frequencies. First column does not hold any data.


   .. rubric:: Examples

   >>> a = np.random.randn(32,32)
   >>> f = np.fft.fft2(a)
   >>> rf = np.fft.rfft2(a)
   >>> cf = as_rfft2_conj(f)
   >>> np.allclose(cf[2,5], f[-2,-5])
   True


.. py:function:: as_rfft2_data(a, axes=(-2, -1))

   Converts data from `fft2 space` to `rfft2 half space`.

   .. rubric:: Examples

   >>> a = np.random.randn(32,32)
   >>> f = np.fft.fft2(a)
   >>> rf = np.fft.rfft2(a)
   >>> hf = as_rfft2_data(f)
   >>> np.allclose(hf,rf)
   True


.. py:function:: from_rfft2_data(a, shape=None, axes=(-2, -1))

   Converts halfspace rfft2 data to fullspace fft2 data.

   .. rubric:: Examples

   >>> a = np.random.randn(32,32)
   >>> f = np.fft.fft2(a)
   >>> rf = np.fft.rfft2(a)
   >>> hf = as_rfft2_data(f)
   >>> np.allclose(hf,rf)
   True
   >>> np.allclose(from_rfft2_data(hf, shape = (32,32)), f)
   True


.. py:function:: fft2_k_indexmap(kisize, kjsize, angle=0, sector=5, kstep=1.0, shape=None, mode='rfft2')

   Builds indexmap array of integers ranging from -1 (invalid data)
   and positive integers. Each non-negative integer is a valid k-index computed
   from the sector parameters.

   :param kisize: Height of the fft2 or rfft2 data
   :type kisize: int
   :param kjsize: Width of the fft2 or rfft2 data
   :type kjsize: int
   :param angle: Mean angle of the sector in degrees (-90 to 90).
   :type angle: float
   :param sector: Width of the sector in degrees (between 0 and 180)
   :type sector: float
   :param kstep: k resolution in units of minimum step size.
   :type kstep: float, optional
   :param shape: Shape of the original data. This is used to calculate step size. If not
                 given, rectangular data is assumed (equal steps).
   :type shape: (int,int), optional
   :param mode: Describes inpud data mode. Either 'rfft2' or 'fft2'.
   :type mode: str, optional

   :returns: **map** -- A fullsize ouput array of non-zero valued k-indices where data is valid, -1 elsewhere.
   :rtype: ndarray


.. py:function:: plot_indexmap(graph, mode='rfft2')

   Plots indexmap array. If mode == "rfft2" it plots half-space data,
   If mode =="fft2" it performs plotting of full-spaced data.


.. py:function:: k_select(data, angle, sector=5, kstep=1, k=None, shape=None, mask=None, mode='rfft2')

   k-selection and k-averaging of normalized (and merged) correlation data.

   This function takes (...,i,j,n) correlation data and performs k-based selection
   and averaging of the data. If you analyzed masked video, you must provide
   the mask.

   :param deta: Input correlation data of shape (...,i,j,n)
   :type deta: array_like
   :param angle: Angle between the j axis and the direction of k-vector
   :type angle: float
   :param sector: Defines sector angle, k-data is avergaed between angle+sector and angle-sector angles
   :type sector: float, optional
   :param kstep: Defines an approximate k step in pixel units
   :type kstep: float, optional
   :param k: If provided, only return at a given k value (and not at all non-zero k values)
   :type k: float or list of floats, optional
   :param shape: Shape of the original video frame. If shape is not rectangular, it must
                 be provided.
   :type shape: tuple
   :param mask: A boolean array. This is the mask used in :func:`.video.mask`.
   :type mask: ndarray, optional

   :returns: **out** -- If k s not defined, this is an iterator that yields a tuple of (k_avg, data_avg)
             of actual (mean) k and averaged data. If k is a list of indices, it returns
             an iterator that yields a tuple of (k_avg, data_avg) for every non-zero data
             if k is an integer, it returns a tuple of (k_avg, data_avg) for a given k-index.
   :rtype: iterator, or tuple