petitRADTRANS.sbi.observation
=============================

.. py:module:: petitRADTRANS.sbi.observation

.. autoapi-nested-parse::

   Observation containers and block builders for amortized inference.



Classes
-------

.. autoapisummary::

   petitRADTRANS.sbi.observation.ObservationModality
   petitRADTRANS.sbi.observation.ObservationBlock
   petitRADTRANS.sbi.observation.EncodedObservation
   petitRADTRANS.sbi.observation.ObservationEncoder
   petitRADTRANS.sbi.observation.PreStackedObservations


Functions
---------

.. autoapisummary::

   petitRADTRANS.sbi.observation.build_observation_block
   petitRADTRANS.sbi.observation.build_observation_blocks_from_sample
   petitRADTRANS.sbi.observation.build_observation_block_batch


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

.. py:class:: ObservationModality

   Bases: :py:obj:`str`, :py:obj:`enum.Enum`


   Supported observation block types for SBI conditioning.


   .. py:attribute:: SPECTRUM
      :value: 'spectrum'



   .. py:attribute:: PHOTOMETRY
      :value: 'photometry'



   .. py:attribute:: TIME_SERIES
      :value: 'time_series'



   .. py:attribute:: AUXILIARY
      :value: 'auxiliary'



.. py:class:: ObservationBlock

   Represent one modality-specific observation block.

   Attributes:
       name:
           Stable identifier of the block within a task.
       modality:
           Semantic block type used to dispatch encoding logic.
       values:
           Observed values after any task-level preprocessing.
       uncertainties:
           Optional per-element uncertainty representation.
       coordinates:
           Optional coordinate arrays such as wavelengths or timestamps.
       mask:
           Optional mask applied to the values.
       metadata:
           Additional instrument and preprocessing metadata.


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: modality
      :type:  ObservationModality


   .. py:attribute:: values
      :type:  Any


   .. py:attribute:: uncertainties
      :type:  Any
      :value: None



   .. py:attribute:: coordinates
      :type:  Any
      :value: None



   .. py:attribute:: mask
      :type:  Any
      :value: None



   .. py:attribute:: metadata
      :type:  Mapping[str, Any]


.. py:class:: EncodedObservation

   Encoded representation consumed by a posterior estimator.


   .. py:attribute:: embedding
      :type:  Any


   .. py:attribute:: mask
      :type:  Any
      :value: None



   .. py:attribute:: metadata
      :type:  Mapping[str, Any]


.. py:class:: ObservationEncoder

   Bases: :py:obj:`abc.ABC`


   Transform structured observation blocks into model-ready embeddings.


   .. py:method:: encode(blocks: list[ObservationBlock]) -> EncodedObservation
      :abstractmethod:


      Encode a list of observation blocks into a shared representation.



   .. py:method:: batch_encode(observations: list[list[ObservationBlock]]) -> list[EncodedObservation]

      Encode multiple observations using repeated single-item encoding.



.. py:function:: build_observation_block(name: str, modality: ObservationModality | str, values: Any, uncertainties: Any = None, coordinates: Any = None, mask: Any = None, metadata: Mapping[str, Any] | None = None) -> ObservationBlock

   Build one observation block with modality normalization.


.. py:function:: build_observation_blocks_from_sample(observation_payloads: Mapping[str, Mapping[str, Any]], modalities: Mapping[str, str], sample_index: int) -> list[ObservationBlock]

   Build modality-aware observation blocks for one simulated sample.


.. py:function:: build_observation_block_batch(observation_payloads: Mapping[str, Mapping[str, Any]], modalities: Mapping[str, str]) -> list[list[ObservationBlock]]

   Build observation blocks for each sample in a batched payload.


.. py:class:: PreStackedObservations

   Pre-stacked observation arrays ready to cross the JAX JIT boundary.

   All per-sample ObservationBlock data has been extracted into dense numpy
   arrays before this object is constructed, so JAX can trace through the
   encoder without re-compiling per batch.

   Attributes
   ----------
   stacked_blocks:
       One ``(values, uncertainties, coordinates, mask, log_median_flux,
       spectral_auxiliary_values, global_spectrum_scale)`` tuple per
       observation block. ``values``, ``uncertainties``, ``coordinates``,
       ``mask``, and ``spectral_auxiliary_values`` have shape ``(batch_size,
       n_wl)``. ``log_median_flux`` and ``global_spectrum_scale`` have shape
       ``(batch_size,)``.
   modalities:
       Modality value string for each block, e.g. ``'spectrum'``.
       Treated as static metadata by JAX (does not trigger retrace between
       batches since it is constant for a given SBI task).


   .. py:attribute:: stacked_blocks
      :type:  tuple


   .. py:attribute:: modalities
      :type:  tuple