A 20 minutes guide to SigLab

 
SigLab is a signal calculator. Its goal is to ease the analysis of signal processing simulation results. It allows to view and to manipulate monodimensional signals in a interactive and easy way. This 20 minutes guide should help you to start using it. In fact, I am pretty sure that you will never look at the documentation after having read this document except if you intend to program new functions in SigLab. SigLab is a Free Software released under GPL , the General Public License, please refer to it for details.
 
SigLab was written thanks to the following sponsors :
 

• TDF-C2R (TéléDiffusion de France - Centre d'Etudes en Radiodiffusion et Radiocommunication), Philips Semiconductors Rennes. TDF-C2R and Philips Semiconductors Rennes are concurrently using a proprietary signal processing simulation software and Ptolemy a marvellous free software for simulating signal and video processing algorithms. However compared to the proprietary software used, they really were really missing an interactive signal analysis tool. Free&ALter Soft proposed them then to sponsor this developpment and they accepted,

 

• to learn how to become a sponsor please refer to the sponsor file.

 
SigLab was written by Free&ALter Soft (http://freealter.com). Free&ALter Soft was born in December 1996, since then we provide services around free software to companies and especially to research centers. If you want to know more take a look at our web site. SigLab is one of our development that shows how we master different free software (Ptolemy, Scilab, Tcl/Tk, SpecTcl in this case).
 
You should read the documentation in the following order. First, this introduction, then play a little with siglab, then the technical references, then the user manual, and finally the programmer manual (advised in any case).
 

1. Cruising in signals

 
Before starting SigLab, please install it. Refer to the installation documentation.
Start SigLab by typing :
 

		siglab

 
on a command line of a terminal.
 
You should see the 3 following different windows appearing :
 
 
Fig 1 : the siglab graphical interface
 
 
Fig 2 : the classical scilab window
 
 
Fig 3 : the graphic window in which all signals will appear
 
First, we are going to load 2 signals in siglab. Click on the button with a question mark on the 4th line of the graphical interface.  The following window for choosing a file appears :
 
 
Go in the directory $SCILAB/siglab/test and choose sinus.txt. Click on open. A sinus curve appears  in the graphic window. Now repeat  this operation and load the file rand.txt. You should now have on your graphic window screen the following curves.
 
 
We are now going to move a little in these curves. You should be aware that in fact only a part of the 2 curves are displayed (1000 points). The 2 first button lines of the siglab graphical interface are going to allow us to move into the signals. In fact we are going to start with the buttons on the second lines. Click on the button >, and look at the curve you are now looking at points 2 to 1001 instead of 1 to 1000. Click on the button >>, you now look at the points 1002 to 2001. In fact, we moved from one window. You can now play and try to come back with the buttons < and <<.
 
The button >| allows you to reach the end of the curves. The number of points of each signal is worked out when loading the signal for the first time. You do not have to worry about it. You will then see something similar to the following  graphic :
 
 
Obviously in clicking on the |< you will come back at the start of the curves. We are now going to zoom in and out. To zoom in you just need to click on the button "/2". The size of the window displayed is divided by 2 and the center point of the window stays the same. So if you are at the beginning of the curve with 1000 point displayed, you will then see the signals between the sample 251 and 750 (half of 1000 centered on point 500).
 
 
You will zoom out in clicking on the button "x2". Try to zoom out several time. You will be quickly stopped and the display will not change. This is due to the maximum internal window width limit.
 
Siglab maintains an internal memory buffer of the signals. This buffer has a given limit. If you try to exceed this limit the programm refuses. Happily for you, you may change this limit to fit your available memory and needs. This is done in asking for the graphic manager (button GM).
 
 
The first line is an entry the label of which is "Internal window width". Just type the number of points that fits your needs. For example here, try 20000. Then click on OK. And try to zoom out again with the "x2" button. You will be able to zoom as much as you wish till 20000 points. Obviously, the wider the window, the slower the program.    
 
The first line of buttons and entry in the siglab interface allows to do finer moving within the signals. You can place 2 cursors on the signal sheets C1 and C2. To do that you have 2 solutions :
 

• either you click on the button C1 (resp. C2) on the siglab interface and then click on a point in the signal graphic window. You see appearing in the C1 entry the abscisse of the point that you clicked on. An improvement of the existing design would be to materialise these cursors with 2 vertical lines on the signal graphic windows.

 

• or you directly enter an abscisse value within the C1 (resp. C2) entry on the siglab interface. That is what I did here.  

 
 
Once you have a C1 and C2 value you may zoom between these 2 values in clicking on the x button.
 
You may see all values for all signals in clicking on the button V. For instance, hereunder I am ready to ask for all values between point 1 and 10.
 
 
Beware for an unknown reason (Doc Scilab you hear ?) the value displays is a very slow process. You will then get the window hereunder :
 
 
By the way, it is time to do a small remark on the abscisse numbering : it starts at 1 and NOT AT 0. I know that is not usual for C programmers but Scilab is programmed in Fortran and then all matrices start with element 1. This is very natural for signals, however remember that when you are in the frequency domain : the frequency 0 is at point 1 and all frequencies are then shifted of 1 !
 
Let us continue to play with the graphical manager. (click again on the GM button). You remember the nice window :
 
 
It allows you not only to change the internal window width but also to change the position of the curves, not to display a curve, to add a grid on a curve,to display the amplitude and te phase of the curves, to display the curve with the sampling period.
You change the position of the displayed curve in changing the number in the corresponding entry. You ask for a grid in click in the check button grid, you ask for displaying the amplitude and the phase of a curve in click in the check button real/db-ph, and you suppress the display of a curve in unselecting the display check button.
You display the curve with the sampling period in changing the number in Te,the sampling frequency Fe will be modified in typing return. Don't forget to click in the check button 'Use Te'.You can also choose you the scale of the ordonnee axes thanks to Ymin and Ymax. Once you are happy click on OK. If you chose the same options as we did here you will see :
 
 
The Default order button replace each signal in the frame corresponding to its number :signal one first, then signal two ect...
The Show cursors button allows you to see the cursors C1 and C2 on the graph.
Selecting the Show buffer button, you will see the current buffer (that mean a part of a signal that you have selected before). In fact you will see a part of a frame in color.
You can choose not to display any signal when you work out it, in clicking on the button No display, and only see it when you have finished in unselecting this button. This is very handy when deleting a bunch of signals.
 
As you see it, I also put the deletion of a signal and the saving behind the graphical manager. To del a signal, just click on its button and then click on del. The signal will disappear and will not be available anymore. To save a signal clik on the save button. The following interface appears :
 
 
Select a the signal that you wish to save and the portion of the signal to save. Then choose a file name (don't forget the data type: ascii ...), or click on the ... button. A classic file name selection window for saving will appear.
 
They are 2 things that are important. First, today, it is only possible to save samples that are in memory (you remember the internal memory width explanation ?). So the best way to achieve that, is to save things that are displayed or to display what you wish to save.
 
Second, there are a lot of file format that are available in scilab and then in siglab. I decided to base all  file type identification mecanism on the file extension. So basically, if you want to save your point in a binary file with longs int you MUST use the .l extension in the filename. And if you wish to save complex values in the same way, it MUST be the .cl extension. If you wish to save complex values in a text file, you must use the .complex extension. Please, look in the corresponding combobox in the save dialog to see all the possible file type and then extensions. Finally, if no extension match, it is supposed that it is an ascii file. I usually use either .txt or .val extensions in this case, but you are free to use what you wish.
 
We don't yet talk about the small button i between the GM and the del buttons. It is noted i like informations. Clicking on it you will get the important informations for each signal : type, length, duration ...
 

2. Operating on signals

 
You are certainly impatient to see how Siglab handles operations on signals. You remarked the 2 buttons S1 and S2 on the 4th lines of the siglab graphical interface. They allow you to operate on signals as if they were numbers. Let's try to click on S1 then on the button + then on S2 and  finally on the button OK at the bottom. You will see on the central entry the string S1 + S2.
 
 
You should have the following result :
 
 
Yes it works. It is a calculator on signals. A new S3 signals is created and you can do on it everything which is possible with signals loaded from a file. However a fair warning. This worked out signal is not of the same nature as the signals that you previously loaded. It is NOT a signal which is fully calculated, stored in a temporary file and then accessed.
In fact, the values are worked out and stored when necessary. For example if you move in the signal from one window and if the values were not previously calculated they are worked out on the fly. This means that if you suppress a signal which is used for the work out you will have strange results. You may well see in the scilab window errors and the operation that you asked will not work. Suppress the signal that can not be worked out anymore and everything should become normal again.
 
Please, don't be afraid by these warning. I never met such a problem during a "real" use of siglab. I just honestly warn you for the day where ... and in order to explain how siglab works and what are the consequences of this behaviour.
 
I am not going to detail much the possible operations. However, you may :
 

• add, divide (beware 0), multiply, substract 2 signals or a signal and a constant value. Remark that the %i is in fact the unit imaginary value (i or j depending of your application domain) in scilab notation. In fact, basically, all operations that you may do with scilab on a vector is possible (I did not say that it is available, I say that it is possible).

 

• You may also use the operation buttons that are on the right of the panel (abs(, ones(, sqrt(, ^2, log(, exp(, tan(, atan(, cos(, acos(, sin(, asin(). The only curious one is "ones(" that will generate 1 for each sample of the origin signal.

 
These buttons  are supposed to be used in the following way. Click on them , click on a signal and then either close the parenthesis and continue with other signal or operations (abs(S1)+sin(S1)) and/or click on OK.  Do not worry too much with closing braces as the good number of closing braces will be added at the end to match the opening braces. You may then just click on sin( then S1 and then OK.
If the operation did not succeed (due to a division by 0 for example), a message window will pop up and warn you. A signal will however be created but only with 0 values. The log is the "natural" logarithm (the log in base e).
 
If you made an error then click on the button "<-" and it will delete the last order you give (except for signals where you will have to click many times on the button till all signal characters are deleted). The button "C" will delete the whole line.
 

3. Buffer management

 
You are beginning to have explore a bunch of siglab possibilities. The remaining possibilities concern the second panel of buttons. You remarked that till now we did not speak of the 6 small buttons at the very right of the siglab. They allow you to change the operation buttons. If you click on B, you will get the following interface :
 
 
These buttons allow to store values into an internal buffer and to do operations on it among other things (signal or noise generation, and some complex functions such as fft, filtering, convolution and correlation).
 
Basically, you only need to select a signal portion in clicking on the copy button. You get the following dialog :
 
 
You select the signal, a first and a last point, and all the points are put into a special internal memory. You can either paste this values in a new signal (useless, only here for testing, or do a filter on another signal with these values (click on bfilt or filt).
To do a FFT (click on FFT) ,or an inverse FFT (guess where to click), you just have to select a signal, a first and a last point, and a width for the FFT. After doing an absolute value on the FFT of the sinus you will have the following curves :
 
 
The output of the FFT is a complex signal. The real part and the imaginary parts are displayed on two graphs in the same color, on the first graph the real part and on the second graph the imaginary part. The absolute value allows to have the energy of the signal.
As you can see, if you copy the first signal between 1 and 1000, the part of the signal you that you have selected is colored in pink, to suppress the color you just have to open the graphic manager and to unselect the button Show buffer.
 
You can also create almost all signals as you want, using gen or noise buttons(signals generation or noises generation). If you click on the button gen you will get the following interface :
 
 
This interface allows you to create square, triangular, sinusoidal, complex sinusoidal, ramp,Dirac, constant signals, and even sery of Dirac. All you have to do is to select the type of the signal and to give the different parameters asked, to have the wanted signal. For example, choose the following options :
 
 
If you click on the button Gen, you will have directly the foolowing result. But if you click on OK, the command will be writed on the central entry of the siglab interface and you will have to click again on the button OK at the bottom.
 
 
 
The generation of a noise is very similar as the generation of a signal.You can generate uniform, gaussian, complex uniform, complex gaussian noises and random bits.
The two last buttons of this panel allow you to do a correlation or a convolution between two signals.
 
 

4. More functions

 

• The button C.

 
If you click on it,you will see the new panel of buttons :
 
 
As you can see, you can get the derivation and the integration of a signal (buttons deriv. and integ.). The button thres( performs a threshold.  Its values are 1 when the signal is over a threshold, and 0 when it is under.
You can also do, a delay on a signal which make the signal beginning where you want, a spectral estimation, an up sampling, a down sampling, a merge sampling of different matrix files, a split sampling, and  a clamp which gives you a signal between 2 values. For example if you do a clamp on S1 between the values -0.3 and 0.2 you will get:
 
 
The Sync button allows you to refresh your graphics especially in case of problems ("ghost signals" destroyed but with a button still existing, ...). This button should not survive long. It had a role during the debugging of SigLab, today siglab is supposed to be much more robust it used to be (at least that is what my testers said when hitting me some times ago and says thanking me for this marvelous software).
 

• The button D :

 
 
I don't think you want any explications for the five first buttons which are PI, real(, imag(, phase(, log10(, and db(.
The button stat gives you all statistical informations on a signal.
If you click on cut, you should have to select a signal and to give which part of the signal you want to cut, but you can only do it on a matrix file.For example, try to generate an uniform noise and to cut it between 150 and 400. You will see :
 
 
 
 
If you click on button paste to, you should have to give the new origin of the signal which is in  the buffer, so to select which signal you want, you have to do a copy of it before.
The button dup allows you to dupplicate physically any signal that you want.
You can also do an infinite impulse response filtering thanks to the buttton iir.
The button exec allows to execute a macro. Basically, it execute all scilab instructions that are in the file that you indicated. In writing in a file all instructions that you see on the scilab command line when you use siglab, you may create a "macro" for Siglab.
 

•   And last the button E :

 
 
These functions are wrappers around standard ones to avoid imaginary results.
 
This is enough for a start. Use and enjoy. Do not forget to look at the other parts of the documentation when having a question. I hope that you will enjoy its use. Please report all problems that you will meet to arnaud.laprevote@freealter.com or directly on the scilab newsgroup (comp.soft-sys.math.scilab), I read it once a week.