spectrum - SpecTcl Command

SpecTcl Home General Information User Guide Programmer's Guide Obtaining and Installing

Syntax

spectrum [-new] name type parameter-list axis-speclist [datatype]
spectrum -list [-byid] [-showgate] [pattern]
spectrum -list [-showgate] name
spectrum -list -id [-showgate] id
spectrum -delete name [name...]
spectrum -delete id [id...]
spectrum -delete -all
spectrum -trace {add | delete} script

Synopsis

Creates, lists properties of and deletes spectra.

-new will return empty string or reason that the histogram could not be created.
-list will return the set of histograms listed (or the error reason if histograms could not be listed). This is a list containing a sublist for each spectrum. Each spectrum sublist contains in order the Id, the name, dimensionality, list of parameters, and list of resolutions.
-delete will return either a null string or the list of spectra which could not be deleted. For each spectrum a list containing the spectrum name or id and the reason it could not be deleted.
-trace allows you to set list or delete a script that is executed when spectra are added or deleted from SpecTcl.

Top

Detailed Description

SpecTcl maintains a dictionary of spectra. The size of the parameter dictionary and the total amount of spectrum storage is limited only by the program's virtual memory. Each spectra has the following properties:

name A spectrum name which can be used to refer to the spectrum in other operations.
id A positive integer identifier which is sequentially assigned to spectra as they are created. The id can also be used for identification purposes in most cases, however this is less meaningful than the name.
type - The type of spectrum to be created. SpecTcl supports the following spectrum types:

1	1d spectrum of a single parameter is created.
2	2d spectrum of two parameters is created.
g1	1d spectrum of a list of parameters is created.
g2	2d spectrum of a list of at least two parameters is created.
s	Summary 2d spectrum is created of an arbitrary number of parameters.
b	Bitmask spectrum of a single parameter is created
S	A Strip Chart Spectrum is created
m2	Multiply incremented 2-d spectrum.
gd	A gamma "Deluxe" spectrum is created. This is a 2-d gamma spectrum with independent parameters on the x and y axes.

parameter-list The set of parameters which are required to increment the spectra. How this is interpreted depends on the spectrum type. The list has the following composition, depending on the type parameter:

Spectrum Type	Parameter list contents
1	The name of the single parameter to be histogrammed.
2	The names of the two parameters to be histogrammed. The first parameter is on the X axis, the second on the Y.
g1	The names of the parameters to be histogrammed.
g2	The names of the parameters to be histogrammed. The first parameter is on the X axis, the second on the Y.
s	The set of parameters on the X axis of the spectrum. See here for more information.
b	The parameter whose bits will be decoded and histogrammed.
S	The names of the parameters to be used as the time and value for the StripChart.
m2	A list of an even number of parameters. The even numbered parameters (numbered from 0), are x parameters, the odd ones y parameters. for each pair of parameters (e.t. 0, and 1) in the list, the spectrum will be incremented at the channel coordinates defined by that pair. This is different from a g2 spectrum in that the parameter pairs are only adjacent pairs in the paramter list, rather than all permutations of ordered pairs.
gd	A list of two parameter lists. The first list of parameters is the set of x parameter, while the second list of parameters is the set of y parameters.

resolution-list The set of axis resolutions. The number of axis resolutions in the list must be as described below:

Spectrum Type	Resolution List Contents.
1	The single resolution of the X axis.
2	The X and Y axis resolutions in that order.
g1	The single resolution of the X axis.
g2	The X and Y axis resolutions in that order.
s	The Y axis resolution. The X axis resolution is determined by the number of parameters. See here for more information about summary spectra.
b	The resolution of the x axis which determines the number of bits which are histogrammed from the parameter. e.g. if b = 3 then an 8 channel spectrum of the bottom 8 bits is created. Values larger than 32 are allowed, but not very sensible at this time.
S	The single resolution of the X axis.
m2	The X/Y axis definitions. All parameters will be mapped to the axis range/bins defined by their axis.
gd	The X/Y axis definitions. All parameters will be mapped to the axis range/bins defined by their axis.

