1 # Analysis module example: additional notes {#AnalysisExample_ADDITIONAL_NOTES}
3 | Example name: | AnalysisExample |
4 | --------------- | ------------------------------------------- |
5 | Type: | LArSoft module |
6 | Author: | Bill Seligman (seligman@nevis.columbia.edu) |
7 | Created on: | August 7, 2017 |
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.
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
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
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
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.
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
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.
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.
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.
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.
71 8. I put in a couple of examples of how to use associations near the
73 <https://cdcvs.fnal.gov/redmine/projects/larsoft/wiki/Using_art_in_LArSoft#artAssns>
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.
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.
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.
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.
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.
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.
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>
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
119 services.LArG4Parameters.KeepEMShowerDaughters: true
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
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.
137 11. So what's all this stuff about vectors, maps, range-based for
138 loops, and iterators?
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
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
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).
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.
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++.
173 12. "Gosh, AnalysisExample_module.cc is so loooooong! It's got many
174 layers of nested loops. Couldn't you have prepared something
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).
184 Conclusion: This is the kind of code you will write. Feel free to
185 write better! (And don't forget the comments!)
1.8.11 
