Package: apread
apreadpreviously: Catman ReaderSupport this projectCite this projectIf you use this software in any of your work, please cite it using the "Cite this repository" button in the right sidebar or use this:@software{leonbohmann_APReader,
   author = {Bohmann, Leon},
   doi = {10.5281/zenodo.8369804},
   month = sep,
   title = {{leonbohmann/APReader: v1.1.2}},
   url = {https://github.com/leonbohmann/APReader},
   version = {v1.1.2},
   year = {2023}
}GeneralRead binary files produced from catmanAP projects directly into python.CatmanAP procudes .bin files after each measurement. While it is possible to export as a different format (i.e. txt or asc) it's not efficient because one has to change the export format after every measurement. Here comes the treat: Just export as binary and use this package to work with binary files directly.After reading all channels from the binary file, the channels are analyzed and every measure-channel will receive a reference to a time channel, depending on the amount of entries in the channels and the fact, that the time-channel has to contain "time" or "zeit" in its name. What that means is, that a channel with x entries and the name "time - 1" will be regarded as the time-channel of any other channel with x Data Entries.Here is an example plot, generated directly from a binary file:Installation/UpdateAnywhere with python (note the uppercase U):pipinstall-UapreadHow it worksThe workflow of the package is straight-forward. You supply a binary file created with CatmanAP and the script will read that into python.First of all, the binary data is analyzed and packaged into seperateChannelobjects. When allChannelsare created, eachChannel.Namewill be checked against([T|t]ime)|([Z|z]eit), which mark time channels which usually are the reference.TheseChannelsmarked asistimeare the basis forGroups. Inside a group you will find theChannelX(time channel) and a bunch of other channels inChannelsY, which are the channels containing data in that time domain. The corresponding channels inside aGroupare found by analyzing their length. Since the total time measured is the same for all groups, it is assumed thatChannelswith the same data-length belong to the same group. Connecting the matching channels to the group give a structured representation of your measurement data.Now that the Data is available in python you are free to do with that whatever you want. Until Version1.0.xthere were some features in which you can save the data but that feature has been removed.UsageLets say you produced a file calledmeasurements.binand you put it in the directory of your python script, then you can create theAPReaderon that file. It's that simple. The Initialization may take some time depending on how large your .bin-File is.fromapreadimportAPReaderreader=APReader('measurements.bin')# this will read in the filePrint channelsAfterwards you can access theChannelsby accessing theAPReader.ChannelsMember.ChannelandGroupimplement__str__which will return the name and the length of data inside it.forchannelinreader.Channels:print(channel)# "Timechannel 1 - Standard" (120341 Entries)# "T12_ref" (120341 Entries)# "T33" (120341 Entries)# "Timechannel 1 - Quick" (3022344 Entries)# "F1" (3022344 Entries)# "ast089" (3022344 Entries)forgroupinreader.Groups:print(group)# "Timechannel 1 - Standard" (2 Data-channels, 120341 Entries)# "Timechannel 1 - Quick" (2 Data-channels, 3022344 Entries)Plot Channels/GroupsTo review your data on the fly, you can plot every entity in the data structure by calling.plot(). When plotting, every group will get its own figure window, in which all connected channels are plotted.# plot the readers datareader.plot()# plot all groupsforgroupinreader.Groups:group.plot()# plot all channelsforchannelinreader.Channels:channel.plot()As you can see, you can access the channels from the reader, which contains all channels (including time channels) or you can access them from the groups.There are some more functions to plot specific data. When plotting multiple channels each channel gets its own y-axis.group.plotChannel(0)# specific channelgroup.plotChannels(0,3)# channel 1 to 3 (1,2,3)group.plot([0,2,4])# channel 1, 3 and 5The same can be applied to theAPReader. The only difference is that you can plot specific groups instead of channels.reader.plotGroup(0)# specific groupreader.plotGroups(0,3)# group 1 to 3 (1,2,3)reader.plot([0,2,4])# group 1, 3 and 5External HeaderThanks to (hakonbars PR13) you are now able to access external header information usingchannel.exthdr, a dicitionary containing all keys as described inthis sheet.['T0']# ACQ timestamp info (NOW format)['dt']# ACQ delta t in ms['SensorType']# IDS code of sensor type['SupplyVoltage']# IDS code supply voltage['FiltChar']# IDS code of filter characteristics['FiltFreq']# IDS code of filter frequency['TareVal']# Current value in tare buffer['ZeroVal']# Current value in zero adjustment buffer['MeasRange']# IDS code of measuring range['InChar']# Input characteristics (0=x1,1=y1,2=x2,3=y2)['SerNo']# Amplifier serial number['PhysUnit']# Physical unit (if user scaling in effect, this is the user unit!)['NativeUnit']# Native unit['Slot']# Hardware slot number['SubSlot']# Sub-channel, 0 if single channel slot['AmpType']# IDS code of amplifier type['APType']# IDS code of AP connector type (MGCplus only)['kFactor']# Gage factor used in strain gage measurements['bFactor']# Bridge factor used in strain gage measurements['MeasSig']# IDS code of measurement signal (e.g. GROSS, NET) (MGCplus only)['AmpInput']# IDS code of amplifier input (ZERO,CAL,MEAS)['HPFilt']# IDS code of highpass filter['OLImportInfo']# Special information used in online export file headers['ScaleType']# 0=Engineering units, 1=Electrical['SoftwareTareVal']# Software tare (zero) for channels carrying a user scale['WriteProtected']# If true, write access is denied['NominalRange']# CAV value['CLCFactor']# Cable length compensation factor (CANHEAD only)['ExportFormat']# 0=8-Byte Double, 1=4-Byte Single, 2=2-Byte Integer (FOR CATMAN BINARY EXPORT ONLY!)Parallel reading of dataOnly available from versionv1.1.1-alpha1and aboveSeetest/testing.pyfor a full example. Modify the following around yourAPReadercall:importmultiprocessingasmp...if__name__=='__main__':# this line has to be included!# without 'processes=...'!pool=mp.Pool()# pass the pool to the readerreader=APReader(file,parallelPool=pool)# make sure to close the pool after you are done with itmp.close()mp.join()For the parallel loading to work, you have to define a parallel pool of processes in your top-level script. These processes will be accessed from withinAPReader-Functions. When passing no arguments tomp.Pool()it will automatically create as many processes as possible, according to the amount of threads your CPU allows (cores + virtual cores). It does not make sense to pass in more, since theAPReaderspawns the same amount of processes as there are CPU Threads. Increasing the amount of processes in your pool does not increase the amount of parallelism. It is fixed.Keep in mind, that parallelisation is not always faster. Spawning of processes is expensive and can be wasteful for small files.The results fromAPReaderstay the same and you can continue your analysis.Release HistoryVersion 1.1.1-alpha1Added converted timestamp property on channels (Channel.date)PropertyChannel.timewill be deleted at some point in the future...Parallel reading of binary filesMax degree of parallelism is automatically set to amount of available coresVersion 1.1Breaking changesRemoved saving functions, this will be up to the userSince these function change a lot based on current needs, I decided to remove the post-processing functionality completely. The user now needs to do the post-processing on his own, meaning the creation of plots using time and data channels...Changes(hakonbar PR13) Differentiate floating point precision(hakonbar PR13) Reading additional header information(hakonbar PR13) Supplying binary format referenceFixed null returning string conversion functionUsing regex to find time channelsImproved plotting with multiple axesPrinting channels and groups will now give a summary instead of all dataVersion 1.0.22Fixed an issue with groups where time channels are not recognizednow, user is prompted, when suspected time channel is foundplotting is not possible when there is no time-channel foundsave groups and channels even when there is no time channelVersion 1.0.21Updated serialisation-procedures to always encode inUTF-8Version 1.0.20Switched to explicit type hinting withtypingpackage (compatibility issues with python <3.9.x)Version 1.0.15/16Fixed an issue with saving and non-existent directoriesAddedgetasto generate formatted string without savingVersion 1.0.14Output file-names updatedVersion 1.0.12/13Group channels with their time-channel into "groups"Multiple plot modes:Whole fileChannel/Group onlyOutput datajsoncsvVersion 1.0.11Progressbars indicate read-progress of filesMultiple plot modesVersion 1.0.0Convert catman files to channelsMetaLeon Bohmann –mail@leonbohmann.deDistributed under the MIT license. SeeLICENSEfor more information.This software comes with no warranty, expressed or implied. Use at your own risk!https://github.com/leonbohmann/apreader