threshold_set module

Define an object to hold all thresholds of a multipactor test.

class ThresholdSet(thresholds, power_extrema)[source]

Bases: object

Parameters:
classmethod from_instruments(multipac_detector, detecting_instruments, growth_array, threshold_predicate=None, threshold_reducer=None)[source]

Create a ThresholdSet using the specified detection strategy.

Parameters:

  • multipac_detector (Callable[[ndarray[tuple[Any, ...], dtype[double]]], ndarray[tuple[Any, ...], dtype[bool]]]) – Function that takes in the data of an Instrument and returns an array, where True means multipactor and False no multipactor.

  • detecting_instruments (Iterable[Instrument]) – Instruments to apply multipac_detector on.

  • growth_array (ndarray[tuple[Any, ...], dtype[double]]) – Holds 1.0 where power increases, 0.0 where it is stable, -1.0 where it decreases.

  • threshold_reducer (Literal['any', 'all'] | None, default: None) –

    • not provided: thresholds are computed for each instrument independently.

    • ”any”: thresholds appear when multipactor is detected by any of the provided detecting instrument.

    • ”all”: thresholds appear when multipactor is detected by all the provided detecting instrument.

  • threshold_predicate (Callable[[Threshold], bool] | None, default: None) – Function filtering the thresholds. Applied after threshold_reducer.

Return type:

Self

classmethod last(threshold_set, threshold_predicate=None)[source]

Create object holding the last threshold measured by every instrument.

See also

AveragedThresholdSet

Parameters:

  • threshold_set (Self) – Holds all the detected thresholds.

  • threshold_predicate (Callable[[Threshold], bool] | None, default: None) – Additional predicate, eg to exclude thresholds measured during the first power cycles, from a specific detecting instrument, of a certain type…

Return type:

Self

Returns:

Holds only one lower and one upper Threshold per detecting instrument: the last one measured during the test.

classmethod subset(threshold_set, threshold_predicate)[source]

Return object holding a subset of threshold_set.

threshold_predicate is used to filter on the Threshold.

Parameters:
Return type:

Self

classmethod extreme(threshold_set, threshold_predicate=None)[source]

Create object holding only the most extreme Threshold.

For each half cycle:

  • If power increases: keep first lower and last upper threshold.

  • If power decreases: keep first upper and last lower threshold.

    • If there was still multipactor somewhere when the half power cycle ended (e.g. instrument with a lower but no upper threshold), no upper threshold is added.

  • If direction is undetermined: skip the cycle.

Parameters:

  • threshold_set (Self) – The full set of thresholds.

  • threshold_predicate (Callable[[Threshold], bool] | None, default: None) – A function to select relevant thresholds.

Return type:

Self

Returns:

A new object containing only selected extreme thresholds.

remove_singularities(min_consecutive=1)[source]

Remove fugitive Threshold.

If two Threshold are detected by the same Instrument and their Threshold.sample_index are separated by min_consecutive - 1 or less, both objects are removed.

Parameters:

min_consecutive (int, default: 1) – Threshold objects separated by less than min_consecutive sample index are removed. The default min_consecutive=1 removes multipactor spanning over a single sample index.

Return type:

None

_remove_thresholds_at_seesaw()[source]

Clean incorrect Threshold if power follows seesaw profile.

Consider this: - i - 1: max power of the seesaw profile, there is MP - i: new seesaw (min power of the profile), no MP

At i - 1, we did not reach a threshold. But we have a Threshold corresponding to it. So we have to remove it.

Return type:

None

_warn_instruments_at_same_position()[source]

Verify bijection between detecting instruments pos and name.

Return type:

None

sample_indexes(*, threshold_predicate=None)[source]

Return sample indexes matching optional filter.

Parameters:

threshold_predicate (Callable[[Threshold], bool] | None, default: None)

Return type:

list[int]

apply_to(instrument)[source]

Extract instrument data at threshold sample indexes.

Parameters:

instrument (Instrument)

Return type:

ndarray[tuple[Any, ...], dtype[double]]

at(position, tol=1e-10, return_global=False)[source]

Gather all thresholds measured at position.

Parameters:

  • position (float) – Where you want the thresholds.

  • tol (float, default: 1e-10) – Tolerance over the position.

  • return_global (bool, default: False) – To return global multipactors, and also return all thresholds when position is np.nan. np.nan position are associated with “global” instruments, such as ForwardPower, and with “global” multipactors, such as obtained by crossing several Instrument data.

Return type:

list[Threshold]

Returns:

All multipactor thresholds detected at this position.

data_at_thresholds(instruments, tol=1e-10, global_instruments=False, global_multipactor=False, xdata_instrument=None, unique_x_value=None)[source]

Return instrument values at threshold sample indices.

We match Threshold and Instrument objects by position.

