FORTRAN Binding Library Routines

Routines for all Users

HS_INITIALIZE(identity_string)

CHARACTER *n identity_string (input, n <= 40)

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 is called.

HS_UPDATE

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 wasted 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_UPDATE very often.

HS_COMPLETE

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.

HS_COMPLETE_AND_WAIT

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, this call also should be called before calling the HBOOK routine HREND.

HS_HISTOSCOPE(return_immediately)

INTEGER return_immediately (input)

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 (return_immediatly .NE. 0), or it can start it and return after the user closes the Histo-Scope window (return_immediately .EQ. 0).

HS_HISTO_WITH_CONFIG(return_immediately, config_file)

INTEGER return_immediately (input)

CHARACTER *n config_file (input, n <= system maximum for filenames)

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 (return_immediatly .NE. 0), or it can start it and return after the user closes the Histo-Scope window (return_immediately .EQ. 0).

HS_KILL_HISTOSCOPE()

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.

num_scopes = HS_NUM_CONNECTED_SCOPES()

INTEGER num_scopes (returned)

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_LOAD_CONFIG_FILE(config_file)

CHARACTER *n config_file (input)

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)

CHARACTER *n config_string (input)

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.

Routines for HBOOK users

HS_HBOOK_SETUP(top_directory)

CHARACTER *n top_directory (input, n <= HBOOK's maximum)

Call this routine after you book the histograms or Ntuples you will use in the program and after you call HS_INITIALIZE. The routine will set up all current HBOOK histograms and Ntuples in the specified top directory for use with Histo-Scope. The top_directory string supplied should begin with "//". (Note: unpredictable results may occur if this routine is called without first calling the appropriate HBOOK routines for the top directory.)

HS_RESET_HBOOK_SETUP(top_directory)

CHARACTER *n top_directory (input, n <= HBOOK's maximum)

Call this routine if you have booked new histograms or Ntuples, or deleted, renamed, rebinned, or re-set existing ones since calling HS_HBOOK_SETUP. The top_directory string supplied should begin with "//".

Histo-Scope data routines

The Histo-Scope data routines provide a simple interface for creating data items, performing computations on this data, and managing the characteristics of the data items. They can be used instead of HBOOK routines or in addition to them.

Whenever a Histo-Scope data item is created, it is assigned a Histo-Scope identification number, id, which is returned to the calling routine. These id's are sequentially assigned beginning at the number 1 (one) and are NOT preserved across saving the item to a file and reading it back from the file. They are used, instead, for internal identification of an item. For the user's convenience a new User-specified identification number, uid, is accepted which, with its category, always identifies the item. uid's specified by the user must therefore be unique within the category specified for the item or the item will not be created. All item creation routines include a uid parameter. This uid may be specified as 0, in which case it need not be unique within the category. However specifying uid's of 0 will hamper utilization of such routines as HS_SUM_FILE, HS_SUM_CATEGORY, HS_READ_FILE_ITEMS, and HS_SAVE_FILE_ITEMS, which use uid lists to perform their function.

Item Creation Routines

id = HS_CREATE_1D_HIST(uid, title, category, x_label, y_label, num_bins, min, max)

INTEGER uid (input)

CHARACTER *n title (input, n <= 80)

CHARACTER *n category (input, n <= 255)

CHARACTER *n x_label (input, n <= 80)

CHARACTER *n y_label (input, n <= 80)

INTEGER num_bins (input)

REAL min (input)

REAL max (input)

INTEGER id (returned)

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 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 blank (either " '', or ' ') the histogram will appear in the top level category. The histogram axes are given the labels x_label and y_label. num_bins are the number of bins for for the histogram. Any values .LE. min or .GE. max are collected into under- or over-flow 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. If id is .LE. 0, an error occured in creating the histogram (check the arguments supplied to the function). The value of min should be less than max, and num_bins should be greater than 0.

id = 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)

INTEGER uid (input)

CHARACTER *n title (input, n <= 80)

CHARACTER *n category (input, n <= 255)

CHARACTER *n x_label (input, n <= 80)

CHARACTER *n y_label (input, n <= 80)

CHARACTER *n z_label (input, n <= 80)

INTEGER x_bins (input)

INTEGER y_bins (input)

REAL x_min (input)

REAL x_max (input)

REAL y_min (input)

REAL y_max (input)

INTEGER id (returned)

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 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 blank (either " '', or ' ') the histogram will appear in the top level category. 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 .LE. min or .GE. max are collected into under- or over-flow bins. The Histo-Scope defined id for the histogram is returned and is used in later calls to identify the histogram just created. If id is .LE. 0, an error occured in creating the histogram (check the arguments supplied to the function). The value of x_min and y_min should be less than its corresponding maximum, and x_bins and y_bins should both be greater than 0.

id = HS_CREATE_NTUPLE(uid, title, category, num_variables, names)

INTEGER uid (input)

CHARACTER *n title (input, n <= 80 )

CHARACTER *n category (input, n <= 255)

INTEGER num_variables (input)

CHARACTER *n names(num_variables) (input, n <= 80)

INTEGER id (returned)

Defines an Ntuple with num_variables variables and variable names taken from names(num_variables). 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 a string defining a hierarchical "location" for the Ntuple. 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 blank (either " '', or ' ') the Ntuple will appear in the top level category. Storage allocation of the Ntuple 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 histogram is returned and is used in later calls to identify the Ntuple just created. If id is .LE. 0, an error occured in creating the Ntuple (check the arguments supplied to the function).

id = HS_CREATE_INDICATOR(uid, title, category, min, max)

INTEGER uid (input)

CHARACTER *n title (input, n <= 80)

CHARACTER *n category (input, n <= 255)

REAL min (input)

REAL max (input)

INTEGER id (returned)

Creates an indicator. uid defines a user-specified identification number which can later be used along with the category to specify the item created. category is a string 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 blank (either " '', or ' ') the indicator will appear in the top level category. The Histo-Scope defined id for the indicator is returned and is used in later calls to identify the indicator just created. If id is .LE. 0, an error occured in creating the indicator (check the arguments supplied to the function).

id = HS_CREATE_CONTROL(uid, title, category, min, max, default_value)

INTEGER uid (input)

CHARACTER *n title (input, n <= 80)

CHARACTER *n category (input, n <= 255)

REAL min (input)

REAL max (input)

REAL default_value (input)

INTEGER id (returned)

Creates a control. uid defines a user-specified identification number which can later be used along with the category to specify the item created. category is a string 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 blank (either " '', or ' ') the control will appear in the top level category. The Histo-Scope defined id for the control is returned and is used in later calls to identify the control just created. If id is .LE. 0, an error occured in creating the control (check the arguments supplied to the function).

id = HS_CREATE_TRIGGER(uid, title, category)

INTEGER uid (input)

CHARACTER *n title (input, n <= 80)

CHARACTER *n category (input, n <= 255)

Creates a trigger. uid defines a user-specified identification number which can later be used along with the category to specify the item created. category is a string 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 blank (either " '', or ' ') 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. (To check if the trigger has been set a Histo-Scope user, call HS_CHECK_TRIGGER.) If id is .LE. 0, an error occured in creating the trigger (check the arguments supplied to the function).

id = HS_CREATE_GROUP(uid, title, category,groupType,numItems,itemId, errsDisp )

INTEGER uid (input)

CHARACTER *n title (input, n <= 80)

CHARACTER *n category (input, n <= 255)

INTEGER groupType (input)

INTEGER numItems (input)

INTEGER itemId (numItems)(input, numItems <= 81)

INTEGERn errsDisp (numItems)(input, numItems <= 81)

INTEGER id (returned)

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 a string 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 blank (either " '', or ' ') 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. groupType is the group's suggested window type. The number of items in this group, specified by numItems, should not be larger than 81. itemId is an array of HS item ids that compose the group. errsDisp is an array of values (NO_ERROR_BARS, DATA_ERROR_BARS, GAUSSIAN_ERROR_BARS) that corresponds to the itemId array and tells Histo-Scope how to display errors for the corresponding histogram (used only when the corresponding data item is a histogram).

A group can be made out of a number of items in order to display them as a Multiple Plot Window, an Overlaid Plot, or simply as a convenience for putting plots up individually with fewer mouse clicks. Data items may be put into more than one group and there is no limit on the number of groups you can create. Including an item in a group does not effect the display of the item individually in the main panel. The item still appears in the main panel list box and can be viewed individually. The category string can be used to affect how Histo-Scope items appear in the main panel.

When a group is selected in Histo-Scope's main window and the user presses the "View" Button, the groupType field tells Histo-Scope how to display the items in the group. This can be overridden in the Histo-Scope main panel by using the "View Multiple" or "View Overlaid" buttons. If groupType is HS_MULTI_PLOT, pressing the View button displays all the 1- and 2-D histograms in the group as one Multi-plot window. Similarly, if you would like to see all the 1D histograms in a group displayed over each other in one plot window, you can specify a groupType of HS_OVERLAY_PLOT. Triggers, controls, and indicators cannot appear inside a Multiple Plot Window or Overlaid Plot.

Specifying HS_INDIVIDUAL for groupType means that if a group is selected, and the "View" button is pressed on the Histo-Scope main panel, each data item in the group will be viewed individually. In the case of Ntuples, the Ntuple panel will be displayed so that the user can choose the variables to plot and the type to use.

Filling Histograms/Ntuples and Setting Errors

HS_FILL_1D_HIST(id, x, weight)

INTEGER id (input)

REAL x (input)

REAL weight (input)

Adds a value (weight) to the one-dimensional histogram identified by id.

HS_FILL_2D_HIST(id, x, y, weight)

INTEGER id (input)

REAL x (input)

REAL y (input)

REAL weight (input)

Adds a value (weight) to the two-dimensional histogram identified by id.

HS_1D_HIST_BLOCK_FILL(id, data, pos_errors, neg_errors)

INTEGER id (input)

REAL data(num_bins) (input)

REAL pos_errors(num_bins) (input)

REAL neg_errors(num_bins) (input)

Replaces the accumulated bin and error data supplied for the one-dimensional histogram identified by id and clears the overflow bins. data is a one-dimensional array containing the new data for the histogram and must be of the appropriate size (i.e. the correct number of bins) for the one-dimensional histogram being filled. pos_errors and neg_errors are the errors of the one-dimensional histogram. Either error argument can be specified as %VAL(0), in which case the corresponding errors are not changed. pos_errors and neg_errors should have the same number of elements as the histogram has bins. 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 pos_errors and neg_errors should be specified as positive real numbers.

HS_2D_HIST_BLOCK_FILL(id, data, pos_errors, neg_errors)

INTEGER id (input)

REAL data(x_bins, y_bins) (input)

REAL pos_errors(x_bins, y_bins) (input)

REAL neg_errors(x_bins, y_bins) (input)

Replaces the accumulated bin and error data supplied for the two-dimensional histogram identified by id and clears the overflow bins. data is a two-dimensional array containing the new data for the histogram and must be of the appropriate size (i.e. the correct number of bins) for the two-dimensional histogram being filled. pos_errors and neg_errors are the errors of the two-dimensional histogram. Either error argument can be specified as %VAL(0), in which case the corresponding errors are not changed. pos_errors and neg_errors should have the same number of elements as the histogram has bins. 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 pos_errors and neg_errors should be specified as positive real numbers.

HS_SET_1D_ERRORS(id, pos_errors, neg_errors )

INTEGER id (input)

REAL pos_errors(num_bins) (input)

REAL neg_errors(num_bins) (input)

Copies one or both arrays of real numbers representing the errors of a one-dimensional histogram. Either error argument can be specified as %VAL(0), in which case the corresponding errors are not set. Arrays should have the same number of elements as the histogram has bins. If a 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 pos_errors and neg_errors should be specified as positive real numbers.

HS_SET_2D_ERRORS(id, pos_errors, neg_errors)

INTEGER id (input)

REAL pos_errors(x_bins, y_bins) (input)

REAL neg_errors(x_bins, y_bins) (input)

Copies arrays of real numbers representing the errors of a two-dimensional histogram. Either error argument can be specified as %VAL(0), in which case the corresponding errors are not set. Arrays should have the same number of elements in each dimension as the histogram has bins. If positive errors are supplied, but negative ones aren't, Histo-Scope assumes errors are symmetric. Thus memory can be saved by specifying only positive errors when errors are symmetric. Both pos_errors and neg_errors should be specified as positive real numbers.

istatus = HS_FILL_NTUPLE(id, values)

INTEGER id (input)

REAL values(num_variables) (input)

INTEGER istatus (returned)

Adds an array of real values, in the order they are named in HS_CREATE_NTUPLE, to an Ntuple identified by id. Returns istatus. Check this status to ensure the array was added and to be certain your Ntuple still fits within the virtual memory of your machine. istatus .LE. 0 indicates memory was exhausted. istatus .EQ. 0 indicates an incorrect id or other user error. istatus .GT. 0 indicates success. The Ntuple id number is returned upon success.


Setting Indicators, Reading Controls, and Checking Triggers

HS_SET_INDICATOR(id, value)

INTEGER id (input)

REAL value (input)

Sets the value of an indicator to value. The value should be within the range specified for the indicator identified by id. However the indicator is set to the value even if the value is out of range.

HS_READ_CONTROL(id, return_value)

INTEGER id (input)

REAL return_value (returned)

Returns the value of a control in the variable return_value.

istatus = HS_CHECK_TRIGGER(id)

INTEGER id (input)

INTEGER istatus (returned)

Returns 1 if the trigger has been set by Histo-Scope; 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.

Functions for looking up items:

id = HS_ID(uid, category)

INTEGER uid (input)

CHARACTER *n category (input, n <= 255)

INTEGER id (returned)

Returns the Histo-Scope defined 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 item and was also specified when the item was created.

id = HS_ID_FROM_TITLE(title, category)

CHARACTER *n title (input, n <= 80)

CHARACTER *n category (input, n <= 255)

INTEGER id (returned)

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 a string specified at item creation defining a hierarchical "location" for the item.

num_match = HS_LIST_ITEMS(title, category, ids, num, match_flag)

CHARACTER *n title (input, n <= 80)

CHARACTER *n category (input, n <= 255)

INTEGER ids(num) (returned)

INTEGER num (input)

INTEGER match_flag (input)

INTEGER num_match (returned)

Fills a list of Histo-Scope id numbers. The user must allocate at least num integer elements for the array ids. These ids are returned in the order in which the histograms were created, or read in from a file. Returns the number of matching the title/category strings, num_match, which may be larger than num, the maximum number of items that can be returned. title specifies the title of the data items to list. category is a string specified at item creation defining a hierarchical "location" for the item. 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 .EQ. 0, then all id's returned will exactly match the title specified. If match_flag .NE. 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. If the category supplied is not valid, -1 will be returned in num_match.

Functions for getting properties of all items

uid = HS_UID(id)

INTEGER id (input)

INTEGER uid (returned)

Returns the user-specified identification number (uid) value for a given Histo-Scope id, or 0 if id was invalid or not found.

length = HS_CATEGORY(id, category)

INTEGER id (input)

CHARACTER *n category (input, n<=255)

INTEGER length (returned)

Returns the category and its length for a given Histo-Scope id, or -1 if id was invalid.

length = HS_TITLE(id, title)

INTEGER id (input)

CHARACTER *n title (input, n <= 80)

INTEGER length (returned)

Returns the title and its length for an item specified by id, or -1 if id was invalid.

data_type = HS_TYPE(id)

INTEGER id (input)

INTEGER data_type (returned)

Returns the type of data, data_type, referred to by id. Valid types are:

        HS_1D_HISTOGRAM	
        HS_2D_HISTOGRAM	
        HS_NTUPLE 
        HS_INDICATOR	
        HS_CONTROL
        HS_TRIGGER 
        HS_NONE

HS_NONE refers to a non-existent item.

These values are defined in histoscope.inc.


Functions for reading/writing items from/to files

istatus = HS_READ_FILE(filename, prefix)

CHARACTER *n filename (input, n <= system maximum for filenames)

CHARACTER *n prefix (input, n<=255)

INTEGER num_items (returned)

Reads all of the items from the Histo-Scope formatted file specified by filename. All category strings read will be prefixed by a new top level category specified in prefix. This may be specified as %VAL(0) (or " "), meaning that no prefix should be added. Returns the number of items read, or -1 if error.

num_items = HS_READ_FILE_ITEMS(filename, prefix, category, uids, n_uids)

CHARACTER *n filename (input, n <= system maximum for filenames)

CHARACTER *n prefix (input, n<=255)

CHARACTER *n category (input, n <= 255)

INTEGER uids(n_uids) (input)

INTEGER n_uids (input)

INTEGER num_items (returned)

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 %VAL(0) (or " "), 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 an error message will inform the user. If n_uids is .GT. 0, the array uids specifies the uid's of items to read from the file. If uids is %VAL(0) or n_uids .EQ. 0, all items in the specified category and its subcategories will be read. n_uids specifies the number of items in array uids. 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.

num_items = HS_SAVE_FILE(filename)

CHARACTER *n filename (input, n <= system maximum for filenames)

INTEGER num_items (returned)

Saves all current histograms, Ntuples, indicators, and controls created by Histo-Scope library routines or read from Histo_scope files to a Histo-Scope-format file. Triggers are not written to the file. The number of items written is returned in num_items, or -1 if an error occurred. The named file is open for writing ("w"), discarding previous contents, if any.

num_items = HS_SAVE_FILE_ITEMS(filename, category, uids, n_uids)

CHARACTER *n filename (input, n <= system maximum for filenames)

CHARACTER *n category (input, n <= 255)

INTEGER uids(n_uids) (input)

INTEGER n_uids (input)

INTEGER num_items (returned)

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 an array of user id values of length n_uids specifying which items to write. If n_uids is .LE. 0 or uids is %VAL(0), all items in the category specified are saved. 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.

Functions for managing data items

HS_RESET(id)

INTEGER id (input)

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_DELETE(id)

INTEGER id (input)

Deletes a histogram, Ntuple, indicator, control, or trigger identified by id.

HS_DELETE_ITEMS(id, num_ids)

INTEGER id(num_ids)(input)

INTEGER num_ids (input)

Deletes a list of items identified by id.

HS_DELETE_CATEGORY(category)

CHARACTER *n category (input, n <= 255)

Removes and deallocates 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 all subcategories of the category will be deleted. Specifying " " or %VAL(0) 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_CHANGE_UID(id, new_uid)

INTEGER id (input)

INTEGER new_uid (input)

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_CATEGORY(id, newcategory)

INTEGER id (input)

CHARACTER *n category (input, n <= 255)

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)

INTEGER id (input)

CHARACTER *n newtitle (input)

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.

num_items = HS_NUM_ITEMS()

INTEGER num_items (returned)

Returns the number of Histo-Scope data items defined so far.

Functions for Accessing Histogram Data

num_bins = HS_1D_HIST_NUM_BINS(id)

INTEGER id (input)

INTEGER num_bins (returned)

Returns the number of bins for a one-dimensional histogram identified by id, or -1 if id does not refer to a one-dimensional histogram.

HS_2D_HIST_NUM_BINS(id, num_x_bins, num_y_bins)

INTEGER id (input)

INTEGER num_x_bins (returned)

INTEGER num_y_bins (returned)

Returns the number of bins in the two-dimensional histogram specified by id. num_x_bins is the number of bins in X. num_y_bins is the number of bins in Y. -1 is returned for num_x_bins and num_y_bins if id does not refer to a two-dimensional histogram.

HS_1D_HIST_RANGE(id, min, max)

INTEGER id (input)

REAL min (returned)

REAL max (returned)

Returns the minimum (low edge of first bin) value in min and the maximum (high edge of last bin) value in max representing the horizontal limits of a one-dimensional histogram specified by id. If id does not refer to a one-dimensional histogram, zero is returned for min and max.

HS_2D_HIST_RANGE(id, x_min, x_max, y_min, y_max)

INTEGER id (input)

REAL x_min (returned)

REAL x_max (returned)

REAL y_min (returned)

REAL y_max (returned)

Returns the minimum and maximum values representing the horizontal limits of a two-dimensional histogram specified by id. If id does not refer to a two-dimensional histogram, zero is returned for the minimum and maximum values.

num_entries = HS_NUM_ENTRIES(id)

INTEGER id (input)

INTEGER num_entries (returned)

Returns the number of fill operations that have been performed on the histogram referred to by id, or -1 if the id does not refer to a histogram or Ntuple item.

HS_1D_HIST_BIN_CONTENTS(id, data)

INTEGER id (input)

REAL data(num_buns) (returned)

Returns the bin data from a one-dimensional histogram. Data must be dimensioned appropriately for the number of bins in the histogram.

HS_2D_HIST_BIN_CONTENTS(id, data)

INTEGER id (input)

REAL data(num_buns) (returned)

Returns the bin data from a two-dimensional histogram. Data must be dimensioned appropriately for the number of bins in the histogram.

status = HS_1D_HIST_ERRORS(id, pos_errors, neg_errors)

INTEGER id (input)

REAL pos_errors(num_bins) (returned)

REAL neg_errors(num_bins) (returned)

Return the error bar data from a one-dimensional histogram. pos_errors is a one-dimensional array to receive data for upper error bars. Must be dimensioned appropriately for the number of bins in the histogram. neg_errors is a one-dimensional array to receive data for lower error bars. neg_errors can be %VAL(0) which means only positive errors are returned. If non %VAL(0), neg_errors must be dimensioned appropriately for the number of bins in the histogram. The status returned can be:

HS_NO_ERRORS - Item has no error data

HS_POS_ERRORS - Positive errors (only) are returned

HS_BOTH_ERRORS - Positive and negative errors are returned

HS_ITEMNOTFOUND_ERRORS - id does not refer to a one-dimensional histogram

These values are defined in histoscope.inc.

status = HS_2D_HIST_ERRORS(id, pos_errors, neg_errors)

INTEGER id (input)

REAL pos_errors(x_bins, y_bins) (input)

REAL neg_errors(x_bins, y_bins) (input)

Returns the error bar data from a two-dimensional histogram. pos_errors is a two-dimensional array to receive data for upper error bars. Must be dimensioned appropriately for the number of bins in the histogram. neg_errors is a two-dimensional array to receive data for lower error bars. neg_errors can be %VAL(0), which means only positive errors are returned. If not %VAL(0), neg_errors must be dimensioned appropriately for the number of bins in the histogram. The status returned can be:

HS_NO_ERRORS - Item has no error data

HS_POS_ERRORS - Positive errors (only) are returned

HS_BOTH_ERRORS - Positive and negative errors are returned

HS_ITEMNOTFOUND_ERRORS - id does not refer to a one-dimensional histogram

These values are defined in histoscope.inc.

HS_1D_HIST_OVERFLOWS(id, underflow, overflow)

INTEGER id (input)

REAL underflow (returned)

REAL overflow (returned)

Returns the overflow data from a one-dimensional histogram.

HS_2D_HIST_OVERFLOWS(id, overflows)

INTEGER id (input)

REAL overflows(x_bins, y_bins) (returned)

Returns the overflow data from a two-dimensional histogram as a 3 x 3 array:

Figure 47

value = HS_1D_HIST_X_VALUE(id, x)

INTEGER id (input)

REAL x (input)

REAL valu (returned)

Returns the value stored in the histogram bin referenced by x. The result is undefined if id is not a one-dimensional histogram, or if x is not within the range of the histogram.

value = HS_2D_HIST_XY_VALUE(id, x, y);

INTEGER id (input)

REAL x (input)

REAL y (input)

REAL value (returned)

Returns the value stored in the histogram bin referenced by (x,y). The result is undefined if id is not a two-dimensional histogram, or if x or y are not within the range of the histogram.

value = HS_1D_HIST_BIN_VALUE(id, bin_num)

INTEGER id (input)

INTEGER bin_num (input)

REAL value (returned)

Returns the value in the histogram bin referred to by bin (or channel) number bin_num. The result is undefined if id is not a one- dimensional histogram or bin_num is less than 1 or greater than the number of bins.

value = HS_2D_HIST_BIN_VALUE(id, x_bin_num, y_bin_num)

INTEGER id (input)

INTEGER x_bin_num (input)

INTEGER y_bin_num (input)

REAL value (returned)

Returns the value in the histogram bin referred to by bin (or channel) number (x_bin_num , y_bin_num). The result is undefined if id is not a two-dimensional histogram or bin_num is less than 1 or greater than the number of bins for the axis.

Calculations on histogram data

HS_1D_HIST_MINIMUM(id, x, bin_num, value)

INTEGER id (input)

REAL x (returned)

INTEGER bin_num (returned)

REAL value (returned)

Returns the x-coordinate (x), the bin number (bin_num), and the bin content (value) where the histogram data reaches a minimum. The routine returns a bin_num of 0 if the histogram does not refer to a one-dimensional histogram or the histogram is empty (i.e. has not yet been filled).

HS_2D_HIST_MINIMUM(id, x, y, x_bin_num, y_bin_num, value)

INTEGER id (input)

REAL x (returned)

REAL y (returned)

INTEGER x_bin_num (returned)

INTEGER y_bin_num (returned)

REAL value (returned)

Returns the x- and y-coordinate (x and y) the 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 a bin number of 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_1D_HIST_MAXIMUM(id, x, bin_num, value)

INTEGER id (input)

REAL x (returned)

INTEGER bin_num (returned)

REAL value (returned)

Returns the x-coordinate (x), the bin number (bin_num), and the bin content (value) where the histogram data reaches a maximum. The routine returns a bin_num of 0 if the histogram does not refer to a one-dimensional histogram or the histogram is empty (i.e. has not yet been filled).

HS_2D_HIST_MAXIMUM(id, x, y, x_bin_num, y_bin_num, value);

INTEGER id (input)

REAL x (returned)

REAL y (returned)

INTEGER x_bin_num (returned)

INTEGER y_bin_num (returned)

REAL value (returned)

Returns the x- and y-coordinate (x and y) the 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 a bin number of 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_1D_HIST_STATS(id, mean, std_dev)

INTEGER id (input)

REAL mean (returned)

REAL std_dev (returned)

Calculates and returns the mean and standard deviation of a one-dimensional histogram.

HS_2D_HIST_STATS(id, x_mean, y_mean, x_std_dev, y_std_d

INTEGER id (input)

REAL x_mean (returned)

REAL y_mean (returned)

REAL x_std_dev (returned)

REAL y_std_dev (returned)

Calculates and returns the mean and standard deviation in x and y of a two-dimensional histogram.

integrl = HS_HIST_INTEGRAL(id)

INTEGER id (input)

REAL integrl (returned)

Calculates the integral (the sum of the bin contents * binwidth) of the bin data in a histogram. Overflow data is not counted. The result returned is -1.0 if id does not exist or does not refer to a one-dimensional histogram.

HS_HIST_SET_GAUSS_ERRORS(id)

INTEGER id (input)

Calculate and store Gaussian errors in a histogram. If positive errors have been previously stored, they 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 one-dimensional or a two-dimensional histogram, no action is taken besides printing an error message.

new_id = HS_SUM_HISTOGRAMS(uid, title, category, id1, id2, const1, const2)

INTEGER uid (input)

CHARACTER *n title (input, n <= 80)

CHARACTER *n category (input, n <= 255)

INTEGER id1, id2 (input)

REAL const1, const2 (input)

INTEGER new_id (returned)

Creates a new histogram (one-dimensional or two-dimensional) whose data is the sum, bin by bin, of two histograms specified by HistoScope identification numbers id1 and id2. The bin content 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 but not both. Also one of the id's can be 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 ("Low" errors are ignored). 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 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 blank (either " '', or ' ') the histogram will appear in the top level category. The routine returns an error (an id of -1) if both histograms are nonexistent, the histogram types are different, or the number of bins, or low/upper edges are inconsistent. Returns the id of a new histogram containing the sum of the two histograms, or -1 if the operation could not be performed.

new_id = HS_MULTIPLY_HISTOGRAMS(uid, title, category, id1, id2, const)

INTEGER uid (input)

CHARACTER *n title (input, n <= 80)

CHARACTER *n category (input, n <= 255)

INTEGER id1, id2 (input)

REAL const (input)

INTEGER new_id (returned)

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 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 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 blank (either " '', or ' ') the histogram will appear in the top level category. Returns the id of the new histogram containing the result of the operation, or -1 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.

new_id = HS_DIVIDE_HISTOGRAMS(uid, title, category, id1, id2, const)

INTEGER uid (input)

CHARACTER *n title (input, n <= 80)

CHARACTER *n category (input, n <= 255)

INTEGER id1, id2 (input)

REAL const (input)

INTEGER new_id (returned)

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 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 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 blank (either " '', or ' ') 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, or -1 if an error occurred.

new_id = HS_1D_HIST_DERIVATIVE(uid, title, category, id)

INTEGER uid (input)

CHARACTER *n title (input, n <= 80)

CHARACTER *n category (input, n <= 255)

INTEGER id (input)

INTEGER new_id (returned)

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 its HistoScope id, has error bars, the errors are computed assuming that there is no statistical correlation between bins and the error values are Gaussian. 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. 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.

Summing Groups of Histograms and Ntuples

The two routines, HS_SUM_CATEGORY and HS_SUM_FILE, are designed to allow the user to sum together the data items from two different runs of the same program. For example, if on one day, a program creates the following items:


category       uid           item type

mydata	        101         1-d histogram
mydata	        102         2-d histogram
mydata/ntuples	202         Ntuple

and writes these items to a file, the next day, he can use HS_SUM_FILE to sum today's one-dimensional histogram with its corresponding 1-d histogram on the file, sum today's two-dimensional histogram with its corresponding 2-d histogram on the file, and merge together the two Ntuples. The HS_SUM_FILE call for the above example would look as follows:

CALL HS_SUM_FILE(FILENAME, `mydata', `sum')

and would create the following new items:

category       uid           item type

sum             101          1-d histogram
sum             102          2-d histogram
sum/ntuples     202          Ntuple

These routines search the items in the category specified and match their uid's with the data items found in the file (for HS_SUM_FILE) or second category (for HS_SUM_CATEGORY) specified. An error message will be printed if the data types do not match when the data items' uid's do match. An error message is also printed if two histograms or Ntuples with matching uid's do not have the same properties, for instance a different number of bins or variables. The resulting summed data items are created in memory and are given the new category specified (result_category). Items other than histograms and n-tuples are ignored.

HS_SUM_CATEGORY(category1, category2, result_category)

CHARACTER *n category1, *n category2 (input)

CHARACTER *n result_category (input)

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), the uids/subcategories and binning properties are identical. Items with uid .EQ. 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 uid's and static properties, a new histogram with the same uid will be created which is the sum, bin by bin, in 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 cannot be NULL nor empty (Uncategorized), nor contain "...". result_category is the top category for the newly created category.

HS_SUM_FILE(filename, category, result_category)

CHARACTER *n filename (input, n <= system maximum for filenames)

CHARACTER *n category (input, n <= 255)

CHARACTER *n result_category (returned)

Read all of the items from filename, 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(FILE1, 'allsum') and loop over the others, calling repetitively HS_SUM_FILE(FILEn, '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". For example, to sum three files:

            call HS_INITIALIZE('Example')
            call HS_READ_FILE('file1.hs', 'allsum')
            call HS_SUM_FILE('file2.hs', 'allsum',allsum')
            call HS_SUM_FILE('file3.hs', 'allsum',allsum')

Functions for accessing Ntuple data

num_var = HS_NUM_VARIABLES(id)

INTEGER id (input)

INTEGER num_var(returned)

Returns the number of variables (num_var) in the Ntuple referred to by id. Returns -1 if the id is not valid or not an Ntuple.

num_entries = HS_NUM_ENTRIES(id)

INTEGER id (input)

INTEGER num_entries (returned)

Returns the number of entries stored in the Ntuple referred to by id, or -1 if the id is not a valid item.

length = HS_VARIABLE_NAME(id, column, name)

INTEGER id (input)

INTEGER column (input)

CHARACTER *n name (returned)

INTEGER length (returned)

Returns the name and length of a given variable for the Ntuple specified by id. column is the variable's index (i.e., the column number) and name is the mnemonic name of this variable in the Ntuple.

index = HS_VARIABLE_INDEX(id, name)

INTEGER id (input)

CHARACTER *n name (input)

INTEGER index (returned)

Returns the index (i.e. 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.

value = HS_NTUPLE_VALUE(id, row, column)

INTEGER id (input)

INTEGER row (input)

INTEGER column (input)

REAL value (returned)

Returns the value (value) in an Ntuple, at a specified row and column index. value is undefined (-1.0 is returned, however) if id does not exist or refers to an item other than an Ntuple.

HS_NTUPLE_CONTENTS(id, data)

INTEGER id (input)

REAL data(num_entries, num_variables) (returned)

Returns all of the data in an Ntuple, specified by id, in the form of a two-dimensional array named data which contains floating point values. The array must be dimensioned to the number of rows (entries) by the number of columns (elements or variables) in the Ntuple.

HS_ROW_CONTENTS(id, row, data)

INTEGER id(input)

INTEGER row (input)

REAL data(num_variables) (returned)

Returns the contents of a row (or entry) of Ntuple data specified by id and places it in the array data. Data must be dimensioned to the number of variables (elements) in the Ntuple. 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_COLUMN_CONTENTS(id, column, data)

INTEGER id (input)

INTEGER column (input)

REAL data(num_entries) (returned)

Returns the contents of a column of Ntuple data specified by id and places it in the array data. 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.

new_id = HS_MERGE_ENTRIES(uid, title, category, id1, id2)

INTEGER uid (input)

CHARACTER *n title (input, n <= 80)

CHARACTER *n category (input, n <= 255)

INTEGER id1, id2 (input)

INTEGER new_id (returned)

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 histogram. Returns id, the Histo-Scope id of the newly created Ntuple, or -1 if the Ntuples referred by id1 or id2 don't exist, are not Ntuples or have a different number of variables. The variable names are taken from id1, and are assumed to be identical to those of id2.