PES detector

Some mnemonics and functions related to the Photo-Electron Spectrometer (PES). Documentation in the form of a notebook.

src/toolbox_scs/detectors/pes.py

@@ -23,7 +23,53 @@ def get_pes_tof(run, mnemonics=None, merge_with=None,
                 baseStart=None, baseWidth=80,
                 sample_rate=2e9):
     """
-    blablabla
+    Extracts time-of-flight spectra from raw digitizer traces. The
+    tracesvare either loaded via ToolBox mnemonics or those in the
+    optionally provided merge_with dataset. The spectra are aligned
+    by pulse Id using the SASE 3 bunch pattern, and have time coordinates
+    in nanoseconds.
+
+    Parameters
+    ----------
+    run: extra_data.DataCollection
+        DataCollection containing the digitizer data
+    mnemonics: str or list of str
+        mnemonics for PES, e.g. "PES_W_raw" or ["PES_W_raw", "PES_ENE_raw"].
+        If None and no merge_with dataset is provided, defaults to "PES_W_raw".
+    merge_with: xarray Dataset
+        If provided, the resulting Dataset will be merged with this
+        one. The PES variables of merge_with (if any) will also be
+        computed and merged.
+    start: int
+        starting sample of the first spectrum in the raw trace.
+    width: int
+        number of samples per spectra.
+    origin: int
+        sample of the raw trace that corresponds to time-of-flight origin.
+        If None, origin is equal to start.
+    width_ns: float
+        time window for one spectrum. If None, the time window is defined by
+        width / sample rate.
+    baseStart: int
+        starting sample of the baseline.
+    baseWidth: int
+        number of samples to average (starting from baseStart) for baseline
+        calculation.
+    sample_rate: float
+        sample rate of the digitizer.
+
+    Returns
+    -------
+    pes: xarray Dataset
+        Dataset containing the PES time-of-flight spectra (e.g. "PES_W_tof"),
+        merged with optionally provided merg_with dataset.
+
+    Example
+    -------
+    >>> import toolbox_scs as tb
+    >>> import toolbox_scs.detectors as tbdet
+    >>> run, ds = tb.load(2927, 100, "PES_W_raw")
+    >>> pes = tbdet.get_pes_tof(run, merge_with=ds)
     """
     def to_processed_name(name):
         return name.replace('raw', 'tof')