Signal

toksearch.Signal

Bases: ABC

Abstract base class for signals

This class is intended to be subclassed to create signals that can be fetched from a data source. The class provides a fetch method that fetches the data for a given shot, and a fetch_as_xarray method that fetches the data as an xarray Dataset object.

The general idea is that a signal is created with a set of parameters that are used to fetch the data for a given shot. The signal is then registered with a SignalRegistry object, which keeps track of all signals used in a toksearch application. This allows for easy cleanup of all signals (and associated resources) when the application is done.

The fetch method is the main method that needs to be called to fetch the data for a shot. It first performs registration of the signal with the SignalRegistry object. It then calls the gather method, which is an abstract method that needs to be implemented by subclasses. The gather method is responsible for collecting the data for a shot, and should return a dictionary containing the data fetched for the signal. The dictionary should contain a key 'data' with the data, and keys for each dimension of the data, with the values being the values of the dimensions. If the with_units attribute is True, the dictionary should also contain a key 'units' with the units of the data and dimensions.If a callback function has been set with the set_callback method, it is called after the data is fetched.

Methods:

Name	Description
fetch	Fetch the data for a shot.
fetch_as_xarray	Fetch the data for a shot as an xarray DataArray object.
gather	Abstract method. Collect the data for a shot. This method should be implemented by subclasses.
cleanup_shot	Abstract method. Clean up any resources specific to a shot. For example, if an MDSplus tree is opened to fetch data, this method should close the tree.
cleanup	Abstract method. Clean up any resources shared between shots. For example, if a network connection is opened to fetch data (and shared amongst multiple shots), this method should close it.
set_callback	set a callback function to be called after the data is gathered in the fetch method
set_dims	set the dimensions of the signal

Note:

gather, cleanup, and cleanup_shot are abstract methods that need to be implemented
by subclasses.

Attributes:

Name	Type	Description
dims	Iterable[str]	A list or other iterable of the labels for each dimension of the signals data. Most typically, this is just time, so the default is ('times',). If, for example, you have a time varying profile with, say, a radial dimension, you could pass ('times', 'radius'). The order is significant since, and in the case of MDSplus, it needs to match the way dim_of(0), dim_of(1),... are stored.
data_order	Iterable[str]	A list or other iterable of the labels for each dimension of the signals data. This is to be used when the dimension order fetched in MDSplus, dim(0),dim(1)... does not match the shape of the data stored. This list should match the order that the dimensions are stored in the actual data, and should be complementary with the dims parameter. Ex) If in MDSplus, dim(0) = 'rho', dim(1) = 'times', then the following would be used: dims = ('rho','times') But, if the data shape (n_times, n_rho), then the following would be used to match the data shape: data_order = (1,0) or ("times","rho")
with_units	bool	A boolean flag that indicates whether to fetch the units of the signal. If True, the fetch_units method will be called to fetch the units of the signal in the fetch method.

cleanup() abstractmethod

Close down any resources that are shared amongst multiple shots.

This typically means closing a network connection to a remote server.

cleanup_shot(shot) abstractmethod

Close down any per-shot resources needed to fetch data a shot

For instance, if an mds datasource is being used, this will close the tree.

fetch(shot)

Fetch the data for a shot

Parameters:

Name	Type	Description	Default
shot	int	The shot number to fetch the data for	required

Returns:

Name	Type	Description
dict	dict	A dictionary containing the data fetched for the signal. The dictionary will contain a key 'data' with the data, and keys for each dimension of the data, with the values being the values of the dimensions. If the with_units attribute is True, the dictionary will also contain a key 'units' with the units of the data and dimensions.

fetch_as_xarray(shot)

Fetch the data for a shot as an xarray DataArray object

Returns a DataArray object with dimensions specified in the dims attribute of the Signal object.

Parameters:

Name	Type	Description	Default
shot	int	The shot number to fetch the data for	required

Returns:

Type	Description
DataArray	xr.DataArray: An xarray DataArray object containing the data fetched for the signal, with dimensions specified in the dims attribute of the Signal object.

gather(shot) abstractmethod

Collect the data for a shot

set_callback(func)

Set a callback function to be called after the data is fetched in the fetch method

Parameters:

Name	Type	Description	Default
func	function	The callback function to call. The function should take a single argument, which is a dictionary containing the data fetched for the signal. The function should return a dictionary containing the modified data.	required

Returns:

Name	Type	Description
Signal	Signal	The signal object. This allows for chaining of method calls. eg signal.set_callback(func).set_dims(dims).fetch(shot)

set_dims(dims, data_order=None)

Set the dimensions of the signal

This method sets the dimensions of the signal. The dimensions are used to fetch the dimensions of the signal in the fetch_dims method. The dimensions are also used to create an xarray Dataset object in the fetch_as_xarray method.

Parameters:

Name	Type	Description	Default
dims	iterable of strings	A list or other iterable of the labels for each dimension of the signals data. Most typically, this is just time, so the default is ('times',). If, for example, you have a time varying profile with, say, a radial dimension, you could pass ('times', 'radius'). The order is significant since, and in the case of MDSplus, it needs to match the way dim_of(0), dim_of(1),... are stored.	required

Other Parameters:

Name	Type	Description
data_order	list	A list or other iterable of the labels for each dimension of the signals data. This is to be used when the dimension order fetched in MDSplus, dim(0),dim(1)... does not match the shape of the data stored. This list should match the order that the dimensions are stored in the actual data, and should be complementary of the dims parameter. Ex) MDSplus storage -> dim(0) = 'rho', dim(1) = 'time' dims = ('rho','time') Data shape -> (time X rho) data_order = (1,0) or ("time","rho")

Returns:

Name	Type	Description
Signal	Signal	The signal object. This allows for chaining of method calls. eg signal.set_callback(func).set_dims(dims).fetch(shot)