axis-speclist is a list of axis specifications for each axis in the histogram. Axis specifications can either an axis resolution or an axis specification. An axis resolution is the number of bits of resolution n in the axis. For an axis resolution, the number or channels in the axis is 2**n, and the channels are in the range [0, 2**n). An axis specification, is a three element list {low high n}. The axis will contain n channels that run in the range [low, high].
datatype represents the type of data for each channel of the histogram:

byte	Each channel is 8 bits.
word	Each channel is 16 bits.
long	Each channel is 32 bits.

Various forms of the spectrum command manipulate, or query this parameter dictionary.

Top

spectrum [-new] name ndim parameter-list axis-speclist

Creates a new spectrum. Note that the -new switch is optional. The spectrum attributes are assigned as follows:

name taken from the name comand line parameter.
datatype the type of spectrum being created.
parameter-list taken from the single parameter-list parameter. This must be a properly formatted TCL/Tk list. Thus to specify two parameters, par1 and par2 for a 2-d spectrum, use the syntax: {par1 par2}. For 1-d spectra, the brackes are not needed.
axis-speclist is a list of axis specifications. Each axis specification is either an axis resolution or an axis specification. An axis resolution is the number of bits of resolution n in the axis. For an axis resolution, the number or channels in the axis is 2**n, and the channels are in the range [0, 2**n). An axis specification, is a three element list {low high n}. The axis will contain n channels that run in the range [low, high]. For example:

spectrum name1   1  res     12                 ;# 4096 channels 0-4095

spectrum name2   1  spec    {{-10.0 10.0 200}} ;# 200 channels in the range [-10, 10).

spectrum name3   2 {res spec} {12 {-10.0 10.0 200}} ;# X is res y is spec/

spectrum name4   S {time value} 10 ;# 10 bit x-Axis/

datatype - The type of data stored in the histogram. Note that each spectrum has restrictions on types which are allowed:

1	Can be word or long
2	Can be byte, word, or long
g1	Can be word or long
g2	Can be byte, word or long
s	Can be byte, word or long
b	Can be word or long
m2	Can be byte word or long.
gd	Can be byte word or long.

If creation is successful, the name of the spectrum is returned, otherwise an error message is returned.

Summary Spectra

Summary spectra are intended to be used to aid troubleshooting of large detector systems. Summary spectra are 2-d spectra which provide a single display of many parameters. A summary spectrum histograms parameter values on the y axis for several parameters on the X axis. For example, an Si strip detector could be histogrammed to get an Energy vs. position plot. For example, in the spectrum created by the command:

spectrum Summary s {Si1 Si2 Si3 Si4} 8

creates a 4 x 256 channel spectrum. Each Y strip is histogrammed as follows: strip 0 is a histogram of Si1, Strip 1 is a histogram of Si2, strip 2 is a histogram of Si3.. .and so forth.

Top

spectrum -list [-byid] [-showgate] [ [pattern]

Lists all spectra in the spectrum dictionary. If the optional -byid switch is included, then the spectra are sorted by id, otherwise they are sorted alphabetically by name. If the pattern optional is included then only spectra whose name equals the pattern will be displayed, * can be used a wildcard Spectra are listed in a format which allows them to be easily manipulated by other Tcl commands. The output is a list, where each spectrum is represented by a sublist containing in order: The Spectrum id, spectrum name, dimensionality, parameter list (a properly formatted sub-sublist) axis-definition list (a properly formatted sublist). In order to make processing these definitions easy, all axis definitions are rendered in specification form {low high nchans} regardless of how they were originally specified when the spectrum was created for example:

{24 d1_0 1 {Distribution1} {{0.000000 1023.000000 1024}} long}

{19 d1bl b {Distribution1} {{0.000000 15.000000 16}} long}

{20 d1bw b {Distribution1} {{0.000000 31.000000 32}} word}

{17 d1m 1 {Distribution1} {{100.000000 200.000000 50}} long}

{22 d1sumb s {Distribution1 Distribution1 Distribution1 Distribution2

Distribution1 Distribution1 Distribution1 Distribution1} {{0.000000 1023.000000 1024}} byte}

8 d1-vs-sum 2 {Distribution1 dist1+dist2} {

{0.000000 1023.000000 256} {0.000000 2047.000000 256}} word}

