PaTeS


Table of contents:


Introduction:

“PaTeS” is a toolbox dedicated for random sampling patterns analysis and testing.
You can download it on GitHub. You can also download the zipped version here .

Programming language
“PaTeS” is written almost entirely in Python.

Platform
The toolbox works well with Linux and OS X operating systems.

License
The software is published under GPL license.

Current version
Currently (August 2014) PaTeS v. 1.0 is available.


Paper:

A good start for the topic of random sampling patterns is a paper:  
“Generation and Analysis of Constrained Random Sampling Patterns”
The paper is available on arXiv .

Tutorials:

The tutorials below presents the topics from the paper in a more informal way:

  1. Introduction to random sampling patterns.   [pdf]
  2. Statistical evaluation of sampling patterns.   [pdf]

General description

“PaTeS” toolbox consists of two parts. The first part, a core of the toolbox, is a set of sampling pattern generators. There are three generator algorithms currently (PaTeS v1.0) implemented in the toolbox: jittered sampling (JS), additive random sampling (ARS) and ANGIE algorithm.

Figure 1: Elements of “PaTeS”

The second part of the toolbox is a set of sampling patterns evaluation functions. These functions are:

  • frequency stability evaluation
  • evaluation of minimum distance between sampling points
  • evaluation of maximum distance between sampling points
  • correct patterns counter
  • pdf evaluation
  • unique patterns counter

It is possible to run the evaluation functions directly, but it is recommended to use “PaTeS Evaluation Frame” instead. With this frame it is possible to automatize the process of patterns evaluation. Scheme of “PaTeS Evaluation Frame” is presented below. It consists of two loops.

Internal loop of “PaTeS”:
In the internal loop generated pattens are firstly tested for frequency stability and min/max distances between the sampling points – user have a possibility to switch-off one, two or all of these tests. When the first tests are done, the number of correct patterns is counted – a pattern is counted as correct if its previously computed errors (freq. error, min/max error) do not exceed a limit allowed by the user. Finally, four tests may be performed on sampling patterns:

  1. – PDF test performed on all the patterns
  2. – PDF test performed on CORRECT patterns only
  3. – counter of unique patterns
  4. – counter of CORRECT unique patterns

The user is in control of switching on/off the above tests. The unique patterns counter may be set to store files with unique sampling patterns.

External loop of “PaTeS”:
When the tests are done, stop conditions are tested. If the stop conditions are not fulfilled a new pack of patterns is generated with the same settings. If the stop conditions are fulfilled, the frame leaves the internal loop. There may be more types of sampling patterns to be tested, if that is the case the frame returns to the internal loop again.

Figure 2: Scheme of “PaTeS Evaluation Frame”

The stop conditions checked by the frame are as follows:

  • Convergence conditions:
    1. – convergence of results from frequency stability evaluation
    2. – convergence of results from minimum distance evaluation
    3. – convergence of results from maximum distance evaluation
    4. – convergence of results from correct pattern counter
    5. – convergence of results from pdf evaluation

  • Technical conditions:
    1. – max time spend on each type of patterns
    2. – minimum number of patterns to be tested
    3. – maximum number of patterns to be tested

User may switch on/off any of the above stop conditions. “PaTeS evaluation frame” is configured with configuration dictionary which is passed as an argument to the main function of the frame. here . It is recommended to use “PaTeS” GUI to generate a script which configures and runs the “PaTeS” frame.


Examples

Example #1 – generate ARS sampling patterns
This example shows how to generate additive random sampling (ARS) patterns using the ARS generator from “PaTeS” toolbox. You can find the file here .

Firstly, cPickle module is imported, it will be used to store the patterns into a file. The “PaTeS” toolbox is imported; ANGIE generator (c language implementation) is explicitely imported from generators submodule:

44: import cPickle
45: import pates
46: from pates.generators.ars import _ars

Lines 53-65 configure a dictionary with settings for patterns generator. Time frequency parameters: sampling pattern duration, sampling grid period and the average frequency are configured in the line 57-61. Line 63 sets the variance paramter. Line 65 configures the number of patterns which will be generated:

53: # Dictionary with patterns parameters
54:
55: dPattsPar = {}    # Invoke dictionary
56:
57: dPattsPar['tS'] = 1e-3        # Duration of asampling pattern [1ms]
58:
59: dPattsPar['Tg'] = 1e-6        # Sampling grid period [1 us]
60:
61: dPattsPar['fR'] = 100e3       # Average sampling ratio [100 kHz]
62:
63: dPattsPar['iVar'] = 1         # The variance parameter
64:
65: dPattsPar['nPatts'] = 1e3     # The number of patterns to be generated
66:

Now the generator is run. The dictionary with settings is the first argument or the generator function. The second argument should be an empty dictionary – it is used when the generator is run by the “PaTeS Evaluation Frame”. The ARS generator returns a dictionary with generated patterns and their parameters:

67: # Run the ARS generator
68: dPatt = _ars.generate_patterns(dPattsPar, {})

Finally, the dictionary with patterns is stored in a file:

74: # -------------------------------------------------------------------
75: # Store ARS patterns in a file
76: res_file = open('ARS_patterns.dat', 'wb')
77: cPickle.dump(dPatt, res_file)
78: res_file.close()


Example #2 – generate ANGIE sampling patterns
This example shows how to generate rANdom sampling Generator with Intervals Enabled (ANGIE) patterns using the c implementation of ANGIE generator from “PaTeS” toolbox. You can find the file here . This example is very similar to the previous example (examp_genARS.py) which generates ARS sampling patterns.

The import lines are very similar to the previous example. The only difference is that the ANGIE generator (c language implementation) is explicitly imported from generators submodule instead of the ARS generator.

46: import cPickle
47: import pates
48: from pates.generators.angie import _angie_c

Lines 53-65 configure a dictionary with settings for patterns generator. There is one important difference with the previous example – minimum time between samples is set in the configuration dictionary (line 65).

55: # Dictionary with patterns parameters
56:
57: dPattsPar = {}    # Invoke dictionary
58:
59: dPattsPar['tS'] = 1e-3        # Duration of a sampling pattern [1ms]
60:
61: dPattsPar['Tg'] = 1e-6        # Sampling grid period [1 us]
62:
63: dPattsPar['fR'] = 100e3       # Average sampling ratio [100 kHz]
64:
65: dPattsPar['tMin'] = 5e-6      # The minimum time between samples
66:
67: dPattsPar['iVar'] = 1         # The variance parameter
68:
69: dPattsPar['nPatts'] = 1e3     # The number of patterns to be generated
70:

Just like in the previous example, the generator is run when the configuration dictionary is ready. The dictionary with settings is the first argument of the generator function. The second argument should be an empty dictionary. The generator returns a dictionary with generated patterns and their parameters.

71: # Run the ANGIE generator
72: dPatt = _angie_c.generate_patterns(dPattsPar, {})

Finally, the dictionary with ANGIE patterns is stored in a file.

74: # -------------------------------------------------------------------
75: # Store ANGIE patterns in a file
76: res_file = open('ANGIE_patterns.dat', 'wb')
77: cPickle.dump(dPatt, res_file)
78: res_file.close()


PaTeS GUI

“PaTeS Evaluation Frame” can be configured step by step and run using python scripts. An example of such a script you can find here . It is an example which reproduces the main experiment from the paper “Generation and Analysis of Random Sampling Patterns”.

It is also possible to configure “PaTeS” software in a bit more “what-you-see-is-what-you-get” way. “PaTeS” GUI is a tool dedicated to configure and run the “PaTeS Evaluation Frame” without writing a python script. To start the “PaTeS” GUI go to gui/ directory of the toolbox. When in gui/ directory start the toolbox by running:

$ python pates-gui.py

You will see a window like this:


Figure 3: “PaTeS” GUI

Using the GUI it is possible to set up visually all the parameters of “PaTeS Evaluation Frame”. Name of the project is set up in a field (1). The evaluation frame can store all the generated patterns on a hard drive. If patterns should be stored tick “Patterns storing” checkbox (2). Technical stop conditions are configured in fields (3).

Parameters of the patterns generator are set in fields within a frame (4). It is possible to automatically sweep the random process variance parameter for
all the generator types (7). Type of the generator is set in a field (8). It is possible to compare the configured generator with 2 other generators with different settings. To switch on the generator #2 and the generator #3 please check checkboxes (5) and (6) respectively.

Elements of the gui in the two bottom rows are used to set up the evaluation functions. Here you can switch on/off the functions and set up their parameters. For example, frequency stability evaluation function is switched on/off using a checkbox (9). Its convergence parameters are set using fields (10).

When all the needed parameters are set, press “Generate PaTeS scripts” button to generate output scripts. Two scripts are always generated: project_name_run.py and project_name_view.py.

To run the “PaTeS Evaluation Frame” simply run the first script:

$ python project_name_gui.py

This script will store the result in project_name.dat file. To view the results run:

$ python project_name_view.py

This will plot the results of evaluation.


Page last updated: 9th September 2014 (by Jacek)