Jump to topic:
Initialization and Cleanup
Operations with One-Dimensional Histograms
Fourier Transform
Operations with Two-Dimensional Histograms
Operations with Three-Dimensional Histograms
Histogram Slices and Projections
Histogram Math and Statistics
Miscellaneous Histogram Operations
Operations with Ntuples
Kernel Density Estimation
Operations with Fit Functions
Data Fitting
Displaying Plots
Drawing Labels, Formulas, and Primitives
Making and Importing PostScript Files
Color Management
Looking up Items
Finding Item Properties
Changing Item Properties
Item Copying, Deleting, and Resetting
Triggers, Indicators, and Controls
Data Input and Output
Random Numbers
Getting Help
Miscellaneous Commands
hs::calc Details
Fitting Details
Jump to letter: 1 2 3 a b c d e f g h i j k l m n o p r s t u v w
Initialization and Cleanup
Operations with One-Dimensional Histograms
Fourier Transform
| hs::1d_fft | hs::1d_fourier_conjugate | hs::1d_fourier_divide |
| hs::1d_fourier_multiply | hs::1d_fourier_phase | hs::1d_fourier_power |
| hs::1d_fourier_synthesize |
Operations with Two-Dimensional Histograms
Operations with Three-Dimensional Histograms
Histogram Slices and Projections
| hs::fill_hist_slice | hs::fill_slice | hs::hist_set_slice |
| hs::hist_set_slice_errors | hs::slice_contents | hs::slice_histogram |
| hs::slice_slider | hs::project_2d_histogram | hs::project_3d_histogram |
Histogram Math and Statistics
Miscellaneous Histogram Operations
Operations with Ntuples
Kernel Density Estimation
| hs::kernel_density_1d | hs::kernel_density_2d |
Operations with Fit Functions
Data Fitting
| hs::1d_linear_fit | hs::2d_linear_fit | hs::fit |
| hs::ntuple_poly_fit |
Displaying Plots
| hs::show_histogram | hs::overlay | hs::multiplot |
| hs::expr_plot | hs::list_plot | hs::parametric_plot |
| hs::browse_collection | hs::close_all_windows | hs::close_window |
Drawing Labels, Formulas, and Primitives
| hs::draw | hs::redraw | hs::comment |
| hs::default_latex_packages | hs::latex | hs::undo |
| hs::clear |
Making and Importing PostScript Files
| hs::generate_ps | hs::epsf |
Color Management
| hs::create_general_color_scale | hs::create_linear_color_scale | hs::delete_color_scale |
| hs::replace_color_scale | hs::use_color_scale |
Looking up Items
| hs::num_items | hs::id | hs::id_from_title |
| hs::list_items | hs::lookup_title |
Finding Item Properties
| hs::type | hs::uid | hs::category |
| hs::title | hs::item_info | hs::num_entries |
| hs::item_properties |
Changing Item Properties
| hs::change_category | hs::change_title | hs::change_uid |
| hs::change_uid_and_category |
Item Copying, Deleting, and Resetting
| hs::copy_hist | hs::duplicate_axes | hs::duplicate_ntuple_header |
| hs::copy_data | hs::delete | hs::delete_category |
| hs::delete_items | hs::reset | hs::reset_const |
Triggers, Indicators, and Controls
| hs::create_trigger | hs::check_trigger | hs::create_indicator |
| hs::set_indicator | hs::create_control | hs::read_control |
Data Input and Output
Random Numbers
| hs::gauss_random | hs::hist_random | hs::multinomial_random |
| hs::pick_random_rows | hs::poisson_random | hs::random |
| hs::random_get_state | hs::random_init | hs::random_set_state |
| hs::uniform_random_fill |
Getting Help
| hs::help | hs::fit_manual | hs::html_manual |
Miscellaneous Commands
hs::1d_fft $id1 $id2 $is_direct accumulate?
Arguments : integers id1 and id2, booleans is_direct and accumulate
Returns : nothing
Performs a fast Fourier transform on the data stored in the histogram
with id $id1 (using subroutine RFFT, CERNLIB entry D703) and stores
the obtained coefficients in the histogram with id $id2. Both histograms
must have the same number of bins N which must be a power of 2.
The following Fourier representation is used:
1 N/2 N/2-1
f(k) = -*A_0 + Sum A_m*cos(2*Pi*m*k) + Sum B_m*sin(2*Pi*m*k)
2 m=1 m=1
The argument "is_direct" specifies the direction of the transform:
1 means compute direct transform ($id1 contains f(k), calculate A_m
and B_m), 0 means inverse. The coefficients are stored in the following
order: bin 0 is used to store A_0, bin 1 is used for A_1, bin 2 for B_1,
bin 3 for A_2, bin 4 for B_2, and so on. If set true, the optional
argument "accumulate" instructs the command to add the obtained
coefficients to the bin contents of the histogram with id $id2 rather
than replace them (which is the default behavior).
Note that the standard bin-by-bin multiplication or division of
histograms containing transform coefficients will not correspond to
convolution or deconvolution of the original histograms. To perform
these operations, use special commands hs::1d_fourier_multiply and
hs::1d_fourier_divide.
hs::1d_fourier_conjugate $id1 $id2
Arguments : integers id1 and id2
Returns : nothing
Assuming that the histogram with id $id1 contains a set of Fourier
coefficients, this command fills the histogram with Histo-Scope id
$id2 by their complex conjugates. Please see the description of the
hs::1d_fft command for details on how the Fourier coefficients are
stored. The provided histograms must have the same number of bins,
and this number must be even. $id1 and $id2 may be identical, in which
case the conjugate coefficients will be stored in place of the original
ones.
hs::1d_fourier_divide $uid $title $category $id1 $id2 ignorediv0?
Arguments : integers uid, id1 and id2, strings title and category,
boolean ignorediv0
Returns : integer
Creates a new 1d histogram whose data is the ratio of the Fourier
coefficients stored in the histograms specified by id1 and id2.
The operation is performed in such way that the resulting set of
coefficients corresponds to the Fourier transform of the deconvolution
of the original functions. Arguments uid, title, and category specify
user id, title, and category of the resulting histogram. Histograms
identified by id1 and id2 should contain the same number of bins.
Please see the description of the hs::1d_fft command for details on
how the Fourier coefficients are stored. If set true, the optional
argument ignorediv0 instructs the command not to raise an error in case
division by zero is encountered. Instead, the relevant parts of the
result will be silently set to zero. This command returns a Histo-Scope
id of the new histogram.
hs::1d_fourier_multiply $uid $title $category $id1 $id2
Arguments : integers uid, id1 and id2, strings title and category
Returns : integer
Creates a new 1d histogram whose data is the multiplication of the
Fourier coefficients stored in the histograms specified by id1 and id2.
The operation is performed in such way that the resulting set of
coefficients corresponds to the Fourier transform of the convolution
of the original functions. Arguments uid, title, and category specify
user id, title, and category of the resulting histogram. Histograms
identified by id1 and id2 should have the same number of bins. Please
see the description of the hs::1d_fft command for details on how
the Fourier coefficients are stored. This command returns a Histo-Scope
id of the new histogram.
hs::1d_fourier_phase $id1 $id2
Arguments : integers id1 and id2
Returns : nothing
Fills the histogram with id $id2 with the phase spectrum of a Fourier
transform assuming that the histogram with id $id1 contains a set of
Fourier coefficients obtained earlier using the hs::1d_fft command.
The number of bins in the histogram with id $id2 must be two times
smaller than the number of bins N in $id1. Bin 0 of the histogram with
id $id2 will contain the phase shift of the fundamental frequency term,
bin 1 the phase of the second harmonic, and so on. The very last bin is
an exception: the phase of the N/2th harmonic can not be unambiguously
defined since the N/2th sine term in the Fourier series does not exist
(N is presumed to be even, and then the sine value is 0 at all points).
Instead, this bit shows the "phase" between the N/2th cosine term and
the constant term.
hs::1d_fourier_power $id1 $id2
Arguments : integers id1 and id2
Returns : list of doubles
Fills the histogram with id $id2 with the power spectrum of a Fourier
transform assuming that the histogram with id $id1 contains a set of
Fourier coefficients obtained earlier using the hs::1d_fft command.
The number of bins in the histogram with id $id2 must be two times
smaller than the number of bins N in $id1. The calculated power spectrum
is normalized by the condition
N/2 N-1
Sum P_m = Sum f(k)^2
m=0 k=0
where f(k), 0 <= k < N, are the data being transformed.
The command returns a two-element list of doubles {P_0 P_nonzero} where
P_0 is the power associated with the constant term in the transform, and
P_nonzero is the combined power of all other terms. Histogram $id2 does
not include P_0; instead, bin 0 contains the power associated with
the fundamental frequency term, bin 1 corresponds to the second harmonic,
bin 2 to the third, and so on.
hs::1d_fourier_synthesize $id $P_0 $id_power $id_phase
Arguments : integers id, id_power, id_phase, double P_0
Returns : nothing
Synthesizes a set of Fourier transform coefficients using power and
phase spectra provided in histograms with ids $id_power and $id_phase.
Please see the descriptions of commands hs::1d_fourier_power and
hs::1d_fourier_phase for details about the contents of these spectra.
The P_0 argument specifies the power of the constant term. The obtained
coefficients are placed into the histogram with id $id. The number of
bins N in the histogram of coefficients should be twice larger than
the number of bins in either power or phase histograms. Although this
particular command can operate on histograms with any even N, only when
N is a power of 2 the resulting set of coefficients can be transformed
back into the time domain using the hs::1d_fft command.
hs::1d_hist_bin_contents $id
Arguments : integer id
Returns : binary string
Returns a binary string which contains bin data from a one-dimensional
histogram.
hs::1d_hist_bin_coords $id left_edge?
Arguments : integer id, boolean left_edge
Returns : binary string
Returns a binary string which contains coordinates of bins in
a one-dimensional histogram. If "left_edge" is true then the command
returns coordinates of the left bin edges. If "left_edge" is false
or omitted then the command returns positions of bin centers.
hs::1d_hist_bin_value $id $bin_num
Arguments : integers id and bin_num
Returns : double
Returns the value in the histogram bin referred to by bin (or channel)
number bin_num. The result is undefined if item with given id is not
a one-dimensional histogram or bin_num is less than 0 or greater or
equal to the number of histogram bins.
hs::1d_hist_block_fill $id $data $pos_errors $neg_errors
Arguments : integer id, binary strings or lists of doubles data,
pos_errors, and neg_errors
Returns : nothing
Replaces the accumulated bin and error data supplied for the
one-dimensional histogram identified by id and clears the overflow
bins. data, pos_errors, and neg_errors must be of the appropriate size
for the one-dimensional histogram being filled. Either neg_errors or
both error arguments can be omitted, in which case the corresponding
errors are not changed. If the histogram has positive errors but not
negative ones, Histo-Scope assumes errors are symmetric. Thus memory
can be saved by specifying only positive errors when errors are
symmetric. Both positive and negative errors should be specified as
positive numbers.
hs::1d_hist_cdfvalues $id $coords
Arguments : integer id, list of doubles coords
Returns : list of doubles
Calculates and returns a set of percentages (values of the normalized
cumulative distribution function multiplied by 100.0) for a 1d histogram
with Histo-Scope id $id. All histogram bins must be non-negative. The
length of the list of coordinates is arbitrary. The returned list of
percentages will have the same length. This function is the inverse
of hs::1d_hist_percentiles.
hs::1d_hist_derivative $uid $title $category $id
Arguments : integer uid, strings title and category, integer id
Returns : integer
Create a new histogram (one-dimensional) whose data is the derivative
of the histogram specified by id. This derivative is computed bin by
bin:
Dh/db = (H(j) - H(j-1))/bin_size.
If the input histogram, specified by id, has error bars, the errors are
computed assuming that there is no statistical correlation between bins
and the error values are Gaussian. uid is the User Identification for
the newly created histogram. title defines the title for the histogram.
category is a string defining a hierarchical "location" for the
histogram. Returns new_id which is the id of a new histogram containing
this derivative.
hs::1d_hist_errors $id $type
Arguments : integer id, string type
Returns : binary string
Returns a binary string which contains the data for either upper
or lower error bars for 1d histogram with given $id. The "type"
argument specifies which errors are returned: use "p" or "P" to get
positive errors and "n" or "N" to get negative errors. The returned
string may have 0 length which means that this type of errors is not
defined for the given histogram. The type argument may be omitted in
which case the positive errors are returned if they exist.
hs::1d_hist_labels $id
Arguments : integer id
Returns : list of strings {x_label y_label}
Returns 1d histogram labels as defined when hs::create_1d_hist was
called. This function will produce an error if the item identified
by id does not exist or the item is not a 1d histogram.
hs::1d_hist_maximum $id
Arguments : integer id
Returns : three-element list {x bin_num value}
Returns the coordinate (x), the bin number (bin_num) and the bin
content (value) where the histogram data reaches a maximum. The routine
returns bin number 0 if the histogram is empty (i.e. has not yet been
filled).
hs::1d_hist_minimum $id
Arguments : integer id
Returns : three-element list {x bin_num value}
Returns the coordinate (x), the bin number (bin_num) and the bin
content (value) where the histogram data reaches a minimum. The routine
returns bin number 0 if the histogram is empty (i.e. has not yet been
filled).
hs::1d_hist_num_bins $id
Arguments : integer id
Returns : integer
Returns the number of bins for a one-dimensional histogram identified
by id or throws tcl error if the id does not refer to a one-dimensional
histogram.
hs::1d_hist_overflows $id
Arguments : integer id
Returns : two-element list of doubles {underflow overflow}
Returns the overflow data from a one-dimensional histogram.
hs::1d_hist_percentiles $id $percentages
Arguments : integer id, list of doubles percentages
Returns : list of doubles
Calculates and returns a set of percentiles for a 1d histogram with
Histo-Scope id $id. All histogram bins must be non-negative. The
percentage values should be between 0.0 and 100.0, inclusive.
The length of the list of percentages is arbitrary. The returned
list of percentiles will have the same length. This function is
the inverse of hs::1d_hist_cdfvalues.
hs::1d_hist_range $id
Arguments : integer id
Returns : two-element list of doubles {min max}
Returns the list {min max}, where min is the minimum (low edge of
the first bin) value and max is the maximum (high edge of the last bin)
value representing the horizontal limits of a one-dimensional histogram.
Tcl error is thrown if id does not refer to a one-dimensional histogram.
hs::1d_hist_set_bin $id $ix $value
Arguments : integers id and ix, double value
Returns : nothing
Sets the value of the bin number $ix in the one-dimensional histogram
identified by id. Out-of-range bin numbers are ignored.
hs::1d_hist_set_bin_errors $id $ix $positive_error negative_error?
Arguments : integers id and ix, doubles positive_error and negative_error
Returns : nothing
Sets the errors for the bin number $ix in the one-dimensional histogram
identified by id. Out-of-range bin numbers are ignored. Negative error
may be omitted or specified as an empty string. Positive error may be
specified as an empty string in order to modify just the negative error.
hs::1d_hist_set_overflows $id underflow overflow
Arguments : integer id, doubles underflow and overflow
Returns : nothing
Sets the overflow data for a one-dimensional histogram.
hs::1d_hist_shape $id left_edge?
Arguments : integer id, boolean left_edge
Returns : list of doubles {area mean stdev skewness kurtosis}
Calculates and returns area, mean, standard deviation, skewness, and
kurtosis of a one-dimensional histogram with Histo-Scope id $id.
If the area is not positive then all other elements of the returned
list are set to 0. If optional boolean argument "left_edge" is 1 then
the command uses coordinates of the left bin edges in its calculations.
If "left_edge" is 0 or omitted then the command uses positions of bin
centers.
hs::1d_hist_stats $id
Arguments : integer id
Returns : two-element list of doubles {mean std_dev}
Calculates and returns the mean and standard deviation of
a one-dimensional histogram.
hs::1d_hist_subrange $uid $title $category $parent_id $bin_min $bin_max
Arguments : integers uid, parent_id, bin_min, and bin_max, strings
title and category
Returns : integer
Creates a new 1-d histogram with specified user id, title, and category.
See the description of hs::create_1d_hist for a detailed description
of uid, title, and category arguments. The contents of the new histogram
are created by extracting a subrange from a 1-d histogram with
Histo-Scope id $parent_id. The subrange to use is defined by the
minimum bin number, $bin_min, and the maximum bin number, $bin_max,
both included in the resulting histogram. The command returns a
Histo-Scope assigned id of the new histogram or throws a tcl error.
hs::1d_hist_x_value $id $x
Arguments : integer id, double x
Returns : double
Returns the value stored in the histogram bin referenced by x. The
result is undefined if item with given id is not a one-dimensional
histogram, or if x is not within the range of the histogram.
hs::1d_linear_fit $id $suppress_zero $use_errors
Arguments : integer id, booleans suppress_zero and use_errors
Returns : 7-element mixed list {a b sig_a sig_b rho_ab chisq ndof}
Fits 1d histogram with Histo-Scope id $id to a straight line y = a*x + b
using least-squares minimization. If $suppress_zero is 1 then only
non-zero entries from the histogram are used in the fit. The function
will use histogram errors to weight the fitted points if the optional
argument $use_errors is 1. In this case points with null errors will
be discarded. When $use_errors is 0 or omitted, all errors are assumed
to be equal. The fitted coefficients a and b are returned together
with their errors sig_a and sig_b and correlation coefficient rho_ab.
The chisq element of the return list is defined in the following way:
when $use_errors is 1, it is the actual chi-square of the fit. When
$use_errors is 0 or omitted, it is the sum of squared residuals. ndof
is the number of degrees of freedom (number of points actually used in
the fit minus two). ndof is the only integer element in the return list,
all other elements are doubles.
hs::1d_rotate_bins $id1 $id2 $shift
Arguments : integers id1, id2, and shift
Returns : nothing
Copies data and errors from 1d histogram with id $id1 to 1d histogram
with id $id2 and in the process rotates the bin values by $shift bins
in the direction of increasing X. The histograms must have the same
number of bins. $id1 may be equal to $id2, and the shift value may be
negative.
hs::1d_select_bins $id $num_or_coord $min $max $incl_or_excl
Arguments : integer id, string num_or_coord, double min, double max,
string incl_or_excl
Returns : list of integers or list of doubles
For a 1d histogram with Histo-Scope id $id, this command returns a list
of bins which satisfy a certain condition. If the $incl_or_excl string
is "include" then those bins are returned which content is between min
and max (min <= bin_value <= max). If the $incl_or_excl argument is
"exclude" then those bins are returned which are outside the [min, max]
interval (bin_value < min or bin_value > max). The output list is
returned as the list of bin numbers when $num_or_coord argument is
"bin" or as the list of bin coordinates when $num_or_coord is "coord".
Bin coordinates are returned for the left bin edge.
hs::2d_fill_from_matrix $id $data $pos_errors $neg_errors
Arguments : integer id, lists of lists of doubles data, pos_errors,
and neg_errors
Returns : nothing
Same as hs::2d_hist_block_fill except that data, pos_errors, and
neg_errors arguments are nested lists of doubles instead of binary
strings or flat lists. Number of sublists in each list (number of matrix
rows) should be equal to the number of bins in the histogram y axis, and
the number of elements in each sublist (number of columns) should be
equal to the number of bins in the histogram x axis. After this operation
the command
hs::2d_hist_bin_value $id $x_bin_num $y_bin_num
will return the same result as
lindex [lindex $data $y_bin_num] $x_bin_num
where $x_bin_num and $y_bin_num are any valid x and y bin numbers.
hs::2d_hist_apply_weights $id $idw $axis
Arguments : integers id and idw, string axis
Returns : nothing
This command reweighs rows or columns of a 2d histogram with Histo-Scope
id $id. $idw is the id of a 1d histogram which contents are used as
weights. The weights are applied along x or y axis, according to the
$axis argument. Valid values of the $axis argument are X, x, Y, or y.
The histograms must be bin compatible. For example, if $axis is y then
the number of bins in the 1d histogram with id $idw must be equal to
the number of bins along the y axis in the 2d histogram with id $id.
hs::2d_hist_bin_contents $id
Arguments : integer id
Returns : binary string
Returns a binary string which contains bin data from a two-dimensional
histogram.
hs::2d_hist_bin_coords $id $axis $origin
Arguments : integer id, string axis, boolean origin
Returns : binary string
Returns a binary string which contains x or y coordinates of bins
in a two-dimensional histogram. Valid values of the $axis argument
are X, x, Y, or y. The coordinates are returned for each bin,
and the sequence of bins is the same as in the data returned by
hs::2d_hist_bin_contents command. If $origin is true then the command
returns coordinates of the bottom left bin edges. If $origin is false
or omitted then the command returns positions of bin centers.
hs::2d_hist_bin_value $id $x_bin_num $y_bin_num
Arguments : integers id, x_bin_num, and y_bin_num
Returns : double
Returns the value in the histogram bin referred to by bin (or channel)
numbers x_bin_num, y_bin_num. The result is undefined if item with
given id is not a two-dimensional histogram or if any bin number is
less than 0 or greater or equal to the number of histogram bins along
the corresponding axis.
hs::2d_hist_block_fill $id $data $pos_errors $neg_errors
Arguments : integer id, binary strings or lists of double data,
pos_errors, and neg_errors
Returns : nothing
Replaces the accumulated bin and error data supplied for the
two-dimensional histogram identified by id and clears the overflow
bins. data, pos_errors, and neg_errors must be of the appropriate size
for the two-dimensional histogram being filled. Either neg_errors or both
error arguments can be omitted, in which case the corresponding errors
are not changed. If the histogram has positive errors, but not negative
ones, Histo-Scope assumes errors are symmetric. Thus memory can be
saved by specifying only positive errors when errors are symmetric.
Both positive and negative errors should be specified as positive
numbers. The correspondence between the data and the histogram bins
is such that Y histogram bins change faster than X bins
(column-by-column ordering).
hs::2d_hist_cdfvalues $category $id $axis $coords
Arguments : string category, integer id, string axis,
list of doubles coords
Returns : list of integers
Calculates a set of percentages (values of the normalized cumulative
distribution function multiplied by 100.0) for a 2d histogram with
Histo-Scope id $id. All histogram bins must be non-negative. The cdf
is calculated separately for each row or column by integrating histogram
bin values along the axis specified by $axis. Allowed values for $axis
are "x", "X", "y", or "Y". The calculated percentages are returned in
a set of 1d histograms. These histograms are placed in a category
specified by the $category argument. The length of the list of
coordinates is arbitrary. The returned list of 1d histogram ids will
have the same length.
hs::2d_hist_errors $id $type
Arguments : integer id, string type
Returns : binary string
Returns a binary string which contains the data for either upper
or lower error bars for 2d histogram with given $id. The "type"
argument specifies which errors are returned: use "p" or "P" to get
positive errors and "n" or "N" to get negative errors. The returned
string may have 0 length which means that this type of errors is not
defined for the given histogram. The type argument may be omitted in
which case the positive errors are returned if they exist.
hs::2d_hist_labels $id
Arguments : integer id
Returns : list of strings {x_label y_label z_label}
Returns 2d histogram labels as defined when hs::create_2d_hist was
called. This function will produce an error if the item identified
by id does not exist or the item is not a 2d histogram.
hs::2d_hist_maximum $id
Arguments : integer id
Returns : five-element list {x y x_bin_num y_bin_num value}
Returns coordinates (x and y), bin numbers (x_bin_num and y_bin_num),
and the bin content (value) where the two-dimensional histogram data
reaches a maximum. The routine returns bin number 0 if the histogram
is empty (i.e. has not yet been filled).
hs::2d_hist_minimum $id
Arguments : integer id
Returns : five-element list {x y x_bin_num y_bin_num value}
Returns coordinates (x and y), bin numbers (x_bin_num and y_bin_num),
and the bin content (value) where the two-dimensional histogram data
reaches a minimum. The routine returns bin number 0 if the histogram
is empty (i.e. has not yet been filled).
hs::2d_hist_num_bins $id
Arguments : integer id
Returns : two-element list of integers {n_x_bins n_y_bins}
Returns the list of numbers of bins in the two-dimensional histogram
specified by id or throws tcl error if the id does not refer to
a two-dimensional histogram. n_x_bins is the number of bins in X.
n_y_bins is the number of bins in Y.
Commands like this are best handled by tcl's "foreach" statement, e.g.,
foreach {n_x_bins n_y_bins} [hs::2d_hist_num_bins $id] {}
hs::2d_hist_overflows $id
Arguments : integer id
Returns : nine-element list of doubles
Returns (i.e. copies) the overflow data from a two-dimensional
histogram into a list. The elements of the list are returned in
the following order:
Y ^ | |
| 0 | 3 | 6
ymax| ---|-----|---
| 1 |*****| 7
ymin| ---|-----|---
| 2 | 5 | 8
| | |
|------------------->
xmin xmax X
The contents of element 4 are undefined.
hs::2d_hist_percentiles $category $id $axis $percentages
Arguments : string category, integer id, string axis,
list of doubles percentages
Returns : list of integers
Calculates a set of percentiles for a 2d histogram with Histo-Scope
id $id. All histogram bins must be non-negative. The percentiles are
calculated along the histogram axis specified by $axis. Allowed values
for $axis are "x", "X", "y", or "Y". The calculated percentiles are
returned in a set of 1d histograms. These histograms are placed in
a category specified by the $category argument. The percentage values
should be between 0.0 and 100.0, inclusive. The length of the list
of percentages is arbitrary. The returned list of 1d histogram ids
will have the same length.
hs::2d_hist_range $id
Arguments : integer id
Returns : four-element list of doubles {x_min x_max y_min y_max}
Returns the list of minimum and maximum values representing
the horizontal limits of a two-dimensional histogram specified by id:
{x_min x_max y_min y_max}. Tcl error is thrown if id does not refer
to a two-dimensional histogram.
hs::2d_hist_set_bin $id $ix $iy $value
Arguments : integers id, ix, and iy, double value
Returns : nothing
Sets the value of the bin which has number $ix along the X axis and
$iy along the Y axis in the two-dimensional histogram identified by id.
Out-of-range bin numbers are ignored.
hs::2d_hist_set_bin_errors $id $ix $iy $positive_error negative_error?
Arguments : integers id, ix, and iy, doubles positive_error and
negative_error
Returns : nothing
Sets the errors for the bin which has number $ix along the X axis and
$iy along the Y axis in the two-dimensional histogram identified by id.
Out-of-range bin numbers are ignored. Negative error may be omitted or
specified as an empty string. Positive error may be specified as an empty
string in order to modify just the negative error.
hs::2d_hist_set_overflows $id $overflow_list
Arguments : integer id, nine-element list of doubles
Returns : nothing
Sets the overflow data for a two-dimensional histogram. The elements
of the list follow the same order as in the hs::2d_hist_overflows
command.
hs::2d_hist_stats $id
Arguments : integer id
Returns : four-element list of doubles
{x_mean y_mean x_std_dev y_std_dev}
Calculates and returns the means and standard deviations of
a two-dimensional histogram along both histogram axes.
hs::2d_hist_subrange $uid $title $category $parent_id $axis $bin_min $bin_max
Arguments : integers uid, parent_id, bin_min, and bin_max, strings
title, category, and axis
Returns : integer
Creates a new 2-d histogram with specified user id, title, and category.
See the description of hs::create_2d_hist for a detailed description
of uid, title, and category arguments. The contents of the new histogram
are created by extracting a subrange from a 2-d histogram with
Histo-Scope id $parent_id. The subrange to use is defined by the
minimum $axis axis bin number, $bin_min, and the maximum $axis axis
bin number, $bin_max, both included in the resulting histogram. Allowed
values of the $axis argument are "X", "x", "Y", or "y". The command
returns a Histo-Scope assigned id of the new histogram or throws
a tcl error.
hs::2d_hist_xy_value $id $x $y
Arguments : integer id, doubles x and y
Returns : double
Returns the value stored in the histogram bin referenced by x and y.
The result is undefined if item with given id is not a two-dimensional
histogram, or if x or y are not within the range of the histogram.
hs::2d_linear_fit $id $suppress_zero $use_errors
Arguments : integer id, booleans suppress_zero and use_errors
Returns : 11-element mixed list {a b c sig_a sig_b sig_c
rho_ab rho_ac rho_bc chisq ndof}
Fits 2d histogram with Histo-Scope id $id to a plane z = a*x + b*y + c
using least-squares minimization. If $suppress_zero is 1 then only
non-zero entries from the histogram are used in the fit. The function
will use histogram errors to weight the fitted points if the optional
argument $use_errors is 1. In this case points with null errors will
be discarded. When $use_errors is 0 or omitted, all errors are assumed
to be equal. The fitted coefficients a, b, and c are returned together
with their errors sig_a, sig_b, and sig_c and correlation coefficients
rho_ab, rho_ac, and rho_bc. The chisq element of the return list is
defined in the following way: when $use_errors is 1, it is the actual
chi-square of the fit. When $use_errors is 0 or omitted, it is the sum
of squared residuals. ndof is the number of degrees of freedom (number
of points actually used in the fit minus three). ndof is the only
integer element in the return list, all other elements are doubles.
hs::2d_rotate_bins $id1 $id2 $shift $axis
Arguments : integers id1, id2, and shift, string axis
Returns : nothing
Copies data and errors from 2d histogram with id $id1 to 2d histogram
with id $id2 and in the process rotates the bin values by $shift bins
in the direction of increasing $axis axis. $axis must be one of "x", "X",
"y", or "Y". The histograms must have the same number of bins along both
axes. $id1 may be equal to $id2, and the shift value may be negative.
hs::2d_select_bins $id $num_or_coord $min $max $incl_or_excl
Arguments : integer id, string num_or_coord, double min, double max,
string incl_or_excl
Returns : list of lists of integers or list of lists of doubles
For a 2d histogram with Histo-Scope id $id, this command returns a list
of bins which satisfy a certain condition. If the $incl_or_excl string
is "include" then those bins are returned which content is between min
and max (min <= bin_value <= max). If the $incl_or_excl argument is
"exclude" then those bins are returned which are outside the [min, max]
interval (bin_value < min or bin_value > max). Each bin is represented
either with a pair of bin numbers {nx ny} when $num_or_coord argument
is "bin" or with a pair of bin coordinates {x y} when $num_or_coord
argument is "coord". Bin coordinates are returned for the bottom left
corner.
hs::3d_hist_bin_contents $id
Arguments : integer id
Returns : binary string
Returns a binary string which contains bin data from a three-dimensional
histogram.
hs::3d_hist_bin_coords $id $axis $origin
Arguments : integer id, string axis, boolean origin
Returns : binary string
Returns a binary string which contains x, y, or z coordinates of bins
in a three-dimensional histogram. Valid values of the $axis argument
are X, x, Y, y, Z, or z. The coordinates are returned for each bin,
and the sequence of bins is the same as in the data returned by
hs::3d_hist_bin_contents command. If $origin is true then the command
returns coordinates of the bin edges closest to the 0th bin. If $origin
is false or omitted then the command returns positions of bin centers.
hs::3d_hist_bin_value $id $x_bin_num $y_bin_num $z_bin_num
Arguments : integers id, x_bin_num, y_bin_num, and z_bin_num
Returns : double
Returns the value in the histogram bin referred to by bin (or channel)
numbers x_bin_num, y_bin_num, z_bin_num. The result is undefined if item
with given id is not a three-dimensional histogram or if any bin number
is less than 0 or greater or equal to the number of histogram bins along
the corresponding axis.
hs::3d_hist_block_fill $id $data $pos_errors $neg_errors
Arguments : integer id, binary strings or lists of doubles data,
pos_errors, and neg_errors
Returns : nothing
Replaces the accumulated bin and error data supplied for the
three-dimensional histogram identified by id and clears the overflow
bins. data, pos_errors, and neg_errors must be of the appropriate size
for the three-dimensional histogram being filled. Either neg_errors or
both error arguments can be omitted, in which case the corresponding
errors are not changed. If the histogram has positive errors, but not
negative ones, Histo-Scope assumes errors are symmetric. Thus memory can
be saved by specifying only positive errors when errors are symmetric.
Both positive and negative errors should be specified as positive
numbers. The correspondence between the data and the histogram bins
is such that Y histogram bins change faster than X bins, and Z bins
change faster than Y bins.
hs::3d_hist_errors $id $type
Arguments : integer id, string type
Returns : binary string
Returns a binary string which contains the data for either upper
or lower error bars for 3d histogram with given $id. The "type"
argument specifies which errors are returned: use "p" or "P" to get
positive errors and "n" or "N" to get negative errors. The returned
string may have 0 length which means that this type of errors is not
defined for the given histogram. The type argument may be omitted in
which case the positive errors are returned if they exist.
hs::3d_hist_labels $id
Arguments : integer id
Returns : list of strings {x_label y_label z_label q_label}
Returns 3d histogram labels as defined when hs::create_3d_hist was
called. This function will produce an error if the item identified
by id does not exist or the item is not a 3d histogram.
hs::3d_hist_maximum $id
Arguments : integer id
Returns : seven-element list {x y z x_bin_num y_bin_num z_bin_num value}
Returns coordinates (x, y, and z), bin numbers (x_bin_num, y_bin_num,
and z_bin_num), and the bin content (value) where the three-dimensional
histogram data reaches a maximum. The routine returns bin number 0 if
the histogram does not refer to a two-dimensional histogram, or the
histogram is empty (i.e. has not yet been filled).
hs::3d_hist_minimum $id
Arguments : integer id
Returns : seven-element list {x y z x_bin_num y_bin_num z_bin_num value}
Returns coordinates (x, y, and z), bin numbers (x_bin_num, y_bin_num,
and z_bin_num), and the bin content (value) where the three-dimensional
histogram data reaches a minimum. The routine returns bin number 0 if
the histogram does not refer to a two-dimensional histogram, or the
histogram is empty (i.e. has not yet been filled).
hs::3d_hist_num_bins $id
Arguments : integer id
Returns : three-element list of integers {n_x_bins n_y_bins n_z_bins}
Returns the list of numbers of bins in the three-dimensional histogram
specified by id or throws tcl error if the id does not refer to
a three-dimensional histogram. n_x_bins is the number of bins in X.
n_y_bins is the number of bins in Y, and n_z_bins is the number of bins
in Z.
Commands like this are best handled by tcl's "foreach" statement, e.g.,
foreach {n_x_bins n_y_bins n_z_bins} [hs::3d_hist_num_bins $id] {}
hs::3d_hist_overflows $id $array_name
Arguments : integer id, string array_name
Returns : nothing
Fills the array named $array_name with the overflow data from
a three-dimensional histogram with the given id. All array indices
look like "$i,$j,$k" where i, j, and k vary from 0 to 2 for x, y,
and z axes, respectively. 0 corresponds to underflow, 1 corresponds
to a value within range, and 2 corresponds to overflow. For example,
$array_name(0,1,2) is the number of entries in the given histogram with
x value below the histogram x range, y value within range, and z value
above the histogram z range. Although defined, array element with index
"1,1,1" has no meaning.
hs::3d_hist_range $id
Arguments : integer id
Returns : list of doubles {x_min x_max y_min y_max z_min z_max}
Returns six-element list of minimum and maximum values representing
the limits of a three-dimensional histogram specified by id:
{x_min x_max y_min y_max z_min z_max}. Tcl error is thrown if id does
not refer to a three-dimensional histogram.
hs::3d_hist_set_bin $id $ix $iy $iz $value
Arguments : integers id, ix, iy, and iz, double value
Returns : nothing
Sets the value of the bin which has number $ix along the X axis,
$iy along the Y axis and $iz along the Z axis in the three-dimensional
histogram identified by id. Out-of-range bin numbers are ignored.
hs::3d_hist_set_bin_errors $id $ix $iy $iz $positive_error negative_error?
Arguments : integers id, ix, iy, and iz, doubles positive_error and
negative_error
Returns : nothing
Sets the errors for the bin which has number $ix along the X axis,
$iy along the Y axis and $iz along the Z axis in the three-dimensional
histogram identified by id. Out-of-range bin numbers are ignored.
Negative error may be omitted or specified as an empty string. Positive
error may be specified as an empty string in order to modify just
the negative error.
hs::3d_hist_set_overflows $id $array_name
Arguments : integer id, string array_name
Returns : nothing
Sets the overflow data for a three-dimensional histogram. The array
must have at least 27 elements defined with indices like "$i,$j,$k"
where i, j, and k vary from 0 to 2 (same indexing convention as in
the hs::3d_hist_overflows command).
hs::3d_hist_stats $id
Arguments : integer id
Returns : six-element list of doubles
{x_mean y_mean z_mean x_std_dev y_std_dev z_std_dev}
Calculates and returns the means and standard deviations of
a three-dimensional histogram along all histogram axes.
hs::3d_hist_subrange $uid $title $category $parent_id $axis $bin_min $bin_max
Arguments : integers uid, parent_id, bin_min, and bin_max, strings
title, category, and axis
Returns : integer
Creates a new 3-d histogram with specified user id, title, and category.
See the description of hs::create_3d_hist for a detailed description
of uid, title, and category arguments. The contents of the new histogram
are created by extracting a subrange from a 3-d histogram with
Histo-Scope id $parent_id. The subrange to use is defined by the
minimum $axis axis bin number, $bin_min, and the maximum $axis axis
bin number, $bin_max, both included in the resulting histogram. Allowed
values of the $axis argument are "x", "y", or "z" (not case sensitive).
The command returns a Histo-Scope assigned id of the new histogram or
throws a tcl error.
hs::3d_hist_xyz_value $id $x $y $z
Arguments : integer id, doubles x, y, and z
Returns : double
Returns the value stored in the histogram bin referenced by x, y, and z.
The result is undefined if item with given id is not a three-dimensional
histogram, or if x, y, or z are not within the range of the histogram.
hs::adaptive_c_project ?-include c_utility_code? ?-eval optional_c_code? \
$ntuple_id $uid $title $category $c_filter_expr $c_weight_expr \
$c_x_expr $bin_width_multiplier
Arguments : integers ntuple_id and uid, strings c_utility_code,
optional_c_code, title, category, c_filter_expr,
c_weight_expr, and c_x_expr, double bin_width_multiplier
Returns : integer
Creates a new 1d histogram with specified user id, title, and category,
and fills it using the data from ntuple with id $ntuple_id. See the
description of hs::create_1d_hist for a detailed description of uid,
title, and category arguments. c_filter_expr, c_weight_expr, and
c_x_expr must be valid C expressions which can be evaluated using
ntuple variables represented as floats. The histogram gets filled with
the value of c_x_expr and calculated weight c_weight_expr for a given
ntuple entry only when c_filter_expr is not evaluated to 0 for this
entry. Weights must be non-negative for all rows of the ntuple which
pass the filter. The command will try to figure out the optimal binning
but may perform poorly if the values of c_x_expr include extremely far
outliers (after filtering). bin_width_multiplier is an optional argument
which allows you to adjust the automatically selected bin width.
The default value of bin_width_multiplier is 1.0.
Optionally, an arbitrary set of C utility functions may be defined
using the "-include" option. These functions may be called inside
c_filter_expr, c_weight_expr, and c_x_expr. Optional C code provided
using the "-eval" option will be called just before c_weight_expr and
c_x_expr are calcuated (but after the filter).
The new histogram id is returned on success or a tcl error is thrown
in case of failure. See also the description of hs::ntuple_c_project.
hs::adaptive_stats_histogram $id_source $suppress_zero $uid $title $category \
$bin_width_multiplier
Arguments : integers id_source, suppress_zero, and uid,
strings title and category, double bin_width_multiplier
Returns : integer
Creates a new histogram with specified user id, title, and category,
and fills it using bin values of the histogram with id $id_source.
See the description of hs::create_1d_hist for a detailed description
of uid, title, and category arguments. If $suppress_zero != 0 then only
non-zero entries from $id_source are used. The command will try to
figure out the optimal binning but may perform poorly if the histogram
$id_source has extremely far outliers. bin_width_multiplier is
an optional argument which allows you to adjust the automatically
selected bin width. The default value of bin_width_multiplier is 1.0.
The new histogram id is returned on success or a tcl error is thrown
in case of failure.
hs::add_filled_columns $ntuple_id $uid $title $category name1? values1? \
name2? values2? ...
Arguments : integers ntuple_id and uid, strings title, category,
name1, name2, ..., binary strings or lists of doubles
values1, values2, ...
Returns : integer
Creates a new ntuple with user id, title, and category specified.
See the description of hs::create_ntuple command for a full explanation
of uid, title, and category arguments. Names $name1, $name2, etc. will
be appended to the set of variables in the ntuple with Histo-Scope id
$ntuple_id to form the set of variables of the new ntuple. $values1,
$values2, etc. must be binary strings or lists of doubles of
an appropriate size so that their values can be included in the new
ntuple as column contents of corresponding variables. The command
returns the Histo-Scope id of the new ntuple or throws a tcl error.
hs::allow_item_send $flag
Arguments : integer flag
Returns : nothing
When called with $flag equal 0, this command allows you to disable
Histo-Scope client updates. This is useful when you are doing heavy
calculations creating and deleting histograms frequently and do
not want to see intermediate results. Use this command again with
$flag equal 1 to allow normal updates. Warning: the set of items
before disabling the updates and after enabling them must be the same,
otherwise Histo-Scope clients will loose their synchronization with
the server.
hs::allow_reset_refresh $id $flag
Arguments : integer id, boolean flag
Returns : nothing
This command may be used to enable or disable refresh of ntuple plots
when an ntuple is reset. It may be useful to disable refresh on reset
for ntuples used to draw dynamically updated xy curves (when an ntuple
is created by the hs::create_ntuple command or read from a file, refresh
on reset is enabled). $id must be a valid Histo-Scope ntuple id.
hs::ascii_dump $filename $ids
Arguments : string filename, list of integers ids
Returns : integer
Dumps histograms and ntuples into a file in a human-readable form.
The function return value is the number of items written. The named
file is open for writing ("w"), discarding previous contents, if any.
Filenames "stdout" and "stderr" are special: instead of creating
files named "stdout" or "stderr", the program prints data to
the standard output or the standard error. For every item the program
prints a header which includes uid, title, category, binning
information (for histograms), and variable list (for ntuples).
After that the data are printed.
1d histogram data are printed as follows:
X_0 Value_0 Pos_error_0 Neg_error_0
X_1 Value_1 Pos_error_1 Neg_error_1
.....................
Either negative or both errors are omitted if the histogram has no
such error data.
2d histograms are printed as follows:
X_0 Y_0 Value_0_0 Pos_error_0_1 Neg_error_0_1
X_0 Y_1 Value_0_1 Pos_error_0_1 Neg_error_0_1
......................................................
X_0 Y_max Value_0_max Pos_error_0_max Neg_error_0_max
X_1 Y_0 Value_1_0 Pos_error_1_0 Neg_error_1_0
X_1 Y_1 Value_1_1 Pos_error_1_1 Neg_error_1_1
......................................................
Ntuples are printed one row per line.
hs::bin_coord $id $axis $number left_edge?
Arguments : integer id and number, string axis, boolean left_edge
Returns : double
Returns the bin coordinate for the given histogram, axis, and bin
number. An error is generated if the bin number is out of range.
$axis must be one of "x", "y", or "z" (case insensitive). If "left_edge"
is true then the command returns the coordinate of the left bin edge.
If "left_edge" is false or omitted then the command return the position
of the bin center.
hs::bin_number $id $axis $coord
Arguments : integer id, string axis, double coord
Returns : integer
Returns the bin number for the given histogram, axis, and coordinate
value. $axis must be one of "x", "y", or "z" (case insensitive).
-1 is returned if the coordinate value is out of histogram range.
hs::browse_collection $idlist option? arg? ...
Arguments : list of integers idlist, various options are supplied
as strings
Returns : string
This command creates a top level Tk widget which allows for convenient
browsing of histograms whose Histo-Scope ids are supplied by the $idlist
argument, and returns the name of the new toplevel window. This command
accepts the same options as the hs::show_histogram command, please check
the hs::show_histogram description for details.
The widget's "Search" entry can be used to find the first histogram
in the list whose title matches the typed pattern. The match is
established using the same rules as for the tcl command "string match"
(see the description of hs::lookup_title command for more details).
Click on the "ID" or "Title" labels to sort the entries by id or title.
Subsequent clicks on the same label change the ordering from increasing
to decreasing and back.
hs::calc $argument
Arguments : the argument could be either string or integer
Returns : see below
The hs::calc command has four different forms:
1) hs::calc $id - takes a Histo-Scope histogram id as an arguments
and returns a tcl command (also called handle) associated with it.
The commands associated with histograms provide a convenient
notation for performing various general and/or mathematical
manipulations with histograms in tcl scripts.
2) hs::calc purge - frees up the resources taken by histogram handles
and temporary histograms produced during calculations with handles.
This operation has to be performed from time to time by the
application because there is no automatic garbage collector in
the hs package. In this form the command returns nothing.
3) hs::calc count - returns the number of histogram handles defined
since the last purge operation.
4) hs::calc manual - prints an extended description of the hs::calc
command and histogram handle functionality to the standard output.
This description can also be found in file hs_calc.txt.
hs::category $id
Arguments : integer id
Returns : string
Returns the category string for a given Histo-Scope id. This function
produces an error (which you might want to catch) if an item with this
id does not exist.
hs::change_category $id $newcategory
Arguments : integer id, string newcategory
Returns : nothing
Changes the category of an item specified by its Histo-Scope
identification number, id. If a Histo-Scope is connected when this
routine is called, the Histo-Scope main window will be updated with the
new category.
hs::change_title $id $newtitle
Arguments : integer id, string newtitle
Returns : nothing
Changes the title of an item specified by its Histo-Scope
identification number, id. If a Histo-Scope is connected when this
routine is called, the Histo-Scope main window will be updated with the
new title.
hs::change_uid $id $newuid
Arguments : integers id, newuid
Returns : nothing
Changes the user-defined identification number (uid) to new_uid for an
item specified by its Histo-Scope identification number, id. If a
Histo-Scope is connected when this routine is called, the Histo-Scope
main window will be updated with the new uid.
hs::change_uid_and_category $id $new_uid $newcategory
Arguments : integers id and new_uid, string newcategory
Returns : nothing
Changes the user-defined identification number (uid) and
the category of an item specified by its Histo-Scope
identification number, id. If a Histo-Scope is connected when this
routine is called, the Histo-Scope main window will be updated with
the new category. This command allows you to change both the uid
and the category simultaneously even in those cases when the
sequential change of these attributes is impossible because of
the conflicts with uids and categories of other items.
hs::check_trigger $id
Arguments : integer id
Returns : integer
Returns 1 if the trigger identified by id has been set by a Histo-Scope
user. Otherwise 0 is returned. Please note that this routine will
return 1 once for each button press by the Histo-Scope user. Thus, if
the user has pressed the trigger 5 times, the program must call
hs::check_trigger at least 5 times.
hs::clear option? value? ...
Arguments : various options are supplied as strings
Returns : nothing
Removes all objects created by the commands hs::draw, hs::comment,
hs::latex, and hs::epsf from a Histo-Scope plot.
This command supports the following options:
-window $Win This option specifies the name of the window to clear.
The window named $Win must be created in advance by
one the commands hs::show_histogram, hs::overlay,
hs::multiplot, hs::expr_plot, etc. The default is
to use the window name specified on the most recent
occasion when one of these commands was issued with
the "-window" option.
-row $R This option is used for multiplots to specify the row
of the desired window. Default row is 0.
-column $C This option is used for multiplots to specify the
desired window column. Default column is 0.
hs::close_all_windows
Arguments : none
Returns : nothing
This command instructs Histo-Scope to close all plot windows.
hs::close_window $window_name nocomplain? sync?
Arguments : string window_name, boolean nocomplain and sync
Returns : nothing
This command closes a Histo-Scope window with the given name.
The window with this name must be created in advance by one of
the commands hs::show_histogram, hs::overlay, or hs::multiplot.
If set true, the optional boolean argument "nocomplain" instructs
Histo-Scope not to produce a warning message in case the window
with the given name does not exist or has already been closed.
By default, the window is closed by Histo-Scope asynchronously
with the running script, and this command returns immediately,
before the window disappears from the screen. This behavior may be
altered by setting the optional boolean argument "sync" to 1. In this
case the command will not return until the window is actually closed.
Note that a histogram (or an ntuple) displayed on the window should have
at least one data entry, otherwise the Histo-Scope GUI will wait forever
until the data arrives.
hs::column_cdfvalues $id $column $coords
Arguments : integers id and column, list of doubles coords
Returns : list of doubles
Calculates and returns a set of percentages (values of the normalized
cumulative distribution function multiplied by 100.0) for a given column
of the ntuple with Histo-Scope id $id. The length of the list of
coordinates is arbitrary. The returned list of percentages will have
the same length. This function is the inverse of hs::column_percentiles.
hs::column_contents $id $column
Arguments : integers id and column
Returns : binary string
Returns the contents of a column of Ntuple data specified by id
as a binary string. A column, which can also be called an element
or a variable, is the set of values taken by a single Ntuple
variable for each entry in the Ntuple.
hs::column_edf $ntuple_id $column reverse_order?
Arguments : integers ntuple_id and column, boolean reverse_order
Returns : binary string
Returns the empirical distribution function values for the given ntuple
column, in the same order as ntuple rows are originally filled. If the
optional argument "reverse_order" is set to 1, the function values
will decrease as values in the column increase.
hs::column_maximum $id $column
Arguments : integers id and column
Returns : mixed list {row_number max_value}
Searches for the maximum value in the given column of the ntuple
specified by id. Returns the row in which the maxumum is found
and the value itself.
hs::column_minimum $id $column
Arguments : integers id and column
Returns : mixed list {row_number min_value}
Searches for the minimum value in the given column of the ntuple
specified by id. Returns the row in which the minumum is found
and the value itself.
hs::column_percentiles $id $column $percentages
Arguments : integers id and column, list of doubles percentages
Returns : list of doubles
Calculates and returns a set of percentiles for a given column of
the ntuple with Histo-Scope id $id. The percentage values should be
between 0.0 and 100.0, inclusive. The returned list of percentiles
will have the same length. This function is the inverse of
hs::column_cdfvalues.
hs::column_range $ntuple_id $column_number
Arguments : integers ntuple_id and column_number
Returns : list of doubles {min max}
Finds minimum and maximum values in the specified ntuple column.
hs::column_shape $ntuple_id $column_number
Arguments : integers ntuple_id and column_number
Returns : list of doubles {n_entries mean stdev skewness kurtosis}
Returns the number of ntuple entries, mean, standard deviation,
skewness, and kurtosis for the contents of one column in the ntuple
with id $ntuple_id. In this particular estimate, the sum of squared
deviations is divided by the number of entries (rather than the number
of entries minus one) to get the standard deviation estimate.
hs::column_stats $ntuple_id $column_number $suppress_zero
Arguments : integers ntuple_id, column_number, and suppress_zero
Returns : list of doubles {sum mean stdev min q25 median q75 max}
Calculates various statistics on the contents of one column
in an ntuple. Zero entries are not used in any calculations if
$suppress_zero != 0. The following statistics are returned:
sum : sum of all values
mean : average of the values
stdev : standard deviation
min : minimum value
q25 : 25th percentile
median : median
q75 : 75th percentile
max : maximum value
See also the description of hs::ntuple_c_stats.
hs::comment $text $position option? value? ...
Arguments : string text, mixed list position, various options are
supplied as strings
Returns : nothing
This command can be used to draw comments and labels on top of
Histo-Scope plots. $text specifies the text to draw. The "position"
argument specifies the location of the text inside the plot window.
$position must be either a two- or a six-element list, same format as
in the specifications of object points in the hs::draw command.
Please see the hs::draw description for details about the format and
the coordinate systems.
The following options may be specified in addition to the required
arguments:
-window $Win This option specifies the name of the window to draw
the item in. The window named $Win must be created
in advance by one the commands hs::show_histogram,
hs::overlay, hs::multiplot, hs::expr_plot, etc.
The default is to use the window name specified on
the most recent occasion when one of these commands
was issued with the "-window" option.
-row $R This option is used for multiplots to specify the row
of the desired window. Default row is 0.
-column $C This option is used for multiplots to specify the
desired window column. Default column is 0.
-immediate $I Boolean option which specifies whether the comment
should be drawn immediately. The default value of this
option is 1. It is useful to set this option to 0 if
you plan to make a lot of comments or to draw many
items so that Histo-Scope redraws the window only when
it is complete. The hs::redraw command can be issused
at the end to ensure that every item is displayed.
-fg $F This option is used to specify the color of the text.
-foreground $F The default color is black.
-bg $B This option is used to specify the color of the
-background $B rectangle placed around the text string. The default
value of B is an empty string (means that the rectangle
is transparent).
-font $Fnt Specifies the font to use to draw the text. Use of
this option requires Tk. $Fnt may be given in any form
acceptable by Tk, for example "Times 18 {bold italic}".
X font names may also be used (run "xlsfonts" program
to see the names). Note that not all fonts are
supported in PostScript. The default font for plot
comments may be set with the hs::config_histoscope
command.
-coords $S Specifies default coordinate system for the comment
position and the reference point. $S must be one of
the strings "winabs", "winrel", and "plot". Default
is "winrel" (window relative system).
-origin $O Specifies default coordinate system origin for
the comment position. $O must be one of the letters
"o" (use origin) or "r" (use reference point). Capital
letters may be used as well. Default is "o".
-refpoint $P Specifies reference point which can be used instead
of coordinate system origin. $P must be a valid
point specification: either two- or six-element
list, as discussed in the description of the hs::draw
command. By default, reference point and window
coordinate system origin coincide (this corresponds
to P value of {0 winabs o 0 winabs o}).
-border $Brd Set true in order to draw a thin black rectangular
border around the comment string. Default is false.
-anchor $A Specifies the comment anchor, that is, where in the
string is the point whose location is specified by
the position argument. Allowed anchor values are
"nw" (means north-west), "n", "ne", "w", "center",
"c" (also means center), "e", "sw", "s", and "se".
When a rectangle is drawn around the text string
(that is, when either -bg or -border options are used),
the anchor refers to a point in the rectangle corner,
in the middle of the border, or in the center. Without
a rectangle, the anchor position within a string
becomes somewhat less clearly defined and depends on
the details of the font implementation.
-justify $J Specifies how to justify text in multi-line comments.
Allowed option values are "left", "right", and
"center". Default is "left".
Example
-------
Show histogram with Histo-Scope id 1 and draw its title in big bold
blue letters at the top of the plot window:
set id 1
hs::show_histogram $id -window winname -title "//hs::comment example"
hs::comment [hs::title $id] {0 winabs r -10 winabs r} \
-refpoint {0.5 1.0} -fg blue -bg white \
-anchor n -border on -font {Helvetica 24 bold}
hs::complete
Arguments : none
Returns : nothing
Close all connections with Histo-Scope processes and notify them that
the program is finished. This routine gives connected Histo-Scope
processes a chance to request a last update. This may take a few
seconds to accomplish.
If you are using HBOOK, this routine should be called before calling
hrend, since hs::complete may still access the HBOOK data.
Under rare circumstances, an hs::complete call can take up to 1 minute
to complete if one or more Histo-Scope(s) are viewing a large amount of
data and have somehow fallen behind in receiving the data. This call
allows a maximum of one minute for sending all data requested by
Histo-Scopes before the hs::complete was called.
In order to continue using Histo-Scope library after hs::complete,
hs::initialize must be called again.
hs::complete_and_wait
Arguments : none
Returns : nothing
Notify any connected Histo-Scope processes that the program is finished
and is waiting for them to exit or disconnect. While any Histo-Scope is
connected, this call will not return to the calling program. Instead
all Histo-Scope requests, including new connections will be serviced.
After all connected Histo-Scopes have disconnected, all data memory is
freed and control is returned to the calling program. As noted above,
if you are using HBOOK then this routine should be called before hrend.
hs::concat_histograms $uid $title $category $id1 $id2
Arguments : integers uid, id1, and id2, strings title and category
Returns : integer
This command concatenates, side by side, two histograms with
Histo-Scope ids $id1 and $id2, and creates a new histogram with
specified user id, title, and category. The histograms to be
concatenated must have compatible bin sizes and axis limits.
The lower limit of one histogram must coincide with the upper
limit of the other along one of the coordinate axes. In case of
multidimensional histograms, binning and limits for all other axes
must be identical. Also, the histograms are required to have the same
errors defined. The command returns a Histo-Scope assigned id of
the new histogram or throws a tcl error.
Example
-------
Suppose, we have a 1-d histogram with Histo-Scope id 10 which has
50 bins, and we want to multiply the lower 25 bins by 2. This can be
accomplished by the following sequence of commands:
set id_low [hs::1d_hist_subrange 1 "" "Tmp" 10 0 24]
set id_high [hs::1d_hist_subrange 2 "" "Tmp" 10 25 49]
set id_mult [hs::multiply_histograms 3 "" "Tmp" $id_low 0 2]
set id_result [hs::concat_histograms 4 [hs::title 10] "Tmp"\
$id_mult $id_high]
hs::config_histoscope option? value? ...
Arguments : various options are supplied as strings, the types of
their values depend on the option given
Returns : nothing
This command configures properties of connected Histo-Scopes. Available
options are:
autoHelp $a Turns on or off automatic plot help. $a must be
a boolean. Same functionality is available from
the "Preferences" menu of the Histo-Scope GUI.
bufferGraphics $b Turns graphics buffering on or off. $b must be
a boolean. Same functionality is available from
the "Preferences" menu of the Histo-Scope GUI.
commentFont $f Sets the default font for comments shown inside
the plot windows. $f must be a valid X or Tk font
name. Run "xlsfonts" to see the list of available
fonts. This option requires Tk.
defaultColorScale $c Modifies default color scale used by Histo-Scope.
$c must be a valid color scale tag returned
by command hs::create_linear_color_scale or
hs::create_general_color_scale.
minLineWidth $w Sets the minimal line width to be used for
histogram drawing in PostScript. $w must be
a non-negative double. Histo-Scope default is 0.5.
scat3dThicken $t3 Turns on or off default point size increase in
three-dimensional scatter plots. $t3 must be
a boolean. Points may be drawn thinner or thicker
for each individual plot by using the "Thicken
Points" item in the plot menu.
scatThicken $t2 Turns on or off default point size increase in XY
scatter plots. $t2 must be a boolean. Points may
be drawn thinner or thicker for each individual
plot by using the "Thicken Points" item
in the plot menu.
updatePeriod $p Sets the Histo-Scopes update frequency -- same
functionality is available from the "Preferences"
menu of the Histo-Scope GUI. $p is the update
period in milliseconds.
printTitles $T Turns on or off default printing of window
titles in PostScript files. When printing is on,
individual titles are not printed if they start
with double forward slash, e.g., "//Some title".
titleFont $Tf Sets the font for window titles in PostScript
files (the screen font will not change).
$Tf must be a valid X or Tk font name. This option
requires Tk.
mplotTitleFont $Mf Sets the PostScript font for plot subtitles
in multiplots (the screen font will not change).
$Tf must be a valid X or Tk font name. This option
requires Tk.
printCoords $Pc Turns on or off printing of point coordinates to
the standard output when "Grab Coordinates" menu
is invoked on a plot window. By default, printing
to the standard output is off.
hs::copy_data $id_to $id_from scale_factor?
Arguments : integers id_to and id_from, double factor
Returns : nothing
Copies data and errors from histogram with id $id_from to histogram
with id $id_to. The histograms must have the same number of bins but
may have different binning structure and even different dimensionality.
Overflow bins are discarded. Optional argument "scale_factor" may be
used to multiply bin contents and errors of the target histogram by
a constant. This command may be used for scaling bin contents and errors
of a histogram -- just use its id in place of both id_to and id_from.
hs::copy_hist $id $uid $title $category
Arguments : integers id and uid, strings title and category
Returns : integer
Duplicates a histogram or an ntuple identified by id. New item will
have the user id, title, and category specified by the function
arguments. The Histo-Scope defined id for the new item is returned.
hs::covar_to_corr $matrix
Arguments : list of lists of doubles matrix
Returns : list of lists of doubles
Converts a square covariance matrix into correlation matrix. Elements
in row i and column j (m_ij) are divided by sqrt(m_ii*m_jj).
hs::create_1d_hist $uid $title $category $x_label $y_label $n_bins $min $max
Arguments : integer uid, strings title, category, x_label, and y_label,
integer n_bins, double min, double max
Returns : integer
Create (or book) a one-dimensional histogram. uid defines a
user-specified identification number which can later be used along with
the category to specify the item created. title defines the title for
the histogram window when it is displayed. category is an optional
string (i.e. can be "") defining a hierarchical "location" for
the histogram. Subcategories can be specified using the "/" character
as in UNIX file specifications. If a category or subcategory does not
exist, it is created. If the category argument is "" then the histogram
will appear in the top level category as uncategorized. The histogram
axes are given the labels x_label and y_label. n_bins is the number
of bins in the histogram. Any values <= min or >= max are collected
into underflow and overflow bins. The Histo-Scope defined id for
the histogram is returned to the user and is used in later calls
to identify the histogram just created. The value of min should be
less than max, and n_bins should be greater than 0.
hs::create_2d_hist $uid $title $category $x_label $y_label $z_label \
$x_bins $y_bins $x_min $x_max $y_min $y_max
Arguments : integer uid, strings title, category, x_label, y_label,
and z_label, integers x_bins and y_bins, doubles x_min,
x_max, y_min, and y_max
Returns : integer
Create (or book) a two-dimensional histogram. uid defines a
user-specified identification number which can later be used along with
the category to specify the item created. title defines the title for
the histogram window when it is displayed. category is an optional (can
be "") string defining a hierarchical "location" for the histogram.
Subcategories can be specified using the "/" character as in UNIX file
specifications. If a category or subcategory does not exist, it is
created. If the category argument is "" then the histogram will appear
in the top level category as uncategorized. The histogram axes are
given the labels x_label, y_label, and z_label. x_bins and y_bins
are the number of bins for each axis of the histogram. Any values <= min
or >= max are collected into overflow bins. The Histo-Scope defined id
for the histogram is returned and is used in later calls to identify
the histogram just created. The values of x_min and y_min should be less
than their corresponding maximums, and x_bin and y_bin should both be
greater than 0.
hs::create_3d_hist $uid $title $category $x_label $y_label $z_label \
$q_label $x_bins $y_bins $z_bins $x_min $x_max \
$y_min $y_max $z_min $z_max
Arguments : integer uid, strings title, category, x_label, y_label,
z_label, and q_label, integers x_bins, y_bins, and z_bins,
doubles x_min, x_max, y_min, y_max, z_min, and z_max
Returns : integer
Create (or book) a three-dimensional histogram. uid defines a
user-specified identification number which can later be used along with
the category to specify the item created. title defines the title for
the histogram window when it is displayed. category is an optional (can
be "") string defining a hierarchical "location" for the histogram.
Subcategories can be specified using the "/" character as in UNIX file
specifications. If a category or subcategory does not exist, it is
created. If the category argument is "" then the histogram will appear
in the top level category as uncategorized. The histogram axes are
given the labels x_label, y_label, z_label, and q_label. x_bins, y_bins,
and z_bins are the number of bins for each axis of the histogram. Any
values <= min or >= max are collected into overflow bins. The Histo-Scope
defined id for the histogram is returned and is used in later calls
to identify the histogram just created. The values of x_min, y_min, and
z_min should be less than their corresponding maximums. x_bin, y_bin,
and z_bin should all be greater than 0.
hs::create_control $uid $title $category $min $max $default_value
Arguments : integer uid, strings title and category,
doubles min, max, and default_value
Returns : integer
Creates a control. uid defines a user-specified identification number
which can later be used along with the category to specify the item
created. title defines the title for the control, and category is an
optional string (can be "") defining a hierarchical "location" for
the control. Subcategories can be specified using the "/" character
as in UNIX file specifications. If a category or subcategory does not
exist, it is created. If the category argument is "" then the control
will appear in the top level category. min and max is the minimum and
maximum values for the control. The Histo-Scope user will not be able
to set the control outside of this range. The Histo-Scope defined id
for the control is returned and is used in later calls to identify
the control just created. Note that Tk's "scale" command provides
better look and feel in a similar widget.
hs::create_general_color_scale $underflow_color $color_list $overflow_color
Arguments : strings underflow_color and overflow_color, list of strings
color_list
Returns : a string
Creates a color scale which can be subsequently used to display color
scatter plots and color cell (tartan) plots. Like a histogram axis,
a color scale has a set of color bins mapped to a certain range of some
variable. It also has underflow and overflow colors used to paint
points or bins whose values do not fit into the mapped range. The data
mapping into the set of colors is specified when the plot is actually
displayed using such commands as hs::show_histogram or hs::overlay.
$color_list is a list of color names in any notation acceptable for
the X server. For example, "red", "RGBi:1.0/0.0/0.0", "#ffff00000000",
and "TekHVC:13.0/52.65/100.0" are all acceptable names for the red
color. In addition, color spaces HSV and HLS which are not directly
supported by the X Color Management System are also recognized (so that,
for example, "HSV:0.0/1.0/1.0" is also a valid name for red). The number
of colors in the list should be at least 2. This number should not
exceed 50 on displays which use 8 bits per pixel, and 2000 on displays
which use more bits. $underflow_color and $overflow_color are colors
used to represent underflow and overflow, respectively.
The command returns the tag for the new color scale which can be
later used by other commands. When the color scale info is no longer
needed, the hs::delete_color_scale command may be used to free up
some memory.
This command needs Tk (which is used to verify correctness of the color
names). Please also check the description of hs::create_linear_color_scale
command which may be more convenient for creating simple color scales.
Example
-------
Suppose, we have a 2d histogram with id 10. Then this histogram
can be displayed in three colors red, green, and blue like this:
set scale [hs::create_general_color_scale black {red green blue} white]
hs::show_histogram 10 -mode tartan -colorscale $scale
In this case the full Z axis range is divided into three equal parts
and mapped into the three colors. To map only a certain Z range to color,
use something like
hs::show_histogram 10 -mode tartan -colorscale $scale -zmin 0.0 -zmax 1.0
If the color scale is not specified explicitly, a default color scale
will be used. You can also modify the colors using the Histo-Scope color
editor accessible via the "Adjust Colors..." entry in the plot menu.
hs::create_group $uid $title $category $groupType \
$list_of_ids $list_of_error_types
Arguments : integer uid, strings title, category, and groupType, list of
integers list_of_ids, list of strings list_of_error_types
Returns : integer
Creates a group , which is an item that points to other data items, thus
grouping them into one addressable entity. uid defines a user-specified
identification number which can later be used along with the category to
specify the item created. category is an optional string (can be "")
defining a hierarchical "location" for the group. Subcategories can be
specified using the "/" character as in Unix file specifications.
If a category or subcategory does not exist, it is created.
If the category argument is "" then the group will appear in the top
level category. The Histo-Scope-defined id for the group is returned
and is used in later calls to identify the group just created.
groupType is the group's suggested window type. Allowed values for
groupType are "MULTIPLOT", "OVERLAY", and "INDIVIDUAL". list_of_ids
is a list of Histo-Scope id numbers for the items in the group.
list_of_error_types is a list of strings ("NO_ERROR_BARS",
"DATA_ERROR_BARS", or "GAUSSIAN_ERROR_BARS") that corresponds to
the list_of_ids and tells Histo-Scope how to display errors for
the corresponding histogram (used only when the corresponding data
item is a histogram). The number of elements in the list_of_error_types
should be equal to the number of elements on the list_of_ids and
must not exceed 81.
hs::create_histogram $uid $title $category $qlabel $xlabel $xmin $xmax \
$nxbins ylabel? ymin? ymax? nybins? zlabel? zmin? zmax? nzbins?
Arguments : integers uid, nxbins, nybins, and nzbins, strings title,
category, qlabel, xlabel, ylabel, and zlabel, doubles xmin,
xmax, ymin, ymax, zmin, and zmax
Returns : integer
This is a convenience procedure which books 1, 2, or 3d histogram.
The histogram dimensionality is inferred from the number of arguments
provided (argument "ylabel" and all subsequent arguments are optional).
Internally, this procedure calls one of the commands hs::create_1d_hist,
hs::create_2d_hist, or hs::create_3d_hist. Argument "uid" defines a
user-specified identification number which can later be used along with
the category to specify the item created. "title" defines the title for
the histogram window when it is displayed. "category" defines
a hierarchical "location" for the histogram (see the description of
hs::create_1d_hist command for more details). "qlabel" is the label
used for the magnitude of the histogram bins (e.g., vertical axis label
for 1d histograms). Arguments "xlabel", "xmin", "xmax", and "nxbins"
specify x axis label, histogram minimum and maximum range along the
x axis, and the number of x bins, respectively. When provided, other
arguments specify parameters of the y and z axes in a similar fashion.
This command returns the Histo-Scope defined id of the new histogram.
hs::create_indicator $uid $title $category $min $max
Arguments : integer uid, strings title and category,
doubles min and max
Returns : integer
Creates an indicator. uid defines a user-specified identification
number which can later be used along with the category to specify the
item created. title defines the title for the indicator, and category
is an optional string (can be "") defining a hierarchical "location"
for the indicator. Subcategories can be specified using the "/" character
as in UNIX file specifications. If a category or subcategory does not
exist, it is created. If the category argument is "" then the indicator
will appear in the top level category. min and max is the minimum and
maximum values for the indicator. The Histo-Scope defined id for
the indicator is returned and is used in later calls to identify
the indicator just created. Note that Tk's "scale" command provides
better look and feel in a similar widget.
hs::create_linear_color_scale $colorspace $ncolors $underflow_color \
$start_color $end_color $overflow_color
Arguments : strings colorspace, underflow_color, start_color,
end_color, and overflow_color, integer ncolors
Returns : a string
Creates a color scale which can be subsequently used to display color
scatter plots and color cell (tartan) plots. Like a histogram axis,
a color scale has a set of color bins mapped to a certain range of some
variable. It also has underflow and overflow colors used to paint
points or bins whose values do not fit into the mapped range. The data
mapping into the set of colors is specified when the plot is actually
displayed using such commands as hs::show_histogram or hs::overlay.
Linear color scale is a straight line in the coordinates of the color
space specified by the "colorspace" argument. All color spaces supported
by the X Color Management System may be used: RGB, RGBi, CIEXYZ, CIEuvY,
CIExyY, CIELab, CIELuv, and TekHVC. In addition, two other popular spaces
are supported: HSV (Hue, Saturation, and Value) and HLS (Hue, Luminance,
and Saturation). A detailed description of various color spaces is beyond
the scope of this simple help. If you need more information, please
consult the relevant literature about colorimetry or search the Web for
"color space FAQ". In general, you need to have some idea how your
favorite color space is related to the RGB space so that the whole color
scale stays within the limits imposed by RGB and can be displayed on
the computer screen.
The starting and ending points of the scale are specified by the
"start_color" and "end_color" arguments, respectively. The color
names may be given in any notation acceptable for the X server.
For example, "red", "RGBi:1.0/0.0/0.0", "#ffff00000000",
and "TekHVC:13.0/52.65/100.0" are all acceptable names for the red
color. In addition, color names which start with "HSV:" and "HLS:"
may be used as well (so that, for example, "HSV:0.0/1.0/1.0" is also
a valid name for red). The number of colors in the scale is specified
by the "ncolors" argument. This number should be at least 2. The upper
limit on the number of colors depends on the screen depth: it is 50 for
displays which use 8 bits per pixel and 2000 for displays which use more
bits. Arguments "underflow_color" and "overflow_color" specify colors
used to represent underflow and overflow.
The command returns the tag for the new color scale which can be
later used by other commands. When the color scale info is no longer
needed, the hs::delete_color_scale command may be used to free up
some memory.
This command needs Tk (which is used to verify correctness of
the color names). Arbitrary non-linear color scales may be created
using the hs::create_general_color_scale command.
Examples
--------
The following command creates a color scale identical to the default
Histo-Scope color scale:
hs::create_linear_color_scale HSV 100 black HSV:240/1/1 HSV:0/1/1 magenta
Suppose, we have a 2d histogram with id 10. Then this histogram
can be displayed in a range of RGB colors from blue to red like this:
set scale [hs::create_linear_color_scale RGB 50 black blue red magenta]
hs::show_histogram 10 -mode tartan -colorscale $scale
In this case the full Z axis range is divided into 50 equal parts
and mapped into the 50 colors of the scale. To map only a certain
Z range to color, use something like
hs::show_histogram 10 -mode tartan -colorscale $scale -zmin 0.0 -zmax 1.0
If the color scale is not specified explicitly, a default color scale
will be used. You can also modify the colors using the Histo-Scope color
editor accessible via the "Adjust Colors..." entry in the plot menu.
hs::create_ntuple $uid $title $category $list_of_names
Arguments : integer uid, strings title and category,
list of strings list_of_names
Returns : integer
Defines an Ntuple with number of variables equal to
[llength $list_of_names]. uid defines a user-specified identification
number which can later be used along with the category to specify
the item created. title defines the title for the Ntuple, and category
is an optional (i.e. can be "") string defining a hierarchical
"location" for the histogram. Subcategories can be specified using
the "/" character as in UNIX file specifications. If a category or
subcategory does not exist, it is created. If the category argument
is "", the Ntuple will appear in the top level category as uncategorized.
Each element in the list_of_names is a string naming an Ntuple variable.
Storage allocation is automatic: as the Ntuple grows, more space
will be allocated. However, Ntuples must fit into virtual memory.
The Histo-Scope defined id for the Ntuple is returned and is used in
later calls to identify the Ntuple just created.
The specified Ntuple variable names should, preferably, be valid
C variable names. This allows for subsequent use of fast commands
related to ntuple filtering and statistical computations (such as
hs::ntuple_c_filter and hs::ntuple_c_stats). A valid C variable name
must begin with a letter or underscore, must contain only letters,
digits, and underscores, and must not coincide with a reserved C keyword.
It may also be a properly formed member of a struct, or an array element
with a small non-negative integer index, such as "Kshort[2].Px" or
"point[10]". Unlike real C, no spaces should be used inside such names.
hs::create_trigger $uid $title $category
Arguments : integer uid, strings title and category
Returns : integer
Creates a trigger. uid defines a user-specified identification number
which can later be used along with the category to specify the item
created. title defines the title for the trigger, and category is an
optional string (can be "") defining a hierarchical "location" for
the trigger. Subcategories can be specified using the "/" character
as in UNIX file specifications. If a category or subcategory does not
exist, it is created. If the category argument is "" then the trigger
will appear in the top level category. The Histo-Scope defined id for
the trigger is returned and is used in later calls to identify
the trigger just created. Note that Tk's "button" command provides
better look and feel in a much more versatile widget.
hs::data_to_list $bstring
Arguments : binary string bstring
Returns : list of doubles
Converts binary strings formatted as floating point arrays into tcl
lists of doubles. Useful for conversion of return values of such hs
commands as hs::1d_hist_bin_contents, hs::1d_hist_errors, etc.
hs::default_latex_packages
Arguments : none
Returns : list of strings
This command returns the default list of packages loaded by LaTeX
when the hs::latex command is executed. The users are expected to
overwrite this command. For example, the following code makes
"amsmath", "amsfonts", and "color" default packages:
proc ::hs::default_latex_packages {} {
list amsmath amsfonts color
}
hs::delete $id
Arguments : integer id
Returns : nothing
Deletes a histogram, Ntuple, indicator, control, or trigger identified
by id.
hs::delete_category $category
Arguments : string category
Returns : nothing
Deletes all items in the named category. All data content is lost. The
category string must exactly match the category of the item to be
deleted unless a trailing "..." is specified as part of the category.
When the "..." is specified, data items in the category and all
subcategories of the category will be deleted. Specifying ""
for category will delete all uncategorized items. For example,
specifying a category "HS/..." will delete all items with category "HS"
and "HS/Nts" but not "HSNTuples" nor "hs". If just "..." is specified,
all items are deleted.
hs::delete_color_scale $tag
Arguments : string tag
Returns : nothing
Deletes a color scale created earlier by one of the commands
hs::create_linear_color_scale or hs::create_general_color_scale.
hs::delete_color_scale will generate a tcl error if $tag is not
a valid color scale tag or if it refers to a color scale which
has already been deleted.
hs::delete_items id_list1? id_list2? ...
Arguments : lists of integers id_list1, id_list2, ...
Returns : nothing
Deletes all items identified by ids in the argument lists.
hs::dir $filename
Arguments : string filename
Returns : list of lists
Returns a description of Histo-Scope items saved in the file
with given name. The information about each item is returned in
the four-element list {uid category title type}. Please check
descriptions of commands hs::uid, hs::category, hs::title, and hs::type
for more details on the meaning of respective elements. Each of these
four-element lists is an element of the result. A typical code which
iterates over the the list of items looks like this:
foreach item [hs::dir $filename] {
foreach {uid category title type} $item {}
# Do something useful here with $uid, $category, etc.
}
hs::divide_histograms $uid $title $category $id1 $id2 $const
Arguments : integer uid, strings title and category,
integers id1 and id2, double const
Returns : integer
Create a new histogram (one-dimensional or two-dimensional) whose data
is the division, bin by bin, of two histograms specified by id1 and
id2. uid is the User Identification for the newly created histogram.
title defines the title for the new histogram window when it is
displayed. category is a string defining a hierarchical "location" for
the histogram. Subcategories can be specified using the "/" character
as in UNIX file specifications. If a category or subcategory does not
exist, it is created. If the category argument is "" then
the histogram will appear in the top level category. The bin
content of the new histogram will be equal to const * bin value of
histogram id1 / bin value of histogram id2. If the bin value of
histogram id2 is 0, the value 1 is used in the computation. Returns
new_id which is the id of a new histogram containing the result of the
operation.
hs::draw $item_type $point1 $point2 ... option? value? ...
Arguments : string item_type, mixed lists point1, point2, ...
various options are supplied as strings
Returns : nothing
This command can be used to draw simple objects in Histo-Scope plot
windows. $item_type specifies an item to draw. Valid item types are
"points", "line", "rectangle", "ellipse", and "polygon". Arguments
point1, point2, etc. specify the size and location of the object to draw.
The meaning of these arguments depends on the item type.
Point coordinates may be specified in three different coordinate systems:
1) absolute window system, 2) relative window system, and 3) plot system
(2d plots only). The origin of both absolute and relative window systems
is at the bottom left corner of the plot window. In the absolute window
system the upper right corner of the window has coordinates
{width height}, where dimensions are measured in pixels (as in X window
geometry). In the relative window system the upper right corner of
the window has coordinates {1.0 1.0}. The plot system is defined by
the coordinate axes of the histogram or graph displayed in the window.
Each of the arguments point1, point2, etc. may be either a two-element
list or a six-element list. In the six-element format points are
specified like this: {x system_x origin_x y system_y origin_y}. Here,
x and y are point coordinates (integers or doubles). system_x specifies
the coordinate system to use for x. It must be one of the strings
"winabs", "winrel", and "plot". These strings mean absolute window
system, relative window system, and plot system, respectively. origin_x
is one of the letters "o", "l", or "r" (case insensitive). "O" means
that the x coordinate is specified with respect to the coordinate
system origin, "l" means that the coordinate is given with respect
to the last point already specified (this option can not be used for
the first point in the object), and "r" means that the coordinate origin
is shifted to a special reference point (this point may be set with
the -refpoint option described later). system_y and origin_y have
similar meanings for the y coordinate. In the two-element format the list
specifies x and y coordinates of the point in the default coordinate
system with respect to the default origin. The default coordinate system
and origin may be changed using -coords and -origin options.
The set of points has the following meaning for different values of
the item_type argument:
Item type Meaning of the point coordinates
------------- ------------------------------------------------------
"points" Each point specifies a separate point to draw.
"line" The program will draw a set of straight line
segments passing sequentially through each point.
At least two points must be specified.
"rectangle" Exactly two points must be specified which define
two opposite rectangle corners.
"ellipse" Two or three points must be specified. The first two
points define the corners of the smallest rectangle
which completely encloses the ellipse. If provided,
the x coordinate of the third point is used as the
correlation coefficient (coordinate system and origin
are ignored, and the y coordinate of this point is
ignored as well). If the absolute value of the
correlation coefficient exceeds 1 then no ellipse
will be drawn. If the third point is not provided
then the correlation coefficient is assumed to be 0,
and the major axes of the ellipse will be parallel
to the coordinate axes.
"polygon" At least three points must be specified. The program
draws a polygon with vertexes in each point (the first
and the last point will be connected automatically).
If the polygon is filled, the sequential path between
the vertexes must not self-intersect.
Up to 32 points may be specified in a single command. If any coordinate
of any point is specified in the plot coordinate system, the object
drawing will be clipped at the plot axes.
The hs::draw command supports the following options:
-window $Win This option specifies the name of the window to draw
the item in. The window named $Win must be created
in advance by one the commands hs::show_histogram,
hs::overlay, hs::multiplot, hs::expr_plot, etc.
The default is to use the window name specified on
the most recent occasion when one of these commands
was issued with the "-window" option.
-row $R This option is used for multiplots to specify the row
of the desired window. Default row is 0.
-column $C This option is used for multiplots to specify the
desired window column. Default column is 0.
-immediate $I Boolean option which specifies whether the item should
be drawn immediately. The default value of this option
is 1. It is useful to set this option to 0 if you plan
to draw many items or to make a lot of comments so that
Histo-Scope redraws the window only when it is
complete. The hs::redraw command can be issused at
the end to ensure that every item is displayed.
-fg $F This option is used to specify the color of the point
-foreground $F and line objects as well as the color of the border
for ellipses, rectangles, and polygons. Drawing of
the borders may be suppressed by setting foreground
color to an empty string. The default color is black.
-bg $B This option may be used to specify the fill color
-background $B for ellipses, rectangles, and polygons. By default,
these objects are not filled (they are transparent).
-line $L This option may be used with "line" objects to
specify the style of the line to draw. $L must
be an integer from 0 to 12, and it corresponds
to the standard Histo-Scope line style. Default
line style is 1 (thin solid line).
-arrow $A This option may be used to draw an arrow at the
beginning and/or the end of the "line" object.
Valid option values are "forward", "backward",
"both", and "none". Default is "none".
-coords $S Specifies coordinate system for all object points
defined by two-element lists, including the reference
point. $S must be one of the strings "winabs",
"winrel", and "plot". Default is "winrel" (window
relative system).
-origin $O Specifies coordinate system origin for all object
points defined by two-element lists. $O must be one
of the letters "o" (use origin), "l" (last point),
or "r" (reference point). Capital letters may be used
as well. Default is "o".
-refpoint $P Specifies reference point which can be used instead
of coordinate system origin. $P must be a valid
point specification: either two- or six-element
list, as discussed earlier. This point should always
be specified with respect to the coordinate system
origin. By default, reference point and window
coordinate system origin coincide (this corresponds
to P value of {0 winabs o 0 winabs o}).
Examples
--------
Draw a blue filled rectangle proportional to the window size
in the lower right corner of the window named "w1":
hs::draw rectangle -window w1 {0.8 0} {1.0 0.2} -bg blue
Draw a fixed-size red ellipse in the upper right corner. Make a small
shift towards the plot center to ensure that no part of the ellipse will
be covered by Motif shadows which Histo-Scope draws around each plot:
hs::draw ellipse -window w1 -refpoint {1 1} {-5 winabs r -5 winabs r} \
{-100 winabs l -50 winabs l} -bg red
Draw a thick red arrow towards some point defined by variables x and y
in the plot coordinate system, starting at some fixed distance from
the upper right corner of the window. The arrow will follow the point
in the plot no matter how the plot is paned or resized:
hs::draw line -window w1 -refpoint {1 1} {-50 winabs r -50 winabs r} \
[list $x plot o $y plot o] -arrow forward -fg red -line 12
hs::duplicate_axes $id $uid $title $category
Arguments : integers id and uid, strings title and category
Returns : integer
Duplicates binning structure of the histogram identified by id but
does not copy the data. New histogram will have the user id, title,
and category as specified by the function arguments. The Histo-Scope
defined id for the new item is returned or a tcl error is thrown on
failure.
hs::duplicate_ntuple_header $id $uid $title $category
Arguments : integers id and uid, strings title and category
Returns : integer
Creates an empty ntuple whose variables are identical to the variables
of the ntuple with Histo-Scope id $id. New ntuple will have the user id,
title, and category as specified by the function arguments.
The Histo-Scope defined id for the new item is returned or a tcl error
is thrown on failure.
hs::eigen_sym $m reverse_ordering?
Arguments : list of lists of doubles m, boolean reverse_ordering
Returns : list of lists {eigenvalues eigenvectors}
Calculates eigenvalues and eigenvectors of a symmetric matrix $m.
If the argument matrix is not symmetric then it is symmetrized
internally. The command returns a two-element list. The first element
of this list is the list of eigenvalues in ascending order. The second
element is the list of corresponding eigenvectors. Optional argument
"reverse_ordering" allows you to reverse the ordering of the eigenvalues
(eigenvectors are swapped accordingly). This command uses LAPACK
subroutine DSYEV, and it is only available if the extension has been
compiled with CERNLIB.
hs::epsf $filename $position option? value? ...
Arguments : string filename, mixed list position, various options are
supplied as strings
Returns : nothing
This command can be used to display EPS files on top of Histo-Scope
plots. $filename specifies the file to use. The "position" argument
specifies the location of the imported picture inside the plot window.
$position must be either a two- or a six-element list, same format as
in the specifications of object points in the hs::draw command. Please
see the hs::draw description for details about the format and the
coordinate systems.
The following options may be specified in addition to the required
arguments:
-window $Win This option specifies the name of the window to draw
the item in. The window named $Win must be created
in advance by one the commands hs::show_histogram,
hs::overlay, hs::multiplot, hs::expr_plot, etc.
The default is to use the window name specified on
the most recent occasion when one of these commands
was issued with the "-window" option.
-row $R This option is used for multiplots to specify the row
of the desired window. Default row is 0.
-column $C This option is used for multiplots to specify the
desired window column. Default column is 0.
-ipadx $Xmarg Use these options if you would like to change the
-ipady $Ymarg bounding box specified in the EPS file. Option values
must be two-element lists of integers: $Xmarg should
look like {left right} and $Ymarg as {top bottom}.
These options add margins to the bounding box: positive
values will increase the bounding box by the specified
number of points, and negative will result in clipping
of the image.
-scale $Mag Specifies magnification factor for the image (must be
a positive double). Default is 1.0.
-immediate $I Boolean option which specifies whether the image
should be drawn immediately. The default value of this
option is 1. It is useful to set this option to 0 if
you plan to make a lot of comments or to draw many
items so that Histo-Scope redraws the window only when
it is complete. The hs::redraw command can be issused
at the end to ensure that every item is displayed.
-bg $B This option may be used to specify the color which
-background $B replaces white and transparent pixels in the imported
picture. This color should be left at its default
value, white, unless you are sure that the imported
picture does not have any genuine white paint in it
(text and simple drawings usually don't use any white
paint).
-coords $S Specifies default coordinate system for the comment
position and the reference point. $S must be one of
the strings "winabs", "winrel", and "plot". Default
is "winrel" (window relative system).
-origin $O Specifies default coordinate system origin for
the comment position. $O must be one of the letters
"o" (use origin) or "r" (use reference point). Capital
letters may be used as well. Default is "o".
-refpoint $P Specifies reference point which can be used instead
of coordinate system origin. $P must be a valid
point specification: either two- or six-element
list, as discussed in the description of the hs::draw
command. By default, reference point and window
coordinate system origin coincide (this corresponds
to P value of {0 winabs o 0 winabs o}).
-border $Brd Set true in order to draw a thin rectangular border
around the imported picture. Default is true.
-bordercolor $Bd This option is used to specify the color of the border.
The default color is black.
-anchor $A Specifies the picture anchor, that is, where in the
surrounding rectangle will be the point whose location
is specified by the position argument. Allowed anchor
values are "nw" (means north-west), "n", "ne", "w",
"center", "c" (also means center), "e", "sw", "s",
and "se".
This command needs the "gs" (ghostscript) executable, version 7.0 or
later, and it only works if the Histo-Scope GUI runs on the same computer
as the tcl shell. You can specify the location of the executable by
setting the environmental variable GHOSTSCRIPT (specify the full path).
hs::expr_plot $tcl_expression $variable_name $xmin $xmax option? arg? ...
Arguments : script tcl_expression, string variable_name, doubles
xmin and xmax, various options are supplied as strings
Returns : string or nothing
This command is used to plot mathematical expressions. $tcl_expression
must be a valid tcl script which produces double precision results in
the variable context of the calling procedure. $variable_name is the name
of the function variable. Values $xmin and $xmax define the limits of
the x axis range. The following command line options are supported:
-plotpoints $N Specifies the number of points to plot (may not be
less than 2). If this option is not present, the
function will be plotted using 1000 evaluation points.
-id $hs_id Do not plot the function; instead, the command fills
a two-variable Histo-Scope ntuple with id $hs_id
which has to be created in advance. The first ntuple
variable will be filled with plot's x values, and the
second variable will be filled with corresponding
values of the function. This option may not be used
simultaneously with -overlay and -show.
-overlay $Oname Specifies the name of the overlayed plot to use
for function plotting. If this option is not present,
a unique overlay name will be generated automatically.
This option may not be used together with -id option.
-show $b This boolean option tells the command whether it
should display the plot immediately. The default
behavior is to display the plot if the -overlay
option is not provided. This option may not be used
together with -id.
-window $Win Specifies the window name for subsequent use with
commands hs::comment, hs::generate_ps, etc.
This option is meaningful only when the plot is
actually displayed by the command.
-font $F Specifies font to use for axis labels. Use of this
option requires Tk. $F may be given in any form
acceptable by Tk, for example "Times 18 {bold italic}".
X font names may also be used (run "xlsfonts" program
to see the names). Note that not all fonts are
supported in PostScript. This option is meaningful
only when the plot is actually displayed by the
command.
-xmin $x0 These options specify the lower and upper limits
-xmax $x1 of the horizontal and vertical axes to display.
-ymin $y0 By default, the limits are chosen in such a way
-ymax $y1 that the whole plot is shown. All these options are
meaningful only when the -id option is not used.
-xlabel $lx Specifies the x axis label. If this option is not
used, a label will be generated automatically.
-ylabel $ly Specifies the y axis label. If this option is not
used, a label will be generated automatically.
-title $title Specifies the window title for the plot. If this
option is not used, window title will be generated
automatically.
-line $n This option specifies the line style. There are
13 distinct line styles numbered from 0 to 12.
The default line style is 1 (thin solid line).
-color $cl Specifies the line color. The default color is black.
-marker $m Specifies the marker style. The value must be either
an integer from 0 to 9 or one of the following words:
none, square, circle, star, x, triangle, solidsquare,
solidcircle, thicksquare, or thickcircle. The default
marker style is "none".
-markersize $s The value must be an integer from 0 to 3 or one of
the following words: tiny, small, medium, and large.
The default marker size is "small".
This command returns an empty string if it is called with the "-id"
option; in all other cases it returns the name of the overlayed plot
used to draw the function.
Examples
--------
Draw the exp(x) function from 0 to 4:
hs::expr_plot {expr exp($x)} x 0 2
Draw a family of curves:
foreach {a color} {1 red 2 green 3 blue} {
hs::expr_plot {expr sin($a*$x)/$x} x -10 10 -color $color -overlay o1
}
hs::overlay o1 show -legend off -title "Plots of sin(a*x)/x for a = 1,2,3"
Evaluate a script at regular intervals and draw the result:
hs::expr_plot {
set y [expr {int($x)}]
expr {$x - $y}
} x -3 3 -plotpoints 13
hs::fill_1d_hist $id $x $weight
Arguments : integer id, doubles x and weight
Returns : nothing
Adds a value (weight) to the one-dimensional histogram identified by id.
hs::fill_2d_hist $id $x $y $weight
Arguments : integer id, doubles x, y, and weight
Returns : nothing
Adds a value (weight) to the two-dimensional histogram identified by id.
hs::fill_3d_hist $id $x $y $z $weight
Arguments : integer id, doubles x, y, z, and weight
Returns : nothing
Adds a value (weight) to the three-dimensional histogram identified by id.
hs::fill_hist_slice $slice_id $parent_id $axis1 $bin1 axis2? bin2?
Arguments : integers slice_id, parent_id, bin1, and bin2,
strings axis1 and axis2
Returns : nothing
Fills a 1d or 2d histogram with Histo-Scope id $slice_id using a slice
of a histogram with Histo-Scope id $parent_id. The latter histogram
must have higher dimensionality than the former. Normally, histogram
$slice_id should be created with the aid of hs::slice_histogram command,
using the same parent id and slice axes. Valid axis specifications are
"x", "y", and "z" (not case sensitive). Only one slice axis can be
specified with a 2d parent histogram (omit axis2 and coord2 or use
an empty string for axis2). When both axis1 and axis2 are given,
$slice_id should refer to a 1d histogram, $parent_id should refer to
a 3d histogram, and $axis1 must be different from $axis2. bin1 and
(optionally) bin2 specify parent histogram bin numbers along their
respective axes at which the slices are made. When a bin number is
below 0 or above the allowed limit for the corresponding axis, a tcl
error is generated. Similar operation using coordinates rather than
bin numbers can be performed by hs::fill_slice command.
hs::fill_histogram $id $values weight?
Arguments : integer id, double weight, values may be either a list
of doubles or a binary string of floats
Returns : nothing
Adds one or more entries (weights) to the histogram identified by id.
The number of elements in the "values" argument should be divisible
by the histogram dimensionality. If weight is not provided, it is
assumed to be 1.
hs::fill_ntuple $id $values
Arguments : integer id, values may be either a list of doubles
or a binary string of floats
Returns : integer
Adds an array of values, in the order they are named in
hs::create_ntuple, to an Ntuple identified by id. The number of
elements in the "values" argument must be divisible by the number
of ntuple variables. The ntuple id number is returned upon success,
or a tcl error is generated in case of failure.
hs::fill_slice $slice_id $parent_id $axis1 $coord1 axis2? coord2?
Arguments : integers slice_id and parent_id, strings axis1 and axis2,
doubles coord1 and coord2.
Returns : nothing
Fills a 1d or 2d histogram with Histo-Scope id $slice_id using a slice
of a histogram with Histo-Scope id $parent_id. The latter histogram
must have higher dimensionality than the former. Normally, histogram
$slice_id should be created with the aid of hs::slice_histogram command,
using the same parent id and slice axes. Valid axis specifications are
"x", "y", and "z" (not case sensitive). Only one slice axis can be
specified with a 2d parent histogram (omit axis2 and coord2 or use
an empty string for axis2). When both axis1 and axis2 are given,
$slice_id should refer to a 1d histogram, $parent_id should refer to
a 3d histogram, and $axis1 must be different from $axis2. coord1 and
(optionally) coord2 specify the coordinate values (note, not bin numbers)
along their respective axes at which the slices are made. When the
coordinates are below (or above) the parent histogram range, the slices
are made using the first (or last) bin along the corresponding axis.
Similar operation using bin numbers rather than coordinates can be
performed by hs::fill_hist_slice command.
In order to avoid rounding problems in numerical calculations, this
command adds a small offset (equal to one hundredth of the relevant bin
width) to the argument coordinates. In such a way, coordinates near
the left bin edge end up in the correct bin. Coordinates near the right
bin edge should not be used with this command.
hs::find_data_mismatch $bs1 $bs2 $eps
Arguments : binary strings bs1 and bs2, double eps
Returns : integer
Treats binary strings $bs1 and $bs2 as arrays of floats and returns
the first index for which either the fractional difference between
the array values is larger than $eps or one and only one of the arrays
goes out of bounds. If no such index exists this command returns -1.
hs::fit $datasets $functions opt1? value1? ...
Arguments : mixed list datasets, list of strings functions, various
options are supplied as strings
Returns : string
Creates a new tcl command (also called handle) which can be used for
Minuit-based data fitting, and returns the command name. Data fitting
may be performed in 1, 2, or 3 dimensions. Arbitrary number of datasets
may be fitted simultaneously using arbitrary number of parameters, but
the number of simultaneously variable parameters may not exceed 50 (this
limit may be increased if necessary by recompiling Minuit). The "datasets"
argument is a list of dataset specifiers which define the initial set
of histograms and/or ntuples to fit. At least one specifier must be
provided. Each dataset specifier is itself a list. The first element of
this list must be a Histo-Scope id of a histogram or an ntuple, and
the rest is switches. The following switches may be used in dataset
specifiers which refer to either histograms or ntuples:
-weight $W Specifies the dataset weight in the fit ($W should be
a non-negative double). The default weight is 1.0.
-method $M Specifies the fitting method for this dataset. Possible
M values are:
"L2" -- L2 distance (least squares, all weights equal)
"ls" -- Least squares, errors provided by user
"chisq" -- Chi-square (least squares, errors from the fit)
"ml" -- Maximum likelihood
"eml" -- Extended maximum likelihood
If this switch is not provided then the fit default method
will be used for this dataset (it will be explained later
how to define the fit default method). Note that unbinned
fits may be performed only with maximum likelihood methods.
Dataset specifiers which refer to ntuples may use the following
additional switches: -x, -y, -z, -v, and -e. Values provided after
these switches specify ntuple column names used to define x coordinates
of the data points, y coordinates, z coordinates, data values, and data
errors, respectively. -x switch is required, all other switches are
optional. If -v and -e switches are not provided then the fit will be
unbinned.
The "functions" argument specifies a list of data fitting functions. Each
element of this list must be a valid function tag as defined by commands
hs::function_import, hs::function_compose, etc. All tags must be distinct.
By default, each dataset will be fitted by the sum of all functions.
If this is not the desired behavior then use an empty list in place of
the "functions" argument -- the fit handle will later allow you
to specify different fitting functions for each dataset.
The following command options may be used to set various fit properties:
-name $cmd Specifies the handle name. A command with the same
name must not already exist.
-title $T Specifies the fit title which will be used in various
printouts. Minuit printouts can only use the first
50 characters of the title string.
-description $D Specifies the fit description (an arbitrary string).
The default D value is an empty string.
-method $M Sets the default fitting method which will be assigned
to every dataset which does not explicitly specify its
fitting method. The allowed M values are "L2", "ls",
"chisq", "ml, and "eml". They have the same meanings
as for the dataset-specific "-method" switch. The
default M value is "ls".
-warnings $Warn If set to "false", instructs Minuit to suppress
warning messages about suspicious conditions which
may indicate unreliable results. The default is
to print such messages.
-ignore $Ign If $Ign is "true", the program will not print error
messages generated by fitting functions. The default
option value is "false".
-errdef $UP Sets Minuit value of UP defining parameter errors.
Minuit defines parameter errors as the change in
the parameter value required to change the minimized
function value by $UP. Unless you know exactly what
you are doing, leave this option at its default value
of 1.0.
-precision $Eps Informs Minuit that the relative floating point
arithmetic precision is $Eps. The default value
of this option is 0.0 which means that the program
will use system default for doubles.
-minimizer $Min Sets the Minuit minimizer. $Min must be one of the
following keywords: "migrad", "simplex", or "mini".
Please see Minuit long writeup for the description
of these minimization methods. Default is "migrad"
which is usually the best method for smooth functions.
-minos $Use If $Use is "false", this option instructs the program
not to run MINOS after the minimizer. This may be
useful for saving time in case a large number of fits
is to be performed in the same job. The default is
"true" (run MINOS).
-strategy $Stra Sets the Minuit strategy to be used in calculating
first and second derivatives and in certain
minimization methods. Low values of $Stra mean fewer
function calls and high values mean more reliable
minimization. Currently allowed values are
0, 1 (default), and 2.
-verbose $Level Minuit verbose level:
-1 -- no output except from SHOW commands
0 -- minimum output (no starting values
or intermediate results)
1 -- Minuit "normal" output
2 -- print intermediate results
3 -- show the progress of minimization
The default value of this option is 0.
-timeout $sec Timeout in seconds for the Minuit main loop. 0 or
negative values mean no timeout will be set (this is
the default).
-parameters $P $P is the list of parameter definitions (can be
also supplied later through the fit handle). Each
element of this list is itself a five-element list
{name init_value step state bounds}.
name -- parameter name (a string)
init_value -- parameter initial value (a double)
step -- initial parameter step/uncertainty
(a positive double)
state -- one of two keywords: "variable" or
"fixed"
bounds -- either a list of doubles {min max}
which specify minimum and maximum
allowed parameter values, or an
empty list if the parameter is
unbounded.
$P may also be an empty list (this is the default)
in which case a set of parameters will be created
automatically as a union of all function parameters
(perhaps, the names will be different if not all
function parameter names are unique). To suppress
automatic creation of parameters, $P should be set
to "none".
-mapping $Maplist Specifies the mapping from the fit parameters into
the function parameters. $Maplist is either a special
keyword or a list of mappings for individual functions.
Two special keywords may be used in place of the
Maplist argument: "sequential" and "none". Sequential
mapping is the default -- it means that one-to-one
mapping of the fit parameters into the function
parameters will be established using parameter
positions in their respective lists. In this case the
number of fit parameters should be equal to the total
number of parameters in all functions used (this
condition will be satisfied automatically if the fit
parameters are autogenerated). The keyword "none"
may be used if you don't want to specify any parameter
mapping at this time -- the mapping will have to be
set up later using the fit handle.
When $Maplist is actually a list of individual
function mappings, each element in this list is itself
a two-element list {tag map}. The first element is
a tag of a fitting function. The second element is
either a string of pseudo-C code or a special keyword
which designates a precompiled mapping. In the
pseudo-C code the fit parameters should be designated
by name or by number and prefixed with the '%'
character. The function parameters are referred to
by names. Here is an example mapping:
{ double bin_width = 0.05;
area = %nevents * bin_width;
mean = %1;
sigma = sqrt(%variance); }
Besides the special designators for the fit
parameters (whose type should not be declared),
everything else should be normal C code which
can use all the functions provided in the
standard C headers. The character '%' itself
can be written as the "%%" sequence. The mapping
code will be compiled and loaded before the fit
is performed.
The following keywords may be used instead of a C code
map: "sequential", "identical", and "null". Sequential
mapping means that one-to-one mapping of the fit
parameters into the function parameters will be
established using parameter positions in their
respective lists. Identical mapping means that this
function will be given the full list of fit parameters,
and null mapping means that a null pointer will be
provided instead of an array of parameters (this can
only work for functions without any parameters).
If a mapping for some fitting function has not been
defined before the minimization step, the code will
attempt to use a default mapping. Null mapping is
the default for functions without any parameters,
and sequential mapping is the default for functions
with parameters.
The fit handle returned by this command is the main tool for modifying
fit properties, performing the actual fitting, and displaying results.
A description of the handle functionality is available in file hs_fit.txt
which can also be viewed online by executing the command hs::fit_manual.
Examples
--------
Suppose, we want to fit a histogram with id 5 using Gaussian probability
density, and this histogram has its own errors. Then the following code
may be used:
set myfit [hs::fit 5 gauss] ;# Create the fit handle using
;# the default fitting method "ls".
$myfit fit ;# Perform the fit.
$myfit show ;# Display the fit plot.
Suppose, an ntuple with id 6 has columns named X and Y. A two-dimensional
unbinned maximum likelihood fit of the data contained in these columns
with bivariate Gaussian distribution can be set up like this:
set nfit [hs::fit {6 -x X -y Y} bivar_gauss -method ml]
In the maximum likelihood method users are supposed to fix the function
normalization before the fit:
$nfit parameter volume configure -state fixed
$nfit fit
For more examples please read the file hs_fit.txt.
hs::fit_manual
Arguments : none
Returns : nothing
Prints a detailed description of the hs extension data fitting procedures
to the standard output.
hs::function $tag $option $arg ...
Arguments : strings tag and option, further arguments depend on
the option used
Returns : return type depends on the option used
Manipulates mathematical functions used for data fitting. The tag
argument specifies the identification string assigned to the given
function by the hs::function_import command. The following command
options are supported: "exists", "info", "configure", "cget", "copy",
"rename", "eval", "scan", "integrate", "invcdf", "random, "and "moments".
These options are used as follows:
* hs::function $tag exists
Returns 1 if $tag is a valid function identification string, 0 otherwise.
* hs::function $tag info
Returns info about the function specified by $tag in the form of
a list {dlltoken name description ndim composite mode refcount npars
npars_min npars_max parlist init_fun fit_fun grad_fun cleanup_fun}.
Most list elements have the same meaning as in the hs::function_import
command. The additional elements are:
composite Boolean element which is set true in case the function
is a composition of other functions (created by one of
the commands hs::function_sum, hs::function_divide,
hs::function_multiply, or hs::function_compose).
refcount Reference counter which shows how many fits are using
this function. The function "mode" parameter can only
be changed when the reference counter is 0, and the
function is not composite.
npars The current number of function parameters in case
npars_min != npars_max.
* hs::function $tag configure ?attr1? ?value1? ?attr2? ?value2? ...
Changes function attributes. The following attributes can be changed:
"name", "description", "mode", and "parameters". Optionally, attribute
names may be preceded by the "-" sign, like in Tk.
Example
-------
hs::function gauss configure -name "Gaussian pdf" \
-parameters {area mean sigma}
When invoked without any attribute values, the command returns the list
of all configurable function attributes with their current values.
* hs::function $tag cget $attr
Returns the value of the given attribute. The following attribute
names can be specified: "dll", "name", "description", "ndim",
"composite", "mode", "refcount", "npars", "npars_min", "npars_max",
"usedpars", "parameters", and "functions". Optionally, attribute names
may be preceded by the "-" sign, like in Tk. With the "usedpars"
attribute, the command returns the list of parameters currently used
by the function which may be different from the full list of parameter
names returned for the "parameters" attribute.
* hs::function $tag copy ?newtag?
Copies the fitting function. Optional newtag argument specifies
the identification string (tag) for the copy. In this form, the command
returns the tag of the copied function. Function copies are used
when the fit needs more than one function of the same type (for example,
two Gaussians with different means and/or standard deviations).
* hs::function $tag delete
Deletes the fitting function with the given tag. This operation will
succeed only if the function reference counter is 0.
* hs::function $tag rename $newtag
Changes the identification tag of the fitting function or deletes
it in case the newtag argument is an empty string. A function can
be renamed or deleted only when its reference counter is 0.
* hs::function $tag eval {name1 value1} ... {nameN valueN}
Evaluates the function identified by $tag at a point. The values
of all variables and parameters should be provided in the lists
of name-value pairs which follow the "eval" keyword.
Example
-------
hs::function gauss eval {x 0.5} {area 1} {mean 0} {sigma 1}
The parsing of the name-value pairs makes this form rather slow
for the purpose of multiple repetitive function evaluation. Consider
using the "scan" or "listeval" options when multiple evaluations are
necessary.
* hs::function $tag listeval {name1 {val1_0 val1_1 ...}} ... {nameN valN}
Similar to "eval" but the function is evaluated for a sequence of
values provided for the first parameter or variable. This sequence
can be either a list or a binary string of floats. The result is
returned in the same form: either a list or a binary string of
the same length and in the corresponding order.
Example
-------
hs::function gauss listeval {x {0.5 1.1}} {area 1} {mean 0} {sigma 1}
* hs::function $tag scan $result_specifier {name1 value1} ...
Evaluates the function identified by $tag at a set of points.
$result_specifier is a list whose first element is the Histo-Scope id.
This id may refer to a histogram or Ntuple, and tells the command where
to store the calculated function values. Subsequent elements of the list
specify the variables or parameters which should be scanned and, in case
of Ntuples, the scan ranges:
{id name} id refers to a 1d histogram
{id name1 name2} id refers to a 2d histogram
{id name1 name2 name3} id refers to a 3d histogram
{id {name1 min1 max1 npoints1}} id refers to an Ntuple, 1d scan
{id {name1 min1 max1 npoints1} {name2 min2 max2 npoints2}} 2d scan
{id {name1 min1 max1 npoints1} {name2 min2 max2 npoints2}\
{name3 min3 max3 npoints3}} 3d scan
The number of variables in the result ntuple must be equal to the
dimensionality of the scan plus one. The values of fixed parameters
and/or variables should be provided in the lists of name-value pairs
which follow the result specifier.
Examples
--------
set id1 [hs::create_2d_hist 1 "Gauss Scan" "Tmp" \
Mean Sigma Gauss(x=0) 50 50 -5 5 0.5 3]
hs::function gauss scan [list $id1 mean sigma] {x 0} {area 1}
hs::show_histogram $id1
set id2 [hs::create_ntuple 2 "Example Ntuple" "Tmp" {x Gauss(0,1)}]
hs::function gauss scan [list $id2 {x -5 5 1000}] \
{area 1} {mean 0} {sigma 1}
hs::overlay ov show add $id2 xy -x x -y Gauss(0,1) -color blue
* hs::function $tag integrate ... $range_specifier ... {name1 value1} ...
Performs numerical integration (1, 2, or 3d) of the function identified
by $tag. The integration ranges are specified by four-element lists
{varname min max n_intervals}. The values of fixed parameters and/or
variables should be provided in the lists of name-value pairs (the order
of name-value pairs and range specifiers is arbitrary). The command
returns the value of the integral.
Example
-------
hs::function gauss integrate {x -1 1 100} {area 1} {mean 0} {sigma 1}
* hs::function $tag moments ... $range_specifier ... {name1 value1} ...
Numerically evaluates statistical moments of the function identified
by $tag using the Simpson integration rule. The variable or parameter
range is specified by a four-element list {varname min max n_intervals}.
The values of fixed parameters and/or variables should be provided in
the lists of name-value pairs (the order of name-value pairs and
the range specifier is arbitrary). The function must not be negative
anywhere inside the integration range. The command returns five-element
list {area mean standard_deviation skewness kurtosis}.
Example
-------
hs::function gauss moments {x 0} {area 1} {mean -5 5 100} {sigma 1}
* hs::function $tag cdf {x1 x2 ...} ... $range_specifier ... \
{name1 value1} ...
Calculates cumulative distribution function values for coordinate
values x1, x2, etc. The returned values will be between 0 and 1.
The variable or parameter for which the cdf is evaluated is specified
by a four-element list {varname min max n_intervals}. The cdf is built
numerically in the specified range. On each of the intervals the
function is approximated by a second order polynomial. The values of
fixed parameters and/or variables should be provided in the lists of
name-value pairs (the order of name-value pairs and the range specifier
is arbitrary). The function must not be negative anywhere inside the
specified range. The command returns the list of cdf values which
correspond to given values of variable or parameter.
* hs::function $tag invcdf {cdf1 cdf2 ...} ... $range_specifier ... \
{name1 value1} ...
Calculates inverse cumulative distribution function values for cdf
values cdf1, cdf2, etc. Each cdf value must be between 0 and 1.
The variable or parameter for which the inverse cdf is evaluated
is specified by a four-element list {varname min max n_intervals}.
The inverse cdf is built numerically in the specified range. On each
of the intervals the function is approximated by a second order
polynomial. The values of fixed parameters and/or variables should be
provided in the lists of name-value pairs (the order of name-value
pairs and the range specifier is arbitrary). The function must not be
negative anywhere inside the specified range. The command returns
the list of variable or parameter values which correspond to given
cdf values.
* hs::function $tag invcdf_lin {cdf1 cdf2 ...} ... $range_specifier ... \
{name1 value1} ...
Same as "invcdf" option except that linear function approximation
is used on each interval instead of quadratic. This option works
better than "invcdf" for functions which have a very small magnitude
of the second derivative.
* hs::function $tag random $n ... $range_specifier ... {name1 value1} ...
Generates $n random numbers according to the given function. The variable
or parameter for which random numbers are generated is specified by
a four-element list {varname min max n_intervals}. The random numbers
are generated by numerically building inverse cumulative density function
in the specified range. On each of the intervals the function is
approximated by a second order polynomial. The values of fixed parameters
and/or variables should be provided in the lists of name-value pairs
(the order of name-value pairs and the range specifier is arbitrary).
The function must not be negative anywhere inside the integration range.
The command returns the list of generated random numbers.
Example
-------
The following code snippet will fill a 1d histogram with Histo-Scope id 1
with 10000 random numbers from the Cauchy distribution:
hs::fill_histogram 1 [hs::function cauchy random 10000 {x -5 5 200} \
{area 1} {peak 0} {hwhm 1}]
hs::function_browser option? arg? ...
Arguments : various options supplied as strings
Returns : string
This command creates a top level Tk widget which allows for convenient
browsing and shape exploration of one dimensional data fitting functions.
Possible options are -histo, -function, -plotpoints, -xmin, -xmax, -line,
-color, -fill, -fillcolor, -marker, and -markersize. The "-histo" option
is used with a boolean value which specifies whether function plots will
be drawn as histograms or as ntuple xy plots (the latter is the default,
it corresponds to option value "false"). The "-function" option can be
used to specify the identification tag of the initial function. This
must be one of the existing tags, present in the list returned by the
hs::function_list command. The "-plotpoints" option can be used to
specify the number of points to plot (may not be less than 2).
The meaning of the remaining options is the same as in the hs::overlay
command, please check its description for details.
When a function is chosen, a set of scales is added to the GUI, one for
each function parameter. Parameter values can be modified by moving
the sliders, by clicking inside the scale troughs, or by typing desired
values into the corresponding entries (hit "Enter" when done typing).
The range of a scale is expanded automatically if the number typed
into the corresponding entry is outside the scale limits. Use small
"[" and "]" buttons to reduce the scale ranges when necessary.
The "X min", "X max", and "Points" entries can be used to adjust
the axis range and the number of points used by the plots, either
before the plot is created (for histograms) or while the plot is
being displayed (for ntuple xy plots).
Since the information about valid parameter ranges is not available
for user functions, for every such function you'll need to adjust
the scale ranges first and then hit the "New plot" button in order to
view the curve.
The command returns the name of the new toplevel window.
hs::function_compile $tag $name $code $parlist ndim?
Arguments : strings tag, name, and code, list of strings parlist,
integer ndim
Returns : string
This command is useful for compiling simple mathematical expressions
for use in data fitting (complicated user functions are better handled
by the hs::function_template command). The arguments are as follows:
tag Unique function identification string which will be used
later by other commands related to data fitting functions.
name Arbitrary string which names the function.
code Pseudo-C code which must result in a double value.
As variables, it may only use "x", "y", "z", "mode", and
parameter names listed in $parlist. It may use functions
from the standard C headers.
parlist List of parameter names. All parameters of the same function
should have different names, and each parameter name must be
a valid C variable name (must contain only letters, digits,
and underscores, start with a letter or an underscore, and
must not coincide with a reserved C keyword).
ndim This optional argument may be used to override the heuristic
used to determine the dimensionality of the variable space.
For example, if $code looks like "x*y" then by default
the function will be defined in 2d space. To define "x*y"
function in 3d space, use ndim value of 3.
The command returns the tag of the new data fitting function (just $tag
if everything goes well).
Example
-------
hs::function_compile cos "Cosine Function" {A*cos(w*x+phase)} {A w phase}
hs::function_compose ?-result newtag? $tag1 $a $tag2 $b
Arguments : strings newtag, tag1 and tag2, doubles a and b
Returns : string
Defines a new data fitting function which is a composition of functions
f1 and f2 identified by strings $tag1 and $tag2, respectively.
The resulting function is f1($a * f2(...) + $b, ...), where the sum
$a * f2(...) + $b is used in place of the first f1 variable. When
the optional "-result" switch is used, the newtag argument specifies
the identification string (tag) for the resulting function. Without
the switch, the tag is generated automatically. The command returns
the tag of the composite function. Name, description, and the parameter
names of the resulting function are assigned automatically, and can
later be changed using "configure" option of the hs::function command.
The parameter names will be set to "Pn" where n varies from 0 to
the total number of parameters minus one. P0 corresponds to the first
parameter of the f1 function.
hs::function_divide ?-result newtag? $c $tag1 $tag2
Arguments : strings newtag, tag1 and tag2, double c
Returns : string
Defines a new data fitting function which is a ratio of the fitting
functions identified by strings $tag1 and $tag2 multiplied by
the constant value $c. When the optional "-result" switch is used,
the newtag argument specifies the identification string (tag) for
the resulting function. Without the switch, the tag is generated
automatically. The command returns the tag of the composite function.
Name, description, and the parameter names of the resulting function
are assigned automatically, and can later be changed using "configure"
option of the hs::function command. The parameter names will be set
to "Pn" where n varies from 0 to the total number of parameters minus
one. P0 corresponds to the first parameter of the function identified
by $tag1.
hs::function_import $tag $dlltoken $name $description $ndim $default_mode \
$npars_min $npars_max $parlist $init_fun $fit_fun \
$grad_fun $cleanup_fun
Arguments : strings tag, name, description, init_fun, fit_fun, grad_fun,
and cleanup_fun, list of strings parlist, integers dlltoken,
ndim, default_mode, npars_min, and npars_max.
Returns : string
This command sets up mathematical functions used for data fitting.
Each fitting function is actually a collection of up to four C or FORTRAN
functions in which specific functions can be used for initialization,
cleanup, actual function evaluation, and precise calculation of
the function gradient over parameters. The arguments are as follows:
tag Unique function identification string which will be used
later by other commands related to data fitting functions
(for example, hs::function).
dlltoken Shared library token which must be obtained earlier
with the hs::sharedlib command.
name Arbitrary strings which are supposed to provide basic
description information about the function.
ndim Specifies the number of function variables (1, 2, or 3).
default_mode Each data fitting function has a special integer parameter
(called "mode") which can be inspected and modified from
tcl but isn't changed during the fitting process. This
parameter can be optionally used to alter the function
behavior, for example, change degree of a polynomial,
provide an index into some array of data structures known
to the function, etc. The default_mode argument specifies
the initial value of this parameter.
npars_min Minimum allowed number of function parameters.
npars_max Maximum allowed number of function parameters. When
npars_min != npars_max (like in the polynomial function),
it is assumed that the number of parameters is given
by function mode.
parlist List of parameter names. Must have npars_max names. If
the number of names in the list is less than npars_max,
the missing parameter names will be set to "Pn" where
n is a number from 0 to npars_max-1. All parameters
of the same function should have different names, and
each parameter name must be a valid C variable name
(contain only letters, digits, and underscores, and start
with a letter or an underscore).
init_fun The C or FORTRAN name of the function which will be
called once when the function is first used for data
fitting. The compiled code of the function is supposed
to reside in the shared library specified by the dlltoken
argument. The C prototype of this function looks like this:
int cfun(const int *pmode);
pmode is a pointer to an integer parameter which will
not be modified during the fitting process. The *pmode
value can be used to modify the function behavior
as necessary. The corresponding FORTRAN function looks
like this:
integer function ffun(mode)
integer mode
The initialization function should return 0 when everything
is OK. The init_fun argument can be an empty string which
indicates that no special initialization is needed.
fit_fun The C or FORTRAN name of the function which will be
evaluated for each data point during fitting. The C
function names should not end with an underscore, otherwise
they may be confused with FORTRAN names. The C function
prototype looks like this:
double cfun(double x, double y, double z, int mode,
const double *pars, int *ierr);
and the FORTRAN implementation should look like this:
double precision function ffun(x, y, z, mode, pars, ierr)
double precision x, y, z, pars(*)
integer mode, ierr
In both cases, x is the first function variable, y is
the second variable (may be ignored by the function if
the function is one-dimensional), z is the third variable
(may be ignored), mode is the operation mode parameter
(may be ignored), pars is the array of parameters, and
ierr is the error status (should be set to 0 on exit
if everything is OK). The length of the pars array will
be equal npars_min in case npars_min == npars_max or
to the value of mode in case npars_min != npars_max.
grad_fun The C or FORTRAN name of the function which calculates
the gradient of the fitting function over parameters.
The explicit gradient calculation is not necessary but
may be used to speed up the fitting. The C function
prototype looks like this:
int cfun(double x, double y, double z, int mode,
const double *pars, double *grad);
where x, y, z, mode, and pars arguments have the same
meanings as in the fitting functions, and grad is a pointer
into an array which on exit should be filled by the values
of partial derivatives over corresponding parameters. The
function should return 0 when everything is OK. The FORTRAN
function looks like this:
integer function ffun(x, y, z, mode, pars, grad)
double precision x, y, z, pars(*), grad(*)
integer mode
The grad_fun argument may be specified as an empty string
in which case the gradient will be evaluated internally
using the fitting function itself.
cleanup_fun The C or FORTRAN name of the function which will be
called once when the fitting function no longer used
in any fits. The function prototype is the same as
for init_fun. This argument can be an empty string
when no special cleanup is needed.
This command returns the function tag in case all the relevant code
has been successfully located in the shared library, or throws a tcl
error in case of a problem.
hs::function_list pattern?
Arguments : string pattern
Returns : list of strings
Returns the list of identification strings (tags) for currently defined
data fitting functions. If optional argument "pattern" is specified then
only tags matching the pattern are returned. The match is established
using the same rules as for the tcl command "string match".
hs::function_multiply ?-result newtag? $c $tag1 $tag2
Arguments : strings newtag, tag1 and tag2, double c
Returns : string
Defines a new data fitting function which is a product of the fitting
functions identified by strings $tag1 and $tag2 multiplied by
the constant value $c. When the optional "-result" switch is used,
the newtag argument specifies the identification string (tag) for
the resulting function. Without the switch, the tag is generated
automatically. The command returns the tag of the composite function.
Name, description, and the parameter names of the resulting function
are assigned automatically, and can later be changed using "configure"
option of the hs::function command. The parameter names will be set
to "Pn" where n varies from 0 to the total number of parameters minus
one. P0 corresponds to the first parameter of the function identified
by $tag1.
hs::function_plot $tag $varname $min $max option? arg? ... {name1 value1} ...
Arguments : strings tag and varname, doubles min and max, string name1,
double value1, various options are supplied as strings
Returns : string or nothing
This command can be used to draw data fitting functions. $tag must be
a valid function identification string (as in the hs::function_import
command). $varname is the name of a function variable or parameter.
$min and $max define the limits of the parameter range. The values
of fixed parameters and variables must be defined using two-element
lists of name-value pairs as in {name1 value1}. This command accepts
the same options as the hs::expr_plot command. Please check the
hs::expr_plot description for details. The return value of this command
is an empty string if it is called with the "-id" option; in all other
cases it returns the name of the overlayed plot used to draw the curve.
Example
-------
hs::function_plot gauss x -3 3 {area 1} {mean 1} {sigma 1} -color blue
hs::function_sum ?-result newtag? $c1 $tag1 $c2 $tag2
Arguments : strings newtag, tag1 and tag2, doubles c1 and c2
Returns : string
Defines a new data fitting function which is a sum of the fitting
functions identified by strings $tag1 and $tag2 with weights $c1 and
$c2. When the optional "-result" switch is used, the newtag argument
specifies the identification string (tag) for the resulting function.
Without the switch, the tag is generated automatically. The command
returns the tag of the composite function. Name, description, and
the parameter names of the resulting function are assigned automatically,
and can later be changed using "configure" option of the hs::function
command. The parameter names will be set to "Pn" where n varies
from 0 to the total number of parameters minus one. P0 corresponds
to the first parameter of the function identified by $tag1.
hs::function_template $filename option? arg? ...
Arguments : string filename, various options are supplied as strings
Returns : nothing
Generates a template file named $filename for a user-developed data
fitting function. Note that the file will be overwritten if it already
exists. The template code can then be edited, compiled, dynamically
loaded into the running program, and the function can be added to
the set of standard fitting functions. The following command line
options are supported:
-lang $L Specifies the programming language. "C" stands for C,
"f" or "fortran" stands for FORTRAN (capitalization is
ignored). By default, the programming language is
figured out automatically from the file extension:
FORTRAN will be used with extensions .f, .for, .FOR,
.F, .fpp, .FPP, and C will be used in all other cases.
-init $Iname Specifies the name of the initialization function.
Default value of this option is an empty string
(no initialization needed).
-fname $Fname Specifies the name of the data fitting function.
Default value of this option is "myfit". Note that
functions may not be named as standard C keywords.
-grad $Gname Specifies the name of the gradient function. Default
value of this option is an empty string (do not perform
explicit gradient calculation).
-cleanup $Cname Specifies the name of the cleanup function. Default
value of this option is an empty string (no cleanup
needed).
Instead of the normal "histoscope.h" file, the C templates include
the file "histoscope_stub.h". This file declares the "stub" API to
Histo-Scope. When a shared object is loaded, the calls to the original
statically compiled Histo-Scope functions may or may not be resolved,
depending on the system implementation. The "stub" API functions are
resolved on all UNIX platforms. This portability, however, is achieved
by using an additional level of indirection per function call. If your
code has to be very efficient and you do not care about portability,
you can try to include "histoscope.h" instead of "histoscope_stub.h".
This works, for example, on Linux (but fails on IRIX).
hs::gauss_random $mean $stdev num_points?
Arguments : doubles mean and stdev, integer num_points
Returns : double or list of doubles
Generates random numbers according to the Gaussian distribution with
given mean and standard deviation. If optional argument num_points is
specified then this procedure returns a list of $num_points random
numbers, otherwise just one number is returned.
This command is available only if the extension has been compiled
with CERNLIB.
hs::generate_ps $window_name $filename sync?
Arguments : strings window_name and filename, boolean sync
Returns : nothing
This command makes a PostScript file for a Histo-Scope window with
the given name. The window with this name must be created in advance by
one of the commands hs::show_histogram, hs::overlay, hs::multiplot, etc.
The file with given name will be overwritten if it already exists.
To avoid confusions, this command works only when there is just a single
Histo-Scope connected to the process. By default, the file is generated
by Histo-Scope asynchronously with the running script, and this command
returns immediately (a warning message is later printed to stderr
in case of subsequent failure). This behavior may be changed by setting
the optional boolean argument "sync" to 1. In this case the command
will not return before the file is actually created and will generate
a tcl error on failure.
Note that a histogram (or an ntuple) displayed on the window should have
at least one data entry, otherwise the Histo-Scope GUI will wait forever
until the data arrives.
hs::globcc $matrix $i n_events?
Arguments : list of lists of doubles matrix, integers i and n_events
Returns : either a double or a two-element list of doubles
Calculates global correlation coefficient (also known as "coefficient
of determination" or R-squared) for the $i th column of a symmetric
positive definite matrix $matrix (presumably, this is a covariance
matrix produced by hs::ntuple_c_covar or another similar method). This
coefficient corresponds to the strongest correlation between variable
number $i and a linear combination of all other variables. When optional
argument n_events is provided, the command also calculates the adjusted
global correlation coefficient which takes into account the number of
degrees of freedom in the problem. In this case, both standard and
adjusted coefficients are returned in a two-element list of doubles.
The adjusted coefficient is an approximate quantity, and may be 0 even if
the $i th variable is not completely uncorrelated with other variables.
The adjusted coefficient can be used to judge whether an addition of
a new variable results in a better prediction for a response variable
in a linear regression procedure (the standard coefficient can never
decrease when a new variable is added).
This command is only available if the extension has been compiled with
CERNLIB.
hs::have_cernlib
Arguments : none
Returns : boolean
Returns 1 or 0 if the tcl API was compiled with or without CERNLIB.
Several API functions use CERNLIB in their implementation. These
functions will not be available if the API was compiled without
CERNLIB support.
hs::help $name
Arguments : string name (or none)
Returns : nothing
Prints a help message about the Histo-Scope tcl API command which matches
string $name. Matching is determined using the same rules as for the tcl
command "string match". If there is more than one match then the command
prints a message that the string is ambiguous and shows all matches.
The command interprets the following characters in a special way:
* Matches any sequence of characters in $name, including
a null string.
? Matches any single character in $name.
[chars] Matches any character in the set given by chars. If a sequence
of the form x-y appears in chars then any character between
x and y, inclusive, will match.
\x Matches the single character x. This provides a way of
avoiding the special interpretation of the characters *?[]\
An introductory help message is printed if the argument is not specified.
hs::hist_bin_width $id
Arguments : integer id
Returns : double
Returns bin width (1d case), area (2d case), or volume (3d case) for
the histogram with given id.
hs::hist_error_status $id
Arguments : integer id
Returns : integer
Returns the information about the presence of error data for a histogram
with Histo-Scope id $id. The command returns one of the following codes:
-1 Means that the item with id $id doesn't exist or not a histogram.
0 No errors defined for this histogram.
1 This histogram has positive errors only.
2 This histogram has both positive and negative errors.
hs::hist_function_chisq $id $tag $scan_variables {name1 value1} ...
Arguments : integer id, string tag, list of strings scan_variables,
mixed lists {name1 value1} ...
Returns : three-element mixed list {cl chisquare ndof}
Performs a chi-square test of the histogram with id $id against
the function specified by $tag. See the description of hs::function
command for a detailed description of the tag argument. The histogram
must have errors defined. Negative errors are meaningful. If defined,
negative errors are used in case the histogram bin value is higher
than the function value calculated at the coordinates of this bin.
"scan_variables" is the list of function variables and/or parameters
which will be varied when histogram bin coordinates are scanned.
The size of this list must be equal to the histogram dimensionality.
The first element corresponds to the histogram x axis, the second
(if provided) to the y axis, etc. Pairs {name1 value1} ... should
provide values of all function variables and/or parameters which stay
constant during the scan.
This command returns the triple {cl chisquare ndof} which contains
the calculated test confidence level, chi-square value, and the number
of degrees of freedom. Only bins whose errors are larger than zero
are used in the test and counted as degrees of freedom.
When testing results of a probaility density fit, please use the
chi-square test built into the fitter rather than this command.
The fitter uses a better method for calculating function area for
each histogram bin.
Example
-------
Suppose, we have a 1d histogram with Histo-Scope id 1 and want to test
its contents against the linear function y = 3*x + 2. The following
command will perform the chi-square test:
hs::hist_function_chisq 1 linear_1d {x} {a 3} {b 2}
hs::hist_integral $id
Arguments : integer id
Returns : double
Calculates the integral (the sum of the bin contents * bin width) of the
bin data in a histogram. Overflow data is not counted.
hs::hist_l1_norm $id
Arguments : integer id
Returns : double
Calculates the L1 norm (the sum of absolute bin values * bin width)
of the bin data in a histogram. Overflow data is not counted.
hs::hist_l2_norm $id
Arguments : integer id
Returns : double
Calculates the L2 norm (the sum of squared bin values * bin width)
of the bin data in a histogram. Overflow data is not counted.
hs::hist_num_bins $id
Arguments : integer id
Returns : integer
Returns the total number of bins in the histogram with given id.
hs::hist_random $id $num_points
Arguments : integers id and num_points
Returns : list of doubles
Generates random points according to the given histogram. Returns
a flat list of doubles. Number of elements in the list will be equal
$num_points times histogram dimensionality. For example, for a 3-d
histogram the elements of the list will be {x0 y0 z0 x1 y1 z1 ...}.
This command is only available if the extension has been compiled with
CERNLIB.
hs::hist_scale_data $id $scale
Arguments : integer id, double scale
Returns : nothing
Scales the data of a histogram with given id by $scale. The scale factor
must not be zero. The errors are not changed. See also the descriptions
of hs::copy_data, hs::hist_scale_errors.
hs::hist_scale_errors $id $scale
Arguments : integer id, double scale
Returns : nothing
Scales the errors of a histogram with given id by $scale. The histogram
must have errors defined, and the scale factor must be positive.
hs::hist_set_error_range $id $min $max
Arguments : integer id, doubles min and max
Returns : nothing
Trims positive errors of the histogram with Histo-Scope id $id. After
this operation the smallest error will be equal $min and the largest
will be equal $max. All errors are set to $min if the errors were
undefined. $min must not be negative, and must not exceed $max. $max
may be specified as an empty string in which case the errors will not
be trimmed from above.
hs::hist_set_gauss_errors $id
Arguments : integer id
Returns : nothing
Calculate and store Gaussian errors in a histogram. Any positive and
negative errors stored previously will be disregarded. The new errors
will be stored in the "positive" error array. The errors are computed
assuming the central limit theorem: they are equal to the square root
of the bin contents. If one or more bin value is negative, no errors
are created or changed, and an error message is printed. If the item
referred by id is not a histogram, no action is taken besides printing
an error message.
hs::hist_set_slice $id $bin0 $stride $data
Arguments : integers id, bin0, and stride, binary string or list of
doubles data
Returns : nothing
Replaces some or all bin values in a histogram identified by id with
provided data. Histogram contents are treated as a linear sequence of
bins. In this sequence, the bin number along the Z axis changes most
frequently (Z axis corresponds to the last C array index), and the bin
number along the X axis is the slowest to change. $bin0 specifies the
number of the first replaced bin in the sequence. If $bin0 is less than
0 or larger than the number of the last bin in the sequence then the
command has no effect. $stride sets the distance between replaced bins
(may be negative).
hs::hist_set_slice_errors $id $bin0 $stride $positive_errors negative_errors?
Arguments : integers id, bin0, and stride, binary strings or lists of
doubles positive_errors and negative_errors
Returns : nothing
Replaces some or all error values in a histogram identified by id with
provided errors. Histogram contents are treated as a linear sequence of
bins. In this sequence, the bin number along the Z axis changes most
frequently (Z axis corresponds to the last C array index), and the bin
number along the X axis is the slowest to change. $bin0 specifies the
number of the first bin in the sequence whose errors are replaced.
If $bin0 is less than 0 or larger than the number of the last bin in
the sequence then the command has no effect. $stride sets the distance
between replaced bins (may be negative). If the negative_errors argument
is omitted or specified as an empty string then negative errors are not
changed. positive_errors argument may be specified as an empty string
in order to modify just the negative errors.
hs::histo_with_config $return_immediately $config_file
Arguments : boolean return_immediately, string config_file
Returns : nothing
For users who want to build Histo-Scope into their program and have it
automatically display plots. hs::histo_with_config invokes Histo-Scope
as a sub-process and displays the plots specified in the configuration
file config_file. The scope process is pre-connected to display the
data generated in the user process. The routine can either start the
Histo-Scope and return immediately if $return_immediately is true,
or it can start it and return after the user closes the Histo-Scope
window if $return_immediately is false.
hs::histoscope $return_immediately
Arguments : boolean return_immediately
Returns : nothing
For users who want to build Histo-Scope into their program rather
than using it separately as an inspection tool. hs::histoscope invokes
Histo-Scope as a sub-process. The scope process is pre-connected
to display the data generated in the user process. The routine
can either start the Histo-Scope and return immediately in case
$return_immediately is true, or it can start it and return after
the user closes the Histo-Scope window if $return_immediately is false.
hs::histoscope_hidden
Arguments : none
Returns : nothing
For users who want to build Histo-Scope into their program rather than
using it separately as an inspection tool. hs::histoscope_hidden invokes
Histo-Scope as a sub-process. The scope process is pre-connected to
display the data generated in the user process. The Histo-Scope GUI
interface does not appear on the display. All configuration operations
must be performed by hs::load_config_string, hs::load_config_file,
hs::overlay, or other similar commands.
hs::hs_update
Arguments : none
Returns : nothing
This routine must be called periodically to keep the Histo-Scope
display up to date and to accept connections from Histo-Scopes. You may
call this as often as you like with no adverse impact on CPU usage. It
will only transmit the data for the items that are currently displayed,
and only as frequently as requested by the user of the Histo-Scope
process, even if you call hs::hs_update very often. See also the
description of hs::periodic_update.
hs::html_manual $filename
Arguments : string filename
Returns : nothing
Generates hs extension manual using HTML format and saves it in file
named $filename. Warning: if a file with this name already exists,
it will be overwritten.
hs::id $uid $category
Arguments : integer uid, string category
Returns : integer
Returns the Histo-Scope id for a specified uid and category pair, or -1
if a match was not found. uid is the user-specified identification
number which was specified when the item was created. category is a
string defining a hierarchical "location" for the indicator also
specified when the item was created. The Histo-Scope defined id is
returned.
hs::id_from_title $title $category
Arguments : strings title and category
Returns : integer
Returns the Histo-Scope id for a specified item title and category
pair, or -1 if a match was not found. title is the title specified for
the item when it was created. category is the string specified at item
creation defining a hierarchical "location" for the item.
hs::import_ntuple_data $filename $id strict_columns?
Arguments : string filename, integer id, boolean strict_columns
Returns : integer
Reads columns of floating point numbers from a text file with given name
into an ntuple with given id. Empty lines and lines which start with "#"
(perhaps, preceded by white space) are ignored. If the "strict_columns"
argument is set to 1 or omitted then the number of columns in the file
must coincide with the number of variables in the ntuple. If the
"strict_columns" argument is set to 0 then the number of columns in
the input file can be arbitrary, and not necessarily the same from one
line to another. If a line has more columns than the number of ntuple
variables then columns at the end of the line will be ignored. If the
number of columns in a line is smaller than the number of ntuple
variables then missing values will be filled with zeros.
This command returns the number of rows added to the ntuple.
hs::initialize $identity_string
Arguments : string identity_string
Returns : nothing
Initialize the Histo-Scope connection software and set up a potential
connection to a Histo-Scope process. The identity string identifies the
process in the Histo-Scope connection panel and may be up to 40
characters long. This routine should be called before any other
Histo-Scope routine.
hs::item_info $idlist
Arguments : list of integers idlist
Returns : nothing
Prints type, user id, category, and title for the items whose Histo-Scope
ids are in the list $idlist. If the idlist argument is omitted then the
information is printed for all Histo-Scope items.
hs::item_properties $id
Arguments : integer id
Returns : mixed list
Returns user id, category, title, and type for a Histo-Scope item with
given id in a four-element list {uid category title type}. If the item
with given id doesn't exist then the type will be set to "HS_NONE" and
all other elements will be empty strings.
hs::join_entries $uid $title $category $id1 $id2 $keys $vlist1 $vlist2
Arguments : integers uid, id1, and id2, strings title and category,
lists of strings keys, vlist1, and vlist2
Returns : integer
Creates a new ntuple by joining the data of two existing Ntuples
in a special way (similar to SQL inner joins). Arguments uid, title,
and category define user id, title, and a hierarchical "location" for
the new ntuple. $id1 and $id2 specify the ids of existing ntuples
to join. $keys is the list of names which define ntuple columns whose
data must match during the join. This list must have an even number
of items. Each sequential pair of elements is treated as the names
of matching columns in the first and the second ntuple. For the second
ntuple, the set of values in the key columns must be unique for every
ntuple row. $vlist1 specifies the mapping of columns from the first
ntuple into the columns of the new ntuple, and $vlist2 specifies the
mapping of columns from the second ntuple into the columns of the new
ntuple.
Example
-------
Suppose, we have an ntuple with id 1 and variables {run1 event ntracks}
and an ntuple with id 2 and variables {run2 event trigger energy}.
Suppose also that in each row of the ntuple with id 2 the pair of data
values {run2 event} is unique. Then we can create an ntuple with
variables {run evt ntrk trig enrg} as follows:
hs::join_entries 10 "Join Example" "Tmp" 1 2 {run1 run2 event event} \
{run1 run event evt ntracks ntrk} {trigger trig energy enrg}
The new ntuple will have entries for those values of {run1 event} which
are present in both ntuples. The {run evt} values will not necessarily
be unique in the new ntuple if the {run1 event} values were not unique
in the ntuple with id 1.
hs::kernel_density_1d $ntuple_id $variable $bandwidth $result_id \
xmin? xmax? npoints? option? value1? ...
Arguments : integers ntuple_id, result_id, and npoints, string variable,
doubles bandwidth, xmin, and xmax, various options are
supplied as strings
Returns : nothing
This command creates a one-dimensional kernel probability density
estimate for a set of points from ntuple with id $ntuple_id. $variable
is the name of the ntuple variable whose density is to be estimated.
$bandwidth is the global bandwidth to use. $result_id is the id of
an existing 1d histogram or a two-variable ntuple used to store the
density estimate. If $result_id refers to an ntuple then arguments
xmin, xmax, and npoints must specify the interval and the number of
equidistant points in the estimate.
This command supports the following options:
-kernel $K $K is the name of the kernel function to use. Valid
names are "gaussian", "uniform", "epanechnikov",
"biweight", "triweight", and "quadweight". The default
kernel is "gaussian". All kernels are normalized so that
their area is 1 and their interquartile range is equal
to that of the Gaussian kernel.
-weight $W $W is the name of the variable in the ntuple with id
$ntuple_id which will be used as a data point weight.
If this option is not specified, all weights are taken
to be 1.
-localbw $Lb $Lb is the name of the variable in the ntuple with id
$ntuple_id which will be used a local kernel bandwidth
multiplier. The bandwidth for each data point is the
product of this multiplier and the global bandwidth.
hs::kernel_density_2d $ntuple_id $x_variable $y_variable $bandwidth_matrix \
$result_id xmin? xmax? nxpoints? ymin? ymax? nypoints? \
option? value1? ...
Arguments : integers ntuple_id, result_id, nxpoints, and nypoints,
strings x_variable and y_variable, doubles xmin, xmax, ymin,
and ymax, list of lists of doubles bandwidth_matrix,
various options are supplied as strings
Returns : nothing
This command creates a two-dimensional kernel probability density
estimate for a set of points from ntuple with id $ntuple_id. $x_variable
and $y_variable are the names of the ntuple variables respectively used
as the data point x and y coordinates. $bandwidth_matrix specifies
the global bandwidth matrix to use (please see the "-transform" option
description for full explanation). $result_id is the id of an existing
2d histogram or a three-variable ntuple used to store the density
estimate. If $result_id refers to an ntuple then arguments xmin, xmax,
nxpoints, ymin, ymax, and nypoints must be provided. These arguments
specify the grid of points for which the density is estimated.
This command supports the following options:
-kernel $K $K is the name of the kernel function to use. Valid
names are "gaussian", "uniform", "epanechnikov",
"biweight", "triweight", and "quadweight". The default
kernel is "gaussian". All kernels are normalized so that
their volume is 1 and the radius of the sphere which
includes 1/2 of the volume is equal to that of the
Gaussian kernel.
-weight $W $W is the name of the variable in the ntuple with id
$ntuple_id which will be used as the data point weight.
If this option is not specified, all weights are taken
to be 1.
-transform $T $T is a boolean value which may be used to modify the
meaning of the bandwidth_matrix argument. By default,
bandwidth matrix, B, is treated as the measurement
covariance matrix (inverse metric). In this case the
bilinear form used to calculate the distance between
the points looks like this: r^2 = x_t*B^(-1)*x. If $T
is set to 1 then the bandwidth matrix is treated instead
as the coordinate transformation matrix: r^2 = y_t*y,
y = B*x.
-sxsq $SXX These options can be used to specify the names of the
-sysq $SYY variables in the ntuple with id $ntuple_id to be used
-sxsy $SXY as the local estimate of the bandwidth covariance
matrix, S (usually, this covariance matrix is determined
by the precision of the measurement). When these options
are specified, the distances between the points are
calculated as follows: r^2 = x_t*A_t*S^(-1)*A*x.
When $T == 0 (default), A is the inverse square root
of the global bandwidth matrix: A_t*A*B = I, A_t = A
(B must be symmetric in this case). When $T == 1, A = B.
Option -sxsy may be omitted in which case $SXY is
assumed to be 0 for every point (this means that
the measurement errors are uncorrelated).
hs::kill_histoscope
Arguments : none
Returns : nothing
This routine allows you to "kill" any Histo-Scope processes started
via the hs::histoscope or hs::histo_with_config calls. The "kill" is
accomplished through a message request to the Histo-Scope process
for it to exit.
hs::latex $latext $position option? value? ..
Arguments : string latext, mixed list position, various options are
supplied as strings
Returns : nothing
This command can be used to draw simple latex expressions on top of
Histo-Scope plots. $latext specifies the text to draw in LaTeX notation.
The "position" argument specifies the location of the text inside the
plot window. $position must be either a two- or a six-element list,
same format as in the specifications of object points in the hs::draw
command. Please see the hs::draw description for details about the format
and the coordinate systems.
The following options may be specified in addition to the required
arguments: -bordercolor, -scale, -bg, -background, -row, -column, -ipadx,
-ipady, -refpoint, -coord, -coords, -origin, -border, -anchor, -window,
-immediate, -complete, -rotate, -packages, and -interact. All options
except the last four have the same meaning as in the hs::epsf command.
Please see the hs::epsf description for more details. The last four
options have the following meaning:
-complete $B This boolean option specifies whether the latex
expression should be treated as a complete document.
By default $B is "false", and the "hs" extension
generates the necessary \documentclass,
\begin{document}, \end{document}, etc., declarations
for you. You can write your own document header and
footer instead, and then set the -complete option to
"true" so that nothing is added to your latex code.
Make sure though that your latex generates not more
than one page (the result must be EPS-compatible).
-rotate $dir This option allows to perform basic rotation of
LaTeX output. Possible option values are integers
divisible by 90 (rotation angles) or keywords "none",
"left", "right", and "around". Default is "none".
-packages $Plist Specifies the list of additional packages used by
LaTeX to process your input. These packages will
be used together with those returned by the
hs::default_latex_packages command. This option
is ignored when the value of "-complete" oprion
is "true".
-interact $I Specifies LaTeX interactive level. Possible values
are "batch", "nonstop", and "errorstop". Default
is "batch".
This command uses "latex", "dvips", and "gs" executables, and it only
works if the Histo-Scope GUI runs on the same computer as the tcl shell.
Example
-------
Show histogram with Histo-Scope id 1 and draw a latex label in the middle
of the window:
hs::show_histogram 1 -window w
hs::latex -window w -ipadx {3 3} -ipady {3 3} -anchor c -scale 2 {
$$ \textcolor{red}{F(s) = \int_{0}^{\infty} f(t) e^{-st} dt} $$
} {0.5 0.5}
hs::list_items $title $category $match_flag
Arguments : strings title and category, integer match_flag
Returns : list of integers
Fills a list of Histo-Scope id numbers. These ids are returned in the
order in which the histograms were created, or read in from a file.
Title specifies the title of the data item(s) to list.
category is a string defining a hierarchical "location" for the
indicator. Optionally, the category can include a trailing "..." which
will return the id numbers for items in subcategories of the specified
category. For example, "HS/..." matches "HS" and "HS/Nts" but not
"HSNTuples", "HSNTuples" nor "hs". If the category parameter is
specified as "..." all categories will match including uncategorized
items. match_flag specifies exact or inexact matches for the title
string specified. If {$match_flag == 0} then all id's returned will
exactly match the title specified. If {$match_flag != 0} then leading
spaces are ignored and id's containing the specified title are
returned. Specifying "" for title and an inexact match for match_flag
will match all titles. Specifying "" for category will match
uncategorized items.
hs::list_plot $value_list option? arg? ...
Arguments : list of doubles value_list, various options are supplied
as strings
Returns : string or nothing
This command is used to plot a set of points. $value_list is a list
of doubles containing pairs of elements. The first element in each pair
defines the x coordinate of a point, and the second defines the y
coordinate. This command accepts the same options as the hs::expr_plot
command. Please check the hs::expr_plot description for details.
The return value of this command is an empty string if it is called with
the "-id" option; in all other cases it returns the name of the overlayed
plot used to draw the set of points.
Example
-------
hs::list_plot {0 0 1 0 1.5 1 1 2 0 2 -0.5 1 0.5 1} \
-line 0 -color blue -marker solidcircle -markersize large
hs::list_to_data $numlist
Arguments : list of tcl numbers numlist (integers or doubles or mixed)
Returns : binary string
Converts a tcl list into a binary string of floats.
hs::load_config_file $config_file
Arguments : string config_file
Returns : nothing
Calling hs::load_config_file causes all connected Histo-Scopes to read
the configuration file specified by config_file and execute all of the
commands to display plots in the file.
hs::load_config_string $config_string
Arguments : string config_string
Returns : nothing
Calling hs::load_config_string causes all connected Histo-Scopes to
execute all of the commands to display plots in the string specified by
config_string.
hs::lookup_title ?-nocase? $pattern $category
Arguments : strings pattern and category
Returns : list of integers
Returns a list of Histo-Scope items whose titles match string $pattern.
Matching is determined using the same rules as for the tcl command
"string match". The command interprets the following characters in
a special way:
* Matches any sequence of characters in the title, including
a null string.
? Matches any single character.
[chars] Matches any character in the set given by chars. If a sequence
of the form x-y appears in chars then any character between
x and y, inclusive, will match.
\x Matches the single character x. This provides a way of
avoiding the special interpretation of the characters *?[]\
If the "-nocase" option is specified then the pattern is matched against
the titles in a case-insensitive manner. The category argument may be
omitted in which case all categories will be searched. Optionally, the
category can include a trailing "/..." which will return the id numbers
for matching items in the specified category and all its subcategories.
hs::merge_entries $uid $title $category $id1 $id2
Arguments : integers uid, id1, and id2, strings title and category
Returns : integer
Creates a new Ntuple consisting of two existing Ntuples, specified by
$id1 and $id2. These two Ntuples must have an identical number of
variables. $uid is the User Identification number for the newly created
Ntuple. $title defines the title for the new Ntuple. $category is
a string defining a hierarchical "location" for the Ntuple. Returns
the Histo-Scope id of the newly created Ntuple, or throws tcl error
if the Ntuples referred by $id1 or $id2 don't exist or have different
numbers of variables. The variable names are taken from $id1, and are
assumed to be identical to those of $id2.
hs::multinomial_random $sum $problist
Arguments : integer sum, list of doubles problist
Returns : list of integers
Generates random numbers according to the multinomial distribution.
The problist argument defines all multinomial probabilities except
one (the last probability is calculated from the condition that
probabilities should sum up to 1). The number of elements in the
returned result list will be larger by one than the number of elements
in $problist, and the sum of result elements will be equal to $sum.
This command is available only if the extension has been compiled
with CERNLIB.
hs::multiplot $name option? arg? ...
Arguments : string name, various options are supplied as strings
Returns : string or nothing
This command creates a configuration string requesting connected
Histo-Scopes to draw several plots side by side in a multiple-plot
window. The whole string does not have to be created in a single
execution of the command, thus permitting incremental construction
of multiplots. $name is an arbitrary string used to identify the
multiplot. The following command line options are allowed:
-title $Title Specifies window title. If this option is not
present, the window title will be "Untitled".
Use a string which starts with double forward
slash if you intend to suppress the title in
the window PostScript output.
-window $Win Specifies the window name for subsequent use with
commands hs::comment, hs::generate_ps, etc.
-geometry $G Specifies window geometry using the standard
X11 geometry specification string, for example
600x500+100+50. If this option is omitted then
multiplot cells will be drawn using 4x3 aspect
ratio and the window size will be the largest
rectangle which fits into 800x600 pixels.
-legend $OnOff This boolean option can be used to override the
legend behavior of individual overlays in the
multiplot. Specify $OnOff as an empty string
(this is the default) if you would like to set
the legend behavior for each overlay separately.
-font $F Specifies font to use for axis labels. This
option overrides fonts defined for individual
overlays. $F may be given in any form acceptable
by Tk, for example "Times 18 {bold italic}".
X font names may also be used (run "xlsfonts"
program to see the names). Set $F to an empty
string (this is the default) if you would like
to specify axis font for each overlay separately.
add $ids $cell args... Adds one or more histograms and/or plots of
ntuple data and/or overlayed plots to a multiplot
window. This option may appear many times in
a single command. Each element in the list $ids
must be either a valid Histo-Scope item id or
a name of an existing overlayed plot. In the
latter case an overlayed plot with this name
should be created beforehand using hs::overlay
command. Each item in the $ids list is processed
sequentially with the same options, so that
the notation "add [list $id1 $id2] $cell opt
$value ..." is equivalent to "add $id1 $cell
opt $value ... add $id2 $cell opt $value ...".
$cell is the multiplot window cell identifier
which consists of two non-negative integers
separated by a comma. The first integer is the
column number and the second integer is the row
number. The identifier 0,0 refers to the top left
cell in the multiplot. When all items in the $ids
list are Histo-Scope ids, the optional arguments
may specify axis limits, line color, style,
histogram fill, marker size and style, etc. The
options are the same as in the hs::overlay "add"
command, so please refer to the hs::overlay
description for details. If, instead, the $ids
list contains one or more names of overlayed
plots then the available argument options are
-xlabel, -ylabel, -font, -xmin, -xmax, -ymin,
-ymax, -zmin, -zmax, -ipadx, -ipady, -xscale,
-yscale, -zscale, -colorscale, -style, and
-legend which can be used to specify axis labels,
axis font, limits, plot margins, scale types,
color scale, overlay style, and legend behavior
in the same fashion as inside the hs::overlay
command.
getconfig If this option is specified, the command will
return the configuration string needed to build
the multiplot window. This option is mutually
exclusive with the "getcell" option.
getcell $cell If this option is specified, the command will
return the name of the overlayed plot in cell
identified by $cell or an empty string if that
cell is unused. This option is incompatible with
the "getconfig" option. When neither "getconfig"
nor "getcell" options are specified the command
returns an empty string.
show Send the configuration string to the connected
Histo-Scopes so that they display the plot on the
computer screen. The number of cells in the
multiplot window will be calculated automatically
based on the cell identifiers used with the "add"
option.
clear Clear the structures used to build the multiplot
with given name. After this command the name
can be reused to create another multiplot.
The order in which the options appear on the command line doesn't matter.
Example
-------
Suppose, we want to display histograms with Histo-Scope ids 1 through 5
in a two-cell multiplot window. Histograms 1 through 4 are to be shown
overlayed in the same cell using different colors. This can be
accomplished with the following command:
hs::multiplot multi1 show \
add 1 0,0 -color red \
add 2 0,0 -color green2 \
add 3 0,0 -color blue \
add 4 0,0 -color magenta \
add 5 1,0
Here is another way to do the same thing:
hs::overlay tmp add 1 -color red add 2 -color green2 add 3 -color blue
hs::multiplot multi2 show \
add tmp 0,0 \
add 4 0,0 -color magenta \
add 5 1,0
hs::multiply_histograms $uid $title $category $id1 $id2 $const
Arguments : integer uid, strings title and category,
integers id1 and id2, double const
Returns : integer
Creates a new histogram (one-dimensional or two-dimensional) whose data
is the multiplication, bin by bin, of two histograms specified by id1
and id2. The bin content of the new histogram will be equal to const *
bin value of histogram id1 * bin value of histogram id2. If one of the
id's is specified as 0, the other histogram will just be multiplied by
the constant. uid is the User Identification for the newly created
histogram. title defines the title for the new histogram. category is a
string defining a hierarchical "location" for the histogram.
Subcategories can be specified using the "/" character as in UNIX file
specifications. If a category or subcategory does not exist, it is
created. If the category argument is "" then the histogram will appear
in the top level category. Returns the id of the new histogram containing
the result of the operation, or throws a tcl error if the operation could
not be performed. Both histograms specified should be of the same type
and have the same number of bins and bin edges.
hs::next_category_uid $category
Arguments : string category
Returns : integer
Returns the next available user id for a given category.
hs::ntuple_add_variables $ntuple_id $uid $title $category $tcl_filter_expr \
name1? definition1? name2? definition2? ...
Arguments : integers ntuple_id and uid, strings title and category,
script tcl_filter_expr, variable names and definitions
are provided as strings
Returns : integer
Creates a new ntuple with user id, title, and category specified.
See the description of hs::create_ntuple command for a full explanation
of uid, title, and category arguments. Names $name1, $name2, etc. will
be appended to the set of variables in the ntuple with Histo-Scope id
$ntuple_id to form the set of variables of the new ntuple. $definition1,
$definition2, etc. must be valid tcl expressions which can be evaluated
using ntuple variables. The resulting ntuple gets filled for a given
ntuple entry only when $tcl_filter_expr evaluates to "true" for the
given entry. The command returns Histo-Scope id of the new ntuple or
throws a tcl error.
This command is implemented in pure tcl. For big ntuples, use
hs::ntuple_c_add_variables.
Example
-------
Suppose, we have an ntuple with id 5 and variables A, B, and C. Then
hs::ntuple_add_variables 5 1 "New ntuple" "Example category" \
{expr $A > 0} D {expr $B + $C} E {expr $B - $C}
creates a new ntuple with user id 1 and title "New ntuple" in category
"Example category". The new ntuple variables are A, B, C, D, and E.
Variable D is defined as the sum of variables B and C, and variable
E is defined as their difference. Only entries for which A > 0 will
contribute to the new ntuple.
hs::ntuple_bit_histo $uid $title $category $ntuple_id $varname
Arguments : integers uid and ntuple_id, strings title and category,
string varname
Returns : integer
Creates a 1-d histogram with given uid, title, and category. Please
see the description of hs::create_1d_hist for a full explanation of
uid, title, and category arguments. The varname argument specifies
a variable of the ntuple with id $ntuple_id which is treated as
a collection of bits. The resulting histogram shows the frequency
of various bits in the $varname column.
hs::ntuple_block_fill $ntuple_id $data
Arguments : integer ntuple_id, data may be either a list of doubles
or a binary string of floats
Returns : nothing
Replaces the accumulated data in the ntuple with id $ntuple_id with
the data provided in $data. The elements in $data should be arranged
row-by-row, and the total number of elements should be divisible by
the number of variables in the ntuple.
hs::ntuple_c_add_variables ?-include c_utility_code? ?-eval optional_c_code? \
?-cflags flags? $ntuple_id $uid $title $category $c_filter_expr \
name1? definition1? name2? definition2? ...
Arguments : integers ntuple_id and uid, strings c_utility_code,
optional_c_code, flags, title, category, and c_filter_expr,
variable names and definitions are provided as strings
Returns : integer
Creates a new ntuple with user id, title, and category specified.
See the description of hs::create_ntuple command for a full explanation
of uid, title, and category arguments. Names $name1, $name2, etc. will
be appended to the set of variables in the ntuple with Histo-Scope id
$ntuple_id to form the set of variables of the new ntuple. $definition1,
$definition2, etc. must be valid C expressions which can be evaluated
using ntuple variables. The resulting ntuple gets filled for a given
ntuple entry only when $c_filter_expr does not evaluate to 0 for this
entry. The command returns the Histo-Scope id of the new ntuple or
throws a tcl error.
Optionally, an arbitrary set of C utility functions may be defined
using the "-include" option. These functions may be used inside
c_filter_expr, definition1, definition2, etc. Optional C code provided
using the "-eval" option will be called just before definition1,
definition2, etc. are calcuated (but after the filter). The "-cflags"
option can be used to specify additional compilation flags.
Example
-------
Suppose, we have an ntuple with id 5 and variables A, B, and C. Then
hs::ntuple_c_add_variables 5 1 "New ntuple" "Example category" \
{A > 0.f} D {B + C} E {B - C}
creates a new ntuple with user id 1 and title "New ntuple" in category
"Example category". The new ntuple variables are A, B, C, D, and E.
Variable D is defined as the sum of variables B and C, and variable
E is defined as their difference. Only entries for which A > 0 will
contribute to the new ntuple.
hs::ntuple_c_count ?-unique expression_list? ?-include c_utility_code? \
?-eval optional_c_code? $ntuple_id $c_filter_expr
Arguments : integer ntuple_id, strings c_utility_code, optional_c_code,
and c_filter_expr, list of strings expression_list
Returns : integer
Counts the number of ntuple rows which satisfy the condition specified
by $c_filter_expr. A row is counted if $c_filter_expr is not evaluated
to 0 for this row. If the "-unique" option is provided with a non-empty
expression_list then only those rows are counted for which evaluation
of expression_list results in a unique vector of values. $c_filter_expr
and every element of $expression_list must be valid C expressions which
can be evaluated using ntuple variables represented as floats.
Optionally, an arbitrary set of C utility functions may be defined
using the "-include" option. These functions may be called inside
c_filter_expr and expression_list. Optional C code provided using
the "-eval" option will be called just before expression_list is
calcuated (but after the filter). The "-eval" option is ignored
in case "-unique" option is not provided.
Example
-------
Suppose, we have an ntuple with id 5 and variables A, B, and C. Then
hs::ntuple_c_count 5 {A + B > C} -unique [hs::ntuple_variable_list 5]
returns the number of unique rows which satisfy the condition A + B > C.
hs::ntuple_c_covar ?-include c_utility_code? ?-eval optional_c_code? \
$ntuple_id $c_filter_expr $c_weight_expr $expression_list
Arguments : integer ntuple_id, strings c_utility_code, optional_c_code,
c_filter_expr, and c_weight_expr, list of strings
expression_list
Returns : list of lists {list_of_averages covariance_matrix}
Calculates averages and covariance matrix for quantities specified
in the expression_list. Together with c_filter_expr and c_weight_expr,
these quantities must be valid C expressions which can be evaluated
using ntuple variables represented as floats. Each ntuple row will be
included in the calculation of the statistics with weight given by
c_weight_expr only when c_filter_expr is not evaluated to 0 for this row.
Optionally, an arbitrary set of C utility functions may be defined
using the "-include" option. These functions may be called inside
c_filter_expr, c_weight_expr, and expression_list. Optional C code
provided using the "-eval" option will be called just before
c_weight_expr and expression_list are calcuated (but after the filter).
This command returns a two-element list. The first element of this list
is the list of averages, with the same length as expression_list and in
corresponding order. The second element is the covariance matrix which
is represented as a list of rows (or columns since this matrix is
symmetrical). Each row has the same length as expression_list, and
the order of elements in it also corresponds to expression_list.
Example
-------
Suppose, ntuple with id 5 contains data for variables X, V, and T.
We can calculate covariance between X and V*T using the following
command:
hs::ntuple_c_covar 5 1 1 [list X V*T]
hs::ntuple_c_filter ?-include c_utility_code? $ntuple_id $uid $title \
$category $c_filter_expr
Arguments : integers ntuple_id and uid, strings c_utility_code, title,
category, and c_filter_expr
Returns : integer
Creates a new ntuple with user id, title, and category specified.
See the description of hs::create_ntuple for a full explanation of
uid, title, and category arguments. The set of variables in the new
ntuple is the same as in the ntuple with Histo-Scope id $ntuple_id.
The data in the new ntuple is a subset of ntuple $ntuple_id data.
$c_filter_expr must be a valid C integer expression which can be
evaluated using ntuple variables represented as floats. An entry
from ntuple $ntuple_id is copied to the new ntuple only when
$c_filter_expr is not evaluated to 0 for this entry. The command
returns Histo-Scope id of the new ntuple or throws a tcl error.
This command uses gcc internally to compile the filter expression,
so gcc must be installed before this command can be used. For small
ntuples, it may be faster to use hs::ntuple_filter command instead.
Note that every variable name in the ntuple must be a valid C variable
name. This constraint limits the applicability of the hs::ntuple_c_filter
command. For example, this command may not be used with ntuples whose
variable names contain spaces.
Optionally, an arbitrary set of C utility functions may be defined
using the "-include" option. These functions may be called inside
c_filter_expr.
Examples
--------
Suppose, we have an ntuple with id 5 and variables A, B, and C. Then
hs::ntuple_c_filter 5 1 "New ntuple" "Example category" {A + B > 0.f}
creates a new ntuple with user id 1 and title "New ntuple" in the
category "Example category". Only entries for which A+B > 0 will be
copied to the new ntuple from ntuple 5. Same thing can be done with
a utility function like this:
hs::ntuple_c_filter -include {
static float plus(float x, float y)
{
return x+y;
}
} 5 1 "New ntuple" "Example category" {plus(A,B) > 0.f}
The command
hs::ntuple_c_filter 5 2 "Copy ntuple" "Example category" {1}
creates a new ntuple which is a copy of ntuple 5.
hs::ntuple_c_linear_regress ?-include c_utility_code? ?-eval optional_c_code?\
$ntuple_id $c_filter_expr $c_weight_expr $c_response_expr \
$predictor_list
Arguments : integer ntuple_id, strings c_utility_code, optional_c_code,
c_filter_expr, c_weight_expr, and c_response_expr,
list of strings predictor_list
Returns : mixed list {regression_coefficients covariance_matrix
residual_chisquare ndof globcc adjusted_globcc}
Performs multiple linear regression on the quantity specified in
$c_response_expr using elements of $predictor_list as predictor
variables (constant term is automatically included, and it should not
be specified as one of the predictors). $c_filter_expr, $c_weight_expr,
$c_response_expr, and all elements of $predictor_list must be valid C
expressions which can be evaluated using variables of ntuple with
Histo-Scope id $ntuple_id represented as floats. An ntuple entry
is used in the regression procedure with weight $c_weight_expr only
when $c_filter_expr is not evaluated to 0 for this entry.
Optionally, an arbitrary set of C utility functions may be defined
using the "-include" option. These functions may be called inside
c_filter_expr, c_weight_expr, etc. Optional C code provided using
the "-eval" option will be called just before c_weight_expr, etc.
are calcuated (but after the filter).
This command returns a six-element list. The first element of the result
is the list of estimated regression coefficients. Their order corresponds
to the order of elements in predictor_list, and the constant term is
appended at the end. The second element of the result is the covariance
matrix of the regression coefficients (represented as a list of lists of
doubles). The third element is the sum of squared differences between
predicted and observed values of the response quantity. The fourth
element is the number of degrees of freedom in the problem (which is
the number of ntuple entries minus the number of predictor variables
and minus one for the constant term). The fifth and sixth elements
are, correspondingly, standard and adjusted correlation coefficient
between the response quantity and its prediction (often called "global
correlation coefficient" or "coefficient of determination" -- see
the description of hs::globcc command for more detail).
This command is only available if the extension has been compiled
with CERNLIB. Note that at this time weighted regression has not been
extensively tested yet, and for now it is recommended to use 1 as
c_weight_expr.
hs::ntuple_c_project ?-include c_utility_code? ?-eval optional_c_code? \
?-cflags flags? $ntuple_id $proj_id $c_filter_expr $c_expr_0 c_expr_1? ...
Arguments : integers ntuple_id and proj_id, strings c_utility_code,
optional_c_code, flags, and c_filter_expr, various
C expressions are supplied as strings
Returns : nothing
Fills a histogram or an ntuple with id $proj_id with data from ntuple
with id $ntuple_id. c_filter_expr, c_expr_0, c_expr_1, etc. must
be valid C expressions which can be evaluated using ntuple variables
represented as floats. The projection histogram or ntuple gets filled
for a given ntuple entry only when c_filter_expr is not evaluated to 0
for this entry. If $proj_id refers to an ntuple then the number of
expressions provided after the filter must be equal to the number
of columns in this ntuple. If $proj_id refers to a 1d histogram then
c_expr_0 is treated as a weight and c_expr_1 as the x coordinate.
One additional expression, c_expr_2, must be provided when $proj_id
refers to a 2d histogram. This additional expression specifies
the y coordinate.
Optionally, an arbitrary set of C utility functions may be defined
using the "-include" option. These functions may be called inside
c_filter_expr, c_expr_0, etc. Optional C code provided using the
"-eval" option will be called just before c_expr_0, etc. are calcuated
(but after the filter). The "-cflags" option can be used to specify
additional compilation flags.
Note that the projection histogram or ntuple is not reset before filling.
Example
-------
Suppose, we have the following (empty) items:
1. ntuple with id 5 contains data for variables T, A, M, and V
2. histogram with id 6 is a 1d histogram
3. histogram with id 7 is a 2d histogram
4. ntuple with id 8 has three columns
We can histogram variable A as follows:
hs::ntuple_c_project 5 6 1 1 A
We can build 2d distributions of various combinations of variables
like this:
hs::ntuple_c_project 5 7 {T > 5.f} M {T*A-V} {T*A+V}
The above expression builds a 2-d distribution of X,Y entries where
X = T*A-V, Y = T*A+V. Each entry contributes weight M but only if T > 5.
We can fill another ntuple with various combinations of variables:
hs::ntuple_c_project 5 8 1 M {T*A-V} {T*A+V}
Same operation using a utility function:
hs::ntuple_c_project -include {
static float speed(float t, float a, float v)
{
return t*a+v;
}
} 5 8 1 M {T*A-V} {speed(T,A,V)}
hs::ntuple_c_replace_variables ?-project yesno? ?-include c_utility_code? \
?-cflags flags? ?-eval optional_c_code? $ntuple_id $uid $title \
$category $c_filter_expr oldname1? newname1? definition1? \
oldname2? newname2? definition2? ...
Arguments : integers ntuple_id and uid, boolean yesno, strings
c_utility_code, optional_c_code, flags, title, category, and
c_filter_expr, variable names and definitions are provided
as strings
Returns : integer
In the list of columns from the ntuple with id $ntuple_id variables
named $oldname1, $oldname2, etc. will be substituted by variables named
$newname1, $newname2, etc. and defined by $definition1, $definition2,
etc. New variable definitions must be valid C expressions which can be
evaluated using old ntuple variables. If the value of -project option
is 0 (or the option is omitted) then a new ntuple is created with user
id, title, category, and variables specified. If the value of -project
option is 1 then it is assumed that $uid and $category refer to
an existing ntuple whose variables are named in a compatible manner
(title argument is irrelevant in this case). The resulting ntuple gets
filled for a given ntuple entry only when $c_filter_expr does not
evaluate to 0 for this entry. The command returns the Histo-Scope id of
the new ntuple or, when -project option value is 1, the id of the ntuple
onto which the projection is made.
Optionally, an arbitrary set of C utility functions may be defined
using the "-include" option. These functions may be used inside
c_filter_expr, definition1, definition2, etc. Optional C code provided
using the "-eval" option will be called just before definition1,
definition2, etc. are calcuated (but after the filter). The "-cflags"
option can be used to specify additional compilation flags.
hs::ntuple_c_search ?-unique expression_list? ?-include c_utility_code? \
?-reverse r? ?-eval optional_c_code? $ntuple_id $c_filter_expr
Arguments : integer ntuple_id, boolean r, strings c_utility_code,
optional_c_code, and c_filter_expr, list of strings
expression_list
Returns : list of integers
Returns the list of ntuple rows which satisfy the condition specified
by $c_filter_expr. Row number is included in the list if $c_filter_expr
is not evaluated to 0 for this row. If the "-unique" option is provided
with a non-empty expression_list then only those rows are included for
which evaluation of expression_list results in a unique vector of values.
When "-reverse" option is set "true" then the last row among non-unique
rows is selected; otherwise it is the first row. $c_filter_expr and
every element of $expression_list must be valid C expressions which
can be evaluated using ntuple variables represented as floats.
Optionally, an arbitrary set of C utility functions may be defined
using the "-include" option. These functions may be called inside
c_filter_expr and expression_list. Optional C code provided using
the "-eval" option will be called just before expression_list is
calcuated (but after the filter). The "-eval" option is ignored
in case "-unique" option is not provided.
Example
-------
Suppose, we have an ntuple with id 5 and variables A, B, and C. Then
hs::ntuple_c_search 5 {A + B > C} -unique [hs::ntuple_variable_list 5]
returns the list of unique rows which satisfy the condition A + B > C.
hs::ntuple_c_stats ?-include c_utility_code? ?-eval optional_c_code? \
$ntuple_id $c_filter_expr $c_expr
Arguments : integer ntuple_id, strings c_utility_code, optional_c_code,
c_filter_expr, and c_expr
Returns : list of doubles {sum mean stdev min q25 median q75 max}
Calculates various statistics for an arbitrary C expression c_expr which
can be evaluated using ntuple rows. c_filter_expr must also be a valid
C expression which can be evaluated using ntuple variables represented
as floats. The value of c_expr for a given ntuple entry is included in
the set for calculation of the statistics only when c_filter_expr is not
evaluated to 0 for this entry. The following statistics are returned:
sum : sum of all values
mean : average of the values
stdev : standard deviation
min : minimum value
q25 : 25th percentile
median : median
q75 : 75th percentile
max : maximum value
Optionally, an arbitrary set of C utility functions may be defined
using the "-include" option. These functions may be called inside
c_filter_expr and c_expr. Optional C code provided using the "-eval"
option will be called just before c_expr is calcuated (but after
the filter).
See also the description of hs::column_stats.
hs::ntuple_contents $id
Arguments : integer id
Returns : binary string
Returns all of the data in an Ntuple, specified by id, in the form of
a binary string. In this string the Ntuple contents are arranged
row-by-row.
hs::ntuple_creation_template $filename $varlist
Arguments : string filename, list of strings varlist
Returns : nothing
Generates a template C file named $filename for a user-developed ntuple
creation and filling code. Note that the file will be overwritten if it
already exists. $varlist specifies the list of ntuple column names. All
these names must be valid C variable names.
hs::ntuple_dll_scan ?-reverse r? $ntuple_id $dlltoken some_string?
Arguments : integer ntuple_id and dlltoken, boolean r, string some_string
Returns : may return anything, depending on the C code used
This command facilitates scanning of large ntuples using C code.
$ntuple_id is a Histo-Scope id of an ntuple. $dlltoken must be a shared
library token obtained earlier with the hs::sharedlib command.
The library must define a function named "hs_ntuple_scan_function"
with the following C prototype:
int hs_ntuple_scan_function(Tcl_Interp *interp, const float *row_data);
This function is called for every ntuple row. Optionally, the library
may also define functions
int hs_ntuple_scan_init(Tcl_Interp *interp, int ntuple_id,
const char *some_string);
int hs_ntuple_scan_conclude(Tcl_Interp *interp, int ntuple_id,
const char *some_string);
which will be called before and after the row scan, respectively.
All functions must return either TCL_OK or TCL_ERROR. The interpreter
passed to the functions can be used to store the result of the scan.
The optional command argument "some_string" may be used to pass an
arbitrary string to the init and conclude functions (the location of
the string will persist throughout the scan). If this argument is not
specified or specified as an empty string, the init and conclude
functions will get a NULL pointer.
The "-reverse" option may be set "true" to change the order in which
ntuple rows are presented to the scanning function. By default, this
option is "false", and rows are scanned starting with number 0.
A template C file with the skeleton code for the above functions can
be generated using the hs::ntuple_scan_template command. Loading and
unloading of the shared library can be performed together with
the ntuple scan in one step using the hs::ntuple_so_scan command.
hs::ntuple_filter $ntuple_id $uid $title $category $tcl_filter_expr
Arguments : integers ntuple_id and uid, strings title and category,
script tcl_filter_expr
Returns : integer
Creates a new ntuple with user id, title, and category specified.
See the description of hs::create_ntuple command for a full explanation
of uid, title, and category arguments. The set of variables in the new
ntuple is the same as in the ntuple with Histo-Scope id $ntuple_id.
The data in the new ntuple is a subset of ntuple $ntuple_id data.
$tcl_filter_expr must be a valid tcl boolean expression which can be
evaluated using ntuple variables. An entry from ntuple $ntuple_id
is copied to the new ntuple only when $tcl_filter_expr is true for this
entry. The command returns Histo-Scope id of the new ntuple or throws
a tcl error.
This command is implemented in pure tcl. To filter big ntuples, use
hs::ntuple_c_filter or hs::ntuple_so_filter.
Example
-------
Suppose, we have an ntuple with id 5 and variables A, B, and C. Then
hs::ntuple_filter 5 1 "New ntuple" "Example category" {expr $A+$B > 0}
creates a new ntuple with user id 1 and title "New ntuple" in category
"Example category". Only entries for which A+B > 0 will be copied to
the new ntuple from ntuple 5. The command
hs::ntuple_filter 5 2 "Copy ntuple" "Example category" {expr 1}
creates a new ntuple which is a copy of ntuple 5.
hs::ntuple_histo_fill $ntuple_id $histo_id
Arguments : integers ntuple_id and histo_id
Returns : nothing
Fills an ntuple with Histo-Scope id $ntuple_id using contents of
a histogram with Histo-Scope id $histo_id. If the histogram is
one-dimensional then the ntuple may have two to four columns which
are filled as follows: column 0 is filled with coordinates of the
histogram bin centers, column 1 is filled with bin values, column 2
(if exists) is filled with positive errors (or zeros if the histogram
has no errors defined), and column 3 (if exists) is filled with negative
errors (or zeros if the histogram has no negative errors). If the
histogram is two-dimensional then the ntuple may have three to five
columns which are filled in the following order: x coordinates of bin
centers, y coordinates of bin centers, bin values, positive errors,
and negative errors. Three-dimensional histograms are mapped into
the ntuple columns in the following order: x, y, and z coordinates of
bin centers, bin values, positive errors, and negative errors (four to
six columns allowed).
hs::ntuple_paste $uid $title $category $id1 $id2
Arguments : integers uid, id1, and id2 strings title and category
Returns : integer
Creates a new ntuple consisting of two existing ntuples, specified by
$id1 and $id2. These two ntuples must have an identical number of rows.
uid, title, and category arguments define user identification number,
title, and hierarchical "location" for the new ntuple (the description of
hs::create_ntuple command provides more details about these arguments).
The columns of the new ntuple will be formed by concatenation of columns
from ntuples with ids $id1 and $id2. Note that all column names must
be distinct, and the command will fail if some column name is present
in both ntuples.
hs::ntuple_poly_fit $id $xcol $ycol $n reverse_ordering?
Arguments : integers id, xcol, ycol, n, boolean reverse_ordering
Returns : two_element list {coeff sigma}. coeff is itself a list
of doubles {a_0 ... a_n} which represent the fitted
coefficients of the polynomial, and sigma is the estimate
of the standard deviation of the fit residuals.
Fits a polynomial of degree $n (not higher than 20) to a set of
equally-weighted data points whose coordinates are taken from the ntuple
with Histo-Scope id $id. The xcol argument specifies ntuple column number
used as the x coordinate, and the ycol argument specifies column number
for the y coordinate. reverse_ordering is an optional argument which
allows you to reverse the ordering of the polynomial coefficients
returned. The default value of this argument is 0 in which case
the coefficients are returned in the order of increasing degree.
This function uses CERNLIB least squares polynomial fitting algorithm
RLSQPM (CERNLIB entry E201), and it is only available if the extension
has been compiled with CERNLIB.
hs::ntuple_project $ntuple_id $proj_id $filter_expr $expr_0 expr_1? ...
Arguments : integers ntuple_id and proj_id, string filter_expr,
various tcl expressions are supplied as strings
Returns : nothing
Fills a histogram or an ntuple with id $proj_id with data from ntuple
with id $ntuple_id. filter_expr, expr_0, expr_1, etc. must be valid
tcl expressions which can be evaluated using ntuple variables.
filter_expr must result in a boolean value. The projection histogram
or ntuple gets filled for a given ntuple entry only when filter_expr
is true. If $proj_id refers to an ntuple then the number of expressions
provided after the filter must be equal to the number of columns in
this ntuple. If $proj_id refers to a 1d histogram then expr_0 is treated
as a weight and expr_1 as the x coordinate. One additional expression,
expr_2, must be provided when $proj_id refers to a 2d histogram. This
additional expression specifies the y coordinate. The results of expr_0,
expr_1, etc. will be converted to doubles. If such a conversion is not
possible then the command will throw a tcl error.
Note that the projection histogram or ntuple is not reset before filling.
This command is implemented in pure tcl. To project big ntuples, use
hs::ntuple_c_project.
Example
-------
Suppose, we have the following (empty) items:
1. ntuple with id 5 contains data for variables T, A, M, and V
2. histogram with id 6 is a 1d histogram
3. histogram with id 7 is a 2d histogram
4. ntuple with id 8 has three columns
We can histogram variable A as follows:
hs::ntuple_project 5 6 {expr 1} {expr 1} {expr $A}
We can build 2d distributions of various combinations of variables
like this:
hs::ntuple_project 5 7 {expr $T > 5} {expr $M} \
{expr $T*$A-$V} {expr $T*$A+$V}
The above expression builds a 2-d distribution of X,Y entries where
X = T*A-V, Y = T*A+V. Each entry contributes weight M but only if T > 5.
We can fill another ntuple with various combinations of variables:
hs::ntuple_project 5 8 {expr 1} {expr $M} {expr $T*$A-$V} {expr $T*$A+$V}
hs::ntuple_scan_template $ntuple_id $filename
Arguments : integer ntuple_id, string filename
Returns : nothing
Generates a template C file named $filename for a user-developed ntuple
scanning code. Note that the file will be overwritten if it already
exists. The template code can then be edited, compiled, and executed
using the hs::ntuple_so_scan command. $ntuple_id is the Histo-Scope id
of the ntuple to scan. This command will work only when every ntuple
column name is a valid C variable name.
hs::ntuple_so_filter $ntuple_id $uid $title $category $so_file
Arguments : integers ntuple_id and uid, strings title and category,
string so_file
Returns : integer
Creates a new ntuple with user id, title, and category specified.
See the description of hs::create_ntuple for a full explanation of
uid, title, and category arguments. The set of variables in the new
ntuple is the same as in the ntuple with Histo-Scope id $ntuple_id.
The data in the new ntuple is a subset of ntuple $ntuple_id data.
$so_file must be a full path of an existing shared library which
must define function "hs_ntuple_filter_function" with the following
C prototype: int hs_ntuple_filter_function(const float *row_data).
A row from ntuple $ntuple_id is copied to the new ntuple only when
hs_ntuple_filter_function is not evaluated to 0 for this row.
The command returns Histo-Scope id of the new ntuple or throws
a tcl error. See also descriptions of commands hs::ntuple_filter,
hs::ntuple_c_filter.
hs::ntuple_so_scan ?-reverse r? $ntuple_id $so_file some_string?
Arguments : integer ntuple_id, boolean r, strings so_file and some_string
Returns : may return anything, depending on the C code used
This command facilitates scanning of large ntuples using C code.
$ntuple_id is a Histo-Scope id of an ntuple. $so_file must be
a full path of an existing shared library which must define function
"hs_ntuple_scan_function" with the following C prototype:
int hs_ntuple_scan_function(Tcl_Interp *interp, const float *row_data);
This function is called for every ntuple row. Optionally, the library
may also define functions
int hs_ntuple_scan_init(Tcl_Interp *interp, int ntuple_id,
const char *some_string);
int hs_ntuple_scan_conclude(Tcl_Interp *interp, int ntuple_id,
const char *some_string);
which will be called before and after the row scan, respectively.
All functions must return either TCL_OK or TCL_ERROR. The interpreter
passed to the functions can be used to store the result of the scan.
The optional command argument "some_string" may be used to pass an
arbitrary string to the init and conclude functions (the location of
the string will persist throughout the scan). If this argument is not
specified or specified as an empty string, the init and conclude
functions will get a NULL pointer.
The "-reverse" option may be set "true" to change the order in which
ntuple rows are presented to the scanning function. By default, this
option is "false", and rows are scanned starting with number 0.
A template C file with the skeleton code for the above functions can
be generated using the hs::ntuple_scan_template command. If you plan
to use the same shared library to scan many ntuples, consider using
the hs::ntuple_dll_scan command.
hs::ntuple_subrange $uid $title $category $ntuple_id $first_row $last_row
Arguments : integers uid, ntuple_id, first_row, and last_row,
strings title and category
Returns : integer
Creates a new ntuple with user id, title, and category specified.
See the description of hs::create_ntuple for a full explanation of
uid, title, and category arguments. The variables of the new ntuple
are identical to the variables of the ntuple with Histo-Scope id
$ntuple_id, and the contents of the new ntuple are copied from ntuple
$ntuple_id rows between $first_row and $last_row (including both limits).
If $last_row < 0, or $first_row > $last_row, or $first_row is equal to
or exceeds the number of entries in the parent ntuple then the new ntuple
will be empty. This command returns the Histo-Scope id of the new ntuple.
hs::ntuple_subset $uid $title $category $ntuple_id $list_of_names
Arguments : integers uid and ntuple_id, strings title and category,
list of strings list_of_names
Returns : integer
Creates a new ntuple with user id, title, and category specified.
See the description of hs::create_ntuple for a full explanation of
uid, title, and category arguments. The set of variables in the new
ntuple is a subset of variables in the ntuple with Histo-Scope id
$ntuple_id. The selected variables and their new ordering are specified
by the list_of_names argument. The data for these variables is copied
from the ntuple with id $ntuple_id. This command returns the Histo-Scope
id of the new ntuple.
hs::ntuple_value $id $row $column
Arguments : integers id, row, and column
Returns : double
Returns the value in an Ntuple at a specified row and column
index. value is undefined (-1.0 is returned) if id does not exist or
refers to an item other than an Ntuple.
hs::ntuple_variable_list $id pattern?
Arguments : integer id, string pattern.
Returns : list of strings
Returns the list of variables for the ntuple specified by id whose
names match the given pattern. The match is established using the same
rules as for the tcl command "string match". The ordering of columns is
preserved. If the pattern is omitted, all ntuple variables are returned.
hs::num_connected_scopes
Arguments : none
Returns : integer
Returns the number of connected Histo-Scopes. This routine is useful
for checking that a Histo-Scope created with hs::histoscope has
successfully begun executing and is connected to its client program.
Since this takes some time, it is suggested that hs::num_connected_scopes
be called to check that a scope is connected before calling
hs::load_config_file or hs::load_config_string.
hs::num_entries $id
Arguments : integer id
Returns : integer
Returns the number of fill operations that have been performed on the
histogram or ntuple referred to by id, or -1 if the id does not refer
to a histogram or ntuple item.
hs::num_items
Arguments : none
Returns : integer
Returns the number of Histo-Scope data items defined so far.
hs::num_variables $id
Arguments : integer id
Returns : integer
Returns the number of variables in the Ntuple specified by id or throws
tcl error if the id is not valid or does not refer to an Ntuple.
hs::overlay $name option? arg? ...
Arguments : string name, various options are supplied as strings
Returns : a string, or a list of integers, or nothing
This command creates a configuration string requesting connected
Histo-Scopes to draw several histograms or plots of ntuple data in
the same window. The whole string does not have to be created in
a single execution of the command, thus permitting incremental
construction of overlayed plots. $name is an (almost) arbitrary string
used to identify the plot. This string must not be an integer and
it must not contain special characters *?,[]. The following command
line options are supported:
-title $Title Specifies window title. If this option is not given,
the title of the first histogram in the overlayed
plot will become the window title. Use a string which
starts with double forward slash if you intend to
suppress the title in the window PostScript output.
-window $Win Specifies the window name for subsequent use with
commands hs::comment, hs::generate_ps, etc.
-geometry $G Specifies window geometry using the standard
X11 geometry specification string, for example
500x300+150-300. If this option is omitted then the
default geometry 400x300+0+0 will be used (400 pixels
horizontally by 300 pixels vertically in the top left
corner of the screen).
-font $F Specifies font to use for axis labels. Use of this
option requires Tk. $F may be given in any form
acceptable by Tk, for example "Times 18 {bold italic}".
X font names may also be used (run "xlsfonts" program
to see the names). Note that not all fonts are supported
in PostScript.
-legend $onoff Turns the legend on or off in case the overlay contains
more than one plot. Valid values of the $onoff string
are "on" and "off". The default value is "on".
-xlabel $xl These options allow you to specify axis labels. By
-ylabel $yl default, overlays with just one plot will use axis
labels of the plotted item and overlays with more than
one plot will have no labels. These options are used
only by overlays which contain 1d plots of ntuple data
and/or 1d histograms, other overlays ignore them.
-xmin $xmin These options define drawing limits for the plot axes.
-xmax $xmax By default, all items in the overlay are displayed
-ymin $xmin so that their full range is visible. When both limits
-ymax $xmax are specified for the same axis, the lower limit value
-zmin $xmin must be less than the upper limit value.
-zmax $xmax It is a responsibility of the user to ensure that
the specified limits actually overlap with the range
of the displayed items. The limits can be set to
their default values by using an empty string as
the option value. Options -zmin and -zmax are ignored
for 1d plots.
-ipadx $Xmarg This option specifies additional horizontal margins for
drawing the histogram inside its window. $Xmarg must be
a two-element list of integers. The first element
specifies the number of pixels added to the left margin
and the second specifies the number of pixels added to
the right margin. Negative values are ignored. Default
Xmarg value is {0 0}.
-ipady $Ymarg This option specifies additional vertical margins for
drawing the histogram inside its window. $Ymarg must be
a two-element list of integers. The first element
specifies the number of pixels added to the top margin
and the second specifies the number of pixels added to
the bottom margin. Negative values are ignored. Default
Ymarg value is {0 0}.
-xscale $xs These options specify the type of the corresponding
-yscale $ys axis scale. Valid option values are "log" and "linear".
-zscale $zs The default type for all scales is "linear". Option
-zscale is ignored for 1d plots.
-colorscale $C Specifies the color scale to use for tartan plots
of 2d histograms and color scatter plots of ntuples.
The color scale tag $C must be obtained beforehand
using commands hs::create_linear_color_scale or
hs::create_general_color_scale. If the color scale
is not specified, the default Histo-Scope color scale
is used.
-style $Style Specifies how different histograms will be drawn inside
the plot window. The following overlay styles are
currently supported:
user -- use histogram line and fill styles
specified by the user when histograms
are added to the overlay.
plain -- use thin solid black line, no fill
for all histograms.
color1 -- draw histograms using thin solid line
of different color for each histogram.
rainbow -- draw histograms using solid line and
solid fill of different color for each
histogram.
quilt -- draw histograms with a thin solid black
line. Use different fill style for each
subsequent plot.
histo -- draw histograms using different line
styles. This simulates the default
behavior of the Histo-Scope GUI.
histocolor -- draw histograms using different line
styles and different colors.
The default overlay style is "user".
add $ids args... Adds one or more histograms or plots of ntuple data to
an overlayed plot. This option may appear many times in
a single command. Each element in the list $ids must be
either a Histo-Scope id of an item to plot or a name of
another existing overlayed plot. Each item in the $ids
list is processed sequentially with the same options, so
that the notation "add [list $id1 $id2] opt $value ..."
is equivalent to "add $id1 opt $value ... add $id2 opt
$value ...". The options should be provided in agreement
with the type of the element being added to the plot.
* Adding a Histogram
The optional arguments specify line color, style, and
histogram fill to use when the histogram is displayed.
Supported argument options are -mode, -errors, -line,
-color, -fill, and -fillcolor. They have the same
meaning as in the hs::show_histogram command. Option
"-owner" may be used with a boolean argument to specify
that the overlay "owns" the histogram. Such a histogram
will be automatically deleted when it is no longer
used by any overlay. If a Histo-Scope id refers to
a histogram already present in the overlay, this
histogram will not be added another time but the drawing
options will be changed according to the supplied set
of arguments. 2d histograms cannot be overlayed, but you
can make an overlay with a single 2d histogram in it.
* Adding a Plot of Ntuple Data
The first argument after the ntuple id must specify
the plot type. The following plot types are supported:
Specifier Meaning Mandatory Options
--------- ------------------ -----------------
ts Time Series Plot -y
tse TS Plot with Errors -y
xy XY Plot -x -y
xye XY Plot with Errors -x -y
xys Sorted XY Plot -x -y
xyse Sorted XY Plot with Errors -x -y
scat2 XY Scatter Plot -x -y
scat3 XYZ Scatter Plot -x -y -z
h1 Histogram -x -nbins
h1a Adaptive Histogram -x
h2 2D Histogram -x -y
h2a Adaptive 2D Histogram -x -y
cell 2D Cell Plot -x -y
cscat2 Color XY Scatter Plot -x -y -z
tartan Color Cell Plot -x -y
Please refer to the original Histo-Scope documentation at
http://cepa.fnal.gov/CPD/histo_doc/v4_0/histo_ntupl.html
for a detailed description of the first 13 plot types.
The "Color XY Scatter Plot" displays the variable
or expression specified with the -z option using a color
scale. The "Color Cell Plot" displays the number of
events in each 2D histogram bin using color. Both plot
types use the color scale specified by the -colorscale
option. Options -zmin, -zmax, and -zscale may be used to
specify how the data should be mapped into colors. If
neither -zmin nor -zmax option is specified, the color
mapping into data is dynamic. In this case the color
scale always covers the full range of the data.
The rest of the arguments must follow as a sequence of
option and value pairs. With the exception of the
integer-valued option -nbins, all mandatory options must
be followed by a name of one of the ntuple variables.
The following options may be specified in addition to
the mandatory ones:
-owner This option expects a boolean value.
1 means that the overlay "owns" the
plotted ntuple. The ntuple will be
automatically deleted when it is no longer
displayed on any plot. The default value
of this option is 0.
-snapshot This option expects a boolean value.
1 means that a temporary ntuple copy will
be created, and the plot will no longer
change when the original ntuple is filled.
This option implies "-owner 0" because
the overlay automatically owns the copy
but not the original ntuple. The default
value of this option is 0.
-lang Specifies the language ("tcl", "C", or
"none") which will be used to interpret
the expressions provided with options -x,
-y, -z, -ex, -ey, -ex+, -ex-, -ey+, -ey-,
and -filter. The default is "none" which
means that options -x, -y, etc. must be
specified as valid ntuple variable names,
and filter must be an empty string. When
tcl or C are used, this option implies
"-owner 0 -snapshot 1".
-filter Specifies the filter which will be applied
to the ntuple before the plot is made. The
default value of this option is an empty
string (means all rows pass). In case
a non-empty filter expression is used,
the -lang option must be provided in order
to specify the language which will be used
to evaluate this expression. Non-empty
filter implies "-owner 0 -snapshot 1".
-line This option specifies the line style
(1d plots only). There are 18 distinct
line styles for h1 and h1a histograms (as
in the hs::show_histogram command) numbered
from 0 to 17. Only the first 13 of these
are available for ts- and xy-like plots.
The default line style is 1 (thin solid
line).
-color Specifies the line color. The default
color is black.
-fill, These options specify 1d histogram (h1 and
-fillcolor h1a) fill style and color. Please see the
description of hs::show_histogram command
for the list of available fill styles. The
default fill style is "none".
-marker Specifies the marker style for ts- and
xy-like plots. The value must be either
an integer from 0 to 9 or one of the
following designated names: none, square,
circle, star, x, triangle, solidsquare,
solidcircle, thicksquare, or thickcircle.
The default marker style is "none".
-markersize The value must be an integer from 0 to 3
or one of the following words: tiny, small,
medium, and large. The default marker size
is "small". This option is only available
for ts- and xy-like plots (same as -marker).
-sliders This option is available for all histograms,
scatter plots, and cell plots. The expected
value is a list of ntuple variable names
which can be later used to change the
set of points used to build the plot.
Please refer to the original Histo-Scope
documentation for details. The default
value of this option is an empty list.
-binlimit Available for adaptive 1d histograms only.
Specifies the maximum number of points
in a single bin (a positive integer).
The default value of this option is 20.
-nxbins These options may be used to specify
-nybins the initial binning for h2, cell, and
tartan plots. When the plot is shown
on the screen, the number of bins may
be adjusted interactively using rebin
sliders (available in the plot menu).
-ey, These options specify ntuple variables
-ey+, or expressions to use for drawing vertical
-ey- plot errors. These options are available
for tse, xye, and xyse plots.
-ex, These options specify ntuple variables
-ex+, or expressions to use for drawing
-ex- horizontal plot errors. These options are
available for xye plots only.
* Adding Another Overlayed Plot
No additional options allowed. All items from the
overlayed plot with the given name will be added to the
current plot. In case of duplicates the configuration
options (such as line color, style, etc.) will be
updated but a new copy of an item will not be added.
The overlayed plots will be checked for compatibility.
Only the plots which both contain 1d plots of ntuple
data and/or 1d histograms can be combined.
getconfig If this option is specified, the command will return
the configuration string needed to build the overlayed
plot. This option is mutually exclusive with the
"getids" option.
getids If this option is specified, the command will return
the list of ids of Histo-Scope items used in this plot.
This option is incompatible with the "getconfig" option.
When neither "getconfig" nor "getids" options are
specified the command returns an empty string.
show Send the configuration string to the connected
Histo-Scopes so that they display the plot on the
computer screen.
clear Clear the structures used to build the overlayed plot
with given name. After this command the name can be
reused to create another overlayed plot.
The order in which the options appear on the command line doesn't matter.
Examples
--------
Suppose, we want to display 1d histograms with Histo-Scope ids 3 and 4
in the same window using different colors. This can be achieved by
the following command:
hs::overlay ov1 show clear add 3 -color red add 4 -color blue
The same thing can be accomplished incrementally:
hs::overlay ov1 add 3 -color red
hs::overlay ov1 add 4 -color blue show clear
Show the same histograms in two different predefined styles:
hs::overlay ov1 show -style color1 add [list 3 4]
hs::overlay ov1 show -style histo -geometry 400x300+400+0
Suppose, in addition to the above histograms we also have an ntuple
with Histo-Scope id 1 and variables named A, B, C, and D. The following
commands will show histograms of all these variables on one plot:
foreach {variable color} {A red B green C blue D magenta} {
hs::overlay ov2 add 1 h1 -x $variable -nbins 50 -color $color
}
hs::overlay ov2 show
Combine these two overlays and show all six histograms together:
hs::overlay ov2 add ov1 show
Add the A vs. B plot:
hs::overlay ov2 add 1 xy -x B -y A -color cyan show
hs::pack_item $id
Arguments : integer id
Returns : binary string
Returns a binary string which contains XDR-encoded Histo-Scope item
with given id. The item can be restored (perhaps, after a transfer
to a different computer) using the hs::unpack_item command. This
command can pack histograms, ntuples, controls, and indicators.
hs::pack_ntuple_row $id $row
Arguments : integers id and row
Returns : binary string
Encodes the contents of a row (or entry) of Ntuple data specified
by id in a binary string. This binary string can be portably transferred
to another computer and unpacked with hs::unpack_ntuple_row command.
hs::parametric_plot $x_expr $y_expr $param_name $pmin $pmax option? arg? ...
Arguments : scripts x_expr and y_expr, string param_name, doubles
pmin and pmax, various options are supplied as strings
Returns : string or nothing
This command is used to draw parametric curves. $x_expr and $y_expr
must be valid tcl scripts which produce double precision results in
the variable context of the calling procedure. $variable_name is the
name of the parameter. Values $pmin and $pmax define the limits of
the parameter range. This command can be used with all the options
accepted by the hs::expr_plot command. Please check the hs::expr_plot
description for details. In addition, there is a new boolean option
called "-hardzoom". If this option's value is true then the plot
ntuples will be filled only by points lying withing limits specified
by the options "-xmin", "-xmax", "-ymin", and "-ymax" (any or all of
these options may be absent in which case the corresponding limit is
not applied). The default value of the "-hardzoom" option is false.
This command returns an empty string if it is called with the "-id"
option; in all other cases it returns the name of the overlayed plot
used to draw the curve.
Examples
--------
Draw a circle:
set r 1.0
hs::parametric_plot {expr $r*cos($phi)} {expr $r*sin($phi)} phi 0 6.283
Draw an epicycloid:
set a 8.0
set b 5.0
hs::parametric_plot {expr {($a+$b)*cos($t) - $b*cos(($a/$b+1)*$t)}}\
{expr {($a+$b)*sin($t) - $b*sin(($a/$b+1)*$t)}} t 0 [expr 6.2832*$b]\
-color blue
hs::periodic_update $msec
Arguments : integer msec (or strings "stop", "period")
Returns : integer or nothing
This command sets up periodic calls to hs::hs_update. The user needs
to call hs::periodic_update only once. All subsequent calls will be
made by the tcl/Tk event loop in $msec millisecond intervals. 100 msec
seems to be a convenient update period.
To change the update rate call hs::periodic_update again with another
period. To find out the current update period use
hs::periodic_update period
This will return 0 if periodic updates are not set up. To stop client
updates, use
hs::periodic_update stop
This command relies on the presence of the tcl/Tk event loop. If you
are running plain tcl without Tk, you need to take care of the event
loop yourself if necessary.
hs::pick_random_rows $id $npick $uid1 $title1 $category1 uid2? \
title2? category2?
Arguments : integers id, npick, uid1, and uid2, strings title1,
category1, title2, and category2
Returns : an integer or a list of two integers
This command picks $npick random rows from the ntuple with Histo-Scope
id $id and puts them into a new ntuple. The new ntuple will have user
id, title, and category as specified by the uid1, title1, and category1
arguments. Please see the description of hs::create_ntuple command for
more details about user id, title, and category. The new ntuple will
have the same variables as the parent ntuple. The Histo-Scope id of
the new ntuple is returned.
If optional arguments uid1, title2, and category2 are present then this
command creates one more ntuple which holds remaining rows from the
ntuple with id $id. In this case the command returns a two-element
list {id1 id2} which holds Histo-Scope ids of both new ntuples.
This command is only available if the extension has been compiled with
CERNLIB.
hs::poisson_random $mean num_points?
Arguments : double mean, integer num_points
Returns : integer or list of integers
Generates random numbers according to the Poisson distribution with
given mean. If optional argument num_points is specified then this
procedure returns a list of $num_points random numbers, otherwise
just one number is returned.
This command is available only if the extension has been compiled
with CERNLIB.
hs::project_2d_histogram $uid $title $category $id $axis $proj_type \
$suppress_zero
Arguments : integers uid and id, boolean suppress_zero,
strings title, category, axis, and proj_type
Returns : integer
Creates a new 1-d histogram with specified user id, title, and category.
See the description of hs::create_1d_hist for a detailed description
of uid, title, and category arguments. The contents of the new
histogram are created by calculating some statistical property over
the columns or rows of the 2-d histogram with Histo-Scope id $id.
The property to calculate is defined by the proj_type argument.
Valid values of this argument are:
sum : sum of all bin values in a row or column
mean : row or column average of bin values (note, not
coordinates)
stdev : standard deviation of bin values
distmean : average of bin coordinates weighed by bin values
diststdev : standard deviation of bin coordinates weighed by
bin values
min : minimum bin value
max : maximum bin value
median : median of bin values
range : (75th percentile - 25th percentile) * 0.7413
for bin values
distmedian : median of bin coordinates weighed by bin values
distrange : (75th percentile - 25th percentile) * 0.7413
for bin coordinates weighed by bin values
The axis onto which the projection is made is defined by the $axis
argument. Valid values of the axis argument are
X (or x) : project onto X axis
Y (or y) : project onto Y axis
If $suppress_zero is true then only non-zero bin entries are used to
create the projection. In all calculations, only histogram bin values
are used, bin errors are ignored.
hs::project_2d_histogram returns the Histo-Scope id of the new histogram
or throws a tcl error.
Example
-------
hs::project_2d_histogram 1 "New Title" "New Category" 5 Y mean 0
The above command creates a new histogram with user id 1, title
"New Title" in the category "New Category" provided that a 2-d
histogram with Histo-Scope id 5 exists. The x axis binning of the
new histogram will be the same as the y axis binning of the
histogram with id 5. The bin contents of the new histogram will be
averages of histogram 5 x bins for each given y bin.
hs::project_3d_histogram $uid $title $category $id $axis1 $axis2 \
$proj_type $suppress_zero
Arguments : integers uid and id, boolean suppress_zero,
strings title, category, axis1, axis2, and proj_type
Returns : integer
Creates a new 1-d or 2-d histogram with specified user id, title, and
category. See the description of hs::create_1d_hist for a detailed
description of uid, title, and category arguments. Arguments axis1 and
axis2 specify the axes onto which the projection is made. Valid values
of these arguments are
X (or x) : project onto X axis
Y (or y) : project onto Y axis
Z (or z) : project onto Z axis
empty string : do not use this argument, make a 1-d projection
onto the axis specified by the other axis argument
Values of axis1 and axis2 must be distinct. The axis order doesn't
matter. Bins of the 3-d histogram with Histo-Scope id $id which have
the same coordinates in the projection plane (or on the projection axis)
are grouped into subsets. The contents of the new histogram are created
by calculating some statistical property over such bin subsets.
The property to calculate is defined by the proj_type argument.
Valid values of this argument are:
sum : sum of all bin values in a subset
mean : average of bin values in a subset (note, not
coordinates)
stdev : standard deviation of bin values
distmean : average of bin coordinates in the direction orthogonal
to the projection plane, weighed by bin values (this
property can only be used with 2-d projections)
diststdev : standard deviation of orthogonal coordinates weighed
by bin values (2-d projections only)
min : minimum bin value
max : maximum bin value
median : median of bin values
range : (75th percentile - 25th percentile) * 0.7413
for bin values in a subset
distmedian : median of orthogonal bin coordinates weighed by
bin values (used with 2-d projections only)
distrange : (75th percentile - 25th percentile) * 0.7413
for orthogonal bin coordinates weighed by bin values
(2-d projections only)
If $suppress_zero is true then only non-zero bin entries are used to
create the projection. In all calculations, only histogram bin values
are used, bin errors are ignored.
hs::project_3d_histogram returns the Histo-Scope id of the new histogram
or throws a tcl error.
Example
-------
hs::project_3d_histogram 1 "New Title" "New Category" 5 Y "" mean 0
The above command creates a new 1-d histogram with user id 1, title
"New Title" in the category "New Category" provided that a 3-d
histogram with Histo-Scope id 5 exists. The x axis binning of the
new histogram will be the same as the y axis binning of the
histogram with id 5. The bin contents of the new histogram will be
averages of histogram 5 xz bins for each given y bin.
hs::random $n
Arguments : positive integer n
Returns : list of doubles
Returns a list of $n pseudo-random numbers between 0 and 1. This command
uses a high quality uniform random number generator if the extension has
been compiled with CERNLIB, otherwise it uses the tcl built-in generator.
hs::random_get_state
Arguments : none
Returns : mixed list
Returns the state of the hs extension random number generator. The state
can be later restored using the hs::random_set_state command, and the
generator will repeat the sequence. The hs::random_get_state and
hs::random_set_state commands are available only if the extension has
been compiled with CERNLIB.
hs::random_init $seed
Arguments : integer seed
Returns : nothing
Sets the seed of the hs extension random number generator to $seed.
hs::random_set_state $state
Arguments : mixed list state
Returns : nothing
Sets the state of the hs extension random number generator. It is
assumed that the value of the command argument has been obtained earlier
using the hs::random_get_state command. The hs::random_get_state and
hs::random_set_state commands are available only if the extension has
been compiled with CERNLIB.
hs::read_control $id
Arguments : integer id
Returns : double
Returns the current value of a control.
hs::read_file $filename $prefix
Arguments : strings filename and prefix
Returns : integer
Reads all of the items from the Histo-Scope formatted file specified
by filename. All category strings will be prefixed by a new top level
category specified in prefix. This may be "" or omitted, meaning no
prefix is added. Returns the number of items read; otherwise returns
-1 and prints an error message.
hs::read_file_items $filename $prefix $category $uids
Arguments : strings filename, prefix, and category, list of integers uids
Returns : integer
Selectively reads items from a specific category and all its
subcategories that match a list of uids from the Histo-Scope formatted
file specified by filename. All category strings read from the file
will be prefixed by a new top level category specified in $prefix.
This may be specified as "", meaning that no prefix should be added.
If an item with the same (prefixed) category and uid already exists,
the item in the file will not be read and a message will be printed to
inform the user. The list uids specifies the user ids of items to read
from the file. If uids is "" then all items in the specified category
and its subcategories will be read. Returns the number of items read,
or -1 if an error occurred.
For example, if "HS" is specified for category and "Run1" for prefix,
items read from the file with category "HS" will become "Run1/HS" and
items read from the file with category "HS/Ntuples" will become
"Run1/HS/Ntuples". The new (prefixed) category must be less than 255
characters in length, or the item will not be read from the file. To
read non-selectively regardless of the category, specify "" as
category.
See the description of hs::dir command for help about obtaining the
listing of items saved in a Histo-Scope file.
hs::read_items_bytitle ?-nocase? $filename $prefix $title_pattern \
$category_pattern
Arguments : strings filename, prefix, title_pattern, and category_pattern
Returns : integer
Selectively reads items whose titles match string $title_pattern and
categories match string $category_pattern from the specified file into
memory and returns the number of items read. The match is determined
using the same rules as for the tcl command "string match" (see the
description of hs::lookup_title command for more details). If the
"-nocase" option is specified then the pattern match is performed in
a case-insensitive manner. The category_pattern argument may be omitted
in which case all categories will be searched. All category strings read
from the file will be prefixed by a new top level category specified
in $prefix. This may be specified as "", meaning that no prefix should
be added. If an item with the same (prefixed) category and uid already
exists, the item in the file will not be read and a message will be
printed to inform the user.
hs::redraw option? value? ...
Arguments : various options are supplied as strings
Returns : nothing
This command can be used to force window update after hs::draw or
hs::comment commands were used with the "-immediate" option set to 0.
This command supports the following options:
-window $Win This option specifies the name of the window to draw
the item in. The window named $Win must be created
in advance by one the commands hs::show_histogram,
hs::overlay, hs::multiplot, hs::expr_plot, etc.
The default is to use the window name specified on
the most recent occasion when one of these commands
was issued with the "-window" option.
-row $R This option is used for multiplots to specify the row
of the desired window. Default row is 0.
-column $C This option is used for multiplots to specify the
desired window column. Default column is 0.
Example
-------
Save some time by not redrawing every item separately:
foreach {pt1 pt2} {{0.8 0} {1.0 0.2} {0 0} {0.2 0.2}} {
hs::draw rectangle -window w1 $pt1 $pt2 -bg blue -immediate 0
}
hs::redraw -window w1
hs::replace_color_scale $old_tag $new_tag
Arguments : strings old_tag and new_tag
Returns : nothing
Replaces the colors in the color scale specified by $old_tag with the
colors in the color scale specified by $new_tag. $old_tag and $new_tag
must be obtained earlier using commands hs::create_general_color_scale or
hs::create_linear_color_scale. If color scale $old_tag has already been
sent to Histo-Scope with the hs::use_color_scale command then plots which
use this color scale are repainted with new colors.
hs::replace_column_contents $id $col $values
Arguments : integers id and col, values may be either a list of
doubles or a binary string of floats
Returns : nothing
Replaces the contents of column number $col in the ntuple with
Histo-Scope id $id with provided list or binary string of values.
The number of elements in the provided data must coincide with
the number of rows in the ntuple.
hs::reset $id
Arguments : integer id
Returns : nothing
Resets the data item. For histograms, all of the bins and overflows are
set to 0. For Ntuples all of the data is removed. Indicators are set to
*not set*. Controls are set to their default value. For triggers, any
pending trigger presses are cleared. For groups, all the data items in
the group are reset.
hs::reset_const $id $const
Arguments : integer id, double const
Returns : nothing
Resets histograms. All histogram bins are set to const, and overflows
are set to 0.
hs::row_contents $id $row
Arguments : integers id and row
Returns : binary string
Returns the contents of a row (or entry) of Ntuple data specified
by id as a binary string. A row is the collection of values
in a particular Ntuple entry, one value for each variable
(A variable could also be called a column or an element).
hs::save_file $filename
Arguments : string filename
Returns : integer
Saves all current histograms, Ntuples, indicators, and controls created
by Histo-Scope library routines or read from Histo-Scope formatted
files to a Histo-Scope-format file. Triggers are not written to the file.
The number of items written is returned, or -1 if an error occurred.
The named file is open for writing ("w"), discarding previous contents,
if any.
hs::save_file_byids $filename $idlist
Arguments : string filename, list of integers idlist
Returns : integer
Saves the histograms, Ntuples, indicators, and controls specified
in the list of Histo-Scope ids to a Histo-Scope format file.
The number of items written is returned, or -1 if an error occurs.
The file named is open for writing ("w"), discarding previous
contents, if any. This command is only enabled when the Histo-Scope
distribution is patched (see the tcl API README file for more details).
hs::save_file_items $filename $category $uids
Arguments : strings filename and category, list of integers uids
Returns : integer
Selectively saves the histograms, Ntuples, indicators, and controls in
a specified category that match a list of uids to a Histo-Scope format
file filename. Items will be written only when they match the specified
category exactly. Specify "" as the category to save only uncategorized
items. uids is a list of user id values specifying which items to write.
If uids is "" then all items in the category specified are saved.
The number of items written is returned, or -1 if an error occurs.
The named file is open for writing ("w"), discarding previous contents,
if any.
hs::server_port
Arguments : none
Returns : integer
Returns the port number of the Histo-Scope server process, or -1
in case Histo-Scope has not been initialized. The port number can be
used by the patched "histo" executable (via the -port command line
switch) to establish a remote TCP/IP connection.
hs::set_1d_errors $id $pos_errors $neg_errors
Arguments : integer id, binary strings or lists of doubles pos_errors
and neg_errors
Returns : nothing
Same as hs::1d_hist_block_fill, except that this command allows to
change histogram errors without changing data. Omit the neg_errors
argument to change positive errors only. This command also allows to
change negative errors only when positive errors already exist.
Specify $pos_errors as "" if this is desired.
hs::set_2d_errors $id $pos_errors $neg_errors
Arguments : integer id, binary strings or lists of doubles pos_errors
and neg_errors
Returns : nothing
Same as hs::2d_hist_block_fill, except that this command allows to
change histogram errors without changing data. Omit the neg_errors
argument to change positive errors only. This command also allows to
change negative errors only when positive errors already exist.
Specify $pos_errors as "" if this is desired.
hs::set_3d_errors $id $pos_errors $neg_errors
Arguments : integer id, binary strings or lists of doubles pos_errors
and neg_errors
Returns : nothing
Same as hs::3d_hist_block_fill, except that this command allows to
change histogram errors without changing data. Omit the neg_errors
argument to change positive errors only. This command also allows to
change negative errors only when positive errors already exist.
Specify $pos_errors as "" if this is desired.
hs::set_indicator $id $value
Arguments : integer id, double value
Returns : nothing
Sets the value of an indicator to value. The value should be within the
range specified for the indicator. However the indicator is set even if
the value is out of range.
hs::sharedlib $option arg?
Arguments : string option, arg may be a string, an integer, or absent,
depending on the option
Returns : return type depends on the option used
Manages shared libraries which contain mathematical functions used
for data fitting (or some other code). The command may be used with
the following options: "open", "close", "list", and "name".
* hs::sharedlib open ?-export_globals? $filename
Loads a shared library named $filename and returns an integer token
which can later be used with hs::function_import command and other
hs::sharedlib options. If the library exports a function named
"_hs_init" then this function is called. If present, this function
must have the following prototype: int _hs_init(Tcl_Interp *interp).
_hs_init should return TCL_OK on success, and TCL_ERROR on failure.
If "-export_globals" switch is specified then global symbols exported
by the library will be made available to subsequently loaded libraries.
* hs::sharedlib close $token
Unloads a shared library. The token argument must be an integer
obtained from an "hs::sharedlib open" call. The library will not be
unloaded if some functions from the library are still used for data
fitting. An attempt to use a wrong token or to unload the same library
more than once will result in a tcl error. Returns an empty string.
If the library exports a function named "_hs_fini" then this function
is called. _hs_fini prototype is "void _hs_fini(void)".
* hs::sharedlib list
Returns the list of tokens for shared libraries currently loaded.
* hs::sharedlib name $token
Returns the name of the file from which the library was loaded.
The token argument must be an integer obtained from a previous
"hs::sharedlib open" call.
hs::sharedlib_compile $file_list $sharedlib_name option? arg? ...
Arguments : list of strings file_list, string sharedlib_name,
various options supplied as strings
Returns : nothing
Compiles shared library named $sharedlib_name using source files
whose names are listed in $file_list. The source code must be written
in either C or FORTRAN. Files with extensions .f, .for, .FOR, .F, .fpp,
and .FPP are assumed to be FORTRAN files, all other files are assumed
to be C files. The shared library can be subsequently loaded into
a running program using hs::sharedlib or hs::ntuple_so_scan commands.
If you library doesn't compile with default settings, it may be helpful
to provide additional compiler and linker flags using options -cflags,
-fflags, and -linkflags. Each option value should be a list which
specifies additional flags passed, respectively, to C compiler, FORTRAN
compiler, and linker.
hs::show_histogram $id option? arg? ...
Arguments : integer id, various options are supplied as strings
Returns : nothing
This command creates a configuration string requesting connected
Histo-Scopes to display the histogram with id $id in a separate window.
The configuration string is sent to the scopes by means of calling
hs::load_config_string. The following options are supported:
-title $Title Specifies window title. If this option is not given,
the histogram title will become the window title. Use
a string which starts with double forward slash if you
intend to suppress the title in the window PostScript
output.
-window $Win Specifies the window name for subsequent use with
commands hs::comment, hs::generate_ps, etc.
-geometry $G Specifies window geometry using the standard
X11 geometry specification string, for example
500x300+150-300. If this option is omitted then the
default geometry 400x300+0+0 will be used (400 pixels
horizontally by 300 pixels vertically in the top left
corner of the screen).
-font $F Specifies font to use for axis labels. Use of this
option requires Tk. $F may be given in any form
acceptable by Tk, for example "Times 18 {bold italic}".
X font names may also be used (run "xlsfonts" program
to see the names). Note that not all fonts are supported
in PostScript.
-mode $M Specifies the drawing mode for 2d histograms. Valid
modes are:
lego builds a 3d plot using rectangular bars whose
height is proportional to the bin value. This
is the default mode.
cell builds a 2d plot using rectangular cells whose
area is proportional to the bin value.
tartan builds a 2d color plot using rectangles whose
color depends on the bin value. The dependence
may be completely specified using options
-colorscale, -zmin, -zmax, and -zscale. When
Z axis limits are not specified, the mapping
from data into colors is dynamic, and it is
adjusted to cover the full Z axis range as
the histogram bins grow.
This option is ignored for 1d histograms.
-colorscale $C Specifies the color scale to use for tartan plots of
2d histograms. The color scale tag $C must be obtained
beforehand using commands hs::create_linear_color_scale
or hs::create_general_color_scale. If the color scale
is not specified, the default Histo-Scope color scale
is used. This option is ignored for 1d histograms.
-xmin $xmin These options define drawing limits for the histogram
-xmax $xmax axes. The default values of these limits are the axis
-ymin $xmin limits specified when the histogram was created. When
-ymax $xmax both limits are specified for the same axis, the lower
-zmin $xmin limit value must be less than the upper limit value.
-zmax $xmax It is a responsibility of the user to ensure that
the specified limits actually overlap with the range
of the displayed histogram. Options -zmin and -zmax
are ignored for 1d histograms. If an empty string is
specified as an option value, this option has no effect,
and the default limit is used.
-xscale $xs These options specify the type of the corresponding
-yscale $ys axis scale. Valid option values are "log" and "linear".
-zscale $zs The default type for all scales is "linear". Option
-zscale is ignored for 1d histograms.
-ipadx $Xmarg This option specifies additional horizontal margins for
drawing the histogram inside its window. $Xmarg must be
a two-element list of integers. The first element
specifies the number of pixels added to the left margin
and the second specifies the number of pixels added to
the right margin. Negative values are ignored. Default
Xmarg value is {0 0}.
-ipady $Ymarg This option specifies additional vertical margins for
drawing the histogram inside its window. $Ymarg must be
a two-element list of integers. The first element
specifies the number of pixels added to the top margin
and the second specifies the number of pixels added to
the bottom margin. Negative values are ignored. Default
Ymarg value is {0 0}.
-errors $onoff Boolean value $onoff specifies whether the histogram
errors should be displayed. The default $onoff value
is 0 (errors not shown). This option is ignored if
the histogram has no error data.
-line $n Histo-Scope line style number. Valid line styles are
0 (invisible) through 17 (solid circle). The default
line style is 1 (thin solid line). The appearance of
all line styles can be viewed in the "Histogram Style"
interactive panel which can be created for any histogram
by clicking on its plot window with the right mouse
button and invoking the "Set Histogram Style..." menu.
-color $cl Line color (red, green, blue, etc.). Run "showrgb"
program to see the list of available colors on
your computer. The default line color is black.
-fill $Fstyle Specifies Histo-Scope histogram fill style. The fill
style may be specified either as a number from 0 through
38 or as a string. The recognized fill style strings
are: none, solid, fineHoriz, coarseHoriz, fineVert,
coarseVert, fineGrid, coarseGrid, fineX, coarseX,
fine45deg, med45deg, coarse45deg, fine30deg, coarse30deg,
fine60deg, coarse60deg, rFine45deg, rMed45deg,
rCoarse45deg, rFine30deg, rCoarse30deg, rFine60deg,
rCoarse60deg, lFineHoriz, lCoarseHoriz, lFineVert,
lCoarseVert, lFineGrid, lCoarseGrid, lFineX, lCoarseX,
lFine45deg, lMed45deg, lCoarse45deg, lFine30deg,
lCoarse30deg, lFine60deg, lCoarse60deg. The default
fill style is 0 (no fill). The fill appearance can
be viewed in the "Histogram Style" interactive panel.
-fillcolor $cf Histogram fill color. The default fill color is the
histogram line color.
The last four options (-style, -color, -fill, and -fillcolor) only
work for 1d histograms. They are ignored for 2d histograms.
hs::slice_contents $parent_id $result_specifier $axis1 $bin1 axis2? bin2?
Arguments : integers parent_id, bin1, and bin2, strings axis1 and axis2,
list of strings result_specifier
Returns : list of binary strings
Returns contents of a slice of a 2d or 3d histogram with Histo-Scope id
$parent_id. $result_specifier is a list whose components must be strings
"d" (for data), "p" (for positive errors), or "n" (for negative errors).
The returned list of binary strings will have the same number of elements,
and they will be arranged in the requested order. If errors of a certain
type are requested and the histogram has no such errors, the relevant
binary string will be empty. Valid axis specifications are "x", "y",
and "z". When both axis1 and axis2 are given, $parent_id should refer to
a 3d histogram and $axis1 must be different from $axis2. bin1 and
(optionally) bin2 specify parent histogram bin numbers along their
respective axes at which the slices are made. When a bin number is
below 0 or above the allowed limit for the corresponding axis, a tcl
error is generated.
Example
-------
Print data and positive errors from a 3d histogram with Histo-Scope id 1
for all x values in the first bin of y and z:
foreach {data errors} [hs::slice_contents 1 {d p} y 0 z 0] {}
puts "Data are [hs::data_to_list $data]"
puts "Errors are [hs::data_to_list $errors]"
hs::slice_histogram $uid $title $category $parent_id $axis1 $bin1 axis2? bin2?
Arguments : integers uid, parent_id, bin1, and bin2, strings title,
category, axis1, and axis2
Returns : integer
Creates a new 1d or 2d histogram with specified user id, title, and
category. See the description of hs::create_1d_hist for a detailed
description of uid, title, and category arguments. The contents of
the new histogram are created by slicing the histogram with Histo-Scope
id $parent_id at bin numbers and axes specified. Only 2d and 3d
histograms can be sliced. Valid values of the axis1 and axis2 arguments
are
X (or x) : slice with fixed X bin number
Y (or y) : slice with fixed Y bin number
Z (or z) : slice with fixed Z bin number
Only one slice axis can be specified with a 2d parent histogram (omit
axis2 and bin2 or use an empty string for axis2). When both axis1 and
axis2 are given, $parent_id should refer to a 3d histogram and $axis1
must be different from $axis2.
This command returns the Histo-Scope id of the new histogram if the slice
is successfully created, or throws a tcl error on failure. Out-of-range
bin numbers will result in error. When a slice is created, it can be
efficiently refilled with the parent data from different bin numbers
using commands hs::fill_hist_slice and hs::fill_slice.
hs::slice_slider $parent_id $axis1 axis2?
Arguments : integer parent_id, strings axis1 and axis2
Returns : two-element list {window_name slice_id}
Creates a histogram plot and a top level Tk widget which allow for
convenient interactive slicing of 2d and 3d histograms. Works only if
you have Tk version 8.3 or newer. $parent_id is the Histo-Scope id of
a 2d or 3d histogram to slice. Valid values of the axis arguments are:
X (or x) : widget controls which X coordinates to use in the slices
Y (or y) : widget controls which Y coordinates to use in the slices
Z (or z) : widget controls which Z coordinates to use in the slices
Only one slice axis can be specified with a 2d parent histogram (use an
empty string for axis2 or omit it). When both axis1 and axis2 are given,
$parent_id should refer to a 3d histogram and $axis1 must be different
from $axis2.
This command returns a two-element list. The first element of this list
is the name of the new toplevel slider window (a string), and the second
element is the Histo-Scope id of the slice histogram (an integer).
The Histo-Scope plot window will be named "sliceslide_$slice_id".
This plot window name can later be used with commands like hs::draw
and hs::comment.
hs::socket_status
Arguments : none
Returns : boolean
Returns 1 if the socket used for communication with the Histo-Scope GUI
is currently blocked, 0 if not. When more than one GUI is connected the
result is undefined.
hs::sort_ntuple $ntuple_id $column_names reverse_order?
Arguments : integer ntuple_id, list of strings column_names,
boolean reverse_order
Returns : nothing
Sorts the ntuple rows by the values in the given columns. The first
column in the list is the most significant. The second column in the
list will be taken into account to determine the order of two rows
if the first column values are the same for these rows. The third
column will be used if the second column is the same, and so on. By
default, the sorting is performed in the increasing order of given
column values. If the optional argument "reverse_order" is set to 1
then the sorting order is reversed.
hs::special_percentiles $id $suppress_zero $percentages
Arguments : integers id and suppress_zero, list of doubles percentages
Returns : list of doubles
Calculates percentiles for a set of 1d or 2d histogram bin values
(note, not bin positions!). $id is the histogram Histo-Scope id.
Zero bins are removed from the set if $suppress_zero != 0. The
percentage values should be be between 0.0 and 100.0, inclusive.
The length of the list of percentages is arbitrary. The returned
list of percentiles will have the same length.
hs::special_stats $id_source $suppress_zero
Arguments : integers id_source and suppress_zero
Returns : list of doubles {sum mean stdev min q25 median q75 max}
Calculates various statistics on histogram bin values (not bin
positions!). Zero entries are not used in any calculations if
$suppress_zero != 0. The following statistics are returned:
sum : sum of all bin values
mean : average of the bin values
stdev : standard deviation
min : minimum bin value
q25 : 25th percentile
median : median
q75 : 75th percentile
max : maximum bin value
The functions which treat 1d histograms as probability distributions
and calculate various statistics for bin positions are called
hs::1d_hist_stats, hs::1d_hist_shape, and hs::1d_hist_percentiles.
hs::stats_histogram $id_source $suppress_zero $id_fill $weight
Arguments : integers id_source, suppress_zero, and id_fill, double weight
Returns : nothing
Fills 1-d histogram with Histo-Scope id $id_fill using only bin values
but not bin positions of the histogram $id_source. If $suppress_zero != 0
then only non-zero entries from $id_source are used. $weight becomes
the weight argument for hs::fill_1d_hist. weight argument may also be
omitted in which case 1.0 is used as the weight.
hs::sum_category $category1 $category2 $result_category
Arguments : strings category1, category2, and result_category
Returns : nothing
Create a collection of new histograms (one-dimensional or
two-dimensional), and/or Ntuples, based on two existing categories of
data items. All such items within these categories are considered, and
it is assumed that the categories have parallel category trees below a
top prefix (e.g. from a hs::read_file call) and that the
uids/subcategories and binning properties are identical. Items with $uid
== 0 are skipped. For instance, category1 can be specified as "run23",
category2 as "run25", result_category as "run23_25". Then, if a
histogram exists both in "run23/tracking" and in "run25/tracking" with
identical uids and static properties, a new histogram with the same
uid will be created which is the sum, bin by bin, and with category
"run23_25/tracking". Since this routine is intended to accumulate
statistics, no arbitrary constant is provided. category1 and category2
are the top level categories of the categories to be summed. These
can be neither "" nor contain "...". result_category is the top
category for the newly created category.
hs::sum_file $filename $category $result_category
Arguments : strings filename, category, and result_category
Returns : nothing
Read all of the items from file, sum histograms and/or merge Ntuples
with those existing under the top category specified by category and
store all newly created items in a category specified by result_category.
This can be the same as category. Thus, to sum a bunch a files, one can
read the first one by calling
hs::read_file $file_1 "allsum"
and loop over the others, calling repetitively
hs::sum_file $file_n "allsum" "allsum"
The items read from the file will not be kept in memory. A known
deficiency of this routine is that it assumes that there is no top
category already named "tmp_sum_file" or "tmp_sum_result".
Example
-------
To sum three files with names file1.hs, file2.hs, and file3.hs do:
hs::initialize "Example"
hs::read_file "file1.hs" "allsum"
hs::sum_file "file2.hs" "allsum" "allsum"
hs::sum_file "file3.hs" "allsum" "allsum"
hs::sum_histograms $uid $title $category $id1 $id2 $const1 $const2
Arguments : integer uid, strings title and category,
integers id1 and id2, doubles const1 and const2
Returns : integer
Creates a new histogram (one-dimensional or two-dimensional) whose data
is the sum, bin by bin, of two histograms specified by Histo-Scope
identification numbers id1 and id2. Each bin value of the new histogram
will be equal to const1 * bin value of histogram id1 + const2 * bin
value of histogram id2. const1 or const2 can be 0., or one of the id's
can also be set to 0, in which case the corresponding histogram will
not be referenced and the new histogram will simply be the other
histogram multiplied by its constant. The resulting histogram has
number of fills set to number of bins. Errors are propagated assuming
that these errors are Gaussian (i.e. "negative" errors are ignored).
uid is the User Identification for the newly created histogram. title
defines the title for the new histogram. category is a string defining
a hierarchical "location" for the histogram. Subcategories can be
specified using the "/" character as in UNIX file specifications. If a
category or subcategory does not exist, it is created. If the category
argument is "" then the histogram will appear in
the top level category. Returns the id of the new histogram containing
the sum of the two histograms, or throws a tcl error if the operation
could not be performed. An error is thrown if, for example, both
histograms do not exist, the histogram types are different, or the
number of bins or low/upper edges are inconsistent.
hs::sum_ntuple_columns $id_result $id1 $column1 $id2 $column2 ...
Arguments : integers id_result, id1, column1, id2, column2, ...
Returns : nothing
Sums ntuple columns specified by the ntuple ids and column numbers
given, and writes the result into the ntuple with id $id_result.
The ntuples with ids $id1, $id2, etc. must all have the same number
of entries. The number of columns to sum must be at least 1. The sum
is calculated separately for each row (columns are added as vectors).
The result ntuple must contain a single column. Previous contents of
the result ntuple will be deleted.
hs::swap_data_errors $id $errtype
Arguments : integer id, string errtype
Returns : nothing
Swaps data and errors of the histogram with Histo-Scope id $id. The
overflow bins are reset. The argument $errtype controls which errors
are swapped. The allowed values for $errtype are "pos" and "neg".
If the histogram has no errors of the requested type then the data
bins are filled with zeros.
hs::tcl_api_version
Arguments : none
Returns : string
Returns the tcl API version, for example "1.1". If after the version
number is says "original" that means that the Histo-Scope distribution
hasn't been patched when the API was compiled. See the tcl API README
file for more details about the patch.
hs::tcl_command_template $command $filename
Arguments : strings command and filename
Returns : nothing
Generates a template C file named $filename for a tcl command named
$command implemented in C. Note that the file will be overwritten if
it already exists. The file can later be compiled, loaded, and unloaded
dynamically using the hs::sharedlib_compile and hs::sharedlib commands.
hs::tempdir
Arguments : none
Returns : a string
Returns the name of a directory where the hs extension writes temporary
files and compiles shared libraries (by default, it is "/tmp"). For
security reasons, it is recommended that users overwrite this procedure
so that it returns the name of a directory writable only by the user.
For example,
namespace eval ::hs:: {
proc tempdir {} {
return "/home/joe/tmp"
}
}
hs::tempfile $prefix $suffix
Arguments : strings prefix and suffix
Returns : two-element list of strings {filename channel}
Opens a file named ${prefix}XXXXXXXXXX$suffix where each X is replaced
by a random letter or digit. The command checks that a file with this
name does not exist in the file system before opening it. Because of
a potential race condition and for other security reasons the file is
open with attributes RDWR CREAT EXCL TRUNC and read-write permission
for the user only. This command returns a list {filename channel} whose
first element is the name of the new file and the second element is
the tcl channel identifier.
hs::title $id
Arguments : integer id
Returns : string
Returns the title string for a given Histo-Scope id. This function
produces an error (which you might want to catch) if an item with this
id does not exist.
hs::transpose_histogram $uid $title $category $id
Arguments : integers uid and id, strings title and category
Returns : integer
Creates a new 2-d histogram with specified user id, title, and category
by swapping X and Y axes of the 2-d histogram with Histo-Scope id $id.
See the description of hs::create_2d_hist command for the detailed info
about uid, title, and category arguments. The appearance of the new
histogram is a mirror image of the original one. This command returns
the Histo-Scope id of the new histogram or throws a tcl error.
hs::transpose_ntuple $uid $title $category $id
Arguments : integers uid and id, strings title and category
Returns : integer
Creates a new ntuple with specified user id, title, and category by
swapping rows and columns of the ntuple with Histo-Scope id $id. See
the description of hs::create_ntuple command for the detailed info
about uid, title, and category arguments. The variables of the new
ntuple will be named "r0", "r1", "r2", ..., and the number of variables
will be equal to the number of rows in the ntuple with id $id. This
command returns the Histo-Scope id of the new ntuple.
hs::type $id
Arguments : integer id
Returns : string
Returns the type of the item referred to by id. Valid types are:
"HS_1D_HISTOGRAM"
"HS_2D_HISTOGRAM"
"HS_3D_HISTOGRAM"
"HS_NTUPLE"
"HS_INDICATOR"
"HS_CONTROL"
"HS_TRIGGER"
"HS_NONE"
"HS_NONE" refers to a non-existent item.
hs::uid $id
Arguments : integer id
Returns : integer
Returns the user-specified identification number (uid) value for a
given Histo-Scope id, or 0 if id was invalid or not found.
hs::unbinned_ks_test $id1 $varname1 $id2 $varname2
Arguments : integers id1 and id2, strings varname1 and varname2
Returns : two-element list of doubles {cl distance}
Performs the Kolmogorov-Smirnov test on the data from column named
$varname1 in the ntuple with Histo-Scope id $id1 and the data from
column named $varname2 in the ntuple with Histo-Scope id $id2. Returns
the test confidence level and the Kolmogorov distance between the two
samples.
hs::undo
Arguments : none
Returns : nothing
Deletes objects created by the commands hs::draw, hs::comment, hs::epsf,
and hs::latex in the reverse order of their creation. Up to 100 most
recent objects may be deleted.
hs::uniform_random_fill $id $num_points option? value? ...
Arguments : integers id and num_points, various options are
supplied as strings
Returns : nothing
Fills a histogram or an ntuple with Histo-Scope id $id with uniformly
distributed random points. Ntuples are filled so that each variable is
uniformly distributed between 0 and 1. $num_points rows are added to
the ntuple. By default, histograms are filled uniformly over their
ranges, $num_points entries added with unit weight. This behavior can be
modified using optional switches. The following switches are supported:
-weight $W Double. Can be used to modify the weight
used for histogram filling.
-xmin $Xmin -xmax $Xmax All these option take double values. They
-ymin $Ymin -ymax $Ymax can be used to modify the range in which
-zmin $Zmin -zmax $Zmax the random numbers are produced.
hs::unique_rows $uid $title $category $id $variable_names
Arguments : integers uid and id, strings title and category,
list of strings variables_names
Returns : integer
Creates a new ntuple whose variables are identical to the variables
of the ntuple with Histo-Scope id $id and fills it with a subset
of data from the original ntuple. In this subset, the combination
of values in the columns specified by the variable_names argument
will be unique. If $variable_names is an empty list then the new
ntuple will be just a copy of the old one. The new ntuple will have
the user id, title, and category as specified by the function arguments.
The Histo-Scope defined id for the new item is returned or a tcl error
is thrown on failure.
hs::unpack_item $prefix $bstring
Arguments : string prefix, binary string bstring
Returns : integer
Unpacks a Histo-Scope item previously encoded with the hs::pack_item
command. If the "prefix" argument is not an empty string then the item
category string will be prefixed accordingly. This command returns
the id of the unpacked item.
hs::unpack_ntuple_row $id $packed
Arguments : integer id, binary string packed
Returns : nothing
Decodes a binary string created earlier with hs::pack_ntuple_row
command and fills the ntuple with id $id using decoded row contents.
The number of columns in the ntuple whose row is being decoded must
coincide with the number of columns in the ntuple with id $id.
hs::use_color_scale $tag
Arguments : string tag
Returns : nothing
Sends the color scale information to Histo-Scope which remembers it
and allocates pixels on the screen. When this is done, the information
about the scale contents is no longer sent together with data plotting
requests. This speeds up the program communications. The down side is
that this color scale uses up available colors on the screen. This
may be important for older displays which use only 8 bits per pixel.
$tag must be a valid color scale tag returned by one of the commands
hs::create_general_color_scale or hs::create_linear_color_scale.
hs::variable_index $id $name
Arguments : integer id, string name
Returns : integer
Returns the index (the column number in the Ntuple) corresponding
to a given variable specified by its mnemonic name, for a given Ntuple
specified by id. An exact match is required between name and one of the
variable's names defined in the Ntuple. If no match is found, returns
-1. This routine does not check for multiple matches, it successfully
completes at the first occurrence of name.
hs::variable_name $id $column
Arguments : integers id and column
Returns : string
Returns the name of a given variable for the Ntuple
specified by id. column is the variable index (column number)
and name is the mnemonic name of this variable in the Ntuple.
hs::wait_num_scopes $operator $number
Arguments : operator $operator, integer $number
Returns : nothing
This command waits until a certain condition is true about the
number of connected Histo-Scope programs. For example, when you use
"hs::histoscope 1" command in your application, you should wait
until the client is connected before sending any configuration
strings to the GUI. This can be accomplished by using
hs::wait_num_scopes > 0
Allowed values for the $operator argument are >, <, >=, <=, ==, !=
This command will time out if after 1 min of waiting the condition
is still not satisfied.
hs::weighted_column_stats $ntuple_id $column_number $weight_column_number
Arguments : integers ntuple_id, column_number, and weight_column_number
Returns : list of doubles {sum mean stdev min q25 median q75 max}
Calculates various statistics on the contents of one column in an ntuple
weighted by the values of another column. All weights are required to be
non-negative. The following statistics are returned:
sum : sum of all weights
mean : average of the weighted values
stdev : standard deviation
min : minimum value
q25 : 25th percentile
median : median
q75 : 75th percentile
max : maximum value
hs::weighted_unbinned_ks_test $id1 $xvar1 $weightvar1 $neff1 \
$id2 $xvar2 $weightvar2 $neff2
Arguments : integers id1, neff1, id2, and neff2, strings xvar1,
weightvar1, xvar2, and weightvar2
Returns : two-element list of doubles {cl distance}
Performs the Kolmogorov-Smirnov test on the data from column named
$xvar1 weighted by column $weightvar1 in the ntuple with Histo-Scope
id $id1 and the data from column named $xvar2 weighted by column
$weightvar2 in the ntuple with Histo-Scope id $id2. Weight column
names may be specified as empty strings in which case all corresponding
weights are set so 1. $neff1 and $neff2 are the effective numbers of
points to use for this test. Returns the test confidence level and
the Kolmogorov distance between the two samples.
hs::window_names_distinct $onoff
Arguments : boolean onoff
Returns : nothing
Turns on or off checking that the names of all simultaneously displayed
windows are distinct. This checking affects the behavior of various
commands which use window names such as hs::show_histogram, hs::overlay,
hs::close_window, or hs::comment. When checking is on, the hs extension
remembers which windows are open and which are closed, and generates
error messages when, for example, an attempt is made to display two
windows with the same name or to draw a label in a window which has
already been closed. However, this mechanism is not reliable during
interactive sessions when the users can open and close windows using
the Histo-Scope GUI and the window manager (the hs extension is not
aware of these events). Therefore, default is to use this checking in
batch mode (when the value of global variable "tcl_interactive" is 0)
and to turn it off in interactive mode.
The hs::calc command
--------------------
The "hs::calc" command has four different forms:
hs::calc id
Returns the name of a Tcl handle associated with the Histo-Scope
histogram identified by id. A new handle is created if it does not
exist and id refers to a histogram. "Handle" is a Tcl jargon for
a command associated with some data structure. In this case the data
structure is the Histo-Scope histogram. The handle name always starts
with "hs::calc_". If you are using hs::calc, do not create your own
Tcl commands or procedures whose names start with "hs::calc_".
hs::calc purge
Deletes all existing Tcl handles associated with Histo-Scope
histograms. If a histogram is associated with a Tcl handle
and belongs to the Histo-Scope category "Hs_calc_tmp" then it
is also deleted. Use "hs::change_category" command if you want
to preserve some of these histograms.
hs::calc count
Returns the number of Histo-Scope histogram handles created after
the last purge operation.
hs::calc manual
Prints this description to the standard output.
Usage of histogram handles
--------------------------
In the explanations below it is assumed that variables h1 and h2 have
been created as follows:
set h1 [hs::calc $id1]
set h2 [hs::calc $id2]
where $id1 and $id2 are some valid Histo-Scope histogram ids.
$h1 returns the name of the handle
$h1 id returns id of the associated histogram
$h1 type returns type of the associated histogram (HS_1D_HISTOGRAM,
HS_2D_HISTOGRAM, or HS_3D_HISTOGRAM)
$h1 uid returns user id of the associated histogram
$h1 title returns histogram title
$h1 categ returns histogram category
$h1 bin returns binning information for the associated histogram.
The info is returned as {xmin, xmax, nbins} list for
a 1d histogram, as {xmin, xmax, n_x_bins, ymin, ymax,
n_y_bins} list for a 2d histogram, and as {xmin, xmax,
n_x_bins, ymin, ymax, n_y_bins, zmin, zmax, n_z_bins}
list for a 3d histogram.
$h1 stats returns statistics for the associated histogram.
The info is returned as {mean, std_dev} list for a 1d
histogram, as {x_mean, y_mean, x_std_dev, y_std_dev}
list for a 2d histogram, and as {x_mean, y_mean, z_mean,
x_std_dev, y_std_dev, z_std_dev} list for a 3d histogram.
$h1 sum returns the sum of all histogram bins
$h1 integ returns the associated histogram integral (sum of
all bins multiplied by the bin size).
$h1 min returns info for the lowest value bin. {bin_coord,
bin_number, bin_value} list is returned for a 1d histogram.
{x_bin_coord, y_bin_coord, x_bin_number, y_bin_number,
bin_value} list is returned for a 2d histogram.
{x_bin_coord, y_bin_coord, z_bin_coord, x_bin_number,
y_bin_number, z_bin_number, bin_value} list is returned
for a 3d histogram.
$h1 max returns info for the highest value bin. The order of the
elements in the returned list is the same as for the "min"
operation.
$h1 print dumps histogram data to the standard output
$h1 show displays the histogram in a separate window
$h1 del deletes the handle. The associated histogram
is deleted if it is in the "Hs_calc_tmp" category.
Unary mathematical operations
-----------------------------
All unary operations return a handle for the new histogram which is
created by applying, bin-by-bin, some unary operation to the bin
contents of the associated histogram. The new histogram is placed
in the "Hs_calc_tmp" category, and it has no title. No attempt
was made to ensure the correct propagation of errors in all these
operations, so don't assume that the errors in the new histograms
are correct. Overflow bins are discarded.
$h1 /-/ unary minus
$h1 /+/ unary plus (histogram copy)
$h1 deriv derivative (the histogram associated with handle $h1
must be one-dimensional).
$h1 ~ logical NOT
$h1 abs absolute value
$h1 sign "sign". The "sign" operation returns 1 for positive
argument, -1 for negative argument, and 0 for zero argument.
$h1 sqrt square root
$h1 ssqrt "safe square root". The "safe square root" returns
square root for positive arguments and 0 for non-positive.
$h1 exp exponent
$h1 log logarithm
$h1 slog "safe logarithm". Returns logarithm for positive arguments
and -1000.f for non-positive.
$h1 erf error function
$h1 gerf Gaussian cumulative distribution function with mean 0
and width 1.
$h1 trans transpose. Works with 2d histograms only.
Binary mathematical operations
------------------------------
All binary operations return a handle for the new histogram which is
created by applying, bin-by-bin, some binary operation to the bin
contents of two histograms or to the bin contents of one histogram and
to a constant. The new histogram is placed in the "Hs_calc_tmp"
category, and it has no title. The usage is as follows:
$h1 operator $h2
or
$h1 operator const
where "operator" is one of the following:
+, -, *, /, <, >, <=, >=, !=, ==, **, ^, |, &, ||, &&, @, min, max, hypot
Both ** and ^ mean power. | and & mean bitwise OR and AND, respectively
(arguments are converted to integers before the operation is performed,
and the result is converted back to float). It is the responsibility of
a user to ensure that bitwise operations make sense. || means logical OR,
&& means logical AND, @ means concatenate histograms side by side
(the histograms will be tested for bin-compatibility first).
When the first form (with two handles) is used, the operation will
result in error if the associated histograms are not bin-compatible.
When the second form (with constant) is used, a temporary histogram
is created and deleted in the "Hs_calc_tmp" category as a side effect.
The operators must be separated by spaces from both first and second
arguments. No attempt was made to ensure the correct propagation of
errors in all these operations, so don't assume that the errors in
the new histograms are correct. Overflow bins are discarded.
Special histogram operations
----------------------------
-- Get a value of a particular bin in a 1d histogram:
$h1 value bin $x_bin_num
$h1 value coord $x
-- Extract a part of a 1d histogram:
$h1 subrange $x_bin_min $x_bin_max
-- Get a value of a particular bin in a 2d histogram:
$h1 value bin $x_bin_num $y_bin_num
$h1 value coord $x $y
-- Create a 2d histogram slice:
$h1 slice bin x $x_bin_num
$h1 slice bin y $y_bin_num
$h1 slice coord x $x_value
$h1 slice coord y $y_value
-- Extract a part of a 2d histogram:
$h1 subrange x $x_bin_min $x_bin_max
$h1 subrange y $y_bin_min $y_bin_max
-- Create a 2d histogram projection:
$h1 project x $projection_type (projects onto x axis)
$h1 project y $projection_type (projects onto y axis)
where $projection_type is one of the following: "min", "max",
"sum", "mean", or "median".
Example
-------
[[[hs::calc 14] + [hs::calc 17]] / 2] id
returns an id of the new histogram which is an average of histograms
14 and 17 (provided that these histograms exist and have identical
bin structure).
Introduction
------------
To fit your data to a model, you will need to construct the fit using
the hs::fit command and, possibly, the fit handle command returned by
hs::fit. The following information has to be provided:
-- A complete list of datasets which will be fitted (histograms or ntuples,
in case ntuples are fitted one has to specify the columns used). An
arbitrary number of datasets can be fitted simultaneously.
-- A set of functions to use in the fit.
-- Function assignments to datasets. Each dataset may be fitted with
several functions (the functions are simply added), and the same
function may be assigned to more than one dataset. The latter is
useful when, for example, a function is used to fit the background
shape in a sample which contains a signal, and the same function
is used to fit a background-only control sample.
-- A set of parameters for your model.
-- A mapping from the model parameters into the parameters of fitting
functions.
-- The choice of the fitting method (least-squares, maximum likelihood, etc).
-- Optionally, one can provide dataset filters (these can be used to
make exclusion regions).
In reality, the fit construction is usually much simpler than the above
description sounds because very often you can rely on the defaults built
into the hs extension.
A Simple Fitting Example
------------------------
Here is a simple example. Suppose, one wants to fit a Gaussian distribution
to a 1d histogram with Histo-Scope id $id, and this histogram has its own
errors. This can be accomplished as follows:
# Let's create an example histogram here
set id [hs::create_1d_hist 1 "Example histogram" "Tmp" "X" "Y" 20 -2 4]
hs::1d_hist_block_fill $id [hs::list_to_data {0 2 1 2 8 6 14 19 18 20 \
22 26 21 10 13 8 6 3 0 1}] [hs::list_to_data {1 1.4 1 1.4 2.8 2.4 \
3.7 4.4 4.2 4.5 4.7 5.1 4.6 3.2 3.6 2.8 2.4 1.7 1 1}]
# Fit this histogram using the Gaussian distribution
set fit [hs::fit $id gauss] ;# Create the fit handle.
$fit fit ;# Perform the fit.
$fit show ;# Plot the fitted curve on top of the data.
$fit print ;# Print various information, including fitted
;# parameter values, their errors, and chi-square
;# goodness-of-fit test confidence level.
In this example, the command which specifies all necessary fitting information
is "hs::fit $id gauss". The first arguments of the hs::fit command provides
the list of fitted datasets. In our example, this list consists of just one
element, and this element is the Histo-Scope id of the fitted histogram.
The second argument of the hs::fit command is the list of functions which
will be applied to every dataset listed in the first argument. Each element
of this list must be a valid function tag as defined by hs extension commands
hs::function_import, hs::function_compose, etc. "gauss" is the tag assigned
to the Gaussian probability density function by the code which initializes
the hs extension.
In the above example the creation of model parameters happens automatically.
By default, the model parameters are the combined parameters of all functions
used in the hs::fit command, and they are mapped one-to-one to the function
parameters. The fitting method is not specified explicitly, therefore the
default procedure is used (least squares minimization). No dataset filters
have been provided, consequently all histogram bins are used in the fit.
Fitting Methods
---------------
The fitting method may be specified either globally, for all fitted
datasets, using the "-method" option of the hs::fit command, or for
each dataset separately, using the "-method" option in each dataset
specification (this takes precedence over the global method). For example,
the fit in the above example can be changed to use extended maximum
likelihood if the "hs::fit $id gauss" command is modified as follows:
hs::fit $id gauss -method eml
The following fitting methods are supported by the hs extension:
1) "L2" -- minimizes the distance between the data and the fit in the L2
norm (equivalent to least squares with all weights equal). This method
is usually used to fit one dataset at a time when error estimates for
the data points are not available. Fitting more than one dataset is
not recommended whenever L2 method is used because different datasets
often have dissimilar error scales.
2) "ls" -- least squares minimization, errors are provided by the user
either as histogram error data or as an ntuple column. This is the default
fitting method.
3) "chisq" -- least squares minimization, errors are assumed to be equal to
the square root of the number of events predicted by the fit (so-called
Pearson's chi-square minimization).
4) "ml" -- maximum likelihood method. In this method the user is supposed
to take care of the function normalization, usually by fixing the relevant
fit parameter.
5) "eml" -- extended maximum likelihood. The function normalization is taken
care of automatically, but in case of an unbinned fit the user is supposed
to define a grid which will be used to calculate the fit area numerically.
Note that unbinned fits may be performed only with methods 4) and 5).
Dataset Specifications
----------------------
The hs::fit command takes the list of datasets to fit as its first argument.
Each element of this list is itself a list which specifies one dataset. All
individual dataset specifications must look like this:
{id ?opt1 value1? ?opt2 value2? ...}
The first element is the Histo-Scope id of an item to fit (a positive
integer). This item must be either a histogram (1d or 2d) or an ntuple.
All other elements come as option-value pairs. The following options
may be used:
-weight $W Specifies the dataset weight in the fit ($W should be
a non-negative double). The default weight is 1. It may
be useful to change a weight of some dataset to 0 when
several datasets are fitted simultaneously in order to
study the effect of this particular dataset on the fitted
parameter values.
-method $M Specifies the fitting method for this dataset. Possible
M values are "L2", "ls", "chisq", "ml", and "eml". If this
switch is not provided then the fit default method will be
used for this dataset. This switch should not be used unless
it is absolutely necessary because the interpretation of
parameter errors in the mixed-method fit is less clear.
When the fitted item is an ntuple, each ntuple row represents one data
point. In this case, the following additional options may be used:
-x $Xcol Specifies the ntuple column name used to define x coordinates
of the data points. This option is required for ntuple fits.
-y $Ycol The ntuple column which defines y coordinates. This option
is needed for 2d and 3d datasets only.
-z $Zcol The ntuple column which defines z coordinates. This option
is needed for 3d datasets only.
-v $Vcol The ntuple column which defines data values for the given
coordinates.
-e $Ecol The ntuple column which defines data errors.
If the -v switch is not provided for an ntuple then the fit is unbinned,
otherwise the fit is said to be binned even though the positions of
the data points are arbitrary.
Note that it is not necessary to include all datasets at once into the
hs::fit command. More datasets can be added later, using the fit handle.
Here is an example fit which uses an ntuple as a dataset:
set id [hs::create_ntuple 2 "Example ntuple" "Tmp" {x data error random}]
for {set i 1} {$i <= 10} {incr i} {
set random [expr 2*([join [hs::random 12] +] - 6.0)]
set data [expr {$i*$i + $random}]
hs::fill_ntuple $id [list $i $data 2 $random]
}
set fit [hs::fit [list $id -x x -v data -e error] poly_1d]
$fit parameter x0 configure -value 0 -state fixed
$fit fit
$fit show
Another example makes an unbinned fit using the same ntuple:
set fit [hs::fit [list $id -x random] gauss -method ml]
$fit parameter area configure -value 10 -state fixed
$fit fit
$fit show
Fit Functions
-------------
The second argument to the hs::fit command is the list of functions used
to fit every dataset. Each function tag in the fit must be distinct. This
is because the tags correspond not only to the functions themselves but also
to the mappings from the model parameters into the function parameters.
Therefore, in order to include the same function more than once (e.g., fit
some data with a sum of two Gaussians) one has to duplicate the function
first. This can be done using the "copy" operation of the hs::function
command. Example:
hs::function gauss copy gauss1
hs::fit $id {gauss gauss1}
It is not necessary to provide the list of all functions used in the fit
as the argument to the hs::fit command. In fact, when more than one dataset
is fitted simultaneously, this argument is usually an empty list because
the cases when the same function with the same set of parameters can be
usefully employed to fit different datasets are not very common.
Fit Handles
-----------
The hs::fit command returns a handle (sometimes called an "object command"
by tcl programmers) which can be used to perform various operations, set and
examine fit parameters, configure fitting options, plot the results, etc.
The handles may be invoked with the following options:
$handle
When invoked without any additional arguments, the handle command
returns its own name.
$handle id
Returns the unique fit id. This id stays the same even if the handle
command is renamed.
$handle copy ?newhandle?
Creates a copy of the fit data and returns a new handle. The name of
the new handle may be specified as the optional string argument
"newhandle". Without this argument, a new unique command name is
generated automatically.
$handle delete
Deletes the fit and the associated handle.
$handle configure ?option1 value1? ?option2 value2? ...
Configures various fit options. The following options are available:
-title $T Specifies the fit title which will be used in various
printouts. Minuit printouts can only use the first
50 characters of the title string.
-description $D Specifies the fit description (an arbitrary string).
The default D value is an empty string.
-method $M Sets the default fitting method which will be
assigned to every dataset which does not explicitly
specify its fitting method. The allowed M values
are "ls", "L2", "chisq", "ml", and "eml". The default
M value is "ls".
-warnings $Warn If set to "false", instructs Minuit to suppress
warning messages about suspicious conditions which
may indicate unreliable results. The default is
to print such messages.
-status $Stat Specifies the fit status. $Stat must be either "ok"
or "error". The default value is "ok". This option
affects the internal behavior of the fitting code,
and should not normally be set by the application.
-gradient $G $G is a boolean value which specifies whether Minuit
should use an external procedure to calculate
the function gradient over parameters. Right now,
this option should be left at its default value of 0.
-ignore $Ign If $Ign is set "true", the program will not print
error messages generated by fitting functions.
The default Ign value is "false".
-errdef $UP Sets Minuit value of UP defining parameter errors.
Minuit defines parameter errors as the change in
the parameter value required to change the function
value by $UP. Unless you know exactly what you are
doing, leave this option at its default value of 1.0.
-precision $Eps Informs Minuit that the relative floating point
arithmetic precision is $Eps. The default value
of this option is 0.0 which means that the program
will use the system default for doubles.
-strategy $Stra Sets the Minuit strategy to be used in calculating
first and second derivatives and in certain
minimization methods. Low values of $Stra mean fewer
function calls and high values mean more reliable
minimization. Currently allowed values are
0, 1 (default), and 2.
-minimizer $Min Sets the Minuit minimization method. $Min must be
one of the keywords "migrad", "mini", or "simplex".
Default is "migrad".
-minos $Use If $Use is false, instructs the program _not_ to run
MINOS after the minimizer. The default is "true".
-verbose $Level Minuit verbose level:
-1 -- no output except from SHOW commands
0 -- minimum output (no starting values
or intermediate results)
1 -- Minuit "normal" output
2 -- print intermediate results
3 -- show the progress of minimization
The default value of this option is 0.
-timeout $sec Timeout in seconds for the Minuit main loop. 0 or
negative values mean no timeout will be set (this
is the default). Note that timeout does not immediately
stop the main loop since Minuit is not capable of
receiving status information from the fitted function.
Instead, the code modifies the total number of function
calls allowed. As a consequence, Minuit prints somewhat
misleading message to the standard output that the call
limit is exceeded, but the interpreter result contains
the correct diagnostics.
$handle cget $option
This command can be used to examine various fit properties.
The following options are supported: -compiled, -complete, -description,
-errdef, -gradient, -method, -precision, -strategy, -title, -epars, -emat,
-verbose, -ignore, -warnings, -psync, -osync, -dlls, -ministat, -minos,
-minimizer, -wpoints, -timeout, and -status. Most switches have the same
meaning as in the "$handle configure" command. Additional switches are:
-compiled With this switch, the command returns 1 if all parameter
mappings and dataset filters have been compiled, and
0 otherwise.
-complete Returns 0 if there were parameter or mapping changes since
the last minimization run or if the minimization has never
been performed, otherwise returns 1.
-epars Returns the list of parameters for which the error matrix
has been estimated, or an empty list if the matrix has never
been calculated.
-emat Returns the error matrix as a list whose elements are
the matrix rows, or an empty list if the matrix has never
been calculated.
-osync Returns 1 if the fitting options have been passed to Minuit
since the last change, 0 otherwise.
-psync Returns 1 if the fit parameters have been synchronized with
Minuit, 0 otherwise.
-dlls Returns the list of shared libraries which may be unloaded
when the fit is deleted.
-ministat Returns the minimization status as a list
{fmin fedm errdef npari nparx istat}. See the description
of the Minuit subroutine MNSTAT for the meaning of the list
elements. This will be an empty list if the minimization
has not been performed yet after the last configuration
change.
-wpoints Returns the combined total weighed number of points in all
datasets used to calculate the minimization statistics
during the most recent FCN call.
These additional switches correspond to the fit properties which can be
examined from tcl but can not be set explicitly using "configure".
$handle subset opt1? value1? ...
This command manipulates the fit datasets. The following forms may be used:
* $handle subset add $dataset_specifier opt? value? ...
Adds a new dataset to the fit and returns the dataset id (an integer).
dataset_specifier is a list which specifies Histo-Scope histogram or
ntuple to fit. The structure of this list has already been described
in the "Dataset Specifications" section. The following options are
supported:
-filter $filter_code Specifies the filter expression (in C notation)
which will be applied to all dataset points
before they are fitted. The filter code can only
depend on the data point coordinates but not on
the point values. It can use variables x, y,
and z, and must result in an integer value.
A point will be accepted if the result of
the filter expression on the point coordinates
is not 0. For example, the expression
{x < 1 || x > 2} defines an exclusion region
[1, 2]. The C code generated from such filter
expression looks like this:
int filter(double x, double y, double z)
{
return ( x < 1 || x > 2 );
}
The default filter_code value is an empty string
which means that all data points will be used
in the fit. You can use all functions defined
in the standard C headers inside your filter
expression.
-functions $fun_list Specifies the list of tags of the functions
which will be used to fit the dataset. All
these functions will be summed in the fit.
-normregion $descr Specifies the region to use for calculation
of the fit normalization. This option may be
used with unbinned fits only. The descr argument
is a flat list which contains 3 numbers for
every dimension of the dataset: min, max, and
number of intervals to use. For example, this
is how $descr may look like for a 2d fit:
{-5.0 5.0 50 -10.0 10.0 100}. $descr may be
an empty list in which case the normalization
region becomes undefined.
* $handle subset count
Returns the upper limit for the dataset ids in the fit. Note that this
number is not necessarily equal to the total number of datasets since
their ids are not required to be contiguous.
* $handle subset list
Returns the list of ids of datasets used in the fit.
* $handle subset $id $subcommand opt1? value1? ...
Manipulates the dataset identified by $id in the fit. The following
subcommands are supported:
exists Returns 1 if dataset identified by $id
exists in the fit, 0 otherwise.
delete Removes the dataset identified by $id
from the fit. Also, removes functions which
were used to fit just this particular dataset
(note that in such a case fit parameters may
have to be redefined).
info Returns the information about the dataset
identified by $id in the form of a list
{id ndim binned columns filter_string \
functions weight method points normregion}
id -- Histo-Scope id of the data item
ndim -- dataset dimensionality
binned -- set to 1 for binned datasets,
to 0 for unbinned
columns -- five-element list of ntuple
column numbers used to define
x, y, z, data value, and
errors. For histograms, all
these numbers are set to -1.
filter_string -- dataset filter expression
functions -- the set of fitting functions
weight -- the dataset weight in the
statistic being minimized
method -- fitting method to use for this
dataset.
points -- the number of points used to
calculate the minimization
statistics during the most
recent FCN call.
normregion -- normalization region for
an unbinned dataset (or an
empty list if undefined).
stats $what $quantities Returns basic statistical information
about the data or fit. The "what"
argument must be either "data" or "fit".
The "quantities" argument is a a list
which may contain one or more of the
following keywords: npoints, is_pdf, sum,
mean_x, mean_y, mean_z, s_x, s_y, s_z,
rho_xy, rho_xz, rho_yz. If the fit has been
completed then the result will be a list
of values with the same number of elements
and in the requested order. If the fit has
not been completed, the command generates
a tcl error. The fit stats are not calculated
in case an unbinned fit is done using the
"ml" method because in this case we don't
know the support of the fitting function.
The keywords have the following meaning:
npoints -- Number of points used in the fit
(that is, points which passed the
filter and did not cause any
function errors). For data, this
is the same as the result of
"$handle subset $num cget -npoints"
command. For the fit, this may
depend on the grid used for
function normalization (this will
be set to 0 in case of unbinned
"ml" fit).
is_pdf -- This is set to 1 if all values
are non-negative.
sum -- The total number of events. In the
binned case, this is just the sum
of bin values (for the fit it uses
Simpson's integration rule in
which bins are taken to be
integration intervals). In the
unbinned case, for the data this
is just the total number of points
used in the fit. For the unbinned
"eml" fit, this is the fit area
covered by the grid of points used
in the fit. For the unbinned "ml"
fit it is undefined.
mean_x -- Mean x value.
s_x -- X standard deviation.
rho_xy -- XY correlation coefficient.
All other keywords are self-explanatory.
The values corresponding to these keywords
will make sense only if npoints > 0,
is_pdf == 1, and the dimensionality of the
fit is sufficient for creation of relevant
statistics.
configure opt? value? ... Sets the dataset attributes. Available
options are -filter, -functions, -method,
-normregion, and -weight. The meaning of
these options is the same as in the dataset
specifiers and in the "$handle subset add"
command.
cget $option Returns the dataset property identified
by $option. In addition to the standard
configurable options -filter, -functions,
-method, -normregion, and -weight, the
following options are available read-only:
-id, -ndim, -binned, -columns, -points.
The values returned for these options are
the same as the corresponding elements in
the list produced by the "info" subcommand.
Also, there are several special options which
are not directly related to the dataset
definition: -validmethods, -ndof, and -chisq.
Option -validmethods may be used to return
the list of all fitting methods compatible
with this dataset. Options -ndof, and -chisq
return the number of points used in the
chi-square test and the chi-square value for
the fitted data. Note that these options are
only meaningful when the fit is complete and
the dataset is binned, otherwise their return
values are 0.
compiledfilter dll? proc? When issued without the dll and proc
arguments, this subcommand returns 1 in case
the filter expression has already been
compiled and 0 otherwise. Optional dll and
proc arguments can be used to set the dll
number and the C function name to use for
the filtering functions. The proc argument
may be specified as an empty string in
which case the filter is removed (all point
will be used in the fit). It should not be
necessary for a user code to use this
subcommand.
ranges $scan_specifier Scans filter functions of 1-dimensional
datasets and returns the list of allowed
regions in the form {{min1 max1 npoints1} \
{min2 max2 npoints2} ...}. The scan_specifier
argument is a three-element list
{min max npoints} which defines the region
to scan and the density of trial points.
plotfit $result_specifier Fills a Histo-Scope item with fitted values.
$result_specifier is just an id for
a histogram or it must look like this
for ntuple: {id {min max npoints}}
in 1d case or {id {min1 max1 npoints1} \
{min2 max2 npoints2}} in 2d case.
fitvalues $uid $title \ This command calculates the fitted values
$category $is_difference at the coordinates of the data points.
"is_difference" is a boolean argument which
specifies if the program should calculate
the difference between the data and the fit
(when "true") or just calculate the fit.
The command will create the same kind
of Histo-Scope item as the one used
to represent the data: an ntuple or
a histogram. This subcommand returns
the Histo-Scope id of the result.
$handle function
This command manipulates data fitting functions. The following forms
can be used:
* $handle function add $funct opt1? value1? ...
Adds a data fitting function with tag $funct to the fit. $funct
must be a valid function tag as defined by commands hs::function_import,
hs::function_compose, etc. It is not possible to add a function
with the same tag to a fit more than once but it is possible to use
the same function with more than one dataset included in the same fit.
The following options are allowed:
-subsets $datasets $datasets is a list of dataset numbers to
which this function will be added. This option
may be omitted if the fit includes only one
dataset, but for fits with multiple datasets
this option is mandatory.
-mapping $codestring Specifies the mapping from fit parameters into
the function parameters. The mapping is either
a string of pseudo-C code or a special keyword
which designates a precompiled mapping. In the
pseudo-C code the fit parameters should be
designated by name or by number and prefixed
with the '%' character. The function parameters
are referred to by names. Here is an example
mapping:
{ double bin_width = 0.05;
area = %nevents * bin_width;
mean = %1;
sigma = sqrt(%variance); }
Besides the special designators for the fit
parameters (whose type should not be declared),
everything else should be normal C code which
can use all the functions provided in the
standard C headers. The character '%' itself
can be written as the "%%" sequence. The mapping
code will be compiled and loaded before the fit
is performed.
The following keywords may be used instead of
a C code map: "sequential", "identical", and
"null". Null mapping is the default mapping
for fitting functions without parameters, and
sequential mapping is the default for functions
with parameters.
-params $parlist $parlist specifies initial values of the function
parameters (which can be used, for example,
to plot the function) in a list of name-value
pairs. For example, {{mean 0.0} {sigma 1.0}}.
The default value for all parameters is 0.0.
* $handle function list
Returns the list of tags for data fitting functions used in the fit.
* $handle function $tag $subcommand opt1? value1? ...
Manipulates the fitting function identified by tag $tag in the fit.
The following subcommands may be used:
exists Returns 1 if the function with the given
tag is included into the fit, 0 otherwise.
info Returns the info about a function in a list
{name mapping offset subsets parlist}.
offset is the total number of parameters
in all preceding functions used to set up
the sequential parameter mapping.
delete Removes the function from the fit and all
its datasets.
compiledmap dll? proc? When issued without the dll and proc
arguments, this subcommand returns 1 in case
the mapping has already been compiled and
0 otherwise. Optional dll and proc arguments
can be used to set the dll number and the
C function name to use for mapping. dll
number can be -1 to indicate that one of
the precompiled maps should be used.
In this case a precompiled map keyword
should be used in place of the "proc"
argument (see the description of -mapping
option in the "$handle function add"
command for the list of such keywords).
Also, the "proc" argument can be set to an
empty string in which case the mapping
is removed (so that some code can later
install a default mapping). It should not
be necessary for a user code to use this
subcommand.
configure opt1? value1? ... Configures the options -subsets, -mapping,
and -params which have the same meaning as
in the "$handle function add" command.
cget $option Returns the function property identified
by $option. In addition to the standard
options -subsets, -mapping, and -params,
this subcommand supports convenience options
"-npars" which instructs it to return
the number of function parameters,
"-parnames" which returns the list of
just parameter names, and "-parvalues"
which returns the list of just parameter
values.
$handle parameter opt1? value1? ...
This command manipulates fit model parameters. The following forms
may be used:
* $handle parameter add $parname opt? value? ...
Adds a parameter named $parname to the fit. $parname must be different
from the names of already existing parameters in its first ten characters
(FORTRAN-like comparison, dictated by Minuit interface). The following
options are supported:
-value $v $h is the initial parameter value (default is 0.0).
-step $h $h is the initial parameter step size for Minuit.
It must be positive. The default h value is 0.1.
-state $s $s is one of the keywords "fixed" or "variable".
The default is "variable".
-bounds $blist $blist is a two-element list of parameter limits
{min max}. The default blist value is an empty
list which means that the parameter has no limits.
* $handle parameter list
Returns the list of fit parameter names.
* $handle parameter clear
Deletes all fit parameters.
* $handle parameter info
Returns the list of parameter definitions. Each element is itself
a list {name value state step bounds}.
* $handle parameter apply
Passes the current parameter definitions to Minuit. Returns nothing.
* $handle parameter $name $subcommand opt1? value1? ...
Manipulates the parameter named $name in the fit. The following
subcommands may be used:
delete Deletes the parameter named $name.
exists Returns 1 if the parameter named $name
exists, 0 otherwise.
set newvalue? Returns four-element list {value state \
step bounds} for the parameter named $name.
When newvalue is specified, sets the value
of an existing parameter. newvalue may be
either a double value or a four-element list.
configure opt1? value1? ... Sets the parameter properties. Available
options are -value, -state, -step, and
-bounds. The meaning of these options is
the same as in the "$handle parameter add"
command
cget $option Returns the parameter property specified
by $option. When the fit is finished, the
following options are available in addition
to the standard options -value, -state,
-step, and -bounds:
-error -- returns "parabolic" error
-eneg -- returns negative error from Minos
(as a negative number)
-epos -- returns positive error from Minos
-globcc -- returns the global correlation
coefficient. This is a number
between zero and one which gives
the correlation between the
parameter named $name and that
linear combination of all other
parameters which is most strongly
correlated with $name.
-errinfo -- returns the above four properties
in a single list
{error eneg epos globcc}.
$handle info
Returns the information about the fit in a 16-element mixed list. This
list has the following structure:
{title description default_fit_method minimizer minos minuit_options \
global_status timeout ignore_function_errors minimization_status \
parameters error_matrix_pars error_matrix_data dlls datasets \
fit_functions}
The list elements are:
title -- String. Fit title.
description -- String. Fit description.
default_fit_method -- String. Default fitting method which will be
assigned to every dataset which does not
explicitly specify its fitting method.
minimizer -- String. Minuit minimizer to use.
minos -- Boolean. It will be 1 if the fitting procedure
uses MINOS or 0 if MINOS is skipped.
minuit_options -- List {errdef verbose warn strategy eps grad}
global_status -- String "ok" or "error".
timeout -- Integer. 0 or negative means no timeout.
ignore_function_errors -- Boolean.
minimization_status -- List {fmin fedm errdef npari nparx istat}.
See the description of the Minuit subroutine
MNSTAT for the meaning of the list elements.
This will be an empty list if the minimization
has not been performed yet after the last
configuration change.
parameters -- The list of parameters. Each element is itself
a list {name value state step bounds}.
state is a string which is either "fixed" or
"variable". bounds is either an empty list
(unbounded) or a two-element list {min max}.
error_matrix_pars -- The list of names of parameters for which
the error matrix is defined (or an empty list
if the fit is not performed).
error_matrix_data -- Error matrix, each row (or column since it
is symmetric) is itself a list (or an empty list
if the fit is not performed).
dlls -- Dll numbers to unload when the fit is deleted.
datasets -- List of dataset info lists. Please see the
description of the command "$handle subset",
option info, for details about the dataset info
list structure.
fit_functions -- List of fitting function information lists.
Please see the description of the command
"$handle function", option info, for details
about the function info list structure.
Since the hs extension code is still under development, it is unwise to
assume that the number of elements in the fit info list will not change.
However, the new elements are most likely to be appended at the end,
so the following list splicing code should be reasonably safe:
foreach {title description ... fit_functions} [$handle info] break
where ... stands for all other list elements. Note the "break" command
at the end, not {}.
$handle fit ?maxcalls? ?tolerance?
Runs the Minuit minimization cycle after passing parameter values and
fitting options to Minuit. The optional argument "maxcalls" specifies
the (approximate) maximum number of function calls after which
the calculation will be stopped even if it has not yet converged. This
argument may be specified as an empty string (this is the default which
means that the procedure will run until the fit converges). The optional
argument "tolerance" specifies required tolerance on the function value
at the minimum. When "migrad" is used as the minimizer, the default
tolerance is 0.001 (which will also be used if tolerance is specified
as an empty string), and the minimization will stop when the estimated
distance to the minimum (EDM) is less than 0.001 * $tolerance * $UP,
where UP is the Minuit setting which defines parameter errors (see the
description of "$handle config" command, option -errdef). When "simplex"
is used as the minimizer, the minimization will stop when the EDM is less
than $tolerance. In this case the default tolerance value is 0.01 * $UP.
$handle show opt? value? ...
Plots the data and the fit. The plots will be overlayed when fitted
dataset is a 1d curve or a histogram, or they will be shown side-by-side
together with the difference plot in case the dataset is 2-dimensional.
Plotting of 3d datasets is not supported yet. This command can be used
with the following options:
-title $T $T specifies the window title
-info $b Boolean value $b specifies whether to show the parameter
information on top of the plot for the completed fit.
This option has no effect for fits to multiple datasets.
-font $F Specifies the font to use for axis labels. Use of this
option requires Tk. $F may be given in any form acceptable
by Tk, for example "Times 18 {bold italic}". X font names
may also be used (run "xlsfonts" program to see the names).
Note that not all fonts are supported in PostScript.
The command returns the list of multiplots shown (see the hs::multiplot
command description for details). The user should delete these multiplots
when they are no longer needed.
$handle contours $pname1 $pname2 opt? value? ...
Draws error contours for the fit parameters. $pname1 and $pname2 are
the names of the parameters. Valid options are:
-plotpoints $N Specifies the number of points to calculate on every
contour. $N must be a positive integer larger than 4.
The default N value is 200.
-levels $L $L must be a list of positive real numbers which
specifies how many contours to draw and how many
standard deviations they should be from the central
value. The default L value is {1 2 3}.
-show $Show $Show is a boolean value which specifies if the
plot should be displayed immediately. The default
value of this option is "true".
-font $F Specifies the font to use for axis labels. Use of this
option requires Tk.
This command returns the name of an overlayed plot which holds
the curves (see the hs::overlay command description for details).
$handle report $channel $format
Generates a report when the fitting is complete. $channel is a tcl
channel into which the report is written, and $format is the string
which specifies the report format type. At this time, only one format
type is supported: text.
$handle print
Equivalent to "$handle report stdout text".
$handle tune ?-font $fontname?
Starts a fitting GUI which can be used for parameter tuning, fit
plotting, report generation, etc. The "-font" option can be used to
specify the font for axis labels (see "$handle show" description for
details). The command returns the name of the new toplevel window.
$handle goodness $test mcsamples? show_progress?
Returns a fit confidence level from the specified goodness-of-fit test.
The following tests can be specified:
chisq One-sided chi-square goodness-of-fit test. Can be performed
only on binned fits which do not use the "L2" minimization
method.
ks "Classic" one-sided Kolmogorov-Smirnov test. Can only be
used with fits to 1d data. Note that it is almost always
a bad idea to rely on the confidence level returned by this
test since it was designed for comparison of two independent
distributions rather than for goodness-of-fit.
ksmc Kolmogorov-Smirnov test based on Monte-Carlo. Builds
a distribution of Kolmogorov distances by generating random
points according to the fitted distributions, and refitting
these random points. This test is much more reliable than
the "ks" test but it also takes more time. It can only be
used with fits to 1d data.
multires Multiresolution Gaussian smoothing test based on Monte-Carlo.
This test is very reliable, but it is also very slow, and it
works only with fits to single 1d datasets. The default number
of bandwidth settings to use is 20. This number can be changed
by modifying variable "::fit::Default_bandwidth_set_size".
The smallest bandwidth is 1/4 of the bin width (or 1/4 of the
normalization region interval width in case of unbinned fits),
and the largest bandwidth is 1/2 of the whole fitted region.
In between, bandwidth settings increase by a constant factor.
The argument "mcsamples" specifies the number of samples to generate
in Monte-Carlo based tests. When it is omitted or set to an empty string
the default number is used (1000). The "show_progress" argument specifies
whether the code should print out messages related to the progress of
the command execution, which may be useful for long-running MC-based
tests. The default value of this argument is 0 (do not print such
messages).
$handle callback $subcommand $cbtype ?script?
This command may be used to set up fit callbacks. Callbacks are tcl
scripts called when the fit state changes in a certain way. The following
command forms may be used:
* $handle callback add $cbtype $script
This command sets up a fit callback. One of the following keywords must
be used as the "cbtype" argument: "lostsync", "complete", and "delete".
The callback scripts are triggered under the following circumstances:
lostsync -- when the fit structure looses its synchronization with Minuit
complete -- when the fit converges to a stable minimum
destruct -- just before the fit is deleted
The callback scripts will be executed in the global context with two
additional arguments appended: handle and cbtype. Any changes made by
the callback scripts to the list of callback scripts of the same type
will become visible only at the time of the next trigger. Note that
when a fit copy is made, the callbacks are _not_ automatically transferred
to the copy.
* $handle callback delete $cbtype $script
Removes the script $script from the list of callbacks of type $cbtype
(if exists). Returns 1 if a callback is removed and 0 if not.
* $handle callback list $cbtype
Returns the list of all callbacks of the given type.
* $handle callback clear $cbtype
Deletes all callbacks of the given type.
Fit callbacks are useful to keep the fit tuning GUI in sync with the
fit status. They are not normally needed in the user code.
Some fit handle options have equivalent short names or aliases (which may
be easier to type or remember). Here is the list of such options and their
alternative names:
delete : del
parameter : param, parameters
configure : config
contours : contour
fit : mini
goodness : quality
hs::fit options
---------------
In addition to the "-method" option already described in the "Fitting Methods"
section, the following fitting options may be configured when the fit is
created by the hs::fit command: -name, -title, -description, -warnings,
-ignore, -errdef, -precision, -strategy, -verbose, -timeout, -minimizer,
-minos, -parameters, and -mapping. All these options with the exception of
the last two have the same meaning as in the "$handle configure" command.
The last two options may be used to configure fit model parameters and their
mappings to function parameters directly from the hs::fit command without
the use of fit handles (which results in a more compact code). Please see
the description of hs::fit command in the online manual for details about
using these options.
Fitting Example with Multiple Datasets
--------------------------------------
Let's consider an example in which a signal is simultaneously fitted
in four different channels. In each channel, the signal is a Breight-Wigner
resonance peak with the same position and width (but different height) on top
of some background. Suppose also that in each dataset the background can be
sufficiently well modelled by a second degree polynomial. Such fitting
problem may occur, for example, in the reconstruction of the invariant mass
of some resonance whose natural width dominates the detector resolution.
The following code can be cut and paste into a running wish. It is assumed
that the hs extension has already been initialized, and the Histo-Scope GUI
is running.
# First, let's define couple procedures which will help us to make
# various random numbers
proc gauss_random {mean width} {
expr $mean + $width * ([join [hs::random 12] +] - 6.0)
}
proc cauchy_random {peak HWHM} {
expr $peak + $HWHM * tan(3.1415926 * [hs::random 1] - 1.57079632679)
}
# Now, let's simulate the background
set xmin 0.0
set xmax 5.0
set nbins 50
set binwidth [expr {($xmax - $xmin)/$nbins}]
foreach {num a b c} {
0 1 1 40
1 1 -1 40
2 -1 1 40
3 -1 -1 40
} {
set idn($num) [hs::create_1d_hist [expr {$num+10}] \
"Dataset $num" "Tmp" "X" "Y" $nbins $xmin $xmax]
set data {}
for {set bin 0} {$bin < $nbins} {incr bin} {
set x [expr {$bin * $binwidth}]
set mean [expr {$a*$x*$x + $b*$x + $c}]
set value [gauss_random $mean [expr {sqrt($mean)}]]
if {$value < 0.0} {set value 0.0}
lappend data $value
}
hs::1d_hist_block_fill $idn($num) [hs::list_to_data $data]
}
# The following code simulates the signal
set peak 2.0
set width 0.3
foreach {num nevents} {0 400 1 800 2 600 3 900} {
for {set event 0} {$event < $nevents} {incr event} {
hs::fill_1d_hist $idn($num) [cauchy_random $peak $width] 1.0
}
}
# Create the fit. This time we will use chi-square minimization.
set idlist [list $idn(0) $idn(1) $idn(2) $idn(3)]
set fit [hs::fit $idlist {} -title "Fitting several datasets" -method chisq]
# Add the parameters for the fitted peak. Pretend that
# we don't know the real parameter values.
$fit parameter add peak -value 3
$fit parameter add width -value 0.2
# Go over each dataset and add fitting functions and parameters
set i 0
foreach id $idlist {
foreach {name init_value} {a 1 b 1 c 20 signal 10} {
$fit parameter add ${name}_$i -value $init_value
}
hs::function poly_1d copy poly_1d$i
hs::function poly_1d$i configure -mode 4
$fit function add poly_1d$i -subset $i -map [subst {
x0 = 0.0;
a0 = %c_$i;
a1 = %b_$i;
a2 = %a_$i;
}]
hs::function cauchy copy cauchy$i
$fit function add cauchy$i -subset $i -map [subst {
area = %signal_$i;
peak = %peak;
hwhm = %width;
}]
incr i
}
# At this point we have a fit with 4 datasets and 18 parameters.
# Since we have intentionally chosen rather dumb initial values
# for the model parameters, it is unlikely that the automatic
# minimization procedure will converge to the desired minimum
# in 18-dimensional space. Instead, a better idea is to start
# the fit tuner GUI and adjust a few parameters so that the fit
# curves start resembling the data. I suggest tuning the parameters
# "peak" and "signal_$n" (n = 0, 1, 2, 3). After that clicking
# the "Fit" button should accomplish the job.
$fit tune