PDG Encoding Tutorial

Introduction

Please follow this tutorial using the tutorial instance of PdgWorkspace. It runs with a throw-away copy of the PDG database. This allows you to enter mock data without any danger of it showing up in the production database.

The tutorial has several parts. They should be followed in the order shown on this page, because some steps use the input from previous steps.

If you're uncertain about how to do certain operations, you should be able to find out the necessary details using the HowTo recipes on the encoding tool help page.

Part 1: Basics and navigation

1. Log in to the tutorial instance of PdgWorkspace at https://pdgprod.lbl.gov/tutorial/PdgWorkspace/. Your login information (e-mail address or username, and password) is the same as for the production version of PdgWorkspace. After logging in, you can tell that you're not using the production version from the database information displayed in red beneath the PdgWorkspace logo.
2. If you have multiple roles in PDG, you may have access to multiple tools in PdgWorkspace. If the Encoding Tool is not already selected, click on "Encodings" in the top line.
3. Now that you are in the encoding tool, can you tell what papers you need to work on? What papers will you have to work on later, after someone else has done their part? What papers have you completed already? (Hint: use the task filter)
4. If you're an overseer, how can you see the tasks your encoder is currently supposed to work on?
5. If you're a coordinator, how can you see all the tasks your encoder(s) and overseer(s) are responsible for?
6. Choose any one of your papers (in either current or future tasks). How can you get to the actual paper?
7. Click on the task name in the first column to enter the detailed screens about this paper, where you could enter, update and eventually sign off the detailed information encoded for this paper.
8. For now, return to the overall task list.
9. To see the latest information on any paper - even one that you're not responsible for, use "Show tasks for paper" in the task filter. Find another paper and click on the corresponding task. Note how you're not allowed to update that paper's information if you're not responsible for its encoding.

Part 2: Messaging

The encoding tool includes a messaging system that should be used whenever possible instead of e-mailing e.g. the editor or your overseer. Messages are attached to the corresponding tasks. You will get a much faster response from the editor if you use the messaging system rather than e-mail.

1. Choose a task and enter a message to the overseer (if you're an encoder) or encoder (if you're an overseer) for this paper.
2. Enter another message with a request to the editor.
3. Return to the task list and note where the number of messages is shown. Can you directly display the messages from the task list?

Part 3: Assignment of papers (for teams)

For some particles, the same person is always the encoder and the another person is always the overseer. In this case, the system directly assigns each paper to the correct person. You will see this assignment in the task list. If you're in this case, you may skip to Part 4.

If you are working in a team of encoders and/or overseers where different people may take on a different role for each paper, do the following steps:

1. Note how in the task list some of your papers/task are shown as unassigned.
2. To assign a paper to yourself, you can just start working on the corresponding task. Pick a task, enter some author information for the paper, save, and return to the task list. Now check the assignment of the task. (Once you save something, that task will be assigned to you as encoder. If someone already worked on the task as encoder, you will become the overseer for that paper when you save something or sign off the paper.)
3. Alternatively, you can explicitly assign tasks to people in your team by clicking on the link "edit encoder/overseer assignment". This puts the task list into a mode, where one can change task assignments. Use this to assign a task to a different encoder.

Part 4: Explore online help and enter author information

Now it's time to enter some bibliographic information. We will encode dummy data, so it doesn't matter what task/paper you pick.

1. Pick a task.
2. Go to the reference details tab.
3. Look at the different fields. Do you have any questions about what to enter where and in what format? Likely you do, and lots of help is available online! First go to the Help page (link at top of page). Here you find general instructions for encoders and overseers, as well as detailed HowTo articles on most things you might have to do. For example, there's an article about how to add bibliographic information.
4. In addition to the Help page and HowTo articles, most fields provide specific help if you click on the question mark "?" icon. Try one of the "?" icons.
5. In many cases, the system can guess what you might want to enter. The name of many fields is a link that will pop up a selection panel. Click on "Author", "Collaboration", and "Verifier" to explore these panels. Finally, most fields provide suggestions (for example, start typing "AT" in the Collaboration field).
6. Now enter and save some bibliographic information.

Part 5: Enter a measurement

1. Go to the "add measurements" tab where you will add a measurement to an existing datablock (later you will create a new datablock).
2. First display the existing data in the datablock where you want to add a measurement. Pick a datablock (this is mock data, so it doesn't matter which one) from the Datablock browser either by expanding the entries for a particle, or, if you know the corresponding node name, directly "finding" the node.
3. Now that the datablock is displayed, understand what "evaluate macros" does (hint: help icon "?").
4. Enter a new measurement into that datablock (use the different help pages and remember the HowTo articles to find out exactly what you need to do).
5. Move an existing measurement "below the line", so that it is no longer used in averages.
6. Add a measurement with a footnote with the following source text: "#ref{BAI 2000} measures #p{psi(3770)}.". See how this footnote will be rendered. Note that BAI 2000 will be a clickable reference in pdgLive!
7. Attach an existing footnote to the new measurement entered in step 4.

Part 6: Signoff an encoding

Now that you've updated the bibliographic information, hopefully added a verifier, and entered some measurement, you're happy with your encoding and are ready to pass it on to your overseer (or, if you're the overseer, to the editor).

1. In the "review & signoff" tab, check all the information you've entered. If you see "<missing>", make sure you haven't forgotten something.
2. Create the PDF verification pages and check them as well (use the "check" link). This also updates fits and averages for the datablocks you've modified.
3. Finally sign off the encoding (or send it back to the encoder for revision).

Part 7: Add a new datablock

1. Using the toolbox tab, add a new datablock. Assume that the datablock will contain mass measurements that should be displayed in units of "10^-3 GeV".
2. Add a measurement of (2 +- 0.5) E-3 GeV to the datablock and make sure it is correctly displayed.

Part 8: Add a new branching ratio including a decay mode that hasn't been encoded before

1. Using the toolbax tab, first create a new decay, then add a datablock for a new branching ratio.

Terminology

• A task refers to the work needed to enter the information about and results from a particular paper into the database. Each paper can be associated with results for multiple particles. If you are not responsible for all of these particles, your task for that paper is only associated with the particles you're resonsible for. A different task (or tasks) will be created for that paper for the particles that other people are responsible for. Often the terms task and paper are used interchangeably (this is correct in most cases).
• Datablock unit:The unit of a datablock (e.g. "10^-3 GeV") consists of two parts. The actual unit (GeV) and a multiplier ("10^-3"). The multiplier is only used for display purposes. Thus all measurements must be entered in terms of the actual unit, i.e. without the multiplier. This means that if a datablock is displayed in units of "10^-3 GeV", a measurement of "10^-3 GeV" needs to be entered as "1E-3" even though it will be displayed as "1" in the datablock. (Note that when macro evaluation is off, multipliers are not used, so that you see exactly what was entered.)
• Node: A node is an alphanumerical identifier of 4 to 6 characters that identifies a particle or datablock in the PDG computing system.