Getting Started At GlueX

From GlueXWiki
Jump to: navigation, search

Welcome new collaborator! The following is a collection of links and suggestions in order to get you oriented and on the way to analyzing GlueX data.


GlueX is a multi-purpose experiment with many subsystems. Many people work on this experiment, and their efforts are organized into different subgroups, so communication is an important aspect of collaboration.

Information on meetings, mailing lists, and more! (Click "Expand" to the right for more details -->):

are that of the Physics Working Group and the overall Collaboration Biweekly Meeting. for your analysis topic. These meetings can be accessed online via BlueJeans

  • Email lists: GlueX has several email lists used for discussion and annoucements.
    • You will be added to the GlueX Collaboration email list when you become an official Collaboration member.
    • Another important list: halld-physics.
    • Extra help is available the Software Help List.
    • A full list of jlab email groups can be found at (use ctrl+F to search for "halld" and "gluex").
  • Slack is used for more informal communication - many experts and other collaborators hang out there and are available to answer your questions. Sign up here.
  • There is a grad students and postdocs group group: (subscription page).
  • How to find people and contact info:

JLab Visitor Access and Training

To access JLab for shifts or meetings you'll need to complete a few steps of registration and training, described here.

Note that starting March 2021, you will have to reregister your visit even if you had a previous long-term visit established.


  • The software overview page gives a nice short description of the GlueX software chain, and links to more comprehensive documentation.
  • In the GlueX Tutorial 2022, you may find an introduction and useful examples for the individual analysis steps

Registering for a JLab account and configuring GlueX software (Click "Expand" to the right for more details -->):

  • You will need to register as a JLab user and get a computer user account. Find more information on this page.
  • References
    • Here is some documentation about the computing resources available at JLab.
    • Some other general information can be found here.
    • A summary of using the batch farm with GlueX data can be found here.
  • If you are working on the JLab ifarm, you will need to configure the GlueX computing environment. Follow these instructions:
    • Run the command source /group/halld/Software/build_scripts/gluex_env_boot_jlab.csh to configure the gxenv and gxclean commands (assuming your shell is tcsh. If you are using bash, run
      • If you want these commands to be run automatically when you log in, please put them into your .cshrc (tcsh) or .profile (bash) files in your home directory.
    • gxenv (GlueXENVironment) sets up the environment.
      • Without an input file, it uses the most recent GlueX build.
      • It can also be provided with an XML file to setup a particular tagged release of software (e.g. gxenv some_version.xml).
      • The current builds are found in $HALLD_VERSIONS
    • gxclean will remove any GlueX environment configuration from your current environment.
    • The above info is referenced from here.
    • If you are mostly working at another institution, please contact your local software experts. You can also try building your own version of this software, but this will take a lot of time and disk space!

Useful software packages and common (Click "Expand" to the right for more details -->):

  • GlueX software consists of several packages, the most important are described below. For physics analysis, you will likely be mostly working with gluex_root_analysis
    • halld_recon - reconstruction of raw and simulated data, high-level analysis and ROOT skim generation
    • halld_sim - generation of simulated data, amplitude analysis
    • HDGeant4 - next-gen simulation of particles interacting with the detector
    • gluex_root_analysis - Analysis of ROOT skims
  • Other useful software:
  • Simple examples (no more than a few lines)
    • Running hd_root to reconstruct data
    • Generating simulated data
    • Running the ReactionFilter plugin
    • Running a DSelector over ReactionFilter output

Data Analysis

  • The GlueX data set is really huge, so instead of analyzing the reconstructed data directly, you should make a request to have a skim for a particular reaction (or reactions) generated.
    • Please do so at this page.
    • You can find more detailed instructions on this process here.
  • To analyze the ROOT trees, you'll want to use the GlueX ROOT Analysis software
    • Here is some information on making and using a DSelector: slides, pdf (draft)
  • When trying to separate signal from background, you can use several variables, including: [examples will be needed]
    • Time-of-flight particle ID
    • Kinematic fit χ2
    • Flight significance of long-lived particles
    • Kinematic selections
  • If you need to apply flux normalization or efficiency corrections, you can find a tutorial here.
  • If you are doing an amplitude analysis or other complicated fit, a basic introduction to AmpTools can be found here.
  • References
  • Link more tutorial talks in here


  • Simulations are almost always done via Monte Carlo (MC) methods. In other words, simulating many, many events in the detector is generally the easiest way to
  • The easiest way to generate samples of simulated data is using the MC sample submission page
  • Common generators and their uses:
    • gen_amp - sophisticated generator which handles correct angular distributions for many models and for reactions with broad resonances
    • genEtaRegge - are you looking at eta/eta' decays? Then this is a good place to start
    • genr8 - simple phase space generation for many reactions
    • bggen - generates generic photoproduction events, good for looking at backgrounds
    • Would be good to have some simple examples here?
  • Remember, a simulation is only as correct as the inputs it's given. If your simulation distributes particles differently than the data, don't be surprised when data and simulation features look different!

Analysis and Presentation Tips

More detailed advice in here - (Click "Expand" to the right for more details -->):

Here is some general advice about analyzing data and presenting your results. Every analysis is different, but there are some time-tested general rules to keep in mind.

  1. If you're analyzing a channel for the first time, start by making some tight selections to isolate your signal (and thereby minimize physics background contributions). Later you can relax them and try to understand what effect each of them has.
  2. When you are trying new things towards building a better understanding of your variables, try just varying one selection and understanding it before moving on to the next. If you vary multiple things at once, it's tough to tell which one is causing whatever effect you are seeing.
  3. Many times less is more! Be careful about applying too many different event selections, and know what effect each one of them has. Slicing and dicing your data too much can lead to unexpected problems, whether it's difficulties in simulating their effects or accidentally creating a signal.
  4. Even though you may have the 'plumbing' working all the way to your desired goal (asymmetry, cross section, etc), remember those quantities are complicated and involve many things both from data analysis and Monte Carlo. It is best to present things starting from basic quantities (e.g. angular distributions, invariant masses, and only when those are understood then move up the line to more complicated corrections). Step by step is the name of the game.
  5. You should present your results at a topical physics group meeting, to get some feedback and let other people in the Collaboration know what you are doing. If you don't know what meeting to present at, ask your advisor or the Physics Analysis Coordinator (
  6. Don't feel like you have to present at every meeting! Updates are welcomed, where slides previously shown can be in the backups and the new plots shown up front. Don't forget that your audience doesn't remember what you've previously shown nearly as well as you do.
  7. Don't forget to include which data set and which analysis/MC versions you are using in one of your intro slides.
  8. When making comparisons (between data sets, data and MC, plots shown previously) it is helpful to have the two plots being compared side by side. It is hard for most to remember what was shown 2 or 4 weeks ago.
  9. It's a good idea to get your advisor or someone else from your local group to look over your results/slides before you present them. Sometimes a fresh set of eyes sees something obvious that you've missed.
  10. If you get stuck, ask someone! Often someone else will have faced a similar problem to you, and will be happy to share their experience. The Tuesday afternoon Open Analysis Meeting is a good place to start.