firecrown.likelihood_base ========================= .. py:module:: firecrown.likelihood_base .. autoapi-nested-parse:: Base classes for likelihood framework. This module contains all abstract base classes and core types used throughout the likelihood framework. It is designed to be dependency-free with respect to the firecrown.likelihood package to avoid circular import issues. Classes moved from: - likelihood/_base.py: Likelihood, NamedParameters, Statistic, Source, Tracer, etc. Attributes ---------- .. autoapisummary:: firecrown.likelihood_base.SOURCE_GALAXY_SYSTEMATIC_DEFAULT_DELTA_Z firecrown.likelihood_base.SOURCE_GALAXY_SYSTEMATIC_DEFAULT_SIGMA_Z Exceptions ---------- .. autoapisummary:: firecrown.likelihood_base.StatisticUnreadError Classes ------- .. autoapisummary:: firecrown.likelihood_base.Likelihood firecrown.likelihood_base.NamedParameters firecrown.likelihood_base.Statistic firecrown.likelihood_base.GuardedStatistic firecrown.likelihood_base.TrivialStatistic firecrown.likelihood_base.SourceSystematic firecrown.likelihood_base.Source firecrown.likelihood_base.Tracer firecrown.likelihood_base.SourceGalaxyArgs firecrown.likelihood_base.SourceGalaxySystematic firecrown.likelihood_base.SourceGalaxyPhotoZShift firecrown.likelihood_base.PhotoZShift firecrown.likelihood_base.PhotoZShiftFactory firecrown.likelihood_base.SourceGalaxyPhotoZShiftandStretch firecrown.likelihood_base.PhotoZShiftandStretch firecrown.likelihood_base.PhotoZShiftandStretchFactory firecrown.likelihood_base.SourceGalaxySelectField firecrown.likelihood_base.SourceGalaxy Functions --------- .. autoapisummary:: firecrown.likelihood_base.dndz_shift_and_stretch_active firecrown.likelihood_base.dndz_shift_and_stretch_passive Module Contents --------------- .. py:class:: Likelihood(*, parameter_prefix = None, raise_on_unused_parameter = True) Bases: :py:obj:`firecrown.updatable.Updatable` .. autoapi-inheritance-diagram:: firecrown.likelihood_base.Likelihood :parts: 1 Likelihood is an abstract class. Concrete subclasses represent specific likelihood forms (e.g. gaussian with constant covariance matrix, or Student's t, etc.). Concrete subclasses must have an implementation of both :meth:`read` and :meth:`compute_loglike`. Note that abstract subclasses of Likelihood might implement these methods, and provide other abstract methods for their subclasses to implement. .. py:attribute:: raise_on_unused_parameter :value: True .. py:method:: read(sacc_data) :abstractmethod: Read the covariance matrix for this likelihood from the SACC file. :param sacc_data: The SACC data object to be read .. py:method:: make_realization_vector() :abstractmethod: Create a new realization of the model. This new realization uses the previously computed theory vector and covariance matrix. :return: the new realization of the theory vector .. py:method:: make_realization(sacc_data, add_noise = True, strict = True) Create a new realization of the model. This realization uses the previously computed theory vector and covariance matrix. :param sacc_data: The SACC data object containing the covariance matrix :param add_noise: If True, add noise to the realization. If False, return only the theory vector. :param strict: If True, check that the indices of the realization cover all the indices of the SACC data object. :return: the new SACC object containing the new realization .. py:method:: compute_loglike_for_sampling(tools) Compute the log-likelihood of generic CCL data, swallowing some CCL errors. If CCL raises an error indicating an integration error, this function returns -np.inf. :param tools: the ModelingTools to be used in calculating the likelihood :return: the log-likelihood .. py:method:: compute_loglike(tools) :abstractmethod: Compute the log-likelihood of generic CCL data. :param tools: the ModelingTools to be used in calculating the likelihood :return: the log-likelihood .. py:class:: NamedParameters(mapping = None) Provides access to a set of parameters of a given set of types. Access to the parameters is provided by a type-safe interface. Each of the access functions assures that the parameter value it returns is of the specified type. .. py:method:: get_bool(name, default_value = None) Return the named parameter as a bool. :param name: the name of the parameter to be returned :param default_value: the default value if the parameter is not found :return: the value of the parameter (or the default value) .. py:method:: get_string(name, default_value = None) Return the named parameter as a string. :param name: the name of the parameter to be returned :param default_value: the default value if the parameter is not found :return: the value of the parameter (or the default value) .. py:method:: get_int(name, default_value = None) Return the named parameter as an int. :param name: the name of the parameter to be returned :param default_value: the default value if the parameter is not found :return: the value of the parameter (or the default value) .. py:method:: get_float(name, default_value = None) Return the named parameter as a float. :param name: the name of the parameter to be returned :param default_value: the default value if the parameter is not found :return: the value of the parameter (or the default value) .. py:method:: get_int_array(name) Return the named parameter as a numpy array of int. :param name: the name of the parameter to be returned :return: the value of the parameter .. py:method:: get_float_array(name) Return the named parameter as a numpy array of float. :param name: the name of the parameter to be returned :return: the value of the parameter .. py:method:: to_set() Return the contained data as a set. :return: the value of the parameter as a set .. py:method:: set_from_basic_dict(basic_dict) Set the contained data from a dictionary of basic types. :param basic_dict: the mapping from strings to values used for initialization .. py:method:: convert_to_basic_dict() Convert a NamedParameters object to a dictionary of built-in types. :return: a dictionary containing the parameters as built-in Python types .. py:method:: __contains__(key) Check if a key is in the NamedParameters object. :param key: the key to check :return: True if the key is in the NamedParameters object, False otherwise .. py:exception:: StatisticUnreadError(stat) Bases: :py:obj:`RuntimeError` .. autoapi-inheritance-diagram:: firecrown.likelihood_base.StatisticUnreadError :parts: 1 Error raised when accessing an un-read statistic. Run-time error indicating an attempt has been made to use a statistic that has not had `read` called in it. .. py:attribute:: statistic .. py:class:: Statistic(parameter_prefix = None) Bases: :py:obj:`firecrown.updatable.Updatable` .. autoapi-inheritance-diagram:: firecrown.likelihood_base.Statistic :parts: 1 The abstract base class for all physics-related statistics. Statistics read data from a SACC object as part of a multi-phase initialization. They manage a :class:`DataVector` and, given a :class:`ModelingTools` object, can compute a :class:`TheoryVector`. Statistics represent things like two-point functions and mass functions. .. py:attribute:: sacc_indices :type: None | numpy.typing.NDArray[numpy.int64] .. py:attribute:: ready :value: False .. py:attribute:: computed_theory_vector :value: False .. py:attribute:: theory_vector :type: None | firecrown.data_types.TheoryVector :value: None .. py:method:: read(_) Read the data for this statistic and mark it as ready for use. Derived classes that override this function should make sure to call the base class method using: .. code-block:: python super().read(sacc_data) as the last thing they do. :param _: currently unused, but required by the interface. .. py:method:: get_data_vector() :abstractmethod: Gets the statistic data vector. :return: The data vector. .. py:method:: compute_theory_vector(tools) Compute a statistic from sources, applying any systematics. :param tools: the modeling tools used to compute the theory vector. :return: The computed theory vector. .. py:method:: get_theory_vector() Returns the last computed theory vector. Raises a RuntimeError if the vector has not been computed. :return: The already-computed theory vector. .. py:class:: GuardedStatistic(stat) Bases: :py:obj:`firecrown.updatable.Updatable` .. autoapi-inheritance-diagram:: firecrown.likelihood_base.GuardedStatistic :parts: 1 An internal class used to maintain state on statistics. :class:`GuardedStatistic` is used by the framework to maintain and validate the state of instances of classes derived from :class:`Statistic`. .. py:attribute:: statistic .. py:method:: read(sacc_data) Read whatever data is needed from the given :class:`sacc.Sacc` object. After this function is called, the object should be prepared for the calling of the methods :meth:`get_data_vector` and :meth:`compute_theory_vector`. :param sacc_data: The SACC data object to read from. .. py:method:: get_data_vector() Return the contained :class:`Statistic`'s data vector. :class:`GuardedStatistic` ensures that :meth:`read` has been called. first. :return: The most recently calculated data vector. .. py:method:: compute_theory_vector(tools) Return the contained :class:`Statistic`'s computed theory vector. :class:`GuardedStatistic` ensures that :meth:`read` has been called. first. :param tools: the modeling tools used to compute the theory vector. :return: The computed theory vector. .. py:class:: TrivialStatistic Bases: :py:obj:`Statistic` .. autoapi-inheritance-diagram:: firecrown.likelihood_base.TrivialStatistic :parts: 1 A minimal statistic only to be used for testing Gaussian likelihoods. It returns a :class:`DataVector` and :class:`TheoryVector` each of which is three elements long. The SACC data provided to :meth:`TrivialStatistic.read` must supply the necessary values. .. py:attribute:: count :value: 3 .. py:attribute:: data_vector :type: None | firecrown.data_types.DataVector :value: None .. py:attribute:: mean .. py:attribute:: computed_theory_vector :value: False .. py:method:: read(sacc_data) Read the necessary items from the sacc data. :param sacc_data: The SACC data object to be read .. py:method:: get_data_vector() Return the data vector; raise exception if there is none. :return: The data vector. .. py:class:: SourceSystematic(parameter_prefix = None) Bases: :py:obj:`firecrown.updatable.Updatable` .. autoapi-inheritance-diagram:: firecrown.likelihood_base.SourceSystematic :parts: 1 An abstract systematic class (e.g., shear biases, photo-z shifts, etc.). This class currently has no methods at all, because the argument types for the `apply` method of different subclasses are different. .. py:method:: read(sacc_data) Call to allow this object to read from the appropriate sacc data. :param sacc_data: The SACC data object to be read .. py:class:: Source(sacc_tracer) Bases: :py:obj:`firecrown.updatable.Updatable` .. autoapi-inheritance-diagram:: firecrown.likelihood_base.Source :parts: 1 The abstract base class for all sources. .. py:attribute:: cosmo_hash :type: None | int .. py:attribute:: tracers :type: collections.abc.Sequence[Tracer] .. py:attribute:: sacc_tracer .. py:method:: read_systematics(sacc_data) :abstractmethod: Abstract method to read the systematics for this source from the SACC file. :param sacc_data: The SACC data object to be read .. py:method:: read(sacc_data) Read the data for this source from the SACC file. :param sacc_data: The SACC data object to be read .. py:method:: get_scale() :abstractmethod: Abstract method to return the scale for this `Source`. :return: the scale .. py:method:: create_tracers(tools) :abstractmethod: Abstract method to create tracers for this Source. :param tools: The modeling tools used for creating the tracers .. py:method:: get_tracers(tools) Return the tracer for the given cosmology. This method caches its result, so if called a second time with the same cosmology, no calculation needs to be done. :param tools: The modeling tools used for creating the tracers :return: the list of tracers .. py:class:: Tracer(tracer, tracer_name = None, field = None, pt_tracer = None, halo_profile = None, halo_2pt = None) Extending the pyccl.Tracer object with additional information. Bundles together a pyccl.Tracer object with optional information about the underlying 3D field, or a pyccl.nl_pt.PTTracer and halo profiles. .. py:method:: determine_field_name(field, tracer) :staticmethod: Gets a field name for a tracer. This function encapsulates the policy for determining the value to be assigned to the :attr:`field` attribute of a :class:`Tracer`. It is a static method only to keep it grouped with the class for which it is defining the initialization policy. :param field: the (stub) name of the field :param tracer: the name of the tracer :return: the full name of the field .. py:attribute:: ccl_tracer .. py:attribute:: tracer_name :type: str .. py:attribute:: field .. py:attribute:: pt_tracer :value: None .. py:attribute:: halo_profile :value: None .. py:attribute:: halo_2pt :value: None .. py:property:: has_pt :type: bool Answer whether we have a perturbation theory tracer. :return: True if we have a pt_tracer, and False if not. .. py:property:: has_hm :type: bool Answer whether we have a halo model profile. Return True if we have a halo_profile, and False if not. .. py:class:: SourceGalaxyArgs Class for galaxy based sources arguments. .. py:attribute:: z :type: numpy.typing.NDArray[numpy.float64] .. py:attribute:: dndz :type: numpy.typing.NDArray[numpy.float64] .. py:attribute:: scale :type: float :value: 1.0 .. py:attribute:: field :type: str :value: 'delta_matter' .. py:class:: SourceGalaxySystematic(parameter_prefix = None) Bases: :py:obj:`SourceSystematic`, :py:obj:`Generic`\ [\ :py:obj:`_SourceGalaxyArgsT`\ ] .. autoapi-inheritance-diagram:: firecrown.likelihood_base.SourceGalaxySystematic :parts: 1 Abstract base class for all galaxy-based source systematics. .. py:method:: apply(tools, tracer_arg) :abstractmethod: Apply method to include systematics in the tracer_arg. :param tools: the modeling tools use to update the tracer arg :param tracer_arg: the original source galaxy tracer arg to which we apply the systematic. :return: a new source galaxy tracer arg with the systematic applied .. py:data:: SOURCE_GALAXY_SYSTEMATIC_DEFAULT_DELTA_Z :value: 0.0 .. py:data:: SOURCE_GALAXY_SYSTEMATIC_DEFAULT_SIGMA_Z :value: 1.0 .. py:function:: dndz_shift_and_stretch_active(z, dndz, delta_z, sigma_z) Shift and stretch the photo-z distribution using an active transformation. We use "makima" interpolation, a cubic spline method based on the modified Akima algorithm. This approach prevents overshooting when the data remains constant for more than two consecutive nodes. Additionally, we set `extrapolate=False` and we set extrapolated values to zero. The active transformation preserves the redshift array and modifies the dndz array. This transformation introduces an interpolation error on dndz. **Sign convention:** For the pure-shift case (:math:`\sigma_z = 1`), the transformed distribution satisfies: .. math:: n'(z) = n(z + \delta_z) A positive :math:`\delta_z` therefore shifts the distribution toward *lower* redshifts (i.e. the peak moves to :math:`z_{\rm peak} - \delta_z`). .. note:: This sign convention is **opposite** to the one used in the `Cosmosis Standard Library `_ ``photoz_bias`` module (additive mode), which implements :math:`n'(z) = n(z - \Delta z_{\rm CSL})`, so that a positive shift moves the distribution toward *higher* redshifts. The relationship between the two conventions is :math:`\delta_z = -\Delta z_{\rm CSL}`. :param z: the redshifts :param dndz: the dndz :param delta_z: the photo-z shift (positive values shift the distribution toward lower redshifts) :param sigma_z: the photo-z stretch :return: the shifted and stretched dndz .. py:function:: dndz_shift_and_stretch_passive(z, dndz, delta_z, sigma_z) Shift and stretch the photo-z distribution using a passive transformation. The passive transformation modifies the redshift array and preserves the dndz values. For the pure-shift case (:math:`\sigma_z = 1`), each tabulated redshift :math:`z_i` is replaced by :math:`z_i - \delta_z`, so the distribution is shifted toward *lower* redshifts when :math:`\delta_z > 0`. This is equivalent to evaluating the original distribution at :math:`z + \delta_z`: .. math:: n'(z) = n(z + \delta_z) .. note:: See :func:`dndz_shift_and_stretch_active` for details on the sign convention. :param z: the redshifts :param dndz: the dndz :param delta_z: the photo-z shift (positive values shift the distribution toward lower redshifts) :param sigma_z: the photo-z stretch :return: the shifted and stretched dndz .. py:class:: SourceGalaxyPhotoZShift(sacc_tracer, active = True) Bases: :py:obj:`SourceGalaxySystematic`\ [\ :py:obj:`_SourceGalaxyArgsT`\ ], :py:obj:`Generic`\ [\ :py:obj:`_SourceGalaxyArgsT`\ ] .. autoapi-inheritance-diagram:: firecrown.likelihood_base.SourceGalaxyPhotoZShift :parts: 1 A photo-z shift bias. This systematic shifts the photo-z distribution by some amount ``delta_z``. The transformation applied is :math:`n'(z) = n(z + \delta_z)`, so a *positive* ``delta_z`` shifts the distribution toward *lower* redshifts. .. note:: See :func:`dndz_shift_and_stretch_active` for details on the sign convention. The following parameters are special Updatable parameters, which means that they can be updated by the sampler, sacc_tracer is going to be used as a prefix for the parameters: :ivar delta_z: the photo-z shift (positive values shift the distribution toward lower redshifts). .. py:attribute:: delta_z .. py:method:: apply(tools, tracer_arg) Apply a shift to the photo-z distribution of a source. :param tools: the modeling tools use to update the tracer arg :param tracer_arg: the original source galaxy tracer arg to which we apply the systematic. :return: a new source galaxy tracer arg with the systematic applied .. py:class:: PhotoZShift(sacc_tracer, active = True) Bases: :py:obj:`SourceGalaxyPhotoZShift` .. autoapi-inheritance-diagram:: firecrown.likelihood_base.PhotoZShift :parts: 1 Photo-z shift systematic. .. py:class:: PhotoZShiftFactory(/, **data) Bases: :py:obj:`pydantic.BaseModel` .. autoapi-inheritance-diagram:: firecrown.likelihood_base.PhotoZShiftFactory :parts: 1 Factory class for PhotoZShift objects. .. py:attribute:: model_config Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. .. py:attribute:: type :type: Annotated[Literal['PhotoZShiftFactory'], Field(description='The type of the systematic.')] :value: 'PhotoZShiftFactory' .. py:method:: create(bin_name) Create a PhotoZShift object with the given tracer name. .. py:method:: create_global() Create a PhotoZShift object with the given tracer name. .. py:class:: SourceGalaxyPhotoZShiftandStretch(sacc_tracer, active = True) Bases: :py:obj:`SourceGalaxyPhotoZShift`\ [\ :py:obj:`_SourceGalaxyArgsT`\ ] .. autoapi-inheritance-diagram:: firecrown.likelihood_base.SourceGalaxyPhotoZShiftandStretch :parts: 1 A photo-z shift & stretch bias. This systematic shifts and stretches the photo-z distribution by ``delta_z`` and ``sigma_z``, respectively. The shift follows the same sign convention as :class:`SourceGalaxyPhotoZShift`: a *positive* ``delta_z`` shifts the distribution toward *lower* redshifts (i.e. :math:`n'(z) = n(z + \delta_z)` for the pure-shift case :math:`\sigma_z = 1`). .. note:: See :func:`dndz_shift_and_stretch_active` for details on the sign convention. The following parameters are special Updatable parameters, which means that they can be updated by the sampler, sacc_tracer is going to be used as a prefix for the parameters: :ivar delta_z: the photo-z shift (positive values shift the distribution toward lower redshifts). :ivar sigma_z: the photo-z stretch. .. py:attribute:: sigma_z .. py:method:: apply(_, tracer_arg) Apply a shift & stretch to the photo-z distribution of a source. .. py:class:: PhotoZShiftandStretch(sacc_tracer, active = True) Bases: :py:obj:`SourceGalaxyPhotoZShiftandStretch` .. autoapi-inheritance-diagram:: firecrown.likelihood_base.PhotoZShiftandStretch :parts: 1 Photo-z shift and stretch systematic. .. py:class:: PhotoZShiftandStretchFactory(/, **data) Bases: :py:obj:`pydantic.BaseModel` .. autoapi-inheritance-diagram:: firecrown.likelihood_base.PhotoZShiftandStretchFactory :parts: 1 Factory class for PhotoZShiftandStretch objects. .. py:attribute:: model_config Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. .. py:attribute:: type :type: Annotated[Literal['PhotoZShiftandStretchFactory'], Field(description='The type of the systematic.')] :value: 'PhotoZShiftandStretchFactory' .. py:method:: create(bin_name) Create a PhotoZShiftandStretch object with the given tracer name. .. py:method:: create_global() Create a PhotoZShiftandStretch object with the given tracer name. .. py:class:: SourceGalaxySelectField(field = 'delta_matter') Bases: :py:obj:`SourceGalaxySystematic`\ [\ :py:obj:`_SourceGalaxyArgsT`\ ], :py:obj:`Generic`\ [\ :py:obj:`_SourceGalaxyArgsT`\ ] .. autoapi-inheritance-diagram:: firecrown.likelihood_base.SourceGalaxySelectField :parts: 1 The source galaxy select field systematic. A systematic that allows specifying the 3D field that will be used to select the 3D power spectrum when computing the angular power spectrum. .. py:attribute:: field :value: 'delta_matter' .. py:method:: apply(tools, tracer_arg) Apply method to include systematics in the tracer_arg. :param tools: the modeling tools used to update the tracer_arg :param tracer_arg: the original source galaxy tracer arg to which we apply the systematics. :return: a new source galaxy tracer arg with the systematic applied .. py:class:: SourceGalaxy(*, sacc_tracer, systematics = None) Bases: :py:obj:`Source`, :py:obj:`Generic`\ [\ :py:obj:`_SourceGalaxyArgsT`\ ] .. autoapi-inheritance-diagram:: firecrown.likelihood_base.SourceGalaxy :parts: 1 Source class for galaxy based sources. .. py:attribute:: sacc_tracer .. py:attribute:: current_tracer_args :type: None | _SourceGalaxyArgsT :value: None .. py:attribute:: systematics :type: firecrown.updatable.UpdatableCollection[SourceGalaxySystematic] .. py:attribute:: tracer_args :type: _SourceGalaxyArgsT .. py:method:: read_systematics(sacc_data) Read the systematics for this source from the SACC file. :param sacc_data: The SACC data object to be read