ReadValues

From SweepMe! Wiki
Jump to navigation Jump to search

The ReadValues module allows importing parameters from external files, such as text or Excel files.

Key Features

  • Load Complex Parameter Variations: Parameters stored in external files can be used as Sweep Values or Device Parameters.
  • Dynamic Device Control: Device settings in SweepMe! can be dynamically adjusted based on the parameters read from these files.
  • Supported files: Text files (*.txt, *.csv), Excel files (*.xls, *.xlsx), ini files (*.ini)
GUI of the ReadValues module
ReadValues GUI

Loading and reading a file

Select a file with the button "Select file". The path is shown in the field "File", where it can also be entered directly, including parameters {...}. Use the button "Reload file" to read the file again, e.g. after the file was changed.

For Excel files, the field "Sheet" appears. Select the worksheet by its name or by its number (1 for the first sheet). If the sheet cannot be found, the first sheet is loaded.

The loaded values are shown in the table below "Values". Loaded values cannot be edited in the module. To change values, edit the file itself or work with a copy of it.

Procedure

  • Empty lines are automatically skipped.
  • Lines starting with a comment character are skipped as well.
  • An empty cell is represented by an empty string (""). However, if the field "Missing data" is empty, empty cells are replaced by a float('nan') and shown as an empty cell in the table.
  • If desired, the name of the variable and the unit of each column are read from the first available lines (rows).
  • If desired, a certain number of lines can be skipped, e.g. to remove a header.
  • Lines with a number of values that differs from the number of columns are not loaded.

ini files

Variations are not possible when using ini files, instead, the parameters are all read at once. The parameter name is a concatenation of section and option name. E.g. the following ini file

[MySection]
option1 = value1
option2 = value2

creates and sets parameter "MySection-option1" to "value1" and parameter "MySection-option2" to "value2".

Sweep value

In the sweep mode "Each line of file", the Sweep value of ReadValues is the value of the first column. As the Sweep value of each Module is used to generate the file names of the measured data by MakeFile, the first column of the read-in file is essential for the names of the measurement data files.

In the sweep mode "Each column as list", no sweep is done.

Applications

  • Load complex parameter variations that are stored in an external file
  • Load values from a file to hand them over to various Modules as Sweep value
  • Create a configuration file and set Module or Driver settings from the read values using the Parameter_system
  • Load previously measured data to evaluate it by using SweepMe! in combination with the module CustomFunction
  • Load each column of a file as a list, e.g. to process it in a CustomFunction or to use it with the sweep mode "List" of the Sweep module
  • In combination with Condition and Calc you can create conditions for which a measurement is done.
  • in progress: Read multiple files in combination with the module LoadFiles to evaluate a bunch of files with similar structure and content.

User interface

Sweep mode

  • Each line of file: For each line of your file, the ReadValues module performs a variation of the modules in the sequencer that are hierarchically below. At each step, the value of each column is returned.
  • Each column as list: No sweep is done. The data of each column is returned at once as a list.

Options

The following options are found in the collapsible section "Options".

has variable

Part of "Header". Must be checked if the first non-empty, non-comment line of your file specifies the names of the variables related to each column. If unchecked, the columns are named "Col1", "Col2", and so on.

has unit

Part of "Header". Only available if 'has variable' is checked. Must be checked if the line after variables indicates the corresponding units.

Delimiter

The character that separates values of each column: Tab, Comma, Semicolon, Space, or Multiple spaces. With "Multiple spaces", any sequence of spaces or tabs separates two values. It is not needed for Excel files.

Decimal separator

The character used as decimal separator in text files, "." or ",". With ",", numeric values such as "1,5" are read as 1.5. It is not needed for Excel files.

Comment

Character at the beginning of a line that indicates that this line should be skipped during read-in. Choose "#", "*", or "//", or enter another character. In Excel files, a row is skipped if its first cell starts with the comment character.

Missing data

String that indicates missing data, so that SweepMe! can replace each occurrence with a float of 'not-a-number' (nan). Important if data with missing values shall be plotted. The default is "--".

Skip lines

Number of lines that shall be skipped before data is read-in. Empty lines will be automatically skipped. Parameters {...} can be used as well.

Preview lines

Loading large files can lead to delays that are prevented by showing a preview of the data. Enter the number of lines that you need to make sure that the correct file is loaded and which allows a proper performance (1 to 1000, default 100).

recognize as GUI elements

If checked, the content of your file will be displayed as CheckBox or ComboBox if certain patterns are matched:

  • CheckBox: The entry is a string being 'False', 'FALSE', 'True', or 'TRUE'. Booleans in Excel are however loaded as integers (0 or 1) and cannot be interpreted as True or False
  • ComboBox: The entry is separated by '|'

Preview mode

Large files can lead to delays in the program response. For that reason, a preview of typically 100 lines is shown and the label "Values" indicates the number of lines in the preview. If your file has more lines than shown in the preview, they will still be used during the measurement. Adjust the option 'Preview lines' if you need to see all lines of your file.

Disabling lines

In case you would like to disable lines to not use them during the measurement, we recommend adding a column of bool values such as 'False' or 'True' to your file and using the option 'recognize as GUI elements'. A CheckBox will be displayed for each bool value. In combination with the module Condition, measurement points that have the property 'False' can be skipped. To change which lines are used, edit the values in the file and reload it.

Data types

Cell contents are evaluated and changed to python types:

  • Integer: If all values of a column are whole numbers, e.g. 1 or 2.0
  • Float: If all values of a column can be converted by float()
  • Boolean: If cells are recognized in Excel as bool value, e.g. TRUE or FALSE, they will be returned as integers 1 or 0, respectively. Caution: If these fields are treated as text by Excel e.g. "True" or "False", they will be loaded as string.
  • String: All other fields are treated like text fields and a string is returned.

Loading SweepMe! data

Data that was previously measured with SweepMe! can easily be loaded again with ReadValues. The preset options are already adjusted for that purpose.