petitRADTRANS.sbi.inference =========================== .. py:module:: petitRADTRANS.sbi.inference .. autoapi-nested-parse:: User-facing amortized inference services. Classes ------- .. autoapisummary:: petitRADTRANS.sbi.inference.OODDiagnostic petitRADTRANS.sbi.inference.AmortizedRetrievalResult petitRADTRANS.sbi.inference.AmortizedRetrieval Functions --------- .. autoapisummary:: petitRADTRANS.sbi.inference._coerce_block_array petitRADTRANS.sbi.inference._robust_score_summary Module Contents --------------- .. py:function:: _coerce_block_array(values: Any, target_size: int) -> numpy.ndarray | None .. py:function:: _robust_score_summary(values: numpy.ndarray, center: numpy.ndarray, scale: numpy.ndarray, valid_mask: numpy.ndarray) -> tuple[float, float] .. py:class:: OODDiagnostic Describe whether an observation is inside the training support. Attributes ---------- score: Scalar out-of-distribution score. threshold: Optional threshold used to convert the score into a pass/fail decision. passed: Optional boolean indicating whether the observation passed the OOD test. metadata: Auxiliary diagnostic metadata. .. py:attribute:: score :type: float .. py:attribute:: threshold :type: float | None :value: None .. py:attribute:: passed :type: bool | None :value: None .. py:attribute:: metadata :type: Mapping[str, Any] .. py:class:: AmortizedRetrievalResult Return type for amortized inference queries. Attributes ---------- posterior: Posterior samples and any attached diagnostics. posterior_predictive: Optional posterior-predictive report for the same observation. ood_diagnostic: Optional in/out-of-distribution assessment. metadata: Additional metadata such as preprocessing usage during inference. .. py:attribute:: posterior :type: petitRADTRANS.sbi.posterior.PosteriorSamples .. py:attribute:: posterior_predictive :type: Any :value: None .. py:attribute:: ood_diagnostic :type: OODDiagnostic | None :value: None .. py:attribute:: metadata :type: Mapping[str, Any] .. py:class:: AmortizedRetrieval(task: petitRADTRANS.sbi.task.SBITask, posterior_estimator: petitRADTRANS.sbi.posterior.PosteriorEstimator, simulator: petitRADTRANS.sbi.simulator.RuntimeSimulator | None = None, preprocessing_metadata: petitRADTRANS.sbi.preprocessing.TaskPreprocessingMetadata | Mapping[str, Any] | None = None) Serve trained SBI models through a retrieval-like interface. Parameters ---------- task: SBI task compatible with the trained posterior. posterior_estimator: Trained posterior estimator used for encoding and sampling. simulator: Optional simulator override used for posterior-predictive generation. preprocessing_metadata: Optional preprocessing metadata or payload. When omitted the inference service attempts to recover the preprocessing payload saved inside the posterior artifact. Notes ----- Raw user-facing observation blocks are normalized internally before encoding when preprocessing metadata is available, but posterior-predictive comparisons remain on the original observation scale. .. py:attribute:: task .. py:attribute:: posterior_estimator .. py:attribute:: simulator :value: None .. py:attribute:: preprocessing_metadata .. py:method:: _resolve_preprocessing_metadata(preprocessing_metadata: petitRADTRANS.sbi.preprocessing.TaskPreprocessingMetadata | Mapping[str, Any] | None) -> petitRADTRANS.sbi.preprocessing.TaskPreprocessingMetadata | None .. py:method:: prepare_observation_blocks(observation_blocks: list[petitRADTRANS.sbi.observation.ObservationBlock]) -> list[petitRADTRANS.sbi.observation.ObservationBlock] Normalize user-facing observation blocks when preprocessing metadata is available. Parameters ---------- observation_blocks: Raw observation blocks provided by the caller. Returns ------- list[ObservationBlock] Either the original blocks or normalized copies, depending on whether preprocessing metadata is available. .. py:method:: infer(observation_blocks: list[petitRADTRANS.sbi.observation.ObservationBlock], n_posterior_samples: int = 1000, include_posterior_predictive: bool = False, posterior_predictive_interval_level: float = 0.9, n_predictive_forward_model_samples: int | None = None, seed: int | None = None) -> AmortizedRetrievalResult Infer a posterior for one structured observation. Parameters ---------- observation_blocks: Raw observation blocks for one target system. n_posterior_samples: Number of posterior draws to generate. include_posterior_predictive: Whether to also generate a posterior-predictive summary. posterior_predictive_interval_level: Predictive interval level used when generating the optional posterior-predictive report. n_predictive_forward_model_samples: Number of posterior draws passed through the forward model when generating the posterior-predictive summary. When ``None`` all ``n_posterior_samples`` draws are forwarded. Set this to a small value (e.g. 50–200) to avoid a multi-hour hang when ``n_posterior_samples`` is large. seed: Optional seed for posterior and posterior-predictive sampling. Returns ------- AmortizedRetrievalResult Posterior samples and any optional predictive metadata. .. py:method:: posterior_predictive(posterior: petitRADTRANS.sbi.posterior.PosteriorSamples, observation_blocks: list[petitRADTRANS.sbi.observation.ObservationBlock], interval_level: float = 0.9, n_predictive_forward_model_samples: int | None = None, seed: int | None = None) -> petitRADTRANS.sbi.calibration.PosteriorPredictiveReport Generate posterior-predictive draws for a fitted observation. Parameters ---------- posterior: Posterior samples associated with one observed system. observation_blocks: Original observation blocks used for user-facing comparison. interval_level: Central predictive interval level to report. n_predictive_forward_model_samples: Number of posterior draws passed through the forward model. When ``None`` all samples in ``posterior`` are used. Set this to a small value (e.g. 50–200) to keep the number of expensive petitRADTRANS calls manageable. seed: Optional seed for predictive simulation. Returns ------- PosteriorPredictiveReport Predictive summary for the supplied posterior samples. .. py:method:: diagnose_domain(observation_blocks: list[petitRADTRANS.sbi.observation.ObservationBlock]) -> OODDiagnostic | None Estimate whether the observation is in-distribution for the model. Parameters ---------- observation_blocks: Observation blocks to diagnose. Returns ------- OODDiagnostic | None Robust support-distance diagnostic derived from preprocessing statistics, or ``None`` when preprocessing metadata is unavailable.