Skip to content

Beam properties

extra.components.XGM ¤

XGM(run, device=None, default_sase=None)

Interface to an XGM (X-ray Gas Monitor).

Example usage in a Jupyter notebook: 

        -----------------------------------------------------------
In [1]: |xgm = XGM(run) # This will work with a single XGM        |
        |xgm                                                      |
        -----------------------------------------------------------
Out[1]: <XGM for SA1_XTD2_XGM/XGM/DOOCS at 9.3 keV>

        -----------------------------------------------------------
In [2]: |# With multiple XGMs, one needs to be chosen explicitly. |
        |# Either by explicit device name:                        |
        |xgm = XGM(run, "SPB_XTD9_XGM/XGM/DOOCS")                 |
        |                                                         |
        |# Or by passing a SourceData object:                     |
        |xgm = XGM(run, run.alias["spb-xgm"])                     |
        |                                                         |
        |# Or a KeyData object:                                   |
        |xgm = XGM(run, run.alias["spb-xgm"]["data.intensityTD"]) |
        |                                                         |
        |# Or alias name                                          |
        |xgm = XGM(run, "spb-xgm")                                |
        |                                                         |
        |# Or a unique (case-insensitive) substring among XGMs    |
        |xgm = XGM(run, "spb")                                    |
        -----------------------------------------------------------
Out[2]: <XGM for SPB_XTD9_XGM/XGM/DOOCS at 9.3 keV>

Parameters:

Name Type Description Default
run DataCollection

A run containing at least one XGM.

 required
device (str, SourceData, KeyData)

Specify an XGM to use, necessary if a run contains more than one XGM. This can be any of:

  • The device name of the control source.
  • A SourceData or KeyData of either the control source (e.g. SA2_XTD1_XGM/XGM/DOOCS) or instrument source (e.g. SA2_XTD1_XGM/XGM/DOOCS:output) of an XGM.
  • The alias name of either a SourceData or KeyData belonging to an XGM.
  • A unique (case-insensitive) substring of an XGM source name. For example if a run contains HED_XTD6_XGM/XGM/DOOCS and SA2_XTD1_XGM/XGM/DOOCS, then passing device="hed" or device="sa2" will select those XGMs, respectively (passing xtd1 or xtd6 would also work).
 None
default_sase int

Only for XGMs with data for multiple SASE's, to specify a default SASE to retrieve data for. This is useful when working with XGMs on SASE 1 or SASE 3 and you're only interested in data for a specific SASE. This setting applies to all the SASE-specific methods of the class, such as XGM.pulse_energy() and XGM.npulses().

If it is not set the class will try to guess the SASE of the instrument the data was recorded at, and it will throw an error if:

  • It couldn't guess the SASE of the instrument at all.
  • It did guess the SASE of the instrument, but it's a different SASE from the XGM selected. For example, if a run recorded at SQS has both a SASE 1 and SQS XGM and the SQS XGM is selected, default_sase will automatically be set to 3. But if the SASE 1 XGM is selected it will throw an error and ask the user to set default_sase explicitly.

Valid values are: 0, 1, and 3. Passing 0 always selects the main properties of a device, e.g. data.intensityTD instead of the SASE-specific ones.

 None

control_source property ¤

control_source: SourceData

The SourceData object for the control source of the XGM (e.g. SA2_XTD1_XGM/XGM/DOOCS).

instrument_source property ¤

instrument_source: SourceData

The SourceData object for the instrument source of the XGM (e.g. SA2_XTD1_XGM/XGM/DOOCS:output).

wavelength ¤

wavelength(with_units=True)

The nominal wavelength of the X-rays in nanometers.

This calls KeyData.as_single_value() internally, which means it will throw an exception if the wavelength is not constant.

Parameters:

Name Type Description Default
with_units bool

Whether to return a pint.Quantity or a float.

 True

Raises:

Type Description
ValueError

Will be thrown if the number of pulses is not constant.

wavelength_by_train ¤

wavelength_by_train()

Return a 1D DataArray of the nominal wavelength of each train.

photon_energy ¤

photon_energy(with_units=True)

The nominal photon energy in keV.

This calls KeyData.as_single_value() internally, which means it will throw an exception if the wavelength is not constant.

Parameters:

Name Type Description Default
with_units bool

Whether to return a pint.Quantity or a float.

 True

photon_energy_by_train ¤

photon_energy_by_train()

The nominal photon energy in keV of each train.

doocs_server ¤

doocs_server() -> str

The DOOCS server that the Karabo XGM device is connected to.

This information was not stored in older versions of the XGM, so the method may return None if the DOOCS server was not found.

Raises:

Type Description
MultiRunError

A MultiRunError will be thrown whenever the DataCollection contains data from more than one run. This XGM property is stored in the RUN section of EXDF files, and when a run has been unioned with another it is not possible to retrieve RUN values.

pulse_energy ¤

pulse_energy(sase=None, series=False)

Returns the energy per-pulse and per-train in microjoules.

If series=False (the default) this will return a 2D DataArray with dimensions of (trainId, pulseIndex).

For runs with a varying number of pulses, the data will be sliced to the maximum number of pulses. e.g. if a run has 100 trains with only one train containing 10 pulses and all the others 0, the returned array will have a shape of (100, 10). The fill value for the missing pulses will be NaN.

If series=True this will return a 1D Series where all entries with 0 pulses have been dropped, indexed by trainId and pulseIndex.

Note

This uses the data.intensityTD property of the XGM.

Parameters:

Name Type Description Default
sase int

Specify a SASE to retrieve data for. For XGMs from SASE 1 and SASE 3 this can be either 1 or 3 or 0. Passing 0 is a special case that refers to the main properties of an XGM, i.e. it will look at data.intensityTD instead of data.intensitySa1TD with sase=1. This setting overrides the default_sase argument to the constructor.

 None
series bool

Whether to return a 2D DataArray or 1D Series.

 False

slow_train_energy ¤

slow_train_energy(sase=None)

Return the slow train energy from the XGM in microjoules.

This is an average pulse energy, averaged over all pulses for 10-20s.

Parameters:

Name Type Description Default
sase int

Same meaning as in XGM.pulse_energy().

 None

npulses ¤

npulses(sase=None) -> int

The nominal number of pulses.

This will throw an exception if the number of pulses is not constant.

Parameters:

Name Type Description Default
sase int

Same meaning as in XGM.pulse_energy().

 None

Raises:

Type Description
ValueError

Will be thrown if the number of pulses is not constant.

pulse_counts ¤

pulse_counts(sase=None, force_slow_data=False)

Return a 1D DataArray of the number of pulses in each train.

Because the slow data pulseEnergy.numberOf[SAx]BunchesActual property can be unreliable this will always check the slow data counts against the counts in the fast data from XGM.pulse_energy() and return the fast data counts if there is a difference. This can be overridden by passing force_slow_data=True.

Warning

Using force_slow_data=True can give unreliable results, only use it if you specifically want to find what numbers the XGM recorded. In general, prefer using something like the XrayPulses component to find the real number of pulses from the bunch pattern table.

Parameters:

Name Type Description Default
sase int

Same meaning as in XGM.pulse_energy().

 None

max_npulses ¤

max_npulses(sase=None) -> int

The maximum number of pulses.

Parameters:

Name Type Description Default
sase int

Same meaning as in XGM.pulse_energy().

 None

is_constant_pulse_count ¤

is_constant_pulse_count(sase=None) -> bool

Return whether or not the number of pulses is constant.

Parameters:

Name Type Description Default
sase int

Same meaning as in XGM.pulse_energy().

 None

plot ¤

plot(sase=None, figsize=(9, 7))

Plot an overview of data from the XGM.

This combines XGM.plot_pulse_energy(), XGM.plot_energy_per_pulse(), and XGM.plot_energy_per_train() in a single figure.

Example plot:

Parameters:

Name Type Description Default
sase int

Same meaning as in XGM.pulse_energy().

 None
figsize tuple

The size of the Figure.

 (9, 7)

plot_pulse_energy ¤

plot_pulse_energy(sase=None, ax=None, minimal_title=False)

Plot a heatmap of the pulse energies.

Example plot:

Parameters:

Name Type Description Default
sase int

Same meaning as in XGM.pulse_energy().

 None
ax Axes

The axis to plot in. This will default to plt if not provided.

 None
minimal_title bool

Whether to include the proposal/run information and XGM device name in the title.

 False

plot_energy_per_pulse ¤

plot_energy_per_pulse(sase=None, ax=None, minimal_title=False)

Plot the average pulse energy.

Example plot:

Parameters:

Name Type Description Default
sase int

Same meaning as in XGM.pulse_energy().

 None
ax Axes

The axis to plot in. This will default to plt if not provided.

 None
minimal_title bool

Whether to include the proposal/run information and XGM device name in the title.

 False

plot_energy_per_train ¤

plot_energy_per_train(sase=None, window_trains=None, ax=None, minimal_title=False)

Plot the average train energy.

Example plot:

Parameters:

Name Type Description Default
sase int

Same meaning as in XGM.pulse_energy().

 None
window_trains int

The number of trains to use when plotting the rolling average. By default this is chosen automatically based on the number of trains in the run.

 None
ax Axes

The axis to plot in. This will default to plt if not provided.

 None
minimal_title bool

Whether to include the proposal/run information and XGM device name in the title.

 False