USER MANUAL FOR THE IDEA EBV INTERFACE

Preface

The following is a manual to guide the user through the features of the new IDEA. IDEA stands for Interbull Data Exchange Area. IDEA is a restricted area accessible only to member countries through the Interbull website.

File Encoding

For the checking programs to run successfully the encoding of your files must be set to UTF-8.

If this is not the case a message saying

The file seems not to be in UTF-8 encoding and an illegal character has been detected. Please, convert the file to UTF-8 and rerun the check program

will appear on the screen. This means the program DID NOT run successfully.

To change the encoding of a file you have at least two options:

• in Unix/Linux: use the command
  

iconv –f “ISO-8859-1” –t “UTF-8” –o outputfile inputfile

• where ISO-8859-1 stands for the current encoding of your file, here we assume is the standard ISO encoding. But if the encoding used is a different one you have to change it accordingly.

• you can use Notepad++: open the file, click on Encoding and choose the option Convert to UTF8 without BOM and save the file.

Software

The Software menu gives you access to the Interbull checking programs. By clicking on Software a drop down menu will open and you will be able to choose the type of checking program you are interested in, i.e. Pedigree, Proofs or GenoList. Under Software you will also find information on the programs and instructions on how to run them.

Proof's Checking Program

Member organizations will upload national evaluation datasets through IDEA in much the same way as they upload pedigree datasets. There is a downloadable Python program called CheckProofsPara.py available for checking proofs and parameter files. The program will check a format 300 (proof file) and an associated format 301 (parameter file) for formal correctness and prepare a zip file for upload if no errors are found in the files.

The proof file (format 300) is designed to allow considerable flexibility for the user. Each record contains an evaluation (i.e. proof) and associated information for a single brd-pop-trt combination. One file may contain records for as many or few brd-pop-trt combinations as desired. It may be natural for organizations to include all traits in a trait group in the same file, as they have in the past, but this is not essential. They may also choose to upload evaluations for all breeds, populations and traits in a single file if they find that more convenient. If problems are found with some specific combinations, only those combinations need to be re-loaded.

It is essential that proof records for all bulls be included in the same file for any one brd-pop-trt combination whether the dataset is a first submission for the IGE run in question, or a re-submission with some problem corrected. When new data are uploaded for any combination, all records present in IDEA for that combination are deleted prior to loading the new records. Thus, it is not acceptable to submit a partial dataset in order to correct the evaluations of some subset of bulls.

Every proof file must be accompanied by a parameter file!. The records in the parameter file give information about the national evaluations that is common to all records in the proof file for a given brd-pop-trt combination. There must be a record in the parameter file for each brd-pop-trt combination present in the proof file. Extra records present in the parameter file will simply be ignored. This allows users to maintain a single parameter file to be submitted with several proof files, if desired.

The user instructions and file formats (see Appendix I and II) give details on how to run the program and on the checks performed. If no errors are found, a zip file is created with the name IB-ORGCODE-IG-yyymmddThhmmss.zip containing the input proof and parameter files.

The program requires access to the internet and specifically to a few functions/pages in the IDEA web application. Firstly, in order to ensure that the user has the most recent version of the software, the internal version tag is compared to the version listed on the download page and if the user’s copy is older an appropriate message is printed and the program exits. Lists of valid orgcode’s and breed-pop-trait combinations for which the user’s organization has EBV upload authority are also obtained from the IDEA web application. If errors occur they are listed to the screen and no zip file is created. When checking the proof file only the first 10 errors of each type are listed.

Proofs

The Proofs menu gives you access to the main proofs functions which are: Upload, Review, Messages.

Upload and Verify program

By uploading data in IDEA users will no longer need to run the Verify program prior sending data to Interbull Centre. The Verify program will, in fact, be run automatically in IDEA during uploading.

To uploading functionality for parameter and proof files is available under 'Proofs/Upload'. The only file accepted by IDEA is the zip file IB-ORGCODE-IG-yyymmddThhmmss.zip produced by the CheckProofsPara.py, no other files are accepted. Once in 'Proofs/Upload' users will be able to browse the appropriate file and upload it by click on "Submit query".

