LArSoft  v06_85_00
Liquid Argon Software toolkit - http://larsoft.org/
larexamples/v06_14_06/source/larexamples/AnalysisExample/ADDITIONAL_NOTES.md
Go to the documentation of this file.
1 # Analysis module example: additional notes {#AnalysisExample_ADDITIONAL_NOTES}
2 
3 | Example name: | AnalysisExample |
4 | --------------- | ------------------------------------------- |
5 | Type: | LArSoft module |
6 | Author: | Bill Seligman (seligman@nevis.columbia.edu) |
7 | Created on: | August 7, 2017 |
8 
9 
10 This is a detailed supplement to the brief notes in `README.md`. These
11 notes explain why things are done in a certain way in
12 `AnalysisExample_module.cc` (if you followed directions, you've renamed
13 it by now). Believe it or not, it's to teach you something useful.
14 
15 1. "Gosh, there's so much to read!" There are a number of guides (see
16  the links below) that can give you the basic commands to type
17  in. The goal of this tutorial is to explain the reasons why those
18  commands work. That way you know what to change and when to change
19  them.
20 
21  As noted on the web page, "Simplicity is not a virtue of LArSoft."
22  There's a natural tendency to treat a complex software package as
23  a "black box" and not understand what goes on inside. Hopefully
24  all these comments and details will help you open the black box
25  when you need it.
26 
27 2. See
28  <https://cdcvs.fnal.gov/redmine/projects/larsoft/wiki/Using_art_in_LArSoft>
29  for a description of the ART classes used in the.cc file. The
30  description of the artmod command is particularly interesting if
31  you're generating a module from scratch. Of course, since you're
32  starting from this code and editing it to do what you want, you
33  probably won't use the artmod command for this first analysis
34  project.
35 
36 3. Keep focused: You want to read in LArSoft events and create
37  histograms and n-tuples. Don't get bogged down in the detailed
38  code in the .cc file if your task doesn't involve dE/dx of primary
39  particles in an event. You might be better off renaming or moving
40  that file and creating a new one from scratch or using artmod,
41  referring to the original as needed.
42 
43 4. Why the "_module" part of the name? So you'll remember to use the
44  DEFINE_ART_MODULE macro in the file; it's near the end. This lets
45  you use the name of this class in a "module_type" statement in a
46  .fcl file; there's an example in the sample .fcl file in this
47  directory.
48 
49  Also, the name will help the system to compile it in its own
50  library and not to mix with modules from the same source directory.
51 
52 5. If you're familiar with C++, then the "_module.cc" file takes the
53  place of a 'main' routine in LArSoft. If you create any external
54  classes to be called by your module that are part of the same
55  package, you'll put the headers in a .h file and the
56  implementation in a .cxx file.
57 
58 6. Don't confuse the name "AnalysisExample" (in the larexamples
59  repository) with the contents of the package "AnalysisBase" (in
60  the lardataobj repository). The AnalysisBase package contains
61  classes that define the final physics objects produced by the
62  reconstruction process (particle ID, shower energy, etc.). The
63  AnalysisExample package provides an example of how to analyze
64  "stuff" that's been put in LArSoft event records.
65 
66 7. Once you have a ROOT file of histograms and n-tuples, what can you
67  do with it? There's a ROOT tutorial at
68  <http://www.nevis.columbia.edu/~seligman/root-class/> that will
69  teach you how to analyze n-tuples.
70 
71 8. I put in a couple of examples of how to use associations near the
72  end of the code:
73  <https://cdcvs.fnal.gov/redmine/projects/larsoft/wiki/Using_art_in_LArSoft#artAssns>
74 
75  These examples are intended to be sketches, not the full-blown
76  n-tuple creation examples earlier in the code. It should be enough
77  to get you started as you follow the LArSoft reconstruction chain,
78  either forwards or backwards.
79 
80 9. The code in the .cc file fetches simb::MCParticle and
81  sim::SimChannel objects directly. Since that code was written, two
82  services have been created that reads those objects for you, along with
83  simb::MCTruth objects. These are cheat::BackTrackerService, and
84  cheat::ParticleInventoryService.
85 
86  To use this service, get a handle to cheat::BackTrackerService in the
87  same way you get a handle to art::TFileService in the .cc file,
88  then use that handle to invoke any of the methods in
89  ${LARSIM_INC}/larsim/MCCheater/BackTrackerService.h.
90 
91  So why not use that service in AnalysisExample? Because for the
92  work you'll be doing, you'll probably won't be just reading in the
93  simulated particles and channels; you'll probably be creating
94  n-tuples and histograms based on other LArSoft objects. You'll
95  still use the same methods to read in those objects that are shown
96  in the .cc file: create an art::Handle to a std::vector, then use
97  art::Event::GetByLabel to fill the vector.
98 
99  Also, importing data products via services will make experts
100  mutter about good practises. The rule is that if your module uses
101  a data product, it should fetch it by itself. BackTracker is still
102  appreciated for its ability to recover connections between
103  reconstructed and generated particles.
104 
105  Sounds a bit complicated? It can be. That's why there are examples
106  in the code, plus comments in the .fcl file to help you understand
107  how the code connects to job control file.
108 
109  Keep BackTracker in mind; it's a handy tool. But learn I/O from
110  this example and from the wiki page at
111  <https://cdcvs.fnal.gov/redmine/projects/larsoft/wiki/Using_art_in_LArSoft>
112 
113 10. If you want to do dE/dx studies using this code as a starting
114  point, then you're going to need to put the following line at the
115  end of the .fcl script (e.g., prodsingle.fcl) you use to generate
116  events:
117 
118  ```
119  services.LArG4Parameters.KeepEMShowerDaughters: true
120  ```
121 
122  Why? In LArG4, by default, if a particle is a typical product of
123  e-m processes (bremmstrahlung, pair production, etc.) the particle
124  ID stored in the channels and hits is that of the "eve" particle;
125  that is, the ultimate mother particle that interacted in an
126  "interesting" way before converting into an e-m shower. That's a
127  reasonable thing to do if you're working on reconstructing
128  showers.
129 
130  But for dE/dx studies, it becomes confusing; the particle you're
131  tracking seems to have energy losses throughout the volume of the
132  detector. You want to distinguish the particle of interest from
133  any of its daughter particles. Setting the above flag will store
134  the original Geant4 track ID for each daughter's energy deposits,
135  so you can easily exclude them as shown in the code.
136 
137 11. So what's all this stuff about vectors, maps, range-based for
138  loops, and iterators?
139 
140  They're part of an important extension to C++ called STL, the
141  Standard Template Library. (Bonus geek credits if you first read
142  "STL" as "slower than light.") Vectors and maps are used
143  extensively in LArSoft; occasionally other STL containers are used
144  as well.
145 
146  When you first come into contact with STL classes, there's a
147  tendency to treat them like FORTRAN arrays (if you learned
148  programming before 1995) or like Python dictionaries (if you
149  learned programming after 2005). If you use the same techniques to
150  handle vectors and maps as you did in those other languages,
151  you'll get slow, inefficient code that may waste large amounts of
152  memory.
153 
154  Obviously, you can't learn all about STL in a single code
155  example. What I've tried to do is demonstrate some basics: use
156  iterators to step through STL containers (vectors, maps, lists,
157  etc.); don't copy an entire object when you can copy a pointer or
158  an address; use "auto" to save on typing; use "const" to protect
159  your data; take advantage of STL's built-in algorithms when you
160  can (like fast binary searches on sorted containers).
161 
162  To make things a bit more complicated, in Sep-2012 we started
163  using a C++ compiler that enabled the additional language features
164  in C++11. The code examples attempt to illustrate what you can now
165  do with these new features, including the "auto" keyword and
166  range-based for loops.
167 
168  When you start asking, "Why does this method return an entire map
169  instead of some kind of pointer to the map? Are they at least
170  considering move semantics?" then you know you've mastered STL,
171  memory management, and the new extensions to C++.
172 
173 12. "Gosh, AnalysisExample_module.cc is so loooooong! It's got many
174  layers of nested loops. Couldn't you have prepared something
175  shorter?"
176 
177  Perhaps. But every analysis program or script I've seen has
178  contained multiple levels of control structures like this ones you
179  see here. Unlike Algorithms, Tools, or Services, which are often
180  optimized for efficiency, analysis programs just grow and grow and
181  grow. There's not much incentive to break-out functionality into
182  sub-modules (as we do with DetectorDiagonal).
183 
184  Conclusion: This is the kind of code you will write. Feel free to
185  write better! (And don't forget the comments!)