poplar.selection
================

.. py:module:: poplar.selection

.. autoapi-nested-parse::

   Functions for computing noise-realised quantities from optimal SNRs, for the purposes of estimating signal/population detectability.

   ..
       !! processed by numpydoc !!


Functions
---------

.. autoapisummary::

   poplar.selection.matched_filter_snr_from_optimal_snr
   poplar.selection.detection_probability_from_optimal_snr
   poplar.selection.selection_function_from_optimal_snr


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

.. py:function:: matched_filter_snr_from_optimal_snr(optimal_snr: Union[numpy.ndarray, torch.tensor, float], number_of_detectors=1)

   
   Computes detection probabilities from optimal snr values with respect to a detection threshold by sampling
   a non-central chi-square distribution.

   This function is not GPU-compatible and will therefore force synchronisation and movement of data between CPU and GPU. 
   The outputs will be on the same device as the inputs.

   :Parameters:

       **optimal_snr** : Union[np.ndarray, torch.tensor, float]
           Optimal snr values to convert into matched filter snrs.

       **number_of_detectors** : int, optional
           The number of detectors in use, by default 1, by default 1



   :Returns:

       matched_filter_snrs: np.ndarray or torch.tensor
           Matched filter SNRs corresponding to the given optimal SNRs.











   ..
       !! processed by numpydoc !!

.. py:function:: detection_probability_from_optimal_snr(optimal_snr: Union[numpy.ndarray, torch.tensor, float], threshold: float, number_of_detectors=1)

   
   Computes detection probabilities from optimal snr values with respect to a detection threshold using the survival function of
   a non-central chi-square distribution.

   This function is not GPU-compatible and will therefore force synchronisation and movement of data between CPU and GPU. 
   The outputs will be on the same device as the inputs.

   :Parameters:

       **optimal_snr** : np.ndarray or torch.tensor
           Optimal snr values to convert into detection probabilities.

       **threshold** : float
           The detection threshold.

       **number_of_detectors** : int, optional
           The number of detectors in use, by default 1



   :Returns:

       detection_probabilities: np.ndarray or torch.tensor
           The resuling detection probablities for the given detection threshold.











   ..
       !! processed by numpydoc !!

.. py:function:: selection_function_from_optimal_snr(optimal_snr: Union[numpy.ndarray, torch.tensor], threshold: float, number_of_detectors=1)

   
   Computes the selection function (i.e. the mean detection probability) from a set of optimal snr values with respect to a detection threshold using the survival function of
   a non-central chi-square distribution.

   This function is not GPU-compatible and will therefore force synchronisation and movement of data between CPU and GPU. 
   The outputs will be on the same device as the inputs.

   :Parameters:

       **optimal_snr** : np.ndarray or torch.tensor
           Optimal snr values to convert into detection probabilities.

       **threshold** : float
           The detection threshold.

       **number_of_detectors** : int, optional
           The number of detectors in use, by default 1



   :Returns:

       selection function: np.ndarray or torch.tensor
           The resuling selection function for the given detection threshold.











   ..
       !! processed by numpydoc !!