deepextractor.api
=================

.. py:module:: deepextractor.api

.. autoapi-nested-parse::

   Top-level convenience functions for DeepExtractor inference.

   For one-shot use. For repeated inference on many signals, instantiate
   :class:`DeepExtractorModel` or :class:`DeepExtractorSeparator` directly
   to amortise the model load cost.







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

.. py:function:: reconstruct(noisy_input: numpy.ndarray, checkpoint: str = 'DeepExtractor_257', checkpoint_filename: str = CHECKPOINT_BILBY, checkpoint_dir: str | None = None, device: str | None = None, scaler_path: str | None = None) -> numpy.ndarray

   Extract the transient signal from a noisy gravitational-wave strain.

   Loads a DeepExtractor model, runs inference, and returns the reconstructed
   signal. For repeated calls, prefer instantiating :class:`DeepExtractorModel`
   directly to avoid reloading weights on each call.

   :param noisy_input: 1-D array of shape ``(T,)`` or 2-D batch of shape ``(N, T)``.
   :type noisy_input: np.ndarray
   :param checkpoint: Model name. Default ``"DeepExtractor_257"``.
   :type checkpoint: str
   :param checkpoint_filename: Checkpoint filename. Defaults to the bilby-noise checkpoint.
   :type checkpoint_filename: str
   :param checkpoint_dir: Local checkpoint directory. Falls back to HuggingFace Hub if None.
   :type checkpoint_dir: str | None
   :param device: Torch device string. Auto-detected if None.
   :type device: str | None
   :param scaler_path: Path to scaler .pkl. Uses bundled asset if None.
   :type scaler_path: str | None

   :returns: Reconstructed signal, same shape as ``noisy_input``.
   :rtype: np.ndarray


.. py:data:: extract

.. py:function:: separate(h1: numpy.ndarray, l1: numpy.ndarray, checkpoint_path: Union[str, pathlib.Path], scaler=None, device: str | None = None, model_kwargs: dict | None = None) -> deepextractor.model.SeparationResult

   Separate H1 and L1 strain into signal and background in the time domain.

   Loads a :class:`DeepExtractorSeparator`, runs inference, and returns the
   separated components. For repeated calls, instantiate
   :class:`DeepExtractorSeparator` directly to avoid reloading weights.

   :param h1: H1 strain. Shape ``(T,)`` or ``(N, T)``.
   :type h1: np.ndarray
   :param l1: L1 strain. Same shape as ``h1``.
   :type l1: np.ndarray
   :param checkpoint_path: Path to the ``.pth.tar`` checkpoint saved during training.
   :type checkpoint_path: str | Path
   :param scaler: Per-channel input scaler. Pass a fitted
                  :class:`~deepextractor.data.ChannelStandardScaler` instance, a path to
                  a pickled scaler, or ``None`` to skip scaling.
   :type scaler: ChannelStandardScaler | str | Path | None
   :param device: Torch device string. Auto-detected if None.
   :type device: str | None
   :param model_kwargs: Override keyword arguments forwarded to :class:`UNET1D_LSTM_ATT`.
   :type model_kwargs: dict | None

   :returns: Named tuple with fields ``h1_signal``, ``l1_signal``,
             ``h1_background``, ``l1_background``.
   :rtype: SeparationResult