gwkokab.analysis.core.synthetic_pe
==================================

.. py:module:: gwkokab.analysis.core.synthetic_pe


Attributes
----------

.. autoapisummary::

   gwkokab.analysis.core.synthetic_pe.ErrorFunctionRegistryType


Classes
-------

.. autoapisummary::

   gwkokab.analysis.core.synthetic_pe.SyntheticAnalyticalPE
   gwkokab.analysis.core.synthetic_pe.SyntheticDiscretePE


Functions
---------

.. autoapisummary::

   gwkokab.analysis.core.synthetic_pe.calculate_js_metrics
   gwkokab.analysis.core.synthetic_pe.histogram_pdf
   gwkokab.analysis.core.synthetic_pe.js_divergence_from_histograms
   gwkokab.analysis.core.synthetic_pe.synthetic_analytical_pe_main
   gwkokab.analysis.core.synthetic_pe.synthetic_discrete_pe_main


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

.. py:class:: SyntheticAnalyticalPE(filename: str, discrete_waveform: str, coords: Optional[tuple[str, Ellipsis]] = None)

   Bases: :py:obj:`gwkokab.analysis.core.utils.PRNGKeyMixin`


   Mixin class that provides a random number generator key and seed management for
   classes that require random number generation.

   This mixin allows classes to initialize a random key based on a seed and provides a
   property to access the current random key, which is automatically split to ensure
   independent random streams across different parts of the code.


   .. py:method:: generate_parameter_estimates()


   .. py:attribute:: coords
      :value: None



   .. py:attribute:: discrete_waveform


   .. py:attribute:: filename


   .. py:attribute:: waveform_name
      :value: 'GWKokabSyntheticAnalyticalPE'



.. py:class:: SyntheticDiscretePE(filename: str, dataset: Literal['events', 'buffer_events'], error_params_filename: str, size: int, derive_parameters: bool = False, coords: Optional[list[str]] = None, is_delta_error: bool = False)

   Bases: :py:obj:`gwkokab.analysis.core.utils.PRNGKeyMixin`


   Mixin class that provides a random number generator key and seed management for
   classes that require random number generation.

   This mixin allows classes to initialize a random key based on a seed and provides a
   property to access the current random key, which is automatically split to ensure
   independent random streams across different parts of the code.


   .. py:method:: generate_parameter_estimates()

      Generates parameter estimates based on the defined error functions.

      This method should be implemented in subclasses to generate parameter estimates
      using the error functions defined in the `error_function_registry` property.



   .. py:attribute:: coords
      :value: None



   .. py:attribute:: dataset


   .. py:attribute:: derive_parameters
      :value: False



   .. py:property:: error_function_registry
      :type: ErrorFunctionRegistryType


      Returns a dictionary mapping parameters to their corresponding error
      functions.

      The keys of the dictionary can be either strings representing parameter names,
      tuples of strings representing multiple parameter names, or instances of the
      Parameters enum (P) or tuples of such instances. The values are callable functions
      that define how to apply errors to the corresponding parameters.

      :returns: A dictionary mapping parameters to their error functions.
      :rtype: ErrorFunctionRegistryType


   .. py:attribute:: error_params_filename


   .. py:attribute:: filename


   .. py:attribute:: is_delta_error
      :value: False



   .. py:attribute:: root_dir


   .. py:attribute:: size


   .. py:attribute:: waveform_name
      :value: 'GWKokabSyntheticDiscretePE'



.. py:function:: calculate_js_metrics(discrete_samples: numpy.ndarray, analytical_samples: numpy.ndarray, bins: int) -> numpy.ndarray

   Calculates the Jensen-Shannon divergence between the discrete and analytical
   samples for each parameter.

   :param discrete_samples: Discrete samples from the parameter estimation, shape (num_samples, num_parameters).
   :type discrete_samples: np.ndarray
   :param analytical_samples: Analytical samples generated from the error model, shape (num_samples, num_parameters).
   :type analytical_samples: np.ndarray
   :param bins: Number of bins to use for the histogram estimation of the PDFs.
   :type bins: int

   :returns: Array of Jensen-Shannon divergences for each parameter.
   :rtype: np.ndarray


.. py:function:: histogram_pdf(samples: numpy.ndarray, bins: int, value_range: tuple[float, float], weights: Optional[numpy.ndarray] = None) -> tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]

   Build a normalized histogram-based discrete PDF.


.. py:function:: js_divergence_from_histograms(p: numpy.ndarray, q: numpy.ndarray) -> numpy.ndarray

   Jensen-Shannon divergence using natural log.

   Range: [0, ln(2)].


.. py:function:: synthetic_analytical_pe_main()

.. py:function:: synthetic_discrete_pe_main()

   Command-line interface for generating synthetic discrete parameter estimation
   samples.


.. py:type:: ErrorFunctionRegistryType
   :canonical: dict[str | Parameters | tuple[str, ...] | tuple[Parameters, ...], tuple[tuple[str, ...], Callable[..., np.ndarray]]]


   Type alias for the error function registry mapping.