Data processing, file saving & loading

The keyoscacquire.dataprocessing module contains a function for processing the raw data captured with oscilloscope.Oscilloscope, and keyoscacquire.fileio for saving the processed data to files and plots.

Data processing (keyoscacquire.dataprocessing)

This module provides functions for processing the data captured from the oscilloscope to time and voltage values

The output from the Oscilloscope.capture_and_read() function is processed by process_data(), a wrapper function that sends the data to the respective binary or ascii processing functions.

This function is kept outside the Oscilloscope class as one might want to post-process data separately from capturing it.

keyoscacquire.dataprocessing.process_data(raw, metadata, wav_format, verbose_acquistion=True)

Wrapper function for choosing the correct _process_data function according to wav_format for the data obtained from capture_and_read()

Parameters

• raw (ndarray or str) – From capture_and_read(): Raw data, type depending on wav_format

• metadata (list or tuple) – From capture_and_read(): List of preambles or tuple of preamble and model series depending on wav_format. See The preamble.

• wav_format ({'WORD', 'BYTE', 'ASCii'}) – Specify what waveform type was used for acquiring to choose the correct processing function.

• verbose_acquistion (bool) – True prints the number of points captured per channel

Returns

• time (ndarray) – Time axis for the measurement

• y (ndarray) – Voltage values, each row represents one channel

Raises

ValueError – If wav_format is not {‘BYTE’, ‘WORD’, ‘ASCii’}

See also

keyoscacquire.oscilloscope.Oscilloscope.capture_and_read()

File saving and loading (keyoscacquire.fileio)

The Oscilloscope class has the method keyoscacquire.Oscilloscope.save_trace() for saving the most recently captured trace to disk. This method relies on the fileio module.

This module provides functions for saving traces to npy format files (see numpy.lib.format) or ascii files. The latter is slower but permits a header with metadata for the measurement, see Oscilloscope.generate_file_header() which is used when saving directly from the Oscilloscope class.

keyoscacquire.fileio.save_trace(fname, time, y, fileheader='', ext='.csv', print_filename=True, nowarn=False)

Saves the trace with time values and y values to file.

Current date and time is automatically added to the header. Saving to numpy format with save_trace_npy() is faster, but does not include metadata and header.

Parameters

• fname (str) – Filename of trace

• time (ndarray) – Time axis for the measurement

• y (ndarray) – Voltage values, same sequence as channel_nums

• fileheader (str, default "") – Header of file, use for instance Oscilloscope.generate_file_header()

• ext (str, default _filetype) – Choose the filetype of the saved trace

• print_filename (bool, default True) – True prints the filename it is saved to

Raises

RuntimeError – If the file already exists

keyoscacquire.fileio.plot_trace(time, y, channels, fname='', showplot=False, savepng=True)

Plots the trace with oscilloscope channel screen colours according to the Keysight colourmap and saves as a png.

Caution

No filename check for the saved plot, can overwrite existing png files.

Parameters

• time (ndarray) – Time axis for the measurement

• y (ndarray) – Voltage values, same sequence as channel_nums

• channels (list of ints) – list of the channels obtained, example [1, 3]

• fname (str, default "") – Filename of possible exported png

• show (bool, default _show_plot) – True shows the plot (must be closed before the programme proceeds)

• savepng (bool, default _export_png) – True exports the plot to fname.png

keyoscacquire.fileio.load_trace(fname, ext='.csv', column_names='auto', skip_lines='auto', return_as_df=True)

Load a trace saved with keyoscacquire.oscilloscope.save_file()

What is returned depends on the format of the file (.npy files contain no headers), and if a dataframe format is chosen for the return.

Parameters

• fname (str) – Filename of trace, with or without extension

• ext (str, default _filetype) – The filetype of the saved trace (with the period, e.g. ‘.csv’)

• skip_lines ({'auto' or int}, default 'auto') – Number of lines from the top of the files to skip before parsing as dataframe. Essentially the pandas.read_csv() skiprows argument. 'auto' will count the number of lines starting with '#' and skip these lines

• column_names ({'auto', 'header', 'first line of data', or list-like}, default 'auto') –

  Only useful if using with return_df=True:

  • 'header': Infer df column names from the last line of the header (expecting ‘# <comma separated column headers>’ as the last line of the header)

  • 'first line of data': Will use the first line that is parsed as names, i.e. the first line after skip_lines lines in the file

  • 'auto': Equivalent to 'header' if there is more than zero lines of header, otherwise 'first line of data'

  • list-like: Specify the column names manually

• return_as_df (bool, default True) – If the loaded trace is not a .npy file, decide to return the data as a Pandas dataframe if True, or as an ndarray otherwise

Returns

• data (Dataframe or ndarray) – If return_as_df is True and the filetype is not .npy, a Pandas dataframe is returned. Otherwise ndarray. The first column is time, then each column is a channel.

• header (list or None) – If .npy, None is returned. Otherwise, a list of the lines at the beginning of the file starting with '#', stripped off '# ' is returned

keyoscacquire.fileio.load_header(fname, ext='.csv')

Open a trace file and get the header

Parameters

• fname (str) – Filename of trace, with or without extension

• ext (str, default _filetype) – The filetype of the saved trace (with the period, e.g. '.csv')

Returns

header – Lines at the beginning of the file starting with '#', stripped off '# '

Return type

list