API References (Tools)

ensure_set(setpoint_pv: str | List[str], readback_pv: str | List[str], goal: float | List[float], tol: float | List[float] = 0.01, timeout: float = 10.0, verbose: bool = False, keep_data: bool = False, extra_monitors: List[str] | None = None, fillna_method: str = 'linear')

Perform ensure CA device set operation against the given setpoint PV(s) and monitor the readback PV(s) reaching the goal(s) when the value discrepanc(ies) between read and set fall within the range defined by the given tolerance(s). All these actions should be finished or terminated in the maximum allowed seconds defined by timeout.

Please note: when passing a list of PVs, the size of setpoint_pv, readback_pv, goal and tol parameters must be the same, however, if goal and tol is defined as a single float number, they will be expanded to a list of that value for convenience to match the dimension.

keep_data, extra_monitors and fillna_method arguments could be used to return the retrieved data during the ensure set procedure as a DataFrame.

Parameters:

setpoint_pv (str, List[str]) – [A list of] setpoint PV(s).
readback_pv (str, List[str]) – [A list of] readback PV(s), should match the order of setpoint PVs accordingly.
goal (float, List[float]) – [A list of] set value(s) applied to setpoint PV(s), expand to a list if single number is given.
tol (float, List[float]) – [A list of] tolerance value(s) of the discrepancy between set and read, expand to a list if single number is given. Default is 0.01.
timeout (float) – Max waited time in seconds of the entire set procedure, if reached, ‘Timeout’ should be returned. Default is 10.0.
verbose (bool) – If set, show verbose log messages. Default is False.
keep_data (bool) – If set, keep and return all the data events during the ensure set procedure. Defaults to False. All the setpoint and readback PVs are included as the list of PVs for data acquisition, additional ones can be passed via extra_monitors option.
extra_monitors (List[str]) – [A list of] PVs to be monitored during the ensure_set procedure, return as a dataframe.
fillna_method (str) – The algorithm to fill out the NaN values of the retrieved dataset, defaults to ‘linear’, which applies linear interpolation, other options ‘nearest’, ‘ffill’, ‘bfill’, and ‘none’ meaning return the raw dataset.

Returns:

r – A tuple of (ret_string, dataset), ret_string: indicates the result of ensure_set, dataset: the retrieved data events for the setpoint and readback PVs, plus the defined extra monitors.

Return type:

tuple

Examples

>>> from phantasy import ensure_set
>>> sp = ['FE_SCS1:PSQ1_D0726:V_CSET', 'FE_SCS1:PSQ2_D0726:V_CSET']
>>> rp = ['FE_SCS1:PSQ1_D0726:V_RD', 'FE_SCS1:PSQ2_D0726:V_RD']
>>> val = [10, 5]
>>> tol = 0.8     # for all set and read pairs
>>> timeout = 20  # seconds
>>> ensure_set(sp, rp, val, tol, timeout, True)
>>> # keep the retrieved data
>>> extra_monitors = ['fast_vary_pv1', 'slow_vary_pv2',] # sp and rp are included by default
>>> keep_data = True  # keep and return the dataset
>>> fillna_method = 'linear'  # fill the NaN with linear interpolation, defaults, set it as
>>>                           # 'none' to skip filling, if raw dataset is wanted
>>> r, data = ensure_set(sp, rp, val, tol, timeout, True,
>>>                      extra_monitors=extra_monitors, keep_data=True)

fetch_data(pvlist: List[str], time_span: float = 5.0, abs_z: float | None = None, with_data: bool = False, verbose=False, **kws)

Fetch the readback data from a list of given PVs in the given time period in seconds, trim the data beyond the given z-score (absolute value), and return the data of interest.

Parameters:

pvlist (List[str]) – A list of PVs.
time_span (float) – The total time period for fetching data, [second], defaults to 5.0.
abs_z (float) – The absolute value of z-score, drop the data beyond, if not set, keep all the data.
with_data (bool) – If set, return data array as the second element of the returned tuple, if expanded argument is True, three more columns of data for ‘#’, ‘mean’ and ‘std’ are appended to the dataset.
verbose (bool) – If set, print out log messages.

Keyword Arguments:

expanded (bool) – If set along with with_data, return an expanded dataset, defaults to True.
timeout (float) – Connection timeout for all PVs, defaults 5.0 seconds.
data_opt (dict) –
- with_timestamp : bool
If set, return data array with aligned timestamp info, with_data must be set.
- fillna_method : str
The algorithm to fill out the NaN values of the retrieved dataset, defaults to ‘linear’, which applies linear interpolation, other options ‘nearest’, ‘ffill’, ‘bfill’, and ‘none’ meaning return the raw dataset.

Returns:

r – Tuple of averaged value of array [and the full data array if ‘with_data’ is True].

Return type:

tuple

Examples

>>> from phantasy import fetch_data
>>> pvs = [
>>>  'VA:LS1_CA01:CAV1_D1127:PHA_RD',
>>>  'VA:LS1_CA01:CAV2_D1136:PHA_RD',
>>>  'VA:LS1_CA01:CAV3_D1142:PHA_RD',
>>>  'VA:SVR:NOISE'
>>> ]
>>> # Fetch the average readings of the given list of PVs, for 5 seconds, and drop the data
>>> # which |z-score| > 3, show the verbose messages.
>>> avg, _ = fetch_data(pvs, 5, 3, verbose=True)
>>> # return the data table after filtering together with the average readings
>>> avg, data = fetch_data(pvs, 5, 3, verbose=True, with_data=True)
>>> # set expanded False to get the original dataset before expanding (no last 3 columns)
>>> avg, data = fetch_data(pvs, 5, 3, verbose=True, with_data=True, expanded=False)
>>> # return the average without data filtering.
>>> avg, _ = fetch_data(pvs, 5)
>>> # fetch timestamp per event
>>> avg, df = fetch_data(pvs, 5.0, with_data=True, data_opt={'with_timestamp': True})
>>> # returned df with timestamp as the index, PV names as columns, timestamps are
>>> # aligned with fillna_method of 'linear'.

class DataFetcher(pvlist: List[str], **kws)

DataFetcher provides a more robust, flexible and efficient way for fetching data through CA. It’s wrapping the fetch_data function but offers less overhead in terms of managing the working objects.

Parameters:

pvlist (List[str]) – A list of PVs with unique names.

Keyword Arguments:

timeout (float) – The overall connection timeout for all PVs, defaults 5 seconds, meaning if in 5 seconds not all the PVs can be reached, raise an error; increase the timeout by set timeout value via <DataFetcher instance>.timeout = <new timeout>.
verbose (bool) – If set, show more print out messages, defaults False.