nscl_logo_small.gif (2463 bytes)

spectrum - SpecTcl Command

HH00706_.wmf (6530 bytes)

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.

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:

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.

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.

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.

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:

 

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/

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


Last Modified: October 28, 2003by: fox@nscl.msu.edu
Copyright NSCL 1999, All rights reserved