Skip to content

A Python package for reading exported TwinCAT Scope Files.

License

Notifications You must be signed in to change notification settings

CagtayFabry/pytcs

Repository files navigation

pytcs

A Python package for reading exported TwinCAT Scope Files.
Export your TwinCAT Scope files .svdx to .csv and read them into Python.

quickstart

Open a file and create a pandas.DataFrame:

from pytcs import ScopeFile

sf = ScopeFile("example.csv")  # open file and read metadata
df = sf.as_pandas()  # convert to pandas DataFrame

user guide

installation

Install using pip or conda/mamba:

pip install pytcs
conda install pytcs

loading data

To get started, open a file using pytcs.ScopeFile:

from pytcs import ScopeFile

sf = ScopeFile("example.csv")
sf
# > <TwinCAT Scope File at 0x2a157ca9310>
# > name:    example
# > runtime: 0:00:00.999000
# > start:   2022-05-02T13:56:24.376000+00:00
# >
# > Channels:
# >   *var_REAL64: 1.0 ms [None]
# >   *var_UINT64: 1.0 ms [None]
# >   *var_UINT32: 1.0 ms [None]
# >   *var_UINT16: 1.0 ms [None]
# >   *func_units_scaled: 1.0 ms [dV]

You can see the list of channels contained in the file together with the sample time and the unit. When creating a ScopeFile instance only the metadata about the channels is read from the file header. The actual channel data is not loaded, indicated by the * in front of the channels.

You can load all or only a list of channels by using ScopeFile.load()

sf.load()
sf
# > <TwinCAT Scope File at 0x2a157ca9310>
# > name:    example
# > runtime: 0:00:00.999000
# > start:   2022-05-02T13:56:24.376000+00:00
# >
# > Channels:
# >   var_REAL64: 1.0 ms [None]
# >   var_UINT64: 1.0 ms [None]
# >   var_UINT32: 1.0 ms [None]
# >   var_UINT16: 1.0 ms [None]
# >   func_units_scaled: 1.0 ms [dV]

accessing individual channels

Individual channels can be accessed by their name:

sf["func_units_scaled"]
# > ScopeChannel(name='func_units_scaled',
# >   time=array([  0.,   1.,   2., ..., 997., 998., 999.]),
# >   values=array([   10.,     0.,   -10., ..., -9960., -9970., -9980.]),
# >   sample_time=1.0, time_offset=0.0, units='dV')

CSV backends

The default implementation of pytcs uses pandas.read_csv for parsing CSV files. The pandas aims to provide the most flexible support for the various formatting options provided by the TwinCAT Scope export tool.

To improve performance for large files, datatable can be set as an alternative CSV backend. Datatable can be selected by using ScopeFile.read(..., backend="datatable") . However it should be considered experimental since some CSV formats can run into known issues and errors. If you want to use the datatable backend it is recommended run detailed tests with the target format (or change the target format).

exporting to pandas and xarray

To work with the data, convert them to a pandas or xarray object. Channels will automatically be loaded form the file when exporting to other formats. You can select individual channels to export.

sf.as_pandas(channels=["var_REAL64", "var_UINT16"])
# >                          var_REAL64  var_UINT16
# > time
# > 2022-05-02 13:56:24.376         0.0         0.0
# > 2022-05-02 13:56:24.377         1.0         1.0
# > 2022-05-02 13:56:24.378         2.0         2.0
# > 2022-05-02 13:56:24.379         3.0         3.0
# > 2022-05-02 13:56:24.380         4.0         4.0
# > ...                             ...         ...
# > 2022-05-02 13:56:25.371       995.0       995.0
# > 2022-05-02 13:56:25.372       996.0       996.0
# > 2022-05-02 13:56:25.373       997.0       997.0
# > 2022-05-02 13:56:25.374       998.0       998.0
# > 2022-05-02 13:56:25.375       999.0       999.0
# >
# > [1000 rows x 2 columns]

Exporting to an xarray.Dataset will preserve the metadata as attributes.

sf.as_xarray(channels=["var_REAL64", "var_UINT16"])
# > <xarray.Dataset>
# > Dimensions:     (time: 1000)
# > Coordinates:
# >   * time        (time) datetime64[ns] 2022-05-02T13:56:24.376000 ... 2022-05-...
# > Data variables:
# >     var_REAL64  (time) float64 0.0 1.0 2.0 3.0 4.0 ... 996.0 997.0 998.0 999.0
# >     var_UINT16  (time) float64 0.0 1.0 2.0 3.0 4.0 ... 996.0 997.0 998.0 999.0
# > Attributes:
# >     ScopeName:   tc3_scope_3_4_3145_3
# >     File:        C:\Python\weldx-dev\pytcs\tests\data\tc3_scope_3_4_3145_3-Co...
# >     StartTime:   132959733843760000
# >     EndTime:     132959733853750000
# >     start_time:  2022-05-02T13:56:24.376000+00:00
# >     run_time:    0:00:00.999000

dtype support

By default, all data will be read as np.float64. When importing data with ScopeFile.load using the option native_dtypes=True, imported data will be converted to their native dtypes.

TwinCAT Scope numpy IEC61131-3
BIT np.bool_ BOOL
INT8 np.int8 SINT
INT16 np.int16 INT
INT32 np.int32 DINT
INT64 np.int64 LINT
UINT8 np.uint8 USINT
UINT16 np.uint16 UINT
UINT32 np.uint32 UDINT
UINT64 np.uint64 ULINT
REAL32 np.float32 REAL
REAL64 np.float64 LREAL

export options support

The following table lists the compatible ✅ and currently uncompatible ❌ options of the ScopeExporter:

file and value formats
ScaleValues
true
false
DecimalMark
.
,
Seperator
Tab
Blank (space)
Colon
Semicolon
Comma
ExcludeDoubleTimestamp
true
false
SortChannels
true
false
FullTimeStamp
true
false
AdditionalEmptyLine
true
false
ContainEOF
true
false
HeaderKonfiguration
Full Header
ArraySeperator
Tab
AdditionalArraySeperator
true
false
IncludeTriggerInfos
true
false
IncludeMarkerTables
None
MarkerTableOnlyIncludedChannels
true
false
MarkerTableOnlyIncludedMarker
true
false