Difference between revisions of "Getting Started At GlueX"

From GlueXWiki
Jump to: navigation, search
(Simulations)
m (Software)
(29 intermediate revisions by 7 users not shown)
Line 7: Line 7:
 
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.
 
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.
  
* Meetings: GlueX has many [https://halldweb.jlab.org/wiki/index.php/Meetings meetings] that meet on a regular basis (usually every other week).  Important meetings are that of the [https://halldweb.jlab.org/wiki-private/index.php/Physics_Working_Group_Meetings Physics Working Group] and the overall [https://halldweb.jlab.org/wiki/index.php/Hall-D_Weekly_Meeting Collaboration Biweekly Meeting]. You will also want to attend the appropriate [https://halldweb.jlab.org/wiki/index.php/Meetings#Physics topical working group] for your analysis topic.  These meetings can be accessed online via [https://halldweb.jlab.org/wiki/index.php/Connect_to_Bluejeans_Meetings BlueJeans]
+
<div class="toccolours mw-collapsible mw-collapsed">
* Email: 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 good list to subscribe to is the [https://mailman.jlab.org/mailman/listinfo/halld-physics halld-physics] listYou can get extra help at the [https://mailman.jlab.org/pipermail/halld-offline/2016-April/002297.html Software Help List]. A full list of jlab email groups can be found at https://mailman.jlab.org/ (use ctrl+F to search for "halld" and "gluex").
+
 
* Slack is a text chat service used for more informal communication.  Many experts and other collaborators hang out there and are available to answer your questions.  [https://jlab12gev.slack.com/signup Sign up here].
+
Information on meetings, mailing lists, and more! 
* There is a grad students and postdocs group group, which has an email list: gluex_grad_postdoc@jlab.org ([https://mailman.jlab.org/mailman/listinfo/Gluex_grad_postdoc subscription page]). They hosts an online "coffee break" every Tuesday and Thursday at 10 am -  https://bluejeans.com/572904255
+
(Click "Expand" to the right for more details -->):
 +
 
 +
<div class="mw-collapsible-content">
 +
 
 +
* Meetings: GlueX has many [https://halldweb.jlab.org/wiki/index.php/Meetings meetings] that meet on a regular basis (usually every other week) which you can attend [https://halldweb.jlab.org/wiki/index.php/Connect_to_ZoomGov_Meetings over Zoom].  Important meetings include:
 +
** [https://halldweb.jlab.org/wiki-private/index.php/Physics_Working_Group_Meetings Physics Working Group]
 +
** [https://halldweb.jlab.org/wiki/index.php/Hall-D_Weekly_Meeting Collaboration Biweekly Meeting]
 +
** [https://halldweb.jlab.org/wiki-private/index.php/Open_Analysis_Discussions Open Analysis Meeting]
 +
** [https://halldweb.jlab.org/wiki/index.php/Meetings#Physics Topical physics working groups]  
 +
are that of the [https://halldweb.jlab.org/wiki-private/index.php/Physics_Working_Group_Meetings Physics Working Group] and the overall [https://halldweb.jlab.org/wiki/index.php/Hall-D_Weekly_Meeting Collaboration Biweekly Meeting]. for your analysis topic.  These meetings can be accessed online via [https://halldweb.jlab.org/wiki/index.php/Connect_to_Bluejeans_Meetings 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: [https://mailman.jlab.org/mailman/listinfo/halld-physics halld-physics].   
 +
** Extra help is available the [https://mailman.jlab.org/pipermail/halld-offline/2016-April/002297.html Software Help List].  
 +
** A full list of jlab email groups can be found at https://mailman.jlab.org/ (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.  [https://jlab12gev.slack.com/signup Sign up here].
 +
* There is a grad students and postdocs group group: gluex_grad_postdoc@jlab.org ([https://mailman.jlab.org/mailman/listinfo/Gluex_grad_postdoc subscription page]). <!-- They hosts an online "coffee break" every Tuesday and Thursday at 10 am -  https://bluejeans.com/572904255 -->
 
* How to find people and contact info:
 
* How to find people and contact info:
 
** Look at the [https://gluexweb.jlab.org/people GlueX photo gallery] (login required - ask a GlueX colleague for details).
 
** Look at the [https://gluexweb.jlab.org/people GlueX photo gallery] (login required - ask a GlueX colleague for details).
 
** JLab emails can be found using the [https://misportal.jlab.org/mis/staff/staffsearch.cfm JLab phone book] or by using the <code>staff</code> command when logged into the ifarm.
 
** JLab emails can be found using the [https://misportal.jlab.org/mis/staff/staffsearch.cfm JLab phone book] or by using the <code>staff</code> command when logged into the ifarm.
 
** You can also look people up and their institutions in [https://www.jlab.org/Hall-D/shifts/ the GlueX shift scheduler].
 
** You can also look people up and their institutions in [https://www.jlab.org/Hall-D/shifts/ the GlueX shift scheduler].
 +
</div>
 +
 +
</div>
 +
 +
== 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 [https://halldweb.jlab.org/wiki/index.php/JLab_Visitor_Access_and_Training here].
 +
 +
Note that starting March 2021, you will have to reregister your visit even if you had a previous long-term visit established.
  
 
== Software ==
 
== Software ==
 +
* [[Software|The software overview page]] gives a nice short description of the GlueX software chain, and links to more comprehensive documentation.
  
* You will need to get a JLab computing account.  Find more information [https://cc.jlab.org/useraccounts on this page].
+
<div class="toccolours mw-collapsible mw-collapsed">
** If you have trouble accessing the wiki or other services, you may not be part of the "halld" group - contact Mark Ito.
+
Registering for a JLab account and configuring GlueX software
** Also make an account on [https://github.com/ GitHub] and ask Mark Ito to be added to the JeffersonLab organization.
+
(Click "Expand" to the right for more details -->):
** [https://scicomp.jlab.org/docs/FarmUsersGuide Here is some documentation] about the computing resources available at JLab.  Some other general information can be found [https://halldweb.jlab.org/doc-public/DocDB/ShowDocument?docid=4015 here].  A summary of running on the batch farm can be found [https://halldweb.jlab.org/doc-private/DocDB/ShowDocument?docid=4011 here].
+
 
 +
<div class="mw-collapsible-content">
 +
* You will need to register as a JLab user and get a computer user account.  Find more information [https://cc.jlab.org/useraccounts on this page].
 +
** To forward email sent to your JLab address, login at https://jidp2013.jlab.org/idp/Authn/UserPassword and then go to https://cc.jlab.org/pfeditor/edit  Warnings of training and/or badge expiration are sent to your JLab email address - <font color=red>DO NOT MISS THESE</font>.
 +
** Ask the [mailto:aaustreg@jlab.org software coordinator] to add you to the "halld" Linux and SLURM groups.
 +
*** You maybe have trouble accessing the wiki or other services otherwise.
 +
** Also make an account on [https://github.com/ GitHub] and the software coordinator to be added to the <b>JeffersonLab</b> organization.
 +
* References
 +
** [https://scicomp.jlab.org/docs/FarmUsersGuide Here is some documentation] about the computing resources available at JLab.   
 +
** Some other general information can be found [https://halldweb.jlab.org/doc-public/DocDB/ShowDocument?docid=4015 here].   
 +
** A summary of using the batch farm with GlueX data can be found [https://halldweb.jlab.org/doc-private/DocDB/ShowDocument?docid=4011 here].
 
* If you are working on the JLab ifarm, you will need to configure the GlueX computing environment. Follow these instructions:
 
* If you are working on the JLab ifarm, you will need to configure the GlueX computing environment. Follow these instructions:
 
** Run the command <code>source /group/halld/Software/build_scripts/gluex_env_boot_jlab.csh</code> to configure the <code>gxenv</code> and <code>gxclean</code> commands (assuming your shell is tcsh.  If you are using bash, run <code>gluex_env_boot.sh</code>).
 
** Run the command <code>source /group/halld/Software/build_scripts/gluex_env_boot_jlab.csh</code> to configure the <code>gxenv</code> and <code>gxclean</code> commands (assuming your shell is tcsh.  If you are using bash, run <code>gluex_env_boot.sh</code>).
 
*** 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.
 
*** 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. The current builds are found in <code>$HALLD_VERSIONS</code>. 
+
** 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. <code>gxenv some_version.xml</code>).
 +
***The current builds are found in <code>$HALLD_VERSIONS</code>. 
 
** gxclean will remove any GlueX environment configuration from your current environment.
 
** gxclean will remove any GlueX environment configuration from your current environment.
 
** [https://halldweb.jlab.org/docs/build_scripts_web/node6.html#SECTION00062400000000000000 The above info is referenced from here].
 
** [https://halldweb.jlab.org/docs/build_scripts_web/node6.html#SECTION00062400000000000000 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 [https://halldweb.jlab.org/docs/build_scripts_web/node10.html building your own version of this software], but this will take a lot of time and disk space!
 
** If you are mostly working at another institution, please contact your local software experts. You can also try [https://halldweb.jlab.org/docs/build_scripts_web/node10.html building your own version of this software], but this will take a lot of time and disk space!
 +
</div>
 +
 +
</div>
 +
 +
<div class="toccolours mw-collapsible mw-collapsed">
 +
Useful software packages and common
 +
(Click "Expand" to the right for more details -->):
 +
 +
<div class="mw-collapsible-content">
 
* 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
 
* 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
 
** [https://github.com/jeffersonlab/halld_recon halld_recon] - reconstruction of raw and simulated data, high-level analysis and ROOT skim generation
 
** [https://github.com/jeffersonlab/halld_recon halld_recon] - reconstruction of raw and simulated data, high-level analysis and ROOT skim generation
Line 36: Line 84:
 
* Other useful software:
 
* Other useful software:
 
** ROOT: [https://root.cern.ch/root/htmldoc/guides/primer/ROOTPrimerLetter.pdf Primer], [https://root.cern.ch/root/htmldoc/guides/users-guide/ROOTUsersGuide.html User's Guide]
 
** ROOT: [https://root.cern.ch/root/htmldoc/guides/primer/ROOTPrimerLetter.pdf Primer], [https://root.cern.ch/root/htmldoc/guides/users-guide/ROOTUsersGuide.html User's Guide]
** Amptools:
+
** Amptools: [https://github.com/mashephe/AmpTools GitHub], [https://github.com/mashephe/AmpTools/blob/master/AmpTools_User_Guide.pdf User Guide]
 
* Simple examples (no more than a few lines)
 
* Simple examples (no more than a few lines)
 
** Running hd_root to reconstruct data
 
** Running hd_root to reconstruct data
Line 42: Line 90:
 
** Running the ReactionFilter plugin
 
** Running the ReactionFilter plugin
 
** Running a DSelector over ReactionFilter output
 
** Running a DSelector over ReactionFilter output
 +
</div>
 +
 +
</div>
  
 
== Data Analysis ==
 
== 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 [https://halldweb.jlab.org/analysis/SubmitReaction.html at this page].
+
* 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 [https://halldweb.jlab.org/analysis/SubmitReaction.html at this page].
 
** You can find more detailed instructions on this process [https://halldweb.jlab.org/doc-private/DocDB/ShowDocument?docid=4010 here].
 
** You can find more detailed instructions on this process [https://halldweb.jlab.org/doc-private/DocDB/ShowDocument?docid=4010 here].
 
* To analyze the ROOT trees, you'll want to use the GlueX ROOT Analysis software
 
* 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: [https://halldweb.jlab.org/DocDB/0040/004006/002/zihlmann_collab_may19_analysis.pdf slides], [https://halldweb.jlab.org/doc-private/DocDB/ShowDocument?docid=4607 pdf] (draft)
 
** Here is some information on making and using a DSelector: [https://halldweb.jlab.org/DocDB/0040/004006/002/zihlmann_collab_may19_analysis.pdf slides], [https://halldweb.jlab.org/doc-private/DocDB/ShowDocument?docid=4607 pdf] (draft)
* When trying to separate signal from background, there are various variables you can try to look at.  These include:  [examples will be needed]
+
* When trying to separate signal from background, you can use several variables, including:  [examples will be needed]
 
** Time-of-flight particle ID
 
** Time-of-flight particle ID
 
** Kinematic fit &chi;<sup>2</sup>
 
** Kinematic fit &chi;<sup>2</sup>
Line 59: Line 111:
 
** [https://halldweb.jlab.org/wiki-private/index.php/GlueX_Phase-I_Dataset_Summary GlueX Phase-I Dataset Summary]
 
** [https://halldweb.jlab.org/wiki-private/index.php/GlueX_Phase-I_Dataset_Summary GlueX Phase-I Dataset Summary]
 
** [https://halldweb.jlab.org/wiki-private/index.php/Analysis_How-To%27s#How-To_Topics Analysis How-To's]
 
** [https://halldweb.jlab.org/wiki-private/index.php/Analysis_How-To%27s#How-To_Topics Analysis How-To's]
 +
* Link more tutorial talks in here
  
 
== Simulations ==
 
== Simulations ==
Line 72: Line 125:
 
** bggen - generates generic photoproduction events, good for looking at backgrounds
 
** bggen - generates generic photoproduction events, good for looking at backgrounds
 
** Would be good to have some simple examples here?
 
** Would be good to have some simple examples here?
* Remember, a simulation is only as good as the inputs given to it. If your simulation distributes particles differently than the data, don't be surprised when data and simulation look different!
+
* 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 ==
 
== Analysis and Presentation Tips ==
  
 +
* [https://halldweb.jlab.org/wiki-private/index.php/Guidance_for_Presentations Guidance for presentations, including root style script for figures]
 +
* This presentation also has useful advice: [https://halldweb.jlab.org/doc-private/DocDB/ShowDocument?docid=4679 Presentation Tips for GlueX Junior Scientists]. Recording [https://halldweb.jlab.org/doc-private/DocDB/ShowDocument?docid=4680 HERE]
 +
 +
<div class="toccolours mw-collapsible mw-collapsed">
 +
More detailed advice in here -
 +
(Click "Expand" to the right for more details -->):
 +
 +
<div class="mw-collapsible-content">
 
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.
 
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.
  
Line 88: Line 149:
 
# 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.
 
# 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.
 
# 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.
 
# 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.
 +
</div>
 +
 +
</div>

Revision as of 17:21, 21 April 2022

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.

Communication

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 https://mailman.jlab.org/ (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: gluex_grad_postdoc@jlab.org (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.

Software

  • The software overview page gives a nice short description of the GlueX software chain, and links to more comprehensive documentation.

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 gluex_env_boot.sh).
      • 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

  • 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 (sdobbs@fsu.edu).
  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.