Skip to content

Latest commit

 

History

History
210 lines (176 loc) · 7.45 KB

README.md

File metadata and controls

210 lines (176 loc) · 7.45 KB
Raw

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 ✅