{{attachment:ibc_logo.jpg}}

= READ ME - MergePerformance.py =
<<TableOfContents>>

=== General information ===
A Python program called !MergePerformance.py may be used to assemble two or more performance files into a single performance file.

The program produces a merged XML format performance file, i.e. containing the data in the input files, given two or more input XML format performance files.

The program do not require access to the internet to run, and hence cannot do any advanced checking of the input data.<<BR>> The [[https://wiki.interbull.org/public/CheckPerformance?action=print|CheckPerformance]] program is needed for that.

If errors occur, they are listed on the screen (unless redirected elsewhere).

One performance file may contain records for multiple brd-pop-trt combinations but, as that practice leads to very large upload files if used indiscriminately, this is not a recommended practice.<<BR>> This program would primarily be used to assemble multiple traits for the same set of animals into a single performance file to be checked by !CheckPerformance.

For a more detailed description, see [[https://wiki.interbull.org/public/FilePerformanceXML?action=print|description of the XML performance format]].

=== Before Running the Program ===
 . a. Ensure there is a working network connection
 . b. Install [[http://www.python.org|Python]]  (Python3, minimum 3.6). Please note that Python2 is no longer supported by developers.
 . c. Create a new working directory/folder
 . d. Download the !MergePerformance program from https://idea.interbull.org/software into the new directory (you may download !CheckPerformance at the same time)
 . e. Copy the files you want to check to the working directory (This is optional. The path to the files can also be written by the prompt as /path/filename)

=== Executing the Program ===
The shown commands assume that the working directory in point c above, is used as current directory, i.e. start by calling `cd <name of directory>` (once) before running the commands shown below.

First off, lets look at a simple example of how to execute the program that is sufficient in most cases (you will need to replace the name of the performance files in order to successfully run this):

{{{
python3 MergePerformance.py -o MyPerformanceFile.xml PartialPerformanceFile1.xml PartialPerformanceFile2.xml PartialPerformanceFile3.xml
}}}
Synopsis of how to run the program:

{{{
python3 MergePerformance.py [-o OUTPUT] inputfiles...
}}}
Arguments within square brackets (i.e. `[]`) are optional to specify.<<BR>>The argument OUTPUT and inputfiles are supposed to be filenames that may be either relative (i.e. relative to the current directory) or absolute (i.e. they start with a slash)

The `-o OUTPUT` argument is used to specify the file where the merged performance data is put. If this is omitted, no output data is produced, only a test merge is performed.

Running the following command will show a brief description of how to run the program if you need a reminder:

{{{
python3 MergePerformance.py -h
}}}
=== Output From the Program ===
If no problems are discovered in the input files (and the `-o ...` argument is specified), the following message will be written:

{{{
Performance merging program: MergePerformance.py version 2020-11-05 v1.0, provided by Interbull Centre

Done.
}}}
and the specified output file has been produced.

If problems ''are'' discovered, the tail of the above messages will be replaced by one or more messages each trying to describe what the problem is. At some points in the execution, any previously detected problem will cause immediate termination.

 . If you need assistance with this program, please do not hesitate to contact us at interbeef@slu.se .