AusButler for JFR Teamy suite ============================= Tools that allows calculation and presentation of a normalized butler (a so-called "Australian butler") for tournaments directed with JFR Teamy suite. Installation ------------ 1. Download the program package from [author's website](https://github.com/emkael/jfrteamy-ausbutler/releases). 2. Unpack it to the desired directory. 3. [Configure appropriate database connection](#configuration-files). 4. Run `butler.exe` in application directory. Program invocation ------------------ Program, in any order, accepts command line arguments which relate to actions conducted by the application: * `calculate` calculates normalized butler and writes it in the event database * `generate` compiles HTML pages with all results present in the normalized butler database * `send` transmits the pages to the FTP server via Goniec (if `generate` action is selected) Invoking the application without any of the above arguments is equivalent to providing all of them (`calculate`, `generate` and `send`). Additionally, the program by default waits for user input after finishing - this may be turned off, by providing `nowait` argument. Configuration files ------------------- The application relies on five configuration files, JSON-formatted, placed in the `config` subdirectory. --- [`db.json`](config/db.json.EXAMPLE) Defines event database connection parameters: * `user` - DB username * `pass` - DB password * `db` - event database name * `host` - DB server location --- [`butler.json`](config/butler.json) Defines butler calculation parameters. Normalized butler for the pair in a segment is calculated as follows: * raw butler for the pair is limited to the `cutoff_point` value * results above `cutoff_point` are included only partially, as defined per `cutoff_rate` (e.g., by default: `32` and `0.1` mean that 10% of the result above 32 IMP counts) * the result is normalized to IMP per board * average score of the opponents (their raw butler score per board) is added, scaled to the `opponent_factor` parameter (e.g. the default `0.5` means half of the opponents' average is added) * the result is recalculated as a score for the entire segment * if the `only_current` is set, opponents' average is calculated only from segments up to the considered one - so that way normalized butler does not take into account opponents' results from the entire event, but consequent results do not change the calculation for previous segments All calculations are independent from the way raw butler is calculated for all the pairs. Finally, the `segments_in_table_limit` parameters defines how many latest segments are presented in detail in the summary table for the normalized butler (`PREFIXnormbutler.html`). All the previous segments are included in the table header, in compliance with JFR Teamy convention. It's also possible to set an output path different from tournament HTML path. Parameter `output_path` does that. --- [`goniec.json`](config/goniec.json) Defines standard parameters for Goniec transmission. * `enabled` turns the transmission on * `host` and `port` point to the Goniec location --- [`logoh.json`](config/logoh.json) Sets the mapping for text strings used by the application within generated pages to the event database translation identifiers. Typically, doesn't need any adjustments. Every string should be present in the `logoh` table of the event database. **BEWARE**: in case the program raises `KeyError: NUMERIC_ID` error in lines responsible for translating strings, you should reload the correct `.language` into the JFR Teamy event database. --- [`translation.json`](config/translation.json) Sets translations for the strings that are generated by the program, but are not present in the JFR Teamy event database. It consists of a dictionary of values including Polish (`pl`) and English (`en`) variations of the string. The application detects the language version used in the event database based on the string with ID 18 from the event database (`ROUND` for English, `RUNDA` for Polish). Page templates -------------- The `template` directory contains fully customizable page templates for the files generated by the program. * [`table.html`](template/table.html) is the template for the normalized butler summary table - `PREFIXnormbutler.html` file * [`frame.html`](template/frame.html) is the frame template for the normalized butler resutls of single segments - `PREFIXbutlerSEGMENT.htm` files * [`segment.html`](template/segment.html) is the template for the normalized butler pairs resutls of single segments - `PREFIXbutlerSEGMENT.html` files * [`macros.html`](template/macros.html) contains various partial templates used in multiple places of other templates - stuff like headers, separators, result table rows or page footer In most cases there's no need to modify these templates - they're compatible with the standard JFR Teamy formatting. Authors ------- The author of the application is Michał Klichowicz (mkl). This was created for Polish Bridge Union, from the initiative of the Polish Open Team coach, Piotr Walczak. The method was adopted from the *normalized datum* calculated by the Australian Bridge Federation, according to the [2016 Australian National Championships supplementary regulations](http://www.abfevents.com.au/events/spnot/2016/include/2016_SN_Supp_Regs.pdf). License ------- The application is distributed under a [simplified 2-clause BSD license](LICENSE). --- `Breathe on, little sister, breathe on.`