This file is obsolete. Instead, follow the link SCABPrioritizationScript from the SCAB internal twiki

About

The SCAB tool is intended to automate the process of producing prioritized lists of speakers for the use of the speakers committee. It works from an xml file containing all nominations. This nominations file is produced from the Glance data base as described below. It's second input is a list of rules (also in xml format) for validating nominations and producing the priority lists. The tool outputs several files including a list of nominees for each of the defined priorities (now five), a summary file which contains information useful for checking the proper implementation of the rules file and a log file.

How to get it

Simply download it from this page (at the bottom). You will also need to download the rules file.

Usage

For Linux (if windows instructions are needed, I'll figure out how to do it). After making it executable with chmod, you simply type:

scab_tool [rules_file.xml] [nominations_file_name]

If all goes well, the script will, after several seconds produce several files in your working directory:

  • Priority_n.txt (where n = 1,2,3,4,5,none) which contains lists of nominees with the SCAB priority corresponding to n (Priority_none.txt is the list of nominees who are not prioritized). The lists contain many details about each nominee which are useful for understanding if the rules are properly implemented

  • summary.txt which summarizes various statistics and the lists of prioritized nominees, grouped by priority

  • log.txt which might be useful for debugging new rules

  • 6 checklists

  • a file in csv format which can be given to the Glance team for the update

  • a header file which contains a C++ structure holding the results of the prioritization (per nominee) which is useful for making histograms with ROOT

* a file with info on each nominee, including the list of talks which might be useful for checking individual talk assignments

Obtaining the nominations file

Go to the Glance DB web interface and the "SCAB member" tab. Choose "XML" in the "View results as" menu. Without making any selection press "Search". After several seconds, it will ask where you want to save the file.

Working with the rules file

You only need to read this if you want to modify the rules file.

File contents

The first part of the rules file gives the data type definitions as standard xml metadata. This is followed by directives for defining variables and then the rules themselves.

Referencing nomination variables in the nomination record

Each nomination has many associated nomination-variables called "columns" in the nominations file which can be used either directly in the rules definition or in the definition of local variables. The nomination-variables are referred to by their name (as given in the "description" field of the column) enclosed in curly brackets, e.g. {ATLAS Member}. In cases in which comparisons are to be made between two different nominations, the opening bracket should be preceded by a 1 or 2, to distinguish between the two nominations.

File contents

The first part of the rules file gives the data type definitions as standard xml metadata. This is followed by directives for defining variables and then by the rules themselves. The variable definition section contains only variable definitions.

The rules section should contain three lists:

  • a list of selections to be applied to all nominations. Nominations which fail the specified test are discarded

  • a list of redundant nomination pairs. If a redundant pair is found for a particular nominee, one of them is filtered out according to the specified rule

  • a list of priority definitions, and for each priority definition:
    • a list of requirements on the minimum number of nominations for particular nominees which satisfy a given criterion
    • a list of requirements which are applied to any nomination for a particular nominee (only one is checked, it is assumed that whatever variables are used in the check are the same in all nominations for particular nominees)
    • a list of requirements which are applied only to the nomination of the institutee representative of particular nominees (if one is present)

A note on the attributes which specify executable code

Some of the attributes associated with an element are meant to specify executable code. The syntax is basically perl except for a difference in how nomination variables and local variables are specified. The nomination variables correspond to the columns of the nomination file and are referred to as described above.

Defining and using local variables

A local variable is defined by a VarDef statement which

Perl syntax

You can find tutorials on perl by googling but you really need to know only a few things.

  • The operators "eq, gt, lt, ge, le" are for testing equalities and the obvious inequalities. In fact, they assume they are looking at strings (not numbers). I have been using them for testing numbers since the xml parser I use gets confused by ">" and ">". For numeric tests, the function lessequal (defined in scab_tool) can be used when the string operators are not appropriate.

  • the "and" and "or" operators can be used or logical combinations, parentheses for grouping, as usual. The C++ && and || operators are also defined but they confuse the xml parser.

  • for string matchng, perl uses fairly normal regular expression syntax. For example, the expression: "{Submitted by (Appointment)} =~ m/Physics Coordinator/" will evaluate to true if {Submitted by (Appointment)} is either "Physics Coordinator" or "Deputy Physics Coordinator". If you only want matches to "Physics Coordinator" and not "Deputy...", you can write {Submitted by (Appointment)} =~ m/^Physics Coordinator/". The carat means that the first letter following it must be the first character of the string.

  • two functions (which are not standard perl functions) are recognized: isBefore(yyyy/mm/dd, yyyy/mm/dd) compares the two given dates and evaluates to true if the second date is before the first date, isAfter(yyyy/mm/dd, yyyy/mm/dd) evaluates to true if the second date is after the first date. Dates must have the syntax: yyyy/mm/dd. Entries in the nomination records which specify dates can also be used, e.g. {Last Talk}

  • any string other than "0" evaluates to true (so "1" as a condition is always true)

The directives

  • Configuration: the top level xml element. It has two attributes which specify the author of the file and a date

  • NominationSelections: delimits the list of nomination selections (no attributes)

  • NominationSelection: specifies a nomination selection. It takes two attributes: "name" is an arbitrary string which is used in printouts; "Requirement" is code which should evaluate to true for acceptable nominations

  • Redundancies: delimits the list off redundancies

  • Redundancy: usually specifies a pair of nominations of which only one should be used. It has three attributes: "RegEx1" and "RegEx2" give regular expressions. If, for a particular nominee, RegEx1 matches the "Submitted by (Appointment)" field of one nomination and RegEx2 matches the same field of another one, then the condition "Favor_1_If" is applied to decide which of the two to keep. If it evaluates to true, the nomination specified by RegEx1 is kept, otherwise RegEx2's nomination is kept. The other is discarded. If RegEx1 is exactly "IDENTICAL SUBMITTERS" then RegEx2 is ignored and nominations with exactly the same "Submitted by (Appointment)" field are searched for and only one is kept: the one for which "Favor_1_if" is true.

  • PriorityDefs delimits the llst of priority defintions.

  • PriorityDef: specifies a priority definition. It has a "Priority" attribute which must be one of 1,2,3,4,5. Each PriorityDef must also include a list of requirements. There are three types of requirements:
    • RequirementOnSum: specifies the minimum number of nominations (specified in "Minimum") for a particular nominee which meet the criterion specified in "Conditional"
    • RequirementOnAny: specifies a requirement that any of the nominations for a particular nominee must meet (only one is checked, it is assumed that all nominations would give the same answer). There is a single attribute: "Requirement" which should evaluate to true for selected nominees.
    • RequirementOnInstRepNomination: same as RequirementOnAny except that the requirement is only applied to nominations from valid institute reps.

Example of an entry from the nominations file

The following shows name/value pairs of all entries in the xml-formatted nominations file. They are all available as variables for the script.

ATLAS Member -> Albert Einstein
Activities -> Lots
CCID -> 111111
Comments -> this is a comment
Country -> Germany
Email -> Albert.Einstein@cern.ch
First Name -> Albert
Gender -> M
History Entries -> 1
Institute -> Patent Office, Bern
Institute ID -> 1111
Last Name -> Einstein
Last Talk -> 2012/08/13
Memb ID -> 1
Member ID -> 1
Member Initials -> A.
Modification date -> 2012/11/08
Modified by -> Isaac Newton
Modified by (Last Name) -> Newton
Nomination ID -> 1111
Number Of Nominations -> 2
OTP Contribution -> Yes
PROF_ADVANCE -> 
Person type -> 1
Priority -> 1
Professional Adv. -> No Professional Advancement
Professional Adv. ID -> 
Qualification Date -> 1905/09/01
SCAB Priority -> 
Submission date -> 2012/11/08
Submitted by (Appointment) -> Physics Coordinator
Submitted by (Last Name) -> Newton
Submitted by (Name) -> Isaac Newton
Talk Subject -> Overview
Time spent in ATLAS [%] -> 
Topic attachments
I Attachment History Action Size Date Who Comment
XMLxml scab_rules_June_2013.xml r2 r1 manage 7.1 K 2013-07-12 - 15:38 MichaelMedinnis The rules file and the (executable) scab_tool.pl
Unknown file formatext scab_tool r1 manage 25.9 K 2013-07-24 - 16:12 MichaelMedinnis  
Edit | Attach | Watch | Print version | History: r8 < r7 < r6 < r5 < r4 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r8 - 2015-02-06 - MichaelMedinnis
 
    • Cern Search Icon Cern Search
    • TWiki Search Icon TWiki Search
    • Google Search Icon Google Search

    Sandbox All webs login

This site is powered by the TWiki collaboration platform Powered by PerlCopyright & 2008-2020 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
or Ideas, requests, problems regarding TWiki? use Discourse or Send feedback