Parameters:

  • instruments (Iterable[Instrument]) – Instruments to which data must be plotted. Must have .position and .data attributes.

  • tol (float, default: 1e-10) – Tolerance for position matching.

  • global_instruments (bool, default: False) – If instruments not position-specific (eg ForwardPower) should be returned.

  • global_multipactor (bool, default: False) – If multipactor not position-specific (eg thresholds created by merging several other multipactor arrays) should be returned.

  • xdata_instrument (Instrument | None, default: None) – Its data is returned at every threshold. It results in a unique xdata column, without nan, that can be used as a common x-data for plotting.

  • unique_x_value (float | None, default: None) – If given, this value will replace every value of the xdata_instrument column.

Return type:

DataFrame

Returns:

Columns are named by detecting instrument + threshold nature: "NI9205_E4 @ upper threshold (according to NI9205_MP4l)". If xdata_instrument was given, also return this instrument values at every sample index (can be unique value if unique_x_value was given). Indexes are the sample indices at every threshold.

according_to(instrument)[source]

Give thresholds measured by instrument.

Parameters:

instrument (Instrument | str | Literal['any', 'all'])

Return type:

list[Threshold]

remove_detected_by(instrument)[source]

Remove thresholds detected by instrument.

Parameters:

instrument (Instrument | str | Literal['any', 'all'])

Return type:

None

get_threshold_label_color_map(instruments)[source]

Maps threshold dataframe column headers to corresponding colors.

Assumes Threshold.color is already set to the corresponding Instrument color.

Return type:

dict[str, tuple[float, float, float]]

Returns:

Mapping from a header looking like "NI9205_E4 @ upper threshold (according to NI9205_MP4l)", to the threshold color (usually, this is detecting instrument color).

Parameters:

instruments (Sequence[Instrument])

detecting_instruments()[source]

Return instruments that detected at least one threshold.

Return type:

set[str | Literal['any', 'all']]

_thresholds_by_half_power_cycle(threshold_predicate=None)[source]

Group thresholds by half power cycle, based on sample index range.

Each group includes thresholds between two consecutive extrema: [extremum_i.sample_index, extremum_{i+1}.sample_index)

The dictionary key is of the form:

  • “0 (increasing)” if power increases over the interval

  • “1 (decreasing)” if power decreases over the interval

  • “2 (undetermined)” if direction cannot be determined

Note

Not ultra efficient. To update if necessary.

Parameters:

threshold_predicate (Callable[[Threshold], bool] | None, default: None) – Filter the Threshold instances.

Return type:

dict[str, list[Threshold]]

Returns:

Dictionary mapping half-cycle index to thresholds within that range. Keys are sorted by increasing power cycle index values.

class AveragedThresholdSet(thresholds, power_extrema)[source]

Bases: ThresholdSet

Holds average of several thresholds.

The main difference with a classic ThresholdSet is that its data_at_thresholds() is overriden to return data averaged from several Threshold.

Parameters:
classmethod from_threshold_set(threshold_set, threshold_predicate=None)[source]

Create an object holding averaged thresholds.

Parameters:

  • threshold_set (ThresholdSet) – The thresholds to average.

  • threshold_predicate (Callable[[Threshold], bool] | None, default: None) – To filter thresholds to average. A typical example would be lambda t: t.sample_index > 200 to keep only conditioned thresholds.

Return type:

Self

Returns:

Object containing “averaged” thresholds. It contains one lower and one upper threshold per detecting instrument (if already present in the original ThresholdSet).

data_at_thresholds(*args, **kwargs)[source]

Return average of instrument values at threshold sample indices.

Keep the xdata column as a representative index: for each y-column, compute the median of its xdata values.

Parameters:

  • instruments – Instruments to which data must be plotted. Must have .position and .data attributes.

  • tol – Tolerance for position matching.

  • global_instruments – If instruments not position-specific (eg ForwardPower) should be returned.

  • global_multipactor – If multipactor not position-specific (eg thresholds created by merging several other multipactor arrays) should be returned.

  • xdata_instrument – Its data is returned at every threshold. It results in a unique xdata column, without nan, that can be used as a common x-data for plotting.

Return type:

DataFrame

Returns:

Columns are named by detecting instrument + threshold nature. Only index is average (median) of instruments values at the various thresholds.

_remove_thresholds_at_seesaw()

Clean incorrect Threshold if power follows seesaw profile.

Consider this: - i - 1: max power of the seesaw profile, there is MP - i: new seesaw (min power of the profile), no MP

At i - 1, we did not reach a threshold. But we have a Threshold corresponding to it. So we have to remove it.

Return type:

None

_thresholds_by_half_power_cycle(threshold_predicate=None)

Group thresholds by half power cycle, based on sample index range.

Each group includes thresholds between two consecutive extrema: [extremum_i.sample_index, extremum_{i+1}.sample_index)

The dictionary key is of the form:

  • “0 (increasing)” if power increases over the interval

  • “1 (decreasing)” if power decreases over the interval

  • “2 (undetermined)” if direction cannot be determined

Note

Not ultra efficient. To update if necessary.

Parameters:

threshold_predicate (Callable[[Threshold], bool] | None, default: None) – Filter the Threshold instances.

Return type:

dict[str, list[Threshold]]

Returns:

Dictionary mapping half-cycle index to thresholds within that range. Keys are sorted by increasing power cycle index values.

_warn_instruments_at_same_position()

Verify bijection between detecting instruments pos and name.

Return type:

None

according_to(instrument)

Give thresholds measured by instrument.

Parameters:

instrument (Instrument | str | Literal['any', 'all'])

Return type:

list[Threshold]

apply_to(instrument)

Extract instrument data at threshold sample indexes.

Parameters:

instrument (Instrument)

Return type:

ndarray[tuple[Any, ...], dtype[double]]

at(position, tol=1e-10, return_global=False)

Gather all thresholds measured at position.

Parameters:

  • position (float) – Where you want the thresholds.

  • tol (float, default: 1e-10) – Tolerance over the position.

  • return_global (bool, default: False) – To return global multipactors, and also return all thresholds when position is np.nan. np.nan position are associated with “global” instruments, such as ForwardPower, and with “global” multipactors, such as obtained by crossing several Instrument data.

Return type:

list[Threshold]

Returns:

All multipactor thresholds detected at this position.

detecting_instruments()

Return instruments that detected at least one threshold.

Return type:

set[str | Literal['any', 'all']]

classmethod extreme(threshold_set, threshold_predicate=None)

Create object holding only the most extreme Threshold.

For each half cycle:

  • If power increases: keep first lower and last upper threshold.

  • If power decreases: keep first upper and last lower threshold.

    • If there was still multipactor somewhere when the half power cycle ended (e.g. instrument with a lower but no upper threshold), no upper threshold is added.

  • If direction is undetermined: skip the cycle.

Parameters:

  • threshold_set (Self) – The full set of thresholds.

  • threshold_predicate (Callable[[Threshold], bool] | None, default: None) – A function to select relevant thresholds.

Return type:

Self

Returns:

A new object containing only selected extreme thresholds.

classmethod from_instruments(multipac_detector, detecting_instruments, growth_array, threshold_predicate=None, threshold_reducer=None)

Create a ThresholdSet using the specified detection strategy.

Parameters:

  • multipac_detector (Callable[[ndarray[tuple[Any, ...], dtype[double]]], ndarray[tuple[Any, ...], dtype[bool]]]) – Function that takes in the data of an Instrument and returns an array, where True means multipactor and False no multipactor.

  • detecting_instruments (Iterable[Instrument]) – Instruments to apply multipac_detector on.

  • growth_array (ndarray[tuple[Any, ...], dtype[double]]) – Holds 1.0 where power increases, 0.0 where it is stable, -1.0 where it decreases.

  • threshold_reducer (Literal['any', 'all'] | None, default: None) –

    • not provided: thresholds are computed for each instrument independently.

    • ”any”: thresholds appear when multipactor is detected by any of the provided detecting instrument.

    • ”all”: thresholds appear when multipactor is detected by all the provided detecting instrument.

  • threshold_predicate (Callable[[Threshold], bool] | None, default: None) – Function filtering the thresholds. Applied after threshold_reducer.

Return type:

Self

get_threshold_label_color_map(instruments)

Maps threshold dataframe column headers to corresponding colors.

Assumes Threshold.color is already set to the corresponding Instrument color.

Return type:

dict[str, tuple[float, float, float]]

Returns:

Mapping from a header looking like "NI9205_E4 @ upper threshold (according to NI9205_MP4l)", to the threshold color (usually, this is detecting instrument color).

Parameters:

instruments (Sequence[Instrument])

classmethod last(threshold_set, threshold_predicate=None)

Create object holding the last threshold measured by every instrument.

See also

AveragedThresholdSet

Parameters:

  • threshold_set (Self) – Holds all the detected thresholds.

  • threshold_predicate (Callable[[Threshold], bool] | None, default: None) – Additional predicate, eg to exclude thresholds measured during the first power cycles, from a specific detecting instrument, of a certain type…

Return type:

Self

Returns:

Holds only one lower and one upper Threshold per detecting instrument: the last one measured during the test.

remove_detected_by(instrument)

Remove thresholds detected by instrument.

Parameters:

instrument (Instrument | str | Literal['any', 'all'])

Return type:

None

remove_singularities(min_consecutive=1)

Remove fugitive Threshold.

If two Threshold are detected by the same Instrument and their Threshold.sample_index are separated by min_consecutive - 1 or less, both objects are removed.

Parameters:

min_consecutive (int, default: 1) – Threshold objects separated by less than min_consecutive sample index are removed. The default min_consecutive=1 removes multipactor spanning over a single sample index.

Return type:

None

sample_indexes(*, threshold_predicate=None)

Return sample indexes matching optional filter.

Parameters:

threshold_predicate (Callable[[Threshold], bool] | None, default: None)

Return type:

list[int]

classmethod subset(threshold_set, threshold_predicate)

Return object holding a subset of threshold_set.

threshold_predicate is used to filter on the Threshold.

Parameters:
Return type:

Self