Examples

The following chapters include some of the example-procedures in /examples. At the moment the creation of a procedure is fully text-based. Dont panic: it is easier than it looks like. Go to The diaGrabber-API to get all a full overview over the possibilities of diaGrabber

a simple 2d-plot

# -*- coding: utf-8 *-*
# this is the most easiest example: one file, two dimensions, a simple graph to plot
#######################


# after installing diaGrabber you can create procedures everywhere
# you just have to include some of the modules of diaGrabber via...
from diaGrabber import source, target, plot
from diaGrabber.source.methods import merge, calc, exclude, transform

# thats your source: a libreOffice-file
s = source.libreOfficeCalc(
	file= "ressources/2d.ods", sheet="Tabelle1", dataType="float")

# this will be our 'x'
x = s.basisDimension(
	name="I",unit="mA", cellRange="A2:A100", resolution=50)
# and this our 'y'
y = s.mergeDimension(
	name="time", unit="s", cellRange="B2:B100")

# read more about merge- and basis-dimensions the the documentation
# to understand its differences


# we need a target to fill with the values from our source:
t = target.coarseMatrix(s)
t.fill()


# ... and something to plot:
p = plot.Gui(t, showPreferences=False)
p.plot()

# at the end: we save the plot in file
t.save(name="test",folder="output",ftype="txt")

a software-oscilloscope

# -*- coding: utf-8 *-*

# In this example we want to read values from a programm generating a stream.
# diaGrabber is able to plot the values in realtime - therefore it's possible
# to build something like an oscilloscope.


# business as usual: we import everything that we need from diaGrabber
from diaGrabber import source, target, plot
from diaGrabber.source.methods import merge, calc, exclude, transform



# we create a instance of the stream-source-class
f = source.stream(
	# i've written a programm which will generate a sine and a cosine-stream
	# its written in quess what ... python
	command = "python",
	# thats the name of the file
	file="ressources/test_stream.py",
	# if the stream is complete it will print "done". giving this information to
	# diaGrabber will stopp the readout-process when the stream is done.
	stopVia="done",
	# all values printed in one line are seperated by a space:
	dimSeparator=" ",
	# the stream produces float-numbers:
	dataType= "float",
	# if we want to kill the stream direct from diaGrabber:
	keyToEndProcess="\x1a", #Esc
	# this python-script only works when it's started in a shell - other executables
	# can run without it
	runInShell=True)


# the stream only gives merge-(y)-values.
# therefore we create a basis as a counter
n = f.basisDimension(
	name="n",
	unit="-",
	resolution=50,
	# there are two different counters available:
	index="fixedCounter",#from 0 to 49 (resolution-1)
	#and: index="runningCounter", #from 0 to x, where x in the number of readed lines
	include="chronic"
	# with 'chronic' we define that this basis stores only the last n values,
	# where n is the resolution
	)

# here are our two mergeDimensions:
ch0 = f.mergeDimension(
	name="ch0",
	unit="m",
	index=0)
ch1 = f.mergeDimension(
	name="ch1",
	unit="m",
	index=1)

# to explain to you the merge-method 'alias' we add annother mergeDimension
# which only stores  new value if this value is bigger than the last value at
# the same basis-position
ch0max = f.mergeDimension(
	name="ch0max",
	unit="m",
	index=0,
	merge=merge.max())

# with the following command we let the mergeDimension 'ch1' only to take new
# values if the last value of 'ch0max' also was taken
ch1.alias().append(ch0max)


# now we set some arguments for our stream:
f.setArgs(
	# in many cases the stream-source would produce faster new output, than
	# diaGrabber can process and plot
	# therefore we tell diaGrabber only to grab as much values as it can
	# process in the same time:
	readoutEveryNLine="calc",
	# we want to know the number of skipped lines:
	showCalcNLine = True,
	# every n lines diaGrabber will print a status:
	infoEveryNLine=1e3)

# we give our source to the target:
t = target.coarseMatrix(f)

# we create a Gui-instance (graphical user interface)
p = plot.Gui(t)

# we start the interactive plotting of the readout:
t.fillInteractive(p,
	# we have per default 20 frames-per-second ... but 15 are enough for us
	fps = 15,
	# because our sine-waves increase there values continous an autorange
	# of the y-axis is reasonable
	enableAutoRange = ['y'],
	# one of the tree mergeDimensions was just a 'helper' and we dont want to
	# plot it. so we define what merge to plot over what basis:
	show=[('ch0','n'),('ch1','n')],
	# the the stream in done, the Gui will close too
	closeWhenFinished = True)

# if the stream is complete we save its last values in file:
t.save(name="stream", folder="output",ftype="txt")

compare different sources

# -*- coding: utf-8 *-*

# this example shows you the posiblity to compaire and connect values of
# different sources.

# the make this more elusive imagine there are two bavarian professors
# roaming trough the deep bavarian forest (in direction x,y) and explore rare butterflies.
# there are 5 different types of them: (0,1,2,3,4).
# both professors want to know whats the best height for its habitat
# there are some differences in the written results of the professors:
	# * different prefixes (one write distances in km, the other im m)
	# * differenct ammount of values
	# * different resolutions of the basiDimensions
	
# the aim is to connect the results of the 'Type' and to compair the results of
# "best height/Mueller" with "best height/Schroeder"

from diaGrabber import source, target, plot
from diaGrabber.source.methods import merge, calc, exclude, transform


#here are Prof. Muellers results:
#################################
mueller = source.libreOfficeCalc(
	file= "3d_b.ods", folder="ressources/", sheet="result", dataType="float")
##BASIS (in km)
x = mueller.basisDimension(
	name="x",unit="m", prefix='k',cellRange="a2:a229", resolution=20)

y = mueller.basisDimension(
	name="y", unit="m", prefix="k", cellRange="b2:b229", resolution=20)

##MERGE
type_max = mueller.mergeDimension(
	name="Type", unit="-", cellRange="d2:d229", merge=merge.max())

bestHeight = mueller.mergeDimension(
	name="best height/Mueller", unit="m", prefix="c", cellRange="c2:c229")
# the best height is defined as the height, where the type is maximal
bestHeight.alias().append(type_max)



# and this are Prof. Schroeder results:
#######################################
schroeder = source.libreOfficeCalc(
	folder="ressources/", file= "3d_a.ods", sheet="sheet1", dataType="float")

##BASIS## (in m)
x = schroeder.basisDimension(
	name="x",unit="m", cellRange="a2:a317", resolution=30)

y = schroeder.basisDimension(
	name="y", unit="m", cellRange="b2:b317", resolution=30)

##MERGE##
type_max = schroeder.mergeDimension(
	name="Type", unit="-",
	cellRange="d2:d317",merge=merge.max())

bestHeight = schroeder.mergeDimension(
	name="best height/Schroeder",  prefix="c",
	unit="m", cellRange="c2:c317")
bestHeight.alias().append(type_max)
# in contrast to prof. mueller prof. schroeder also captured the quantity of the
# butterflies:
quantity = schroeder.mergeDimension(
	name="Quantity", unit="-", cellRange="e2:e317")



# now we hand over the results of Prof. Schroeder and Prof. Mueller to the target:
t = target.coarseMatrix( (schroeder,mueller) )


#we create the Gui-instance
p = plot.Gui(t, colorTheme = "bright")

# we fill our target interactive
# (later we will see the routes that both profs. have taken)
t.fillInteractive(p,
	# ..and limit the number of readout-lines per second to 20
	lps=20,
	# ... frames per second will be 5
	fps=5,
	# ... and show (at first) only two merge-values
	show=[("best height/Schroeder",'x','y'),("best height/Mueller",'x','y')]
	)

# we like to interpolate one the results without ovewriting them
# that's why we copy the relevant result
t.copyMerge("Type","Type2")

# now we start the interpolation with 'interpolateFine'
# this is a very powerfull, but slow method:
t.interpolateFine(
	# we want to interpolate only the following result:
	mergeName=["Type2"],
	# the focusexponent weight the moments of the existent point on an empty
	# point as follows: moment = 1 / (distance_to_point^focusExponent)
	# therefore a big focusExponent gives very sharp crossover between points
	focusExponent=12,
	# the moment of existent points depends on the ammount of points in this cell
	evalPointDensity=True,
	# we dont want to get interpolated values on points which are to far away
	# so we define a max. absolute distance:
	maxDistance={"x":1e3,"y":1e3} # which is 1 km
	)

# we copy the result again
t.copyMerge("Type2","Type3")

# the last copy will be posterized. with this method it is quit easy to
# recognize areas in an image which belongs together.
t.posterize(
	# because there were only 5 discrete types (0-4) we take this values again:
	values=[0,1,2,3,4],
	mergeName="Type3" )


# now we want to see all merges - that's why we don't set the show-argument this time
p.plot()
# diaGrabber only draw four different displays - all other are tabbet bedind
# the last display
# trough the power of 'Qt' you can grab a tab and move it wherever you want.
# klick on a display the the right preference-tab will be shown.

reading source-files from multiple folders

# -*- coding: utf-8 *-*

## this example show you to read source-files from multiple folders
## have a look at diaGrabber/examples/ressources/timeFolders
## here you will find hundreds of folders. in every folder is a file called
## "line5_T.xy". it include values of a distance and a temperature
## the folders itself represents different time-values
########################################################

## at first we import everything we need from diaGrabber
from diaGrabber import source, target, plot
from diaGrabber.source.methods import merge, calc, exclude, transform

## we create a instance of a plainText-source
f= source.plainText(
	folder="ressources/timeFolders",
	file="line5_T.xy",
	dimSeperator=" 	",
	dataType="float",
	## we don't want to see the statusbar for every file, so we set:
	silentReadout=True
	## if you want to have a message for every new file readout, set
	## silentReadout to False
	)

## if we dont want to do further work on the dimensions itself we dont have to
##  write x = source.xDimension - just calling the method is enough
f.basisDimension(name="distance",unit="m", index=0, resolution=300)
f.mergeDimension(name="Temperature",unit="K",index=1)

## here comes the new part: the folders in the main 'timeFolder' will
## represent a basisDimension. trough defining index='folder'
## if you have a nested system of folders you can add further basisDimensions
## like the following. in this case the order of reference builds the folder-system
f.basisDimension(name="time",unit="s",index="folder", resolution=300)

## we create a target and a GUI-instance
t = target.coarseMatrix( (f) )
p = plot.Gui(t,colorTheme = "bright")

## we command diaGrabber to readout all source-files and to fill the target through:
t.fill()
## we command to plot:
p.plot()


# the interactive readout works too:
t.fillInteractive(p, fps=5)

reading from large files

# -*- coding: utf-8 *-*

# This example shows the readout of a large plainText-file
# during this example you will see the Gui (the graphical user interface) for
# 3 times.
# to know where you are in the procedure, I will tag this positions like this:
###################
######(SEE?)#######
###################

# at first some business as usual: we import everything that we need from diaGrabber
from diaGrabber import source, target, plot
from diaGrabber.source.methods import merge, calc, exclude, transform

# our file is located in ressources/, each dimension is seperated with a space
# the values are of type float (something like 1.23)
f= source.plainText(
	folder="ressources",
	file="large.txt",
	dimSeperator=" ",
	dataType="float",
	#using the following attribute we avoid the (maybe time-expensive)
	#counting of lines:
	nFileLines=40000
	)


# this file is the result of a simulation of a 2d-scan of an electron-beam (eBeam)

# in the file is a timestamp the the beginning of each line:
time=f.mergeDimension(name="time",unit="s",index=0)
# the eBeam scans with a triangle-wave over a substrate
# therefore it moves in x-direction with a simple linear ramp-function
ramp = f.basisDimension(name="ramp",unit="V", index=1, resolution=300)
# and in y-direction with a triangle-function
triangle = f.basisDimension(name="triangle",unit="V",index=2, resolution=300)
# and the signal of an apperature to measure the eBeam:
beam=f.mergeDimension(name="beam",unit="V",index=3)



# the following definitions are optional
##############

# the sweep-signal of the scan in stored in Volt
# to get the real deviation we need to transform the Volt-signal into Meters:
Volt2m_x = transform.interpolationTable([
	[-1,-74.095e-3*2],
	[0,   0],
	[1, 64.701e-3*2]
	], "m")
Volt2m_y = transform.interpolationTable([
	[-1, -53.168e-3*2],
	[0,   0],
	[1,   51.716e-3*2]
	], "m")
# the transform-module has many other fancy classes to transform units
# checkout the documantation!

#now we append the two transform-instances to our sweep-signals:
ramp.transform().append(Volt2m_y)
triangle.transform().append(Volt2m_x)

# for some reason we only want to take those values where the triangle moves up.
# to exclude all other values we let diaGrabber calculate the middle-difference
# of the last 3 values of the triangle-signal
# because of the simulated scan we could also only use the last value, but
# in real measurements the fluctuation of a signal can be so large that we need
# to middle our calculations in some way
triangle.calc().append(calc.delta(3))
# now we define to exclude all values where the result of the calculated values
# is less than zero:
triangle.exclude().append(exclude.calcSmallerValue(triangle.calc().get(0), 0.0))

# we give the source to our target:
t = target.fineMatrix(f)

# we initiate the graphical user interface:
p = plot.Gui(t,
	colorTheme = "bright")

# our source is relatively large, maybe we dont want to readout every line in it.
# to spare time we choose only to read every fifth line in the first run:
f.setArgs(readoutEveryNLine=5)

# we readout the source and fill the target with its values
t.fill()
# we command to plot
p.plot()
###################
######(SEE?)#######
###################

# because we didn't know the range in which our basisDimensions vary diaGrabber will
# scanns the file before the first readout for the max. and min. values of
# all unbounded basisDimensions
# if we used 'fillInteractive(p)' than 'fill' we would see a bright point somewhere in the image.
# this is our point of interest.
# diaGrabber allow you to zoom to a defined point in the targetMatrix.
t.autoZoom(
	mergeName='beam',
	value="max", # in this case we are looking for the maximum value of 'beam'
	scale="relative",
	level=0.15,
	# we want to set a range for all basisDimensions of 15% above and under the point
	)

# now we want to read every line from the source:
f.setArgs(readoutEveryNLine=1)


# we fill our matrix again. but now we want to look at the readout-process
# with the following method:
t.fillInteractive(p, fps=5)


# now i want to show you some process-methods for matrix-like targets:

# this method allows you to transform all dimensions which has a filled
# transform()-container
t.transformDim(rebuildMatrix=False)
# if our tranfrom-method is far away from linear function we also can rebuild
# the matrix after the transfromation via rebuildMatrix=True

# this transformation only works for those transfrom-instances which wouldnt
# have an adhoc-transformation in the readout-process. to do this just add the
# argument 'adhoc=True' in a transform-instance


# as you have seen our bright point is better resolved now. but there is much empty
# space arround it. to fill the gaps we choose the following interpolation-method
# on our 'beam'-field
t.interpolateFast(mergeName="beam", method="cubic")


# finally we plot again.
p.plot()
###################
######(SEE?)#######
###################

working with n-dimensional problems

# -*- coding: utf-8 -*-

# This example show you the possibility of working with multidimensional problems

# As usual we need to include all modules of diaGrabber
from diaGrabber import source, target, plot
from diaGrabber.source.methods import merge, calc, exclude, transform


# This is our source: a libreOffice-document.
# There are two sheets in the document:
	# in 'functions' are all values written as a function of the mergeDimension
	# in 'values' are only the raw values of it.
	# REMEMBER: source.libreOfficeCalc can only read out values, not functions!
ods = source.libreOfficeCalc(
	file= "5d.ods", folder="ressources/", sheet="values", dataType="float")

# In this dokument one mergeDimension (merge) depends on four different
# basisDimensions (one,two,tree,four)
merge = ods.mergeDimension(
	name="merge", unit="-", cellRange="F3:F600", merge=merge.max())

# the given prefix 'm' stands for milli. If you use this attribute all values
# were transformed in the readout. in this case /1000
one = ods.basisDimension(
	name="one",unit="m/s", cellRange="A3:A600", resolution=40)
two = ods.basisDimension(
	name="two", prefix="m", unit="m/s", cellRange="B3:B600", resolution=40)
three = ods.basisDimension(
	name="three", prefix="m", unit="m/s", cellRange="C3:C600", resolution=40)
four = ods.basisDimension(
	name="four", prefix="m", unit="m/s", cellRange="D3:D600", resolution=40)


# now we put the source 'ods' into the target
t = target.fineMatrix( ods )

# the command to fill the target with the values of the source
t.fill()


# to see the result we need to create a instance of plot.Gui:
p = plot.Gui(t,
	colorTheme = "bright",
	closeWhenFinished = False)
# there are many ways to individualize the Gui. You can find all possible
# attributes in the documentation of this class.


# now the command to plot:
p.plot()

# if everything worked well you should see a grey-image and on the left side
# a preference-menue. Right-click on the colorbar to choose a different set of
# colors.
# because its very hard to visualize data with more than 3 dimensions (x,y,contrast)
# the mergeValues in the basisDimensions 'tree' and 'four' were concentrated.
# the standard for this procedure is 'mean'

# if a mergeDimension is fragmented in a basisDimension it can be better to
# use 'sum' instead of 'mean'.

# it is also possible to show the mergeValues at a given 'position' of the
# basisDimension or to show the basisDimension a a timeline via 'as time'.

# a very fancy method is to slice your nD-target. to understand this think of
# a tasty smoked peanut-tofu. imagine the color the tofu is your mergeDimension
# and the position x,y,z are your basisDimensions. your are not able to see
# through the tofu. you only see the border.
# using slices is like taking a knife and slice the tofu in every position you want.
# to use this function you first have to create a second display-widget with
# the add-button on the main widget.
# than 'activate' the slice, choose this its displaynumber and the basisDimension
# you want to look at.
# et voila: a line appears and on the second image the slice is shown.


# now close the image.
# i want you to show the method 'fillInteractive'. With this you can watch the
# plot while the sources were readout.
t.fillInteractive(p,lps=10)
# lps stands here for 'lines-per-second'

# if everything works you see the plot -black-.
# as you see the image 'is filled' with the values of the source - but quite slow.
# you can speed up the readout trough deactivating the limit of the readout-rate.
# the main reason of the slow readout is however the time-expensive plotting of the image.
# therefore you can fill your target faster is you decrease the 'frames per second'
# from 20 (default) to ... maybe 5?

# annother method to accelerate the procedure is to decrease the displayed size of
# your target trough manipulating the 'plot-range' of the displayed basisDimensions
# there are three values: the start- and stop-position and the step.
# if your basis has a resolution of 40 there are 0 to 39 positions.
# increasing the 'step' indicates diaGrabber only to plot every 'step' position
# eg. start=0, stop=20, step=5 will only plot the positions 0,5,10,15,20