The uploading of data will not happen on real time but data will be set on a queue and processed on a later time. Right after clicking "Submit query" a message on the screen will display the amount of parameter and proofs records submitted. A confirmation email will be sent to the email address associated to the user that has uploaded data.
The following are the steps the data will go through during uploading:

1. CheckProofsPara.py will run once again inside IDEA to assure correctness of format and contents

2. The Verify program will check your data against the previous one available.

Confirmation email

Either an "EBV upload success" or an "EBV upload failure" email will be sent to you upon completion of the uploading process. If the uploading is successful the "EBV upload success" email will list some basic information on your data such as:

1. Number of rows in parameter file associated with proofs
2. Number of records read from the proof file
3. Number of animals found by real AID
4. Number of animals found by alias ID
5. Number of flagged rows in proof file

The email can contain up to three different WARNINGs associated to three attachments:

1. Warning: [n] animal(s) were referenced in your file, but not present in the pedigree database. These animals were discarded! See a detailed list in the attached 'missing_animals.csv' file.
2. Warning: [n] animal(s) needing updated pedigree records detected! See 'ped_needed.csv' for a complete list of the animals.
3. Warning: Use of aliases detected! See 'ped_alias.csv' for a complete list of the animals.

An important source of information comes from Number of flagged rows in proof file: this number represents the amount of discrepancies found by the Verify program. If it is 0 (zero) it means that no discrepancies have been found and your data is automatically submitted for the IGE. If it is not 0 (zero) it means that the Verify program has found some discrepancies in your data compared to the previous one available or the system has detected animals with missing pedigree. To double check the data you need to log in IDEA and go to Proof/Review.

Animals not present in IDEA pedigree or lacking pedigree information (i.e. present in the pedigree database but with sire and dam unknown) will be excluded from the international evaluation .

Table 1 summarizes the action needed upon reception of a confirmation email with such warnings and attachments:

After uploading: What's next?

Uploading represents only the very first step for submitting your data for an IGE. Here is a description of the actions you need to follow to submit your data for an IGE.

IDEA Proof/Review

The Proof/Review page contains all the information you need to review your data and eventually submit them for a IGE.

Creation of cross reference in the database

The creation of cross references in the database is made by uploading of a IB202-org_code-yyyymmddThhmmss.zip, i.e. file202 previously checked by CheckLinks.py. Access to the program and its instruction is via the Software menu link.

To upload your file, browse it using the Browse buttom and upload it by clicking on Upload.

Whithin few minutes you will receive an email with the outcome of your uploading: if it was successful or if it failed for some reasons.

Attached to the confirmation email you will find two files called "processed.txt" and "not_processed.txt". The "processed.txt" contains all animals that have been linked in the database, the "not_processed.txt" contains all animals for which the link has been skipped and therefore not performed in the database

Table 4 - Link Upload Legend

Please remember that two IDs will be always considered as two different animals until a proper file202 is uploaded.

In IDEA you can create cross-reference for the following situations:

• linking your domestic animals, i.e. animals for which you are the authoritative organization;
• correcting the ID of your foreign animals (if you are the first reporting organization, see Table 2);
• adding national IDs to a given international ID.

Please be advised that IDEA does not discern between international and national aliases as it solely relies on the international ID.

In IDEA you can now submit cross-references for animals outside your authority. In this case the pair you are trying to link together will be treated as potential duplicates and listed in the corresponding authoritative organization's potential duplicates page, with your choice highlighted.The link will be performed only if the authoritative organization agrees with your choice.

The table below summarizes all possible linking scenarioes together with an explanation of what will happen inside IDEA.

Table 5: Possible linking actions

AID1 and AID2 are according to the format of file202, therefore AID1=wrong/alias AID and AID2=international AID.

Name of the animal

The official name of an animal is equal to the name provided by each official organization. To avoid sudden changes in names or name missing it is extremely important that each authoritative organization always provide a name record, whenever available, for every uploading and be consistent with the name, i.e. do not provide the full name for the first uploading and a short version of it for the next, otherwise the name of the animal will get overwritten.

Please note that IDEA is based on a UTF-8 character encoding. All files entering IDEA must be created with a UTF-8 character encoding as well.

How do I change/add a name for a given animal?