Top

If the optional -showgate switch is supplied, the gate name of the gate currently applied to the spectrum is appended to the end of the list describing each spectrum.

spectrum -list [-showgate] name

Lists the spectrum with the supplied name, or an error message if name could not be listed.

If the optional -showgate switch is supplied, the gate name of the gate currently applied to the spectrum is appended to the end of the list describing each spectrum.

spectrum -list -id [-showgate] id

Lists the spectrum with the supplied id, or an error message if id could not be listed.

If the optional -showgate switch is supplied, the gate name of the gate currently applied to the spectrum is appended to the end of the list describing each spectrum.

spectrum -delete name [name...]

Deletes the spectra listed by name. If some spectra cannot be deleted, then a list is returned containing the set of spectra which could not be deleted and why e.g.

{d7 {No such Spectrum}} {d9 {No such Spectrum}}

Top

spectrum -delete -id id [id...]

Deletes the spectra listed by id.

spectrum -trace {add | delete} [script]

Allows you to add delete or list a script that will be executed when spectra are added or deleted from SpecTcl. If the keyword after the -trace switch is add, the trace affected will be a trace invoked when spectra are created. If the keyword after the -trace switch is delete, the trace affected will be a trace invoked when spectra are deleted.

If script is supplied, it becomes the new trace script for that operation. The previous script is returned as the result of the command. If the script is not supplied, the current trace script is returned.

When a spectrum is added, the add trace is called with the name of the spectrum appended to it. No spectrum traces (add or delete) will fire while the script is executing. At the timethe script is invoked, the spectrum has already been added tothe spectrum dictionary. The following sample script will output the description of the new spectrum to stdout:

proc addtrace name { puts [spectrum -list $name] } spectrum -trace add addtrace; # Establish the trace.

When a spectrum is deleted, the delete trace is called with the name of the spectrum appended to it. When the script is called, the spectrum has not yet been deleted from SpecTcl.

Examples:

spectrum d3-vs-d5 2 {Distribution2 Distribution5} {8 8}   ;# Make a new 2-d spectrum.

spectrum -list -byid                                      ;# List spectra sorted by id.

spectrum mapped 2 {Distribution1 Distribution2} {{10 99 90} {50 99 100}}   ;# Make a 2d spectrum with 90*100 bins.

#  The following multiline example just lists only the names of spectra:

% set result ""

% foreach Spectrum [spectrum -list] {

   append result [lindex $Spectrum 1] "/n"

}                                            ;# result contains the list.

set $result                                 ;# Show the list

d1

d1-vs-sum

d2

d3

d3-vs-sum

d4

d5

sum

#  The following multiline example creates a list widget containing the set of defined

#  spectra packs it onto the default top level window and updates it every second.

listbox .spectra                           ;# Create the list box.

proc specupdate {} {                       ;# Procedure to update the list box by

    .spectra delete 0 [.spectra size]      ;# Deleting all elements and

    foreach spec [spectrum -list] {        ;# Filling the box with the set of defined

      .spectra insert end [lindex $spec 1] ;# spectra.

    after 1000 specupdate                  ;# Reschedules itself.

specupdate                                 ;# This sets up the initial listbox contents.

pack .spectra                              ;# and adds the listbox to the top-level win.

Top

SpecTcl Home General Information User Guide Programmer's Guide Obtaining and Installing