Only authoritative organization or first reporting organization, while the record is till unverified, can modify the name of an animal. To do so simply upload a pedigree file with the new name information and the changes will be recorded in the database.

Potential Duplicates

By clicking on “Duplicates” you will access a table listing all potential duplicates associated to your organization.

The table presents 8 columns: First Animal, Second Animal, Auth. Orgs, Feedback, and 4 action columns such as No Opinion (NO), 1st, 2nd, Not duplicates (ND).

In the First and Second Animal's column you will find information related to the pair of animals considered as potential duplicate. Each animal in the table is presented with its sire, dam, birthdate and name so to make it easier for you to realize if the animals are indeed duplicates or not.

The Auth. Orgs. column shows the organization(s) that are authoritative for the pair. In general, if your organization is authoritative for both animals involved in the conflict you have complete control over the pair. If your organization is authoritative only for one of the two animals then your selected action will appear in the "Feedback" column. The action will be processed only if the other authoritative organization agrees with your selected action.

For each pair you can choose among the following actions: No opinion (NO), 1st animal (1st), second animal (2nd), Not duplicates (ND).

Let's see in details what will happen for each action:

• You are authoritative for both IDs and select "1st": you indicate that the AID appearing in the first animal column is the official ID. By clicking "Submit changes" the ID listed in the "second animal ID" will become an alias of the first animal ID. Likewise if you select "2nd".
• You are authoritative for both IDs and select ND: you indicate that the two IDs are not duplicates. The two IDs will be marked as two different animals, dropped from your list of potential duplicates and they will never reappear.
• You are authoritative for both IDs and select NO: you indicate that you cannot say if the animals are duplicates or not. The pair selected in such way will remain in your potential duplicate page.
• You are authoritative only for one ID: Your choice will appear in the "Feedback" column and will be visible by you and by the other organization involved. An action will be performed only if the other organization agrees with your selection. In case the other organization disagrees the pair will remain in both your duplicate page.

By default your choice is always set to NO (No Opinion). In this way you can decide which pairs to process first, in fact by leaving the selection on NO will leave the pairs inaltered.

Once you have done processing the potential duplicates do not forget to click "Submit Changes" so that your selection(s) can be registered in the database, or they will get lost.

By clicking on "Reset to original values" will set your selection to the latest submitted one.

By default the table will show you the first 200 entries. You can modified the number by clicking on the "show entries" above the table.You can advance to the next group of animals by clicking on "Next/Previous". Also each header is an active header therefore you can sort the content of the table as it better suits you. You can even search for a given ID using the search box.

Statistics menu

By clicking on "Statistics" you will get access to your "Request of Pedigree", "Corrected Animals" file, statistics on overall number of animals pending verification by other organizations and overall number of animals pending verification by your organization.

Request of Pedigree

You can either view or download your request of pedigree. the file has the format shown in Appendix IV. This file contains a list of all animals as loaded by reporting countries and for which you appear as the authoritative organization. This means that only you have the right to say if the pedigree record is correct or not by verifying their pedigree.

Verification Process: How does it work?

For each animal listed in your “Request of Pedigree” file you have to upload its pedigree information as it appears in your own database, using a file format 200 or 601 and CheckPedigree.py. By doing so you are verifying the reported information as the system considers verified only the information provided by the authority organization. When you are verifying an animal's record you might find yourself in front of four possible scenarios, below you find instructions on what to do for each of them.

Scenario 1

If you find that the reported animal ID is correct then you will have to:

• Upload a pedigree file (file200 or 601 previously inspected by CheckPedigree.py) as it appears in your own database.

Scenario 2

If you notice that an animal has been reported with an incorrect international id then you will have to:

• Upload a pedigree record for that animal using its correct id

• AND upload a file202 previously checked by CheckLinks.py. The file202 will provide the cross-reference link between the reported animal's id and the animal's id you verified.

Example:

A country submitted a pedigree for the animal BSWUSAF000000569466 using the ID BSWUSAF000000659466.

As it is an USA animal, the animal will appear in the USA list of Request of Pedigree. When looking at the record USA notices that two numbers have been misplaced. So USA will upload a pedigree file using the correct id for the animal (BSWUSAF000000569466) and create a file202 which will look like:

202 BSWUSAF000000659466 BSWUSAF000000569466

Scenario 3

If you realize that a given animal has been erroneously associated to your organization and you know to which organization it should belong:

• Prepare two file202 containing two entries for the same animal: first file sets the wrong ID to UUUUUUUUUUUUUUUUUUU then second file links the wrong ID to the new organization's ID.

N.B. it is extremely important that you upload these file in the right order, i.e. first the link that sets the AID to invalid (first file202) and then the link creating the cross-reference with the other AID (second file202).

Example:

Animal BSWUSAM000803611398 is sent to USA for validation but USA realizes the animal belongs to DEU instead.

USA prepares two file202 that will look like:

first file202: 202 BSWUSAM000803611398 UUUUUUUUUUUUUUUUUUU

second file202: 202 BSWUSAM000803611398 BSWDEUM000803611398

In this way the USA ID will get status INVALID and will be linked to the DEU ID.

Scenario 4

If you do not know anything about that animal and it does not appear in your database then you have to:

• Create a file202 containing “UUUUUUUUUUUUUUUUUUU” in the “correct IID” field.

Doing so the animal’s international ID will be marked as invalid.

Example:

Animal BSWUSAM000000000008 cannot be found in the USA database.The file 202 will be:

202 BSWUSAM000000000008 UUUUUUUUUUUUUUUUUUU

Invalid IDs

Anytime an AID is submitted to the database with a link to UUUUUUUUUUUUUUUUUUU it will be marked as invalid. This means that its authoritative organization did not find any records of it in its database. Nevertheless such AIDs can still be valid AIDs in other countries, especially if the animal is an old animal or if it was sold as a calf or embryos. Therefore such AID will still be extracted from the database and it could partecipate into a gentic evaluation if it appears itself connected to a genetic proofs or connected via the pedigree to an animal with proofs.

How can I set an animal ID as alias with an invalid status?

In IDEA you can now set an animal ID to invalid and then link it to another ID so that it will become an invalid alias of that given international ID.

In order to do so you need to fullfill two conditions:

1) You need to be either the authoritative organization or the first reporting organization for the ID1 (i.e. the ID you want to set as invalid alias)

2) the new ID must not be present in IDEA

Given that you fullfill both conditions, you will have to proceed in two steps:

First step: you need to set the alias-to-be ID to invalid:

1) Prepare a file 202 linking the wrong ID to UUUUUUUUUUUUUUUUUUU

2) run the file202 with the CheckLinks.py you download from IDEA/Software

3) upload the IB-202.zip file into IDEA

• Second step: you now need to alias the invalid ID to a new ID

1) prepare a file 202 linking the set-to invalid ID (in the previousstep) with the new international ID

2) run the file202 with the CheckLinks.py

3) upload the IB-202.zip file into IDEA

The feedback you will receive in the confiramtion email will say "The AID of the first animal was replaced with the second AID, and turned into an invalid alias."

Corrected Foreign Animals

In this file you find information on the validation activity over an IID, and its pedigree, done by each authoritative organization on your foreign animals. Therefore by checking it you can get corrected IDs and/or corrected pedigree information of the animals you have reported..You can either view or download the file. The file format is specified in Appendix V.

Once you have gone through the file and applied the necessary corrections in your own database, you should reset the content of the file by clicking on "Reset these to the latest updates". By doing so the content of the file will be emptied. Only changes registered in IDEA after your reset day will be listed again in this file.

As these information are retrieved from IDEA in real time it is very important that you use the "Reset these to the latest updates" fuctionality, this will speed up the time necessary for IDEA to display the file.

Pending Animals

The file contains all your foreign animals which appear still unverified by their authoritative organization. By looking at the list you can see which animals the authoritative organization is not able to validate, you might also realize that you had made an error in the ID of the animal. If you wish to correct the animal ID of any one of these animals you can do so by uploading a file 202 previously inspected by the CheckLink.py.

The file format is reported in APPENDIX VI, the file is sorted by the authoritative organization code.

Animals submitted by your organization and awaiting verification by authoritative organization

The table shows the general situation of your pedigree data as it is in the database at the time of your log in. The table contains the authoritative organization, the status of the animals and the overall count. By clicking on "Download" you will be able to download the list. The file has format as descripted in APPENDIX VI.

N.B. Animals associated to your organization and with animal status set to AUTO_CREATED are parents for which you have not provided a pedigree record. To have them dropped from this table you have to upload a pedigree file for these animals.

View statistics for animals that need verification from you

This table contains the list of all animals submitted to the Interbull database by other organizations for which you appear to be the authoritative organization and therefore you need to provide the correct information (see verification procedure above) . The table contains the reporting organization, the country it belongs to and the overall count. This table is useful to monitor your verification process.

Pedigree Conflicts

Although your national pedigree file has been already checked by the CheckPedigree.py for pedigree conflicts, there is the possibility that the international pedigree still shows some birthdates conflicts.To check for that click on "Conflicts", you will access a table showing all conflicts where your organization is involved.

The table contains the "first animal" and the "second animal" involved in the conflict together with their relationship status, i.e. parent, grand-parent, offspring.

As every tables in IDEA, each header is an active header so you can sort the content of teh table as it better fits you. Also you can modify the number of entries shown or search for a particular animal's ID.

How to handle animal's conflicts?

Sometimes a conflict could be due to unverified animals, if this is the case please proceed on verifying the animals double checking that the new birthdate you are going to provide will no more be in conflict.

If you do not know how to fix the conflict you should contact Interbull Centre deciding what action you, as the authoritative organization for that animal, want to take.

So, in general, to fix a conflict you should:

• Upload new pedigree file of the conflicting animal with a new no-conflicting birthdate

• In case you do not know how to fix it you should contact Interbull Centre

APPENDIX I: Organization Codes as provided by Interbull Centre

APPENDIX II: File Format 200 for Dairy Pedigree

APPENDIX IIa:File Format 601 for Beef Pedigree

APPENDIX III: Format File202 Correcting International ID by the Authoritative Organization

(Creates Cross-reference links, valid for dairy and beef users)

APPENDIX IV: Request of Pedigree for Authoritative Organization

APPENDIX V: Corrected Foreign Animals

Each record line is separated from the next by a ‘\n’

APPENDIX VI: Animals Pending Verification

APPENDIX VII: FREQUENTLY ASKED QUESTIONS

Q. How do I know that the pedigree file I have submitted has been successfully uploaded into the database?

A. You will receive a confirmation email with some information on the data you have uploaded.

Q.

How do I know if I have any animal to verify? A. By clicking on “Statistic/View statistics for animals that need verification from you” the table will show you the number of animals you need to verify and their reporting organization.

Q. What do I do if I have animals pending verification?

A. Download from the statistic menu the request of pedigree file. For each of the animal listed in the file you need to provide pedigree information as they appear in your own database and upload them using a file200 format previously checked by CheckPedigree.py. If you notice that the IID of the animals is wrong or is an alias ID then you also have to submit a file202 previously checked by CheckLinks.py.

Q. What I have to do if some IIDs listed in the request of pedigree cannot be found in my own database?

A. In this case you only have to submit a file202, checked by CheckLinks.py, with 19 “U”s (i.e. UUUUUUUUUUUUUUUUUUU) in the correct IID field.

Q. What do I do if I notice that an animal has been reported using a cross-reference ID instead than the official IID?

A. Provide the pedigree information for that animal as it appears in your own database using a file200 previously checked by CheckPedigree.py and also provide a file202, previously checked by CheckLinks.py, putting the correct official IID in the correct IID field.

Q. Can the actual system distinguish between ID formally correct but written in a different format and the real wrong ID?

A. Anytime the authoritative organization provides a file202 the “wrong/alias ID” a croos-reference record is created. The system does not distinguish between “formally correct” or “real wrong” IDs. The system is built on the principle that every ID is considered as potentially wrong until it gets verified by the authoritative organization. If an authoritative organization provides a “correct ID” (cross-reference link, file202) it means that the ID provided by the reporting organization was not entirely correct so it gets replaced with the one provided by the authoritative organization. The information provided by the reporting country is not lost but stored in the alternative scheme table. In case the ID reported in the correct field is represented by the unknown ID (i.e. 19 “U”s) then that ID is treated as “real wrong” and and marked as invalid.