Project

General

Profile

Well met!

For the most up-to-date FNEX guide and Quickstart, please see the FNEX tech note . The information on this wiki may be dated. The tech note is much less likely to be so.

Seriously, go read the FNEX tech note . It has a Cliff Notes version and everything.

FNEX: An introduction

FNEX is an oscillation analysis package that works with the ART framework to provide rapid, adjustable extrapolations, best fits, and confidence level contours with full, event-by-event records. You may use existing variables to describe your events, or define your own variables by creating a custom extension of the FNESetup class. This is a growing project with several planned add-ons. If you are interested in developing this package, please contact Keith at . If you encounter a bug, or feel that a sorely-needed feature is missing, please send friendly suggestions, scathing anathemas, and heartfelt success stories to the same address.

What to expect from this Wiki page

This page contains step-by-step instructions on how to use FNEPackage, starting from the moment that you addpkg_svn -h FNEPackage, to your proud ownership of an extrapolated Far Detector reconstructed energy spectrum--complete with best fit neutrino oscillation parameters describing your data:

By the end of this wiki page, you should also have a sense as to how the package is designed; how to identify problems; and how to create your own customized extrapolation.

Planned expansions for FNEPackage

Feldman-Cousins Surfaces and Contours (May 2015)
Systematic uncertainty options (June 2015)
FNESetup Numu/Nue templates (June 2015)
Voice activation (December 2025)

FNEPackage First Analysis Quickstart

Let us begin with a hypothetical. Your name is Ralexander Addovich, and you want to perform a Far/Near extrapolation using first analysis cuts. You would like to do this using the same variables, and the same cuts, as have been used thus far in the first analysis--perhaps making a few minor changes along the way.

Well, my friend, you are in luck. FNEPackage supports all first analysis variables and cuts, and can be placed into "first analysis" mode simply by making appropriate selections in the FNEPackage .fcl files. How to do so will be the focus of this section.

Download FNEPackage

The first step to creating a Far/Near extrapolation using FNEPackage is to download the package. Set up your preferred version of novasoft, cd into your favorite distribution, and execute:

addpkg_svn -h FNEPackage

Decide upon a numu or nue analysis

Open up fnespectrumprodjob_mc.fcl, and located the producers block. You'll see (among others,possibly) two fnespectrumprodjob templates:

producers:
  {
  CAFMaker:        @local::standard_cafmaker
  FNESpectrumProd: @local::standard_fnespectrumprod_numu_firstana
  #FNESpectrumProd: @local::standard_fnespectrumprod_nue_firstana
  }

In this case, we have chosen the Nue First Analysis template, local::standard_fnespectrumprod_nue_firstana. By default, this template will generate all values needed to apply first analysis Nue cuts. Alternately, you could choose the Numu first analysis template, local::standard_fnespectrumprod_numu_firstana--again, all values needed to apply first analysis Numu cuts will be calculated and saved.

It is important to note that by default, no cuts will be applied at this step. The files produced by running this job are quite small, and space is not much of a concern. By choosing to save all events, you can later apply different combinations of cuts at the FNESpectrumAna step. This latter step runs very rapidly, and so many analyses can be run in short order.

If you are very certain which cuts you would like to apply, however, you can enable or disable particular cuts by taking a look in FNESpectrumProd.fcl . Scroll down to the template that you are interested in -- for the following example, standard_fnespectrumprod_numu_firstana -- and look at the fnecuts block:

 #
 # FNE Cuts
 #

 fnecuts:
 {
        # Disabled
        kNumuDecafCut:
            {
            cut_lo: -0.5
            cut_hi:  1.5
            }

        # Enabled
        kNumu:
            {
            cut_lo:  0.5
            cut_hi:  1.5
            }

        # Disabled
        kNumuQE:
            {
            cut_lo:  -0.5
            cut_hi:  1.5
            }

        # Enabled
        kNumuNonQE:
            {
            cut_lo:  0.5
            cut_hi:  1.5
            }

 }

Above, I have modified the fnecuts block to enable the cuts kNumu and kNumuNonQE. To disable or enable a boolean cut such as these, it is sufficient to change the cut_lo value to -0.5 or 0.5, respectively, for the value of that variable. These cuts are defined in NumuCuts.h .

For the default template, only major cuts are presented explicitly. However, note all cuts available in NumuCuts.h may be enabled or disabled in FNESpectrumProd.fcl in the same manner, simply by adding the appropriate lines to the fnecuts block. For example, you could add an explicit cut on kNumuQuality as:

# Enabled
kNumuQuality:
{
cut_lo:  0.5
cut_hi:  1.5
}

The same is true of the Nue first analysis template local::standard_fnespectrumprod_nue_firstana, for which all cuts in NueCutsFirstAna.h can be enabled in the fnecuts block.

Run the fnespectrumprodjob_mc/data.fcl jobs

Now that you've chosen which first analysis type you'd like to work with, it's time to run over some files. For a full extrapolation, you will need to run over six types of file:

Far Detector 
   Nonswap MC
   Swap MC
   Tauswap MC
   Data
Near Detector
   MC
   Data

Descriptions for all six file types can be found at the Official Datasets website . You need not tell FNEPackage which type of file you are sending it, or how to weight it--the file type will be automatically determined, and the appropriate flags set. During the FNESpectrumAna.fcl step, different contributions will be automatically weighted to reflect the POT of the FD and ND data, as appropriate.

If you attempt to move on to the FNESpectrumProd step without having collected output from all six types of file, the job will halt and tell you which file types are missing. Once you have corrected this, you will be able to run the extrapolation successfully.

For Monte Carlo test extrapolations--e.g., to test the effect of some new variable that you have introduced--you need run over only of the four types of MC file.

Finally, if you are looking to make a first analysis level extrapolation, then make certain to run over the PID-tier data and MC files. These are needed to construct the CAFAna variables that are looked at by first analysis cuts. The reader is directed toward the Official Datasets site for a list of all available data sets.

It is also recommended that you set up some workspace directory to organize and store the output of your jobs. The following structure is particularly useful:

FNEWorkspace_numu/
  FNEProdARTFiles
  FNEProdHistFiles
  FNEAnaARTFiles
  FNEAnaHistFiles

As suggested by the names, the master FNEWorkspace_numu directory contains four directories which each hold a certain type of file. FNEProdARTFiles holds the "-o" output of fnespectrumprodjob_mc/data.fcl; FNEProdHistFiles holds the "-T" output of fnespectrumprodjob_mc/data.fcl; and FNEAnaHist/ProdFiles holds the "-o" and "-T" output of fnespectrumanajob_mc/data.fcl.

Running locally

Now, you are set up to run over event files. Assuming that you have set up an FNEWorkspace as described in the previous section, it is a simple matter of executing the following command for each of your input ART files:

nova -c job/fnespectrumprodjob.fcl \
-s Path/To/ART_Event_File.root \
-o FNEWorkspace_numu/FNEProdARTFiles/fnespectrumprodjob_Event_File_ART.root \
-T FNEWorkspace_numu/FNEProdHistFiles/fnespectrumprodjob_Event_File_Hist.root

The command above displays the suggested naming format for output files, though you are free to label them with whatever consistent method you would like. The output histogram file set by the "-T" flag will contain all debug histograms, while the output ART root file tagged by the "-o" flag will contain a stripped-down ART file containing only FNESpectrum objects. You will not need to modify these files in any way--this information is provided only for interested parties.

If you are using the "-S" flag to describe your input ART files, e.g.,

"-s Path/To/Event_File.root "--> "-S file_of_art_file_names.txt"

then there is an important limitation to keep in mind--both for this job, and for any other ART jobs. You may not run over both Near Det and Far Det files, or both data and MC files, with the same nova -c job.fcl command. This is a particularly important point for this analysis, as we must run over all four possible types of files ( {ND, FD} x {DATA, MC} ) in order to perform a successful Far/Near extrapolation.

Running on the grid

You are free to submit your FNESpectrumProd jobs to the grid using whatever means you would like. However, I might suggest using Satish's submit_nova_art.py script , for which we have already provided a template configuration file as FNEPackage/fnepackage_sam_submit_config.txt. This file is also shown below:

# Job and project options 
--jobname kmatera_fnepackage_numu_job_mc                # Name of your project/jobs, be creative 
--defname prod_pid_FA15-01-12_fd_genie_fhc_fluxswap     # SAM dataset definition, defines files to be processed 
--njobs 5                                               # Number of jobs to run 
--files_per_job 2                                       # Max num files to be processed by each job (if 0, determine from njobs)
--opportunistic                                         # Run in opportunistic mode, i.e. steal non-NOvA nodes, optional 
--print_jobsub                                          # Print jobsub submission block, good for records 

# novasoft options 
-c fnespectrumprodjob_mc.fcl                    # Job fcl for nova executable 
--testrel /nova/app/users/kmatera/tagDev        # Path to test release, optional 
--tag development                               # Tagged release of novasoft to use 

# Copy-back: options for built-in runNovaSAM.py .  
# Advanced usage can replace this block with the --copyOutScript option
--dest /nova/ana/users/kmatera/FNEPackage     # Output directory 
--copyOut                                     # Copy back output to --dest location 
--runDirs                                     # Sort output by run number 
--outTier out1:fnespectrumprod_art            # Extension for ART-ROOT output stream                     
--histTier fnespectrumprod_hist               # Extension for hist (TFileService) output

Recall that the submit script can be run with a config file as submit_nova_art.py -f Path/to/config_file.txt. Please note that if you have a problem with this submission script, you should consult the grid submission page referenced above. You should not consult the FNEPackage maintainer.

Once all jobs have run, collect the "-T" and "-o" output into the appropriate folders in your workspace, and you are set to move on to the next step. You may do this in any way that you wish. However, if you have not modified the names of the TFileService and ART output files used in the default FNEPackage configuration files, the following bash commands:

find /path/to/grid/output/top_directory -name "*hist.root" -print0 | xargs -0 -I {} cp {} /path/to/FNEWorkspace/FNEProdHistFiles/
find /path/to/grid/output/top_directory -name "*art.root"  -print0 | xargs -0 -I {} cp {} /path/to/FNEWorkspace/FNEProdARTFiles/

will do the job nicely.

Choose cuts in FNESpectrumAna.fcl, and run fnespectrumanajob.fcl

Once you have run over all required file types, and organized the results into your FNEWorkspace output directory, it is time to produce an extrapolation.

Open up FNESpectrumAna.fcl, and scroll down to the template that you would like to work with. Once more, the first-analysis template options are fnespectrumanajob_numu_template and fnespectrumanajob_nue_template . You should then find the fnecuts block, and select which cuts you would like to enable/disable. The structure of this fnecuts block is identical to that in FNESpectrumProd.fcl, as shown above -- and as in that file, it is possible to enable any and all cuts described in NumuCuts.h and NueCutsFirstAna.h , using the same names.

You may also want to edit the variables:

EnergyBinLowest:      0.0     // Low limit for your reco energy distribution
EnergyBinHighest:     3.5     // High limit for your reco energy distribution
EnergyBinIncrement:  0.125   // Bin width for your reco energy distribution
FNEProdFileFolder:   "FNEWorkspace_nue/FNEProdHistFiles"  // Path to the "-T" output of your fnespectrumprod jobs.
FNEAnaFileFolder:    "FNEWorkspace_nue/FNEAnaHistFiles"   // Path to which you want to send extrapolation results
FNEExtrapEnumeration: 0       // The type of extrapolation that you want to perform

Finally, open up fnespectrumanajob.fcl, and make certain that this template is selected in the analyzers block:

 analyzers:
    { 
        FNESpectrumAna: @local::standard_fnespectrumana_numu_firstana
        #FNESpectrumAna: @local::standard_fnespectrumana_nue_firstana
    }

Now run your job using fnespectrumanajob.fcl as:

nova -c job/fnespectrumanajob.fcl \
-s FNEWorkspace_numu/FNEProdARTFiles/Any_Prod_Hist_File_In_This_Directory.root \
-o FNEWorkspace_numu/FNEAnaARTFiles/fnespectrumanajob_ART.root \
-T FNEWorkspace_numu/FNEAnaHistFiles/fnespectrumanajob_Hist.root

Your extrapolation will be stored in the folder specified by the FNEAnaFileFolder variable in your FNESpectrumAna.fcl file. Debug histograms and additional information will be stored in the ROOT output file specified by your argument to "-T". At this time, you need not do anything with the information stored in the ART output file specified by your argument to "-o".

How to browse your results

When the job has finished running, final results can be found in the FNEAnaFileFolder specified in your FNESpectrumAna.fcl file:

Structure of the final results directory FNEAnaHistFiles

The file ExtrapStacks.root contains THStack objects which display true and reconstructed energies for Near and Far Detector Monte Carlo events (Stack_*). It also contains TCanvas objects which compare reconstructed energy plots between data and Monte Carlo events (e.g., Far_MC_vs_DATA, Near_MC_vs_DATA, Far_Extrap_vs_DATA). The latter three plots are shown below, for the MC 1 to 1 extrapolation option, and the FA numu non-quasi-elastic cuts applied to 8000 ND events, and 4000 FD events of each type (nonswap, fluxswap, and tau). Results are scaled to 1E20 POT.

Normalized ND RecoE spectrum after applying FA Numu !QE cuts Normalized FD RecoE spectrum after applying FA Numu !QE cuts MC 1 to 1 extrapolation using 8000 ND events, 12000 FD events

The file BestFit.root contains the same objects as ExtrapStacks.root, but with the Monte Carlo events reweighted to reflect the best found fit between data, and the extrapolated Far Detector reconstructed energy spectrum. In both cases, the oscillation parameters used to weight the Monte Carlo events are displayed in the upper-right corner of the Far_Extrap_vs_DATA canvas. For the plots shown here, we used the MC 1 to 1 extrapolation object, and so the best fit plot is identical to the input plot.

As a note: while interesting as a foray into the reconstructed energy spectrum of the MC samples, you may argue that the choice of binning here, is subpar for a real analysis. This is true! Recall that bin size can be changed at any time by revisiting the variables

EnergyBinLowest:      0.0     // Low limit for your reco energy distribution
EnergyBinHighest:     3.5     // High limit for your reco energy distribution
EnergyBinIncrement:  0.125   // Bin width for your reco energy distribution

in your FNESpectrumAna.fcl file, and re-running the job. For example, here we try changing to EnergyBinIncrement: 0.5:

Normalized ND RecoE spectrum after applying FA Numu !QE cuts (better binning) Normalized FD RecoE spectrum after applying FA Numu !QE cuts (better binning) MC 1 to 1 extrapolation using 8000 ND events, 12000 FD events (better binning)

Finding the most visually- or analytically-pleasing choice of bin structure is left as an exercise to the reader.

The file fnespectrumanajob_Hist.root contains the "basic" histograms used to construct the THStack and TCanvas objects in ExtrapStacks.root and BestFit.root, and is useful for debug purposes. The file structure looks as follows:

Structure of the fnespectrumanajob_Hist debug file

The folder FNESpectrumTObjects contains FNESpectrum ART objects saved as TObjects; you will not need to work with this.

The folder PreExtrap_BasicPlots contains individual reconstructed and true energy plots for individual types of event, e.g., Far Detector Monte Carlo events of type nu_mu --> nu_e. This includes the unweighted distributions (exactly as constructed from event files); the weighted distributions (weighted by the oscillation probability on an event-by-event basis); and the normalized distributions (weighted by oscillation probability, and weighted by POT to match up with the POT from all processed data events).

The folder PreExtrap_CombinedPlots contains Near Det and Far Det Monte Carlo "summary" plots, with all events weighted by oscillation probability and by POT (as described above). All contributions to Near Det or Far Det distributions (e.g., all types of Monte Carlo event) are included.

Finally, the folder ExtrapolatedPlots contains the ratio of combined Monte Carlo reconstructed energy distributions to data, for both Near and Far Det distributions; as well as the Far Det extrapolated reconstructed energy spectrum, compared to data.

If something does not look quite right in ExtrapStacks.root and BestFit.root, you can investigate in fnespectrumanajob_Hist.root to determine where things went wrong. As an example, if you had forgotten to include nu_mu --> nu_e type events in our analysis (from the "Swap" class of Monte Carlo event files), then you would see that all plots in the BasicPlots[fd][mc_me] directory were empty.

FNEPackage Custom Extrapolation

Download FNEPackage

The first step to creating a Far/Near extrapolation using FNEPackage is to download the package! Set up your preferred version of novasoft, cd into your favorite distribution, and execute:

addpkg_svn -h FNEPackage

FNESetup

The next step is the heart of FNEPackage's customizability: the FNESetup class. In this class, you must describe which variables you will cut on, and how to derive these variables. You can pick an existing template, or create your own. As an example, let's consider the FNESetup_MCTest class, FNEPackage/FNESetup_MCTest.h/.cxx.

STEP 1 enum value_types

We begin by defining an enumerator containing the types of variable that we may want to cut on:

 
 enum value_types{

      //----- Required
      kSignalType = 0,
      kTrueE,
      kRecoE,

      //----- Particular to this Setup instance
      kVx,
      kVy,
      kVz,

      //----- Counter
      kNumCuts

    };

There are three variables that must always be present: kSignalType, which is the kind of neutrino interaction found (kMCmm, for example, is a Monte Carlo nu_mu-->nu_mu event); kTrueE, which is the true energy of the neutrino in this interaction; and kRecoE, which is the reconstructed energy in this interaction. The rest of the variables are up to your discretion.

STEP 2 SetupCuts( )

In this method, you define all cuts that you would like to apply to the values listed in enum_values. Each cut takes the following form, in which we use a cut on true energy as an example:


    pCutLabel[kTrueE]      = "TrueE";   //Name of variable, for display purposes
    pCut_Lo[kTrueE]        = 1.0;       // Min cut value
    pCut_Hi[kTrueE]        = 4.0;       // Max cut value

You can also set optional parameters:


    pKeep_Lo[kTrueE]       = 0.0;       // Min value for events to keep, e.g., for trying looser cuts later on
    pKeep_Hi[kTrueE]       = 5.0;       // Max value for events to keep " " " 
    pDisplay_Lo[kTrueE]    = 0.0;       // Min value for events to display in debug histograms
    pDisplay_Hi[kTrueE]    = 10.0;       // Max value of events to display " " " 

If these parameters are not set within SetupCuts(), then they will be automatically determined such that the range of Display values is slightly larger than the range of Keep values, which is slightly larger than the range of Cut values.

STEP 3: EvaluateEvent()

In this method, you describe how each variable is to be derived. The quantities that you are looking for may already be derived in one or more of the templates, and their derivations may be taken from there. For each value of interest, you must assign the instance of that value for this event, as well as the low and high uncertainties in that measurement. Using true energy as our example once more:


    std::vector<float> vals(kNumCuts);
    std::vector<float> vals_unc_lo(kNumCuts);
    std::vector<float> vals_unc_hi(kNumCuts);

    ...

    vals[kTrueE]        = nu.Nu().E();
    vals_unc_lo[kTrueE] = 0.98 * nu.Nu().E(); // We assign some arbitrary -2% uncertainty for this example
    vals_unc_hi[kTrueE] = 1.02 * nu.Nu().E(); // We assign some arbitrary +2% uncertainty for this example

    ...

    pVals.push_back(vals);
    pVals_Unc_Lo.push_back(vals_unc_lo);
    pVals_Unc_Hi.push_back(vals_unc_hi);

What is actually passed back from the EvaluateEvent method, are three input parameter vectors of vector<float> objects: pVals, pVals_Unc_Lo, and pVals_Unc_Hi. This is to allow for multiple interactions to be selected / recorded for each event.

For the user, it is sufficient to know that three vectors of floats must be defined in your method, as shown at the top of the code block, above. For each slice, you ought to derive the values that you are interested in, fill in the vals, vals_unc_lo, and vals_unc_hi vectors appropriately; and at the end of each slice, push those vectors back into pVals, pVals_Unc_Lo, and pVals_Unc_Hi.

The user may also wish to treat Near Det and Far Det events differently; or, for that matter, data events and Monte Carlo events. The EvaluateEvent() method is passed booleans isND and isMC, which are automatically determined based upon which files you are running over. If, e.g., reconstructed energy must be determined using different objects for Far Det and Near Det events, you may use these booleans to switch between the way that you derive vals[kRecoE].

STEP 4: Incrementing your custom derived FNESetup class

If you choose to create your own instance of the FNESetup class, you can "activate" it by adding a line to each the FNESetup.h and FNESetup.cxx files. Explicitly, in FNESetup.h, add


#include "FNESetup_MyCustomTemplate.h" 

and in FNESetup.cxx, modify the switch block to include a reference to your class:


 switch(pFNESetupEnumeration){   
    case 0:
      return new FNESetup_MCTest();
      break;
    case 1:
      return new FNESetup_NueTemplate();
      break;     
    case 2:
      return new FNESetup_NumuTemplate();
      break;     
    ....
    case N:
      return new FNESetup_MyCustomTemplate();
      break; 
    }

A full example

A complete working example of a derived FNESetup class may be found in FNEPackage/FNESetup_MCTest.h/.cxx. This template currently only cuts upon whether a neutrino interaction is within the fiducial volume of each detector. It accepts all types of neutrino interactions, and serves as a useful illustration of how oscillation affects the energy spectrum of neutrinos of different types. It is the template that we will be using for all results shown in this section.

FNESpectrumProd.fcl

Running over events

Once your variables have been listed off and defined as in the previous section, you're ready to start running over events. First, you will want to modify your FNESpectrumProd.fcl file. There are four values that you will likely want to set:

    EnergyBinLowest:     0.0     // Low limit for your reco energy distribution
    EnergyBinHighest:    3.5     // High limit for your reco energy distribution
    EnergyBinIncrement:  0.125   // Bin width for your reco energy distribution
    FNESetupEnumeration: 0       // The enumerator for the FNESetup template that you want to use

Now, you are set up to run over event files. It is recommended that you first set up some workspace directory, e.g., mkdir FNEWorkspace. Then, direct the "-o" output to some subfolder of this directory, e.g., FNEWorkspace/FNEProdARTFiles; and the "-T" output to another subfolder of this directory, e.g., FNEWorkspace/FNEProdHistFiles. The reason for this will become apparent in the next section. Once you have set up your output directory, it is a simple matter of executing the following command for each of your input ART files:

nova -c job/fnespectrumprodjob.fcl \
        -s Path/To/ART_Event_File.root \
        -o FNEWorkspace/FNEProdARTFiles/fnespectrumprodjob_Event_File_ART.root \
        -T FNEWorkspace/FNEProdHistFiles/fnespectrumprodjob_Event_File_Hist.root

The command above displays the suggested naming format for output files, though you are free to label them with whatever consistent method you would like. The output histogram file set by the "-T" flag will contain all debug histograms, while the output ART root file tagged by the "-o" flag will contain a stripped-down ART file containing only FNESpectrum objects. You will not need to modify these files in any way--this information is provided only for interested parties.

If you are using the "-S" flag to describe your input ART files, e.g.,

"-s Path/To/Event_File.root "--> "-S file_of_art_file_names.txt" 

then there is an important limitation to keep in mind--both for this job, and for any other ART jobs. You may not run over both Near Det and Far Det files, or both data and MC files, with the same nova -c job.fcl command. This is a particularly important point for this analysis, as we must run over all four possible types of files ( {ND, FD} x {DATA, MC} ) in order to perform a successful Far/Near extrapolation.

For running a local test job, then, it is suggested that the user put together four text files, for four separate jobs. Each file will list ART event files of one particular type, e.g.,

FD_MC_FILES.txt
ND_MC_FILES.txt
FD_DATA_FILES.txt
ND_DATA_FILES.txt

The user will then run the nova -c job/fnespectrumanajob.fcl ... command on each text file, directing its uniquely-named output files to the same FNEWorkspace/ directory. The FNESpectrum analysis package will determine the input data file type automatically, and will set all flags appropriately before running over any events.

Checking the output

Once you've run over your ART .root files, you may want to make certain that the distribution of events passing your cuts looks as expected. With an instance of TBrowser, open the histogram root file that you defined with the "-T" flag while running your job. You will see a file structure that looks like:

File structure of the _hist.root file produced by fnespectrumprodjob.fcl

The folder FNESpectrumProd/FNESpectrumTObjects contains ART FNESpectrum objects saved as TObjects. You will not have any need to work with these. The folder FNESpectrumProd/FNESpectrumProdHists, however, contains several plots that may be useful for debug purposes. For each type of event, there is a separate subfolder (e.g., BasicPlots[nd][mc_mm] contains information for all processed Near Det Monte Carlo neutrino interactions of type nu_mu --> nu_mu). This subfolder contains distributions describing each value that you defined in your FNESetup class. In the example shown below, we have selected the Vx distribution of all Monte Carlo nu_mu-->nu_mu neutrino interactions passing the cuts in the processed Far Det event files:

Example Vx debug plot as contained in the _hist.root file produced by fnespectrumprodjob.fcl

The RecoE and TrueE plots are also accessible directly, for a quick check of the main reason that you are running these jobs -- the energy distributions. Here, we select the plot of reconstructed energy for all Monte Carlo nu_mu-->nu_mu neutrino interactions passing the cuts in the processed Far Det event files. As we are using the FNESetup_MCTest template, RecoE is equal to TrueE:

Example Reco debug plot as contained in the _hist.root file produced by fnespectrumprodjob.fcl

Checking your FNESpectrumProdHists files

The FNEPackage code will run just fine with only one file in your FNEWorkspace/FNESpectrumProdHists directory--however, the results will likely not be what you wanted. In order to perform a true Far/Near extrapolation, you will need to run over files of the following types:

Far Detector 
   Nonswap MC
   Swap MC
   Tauswap MC
   Data
Near Detector
   MC
   Data

Descriptions for all six file types can be found at the Official Datasets website . You need not tell FNEPackage which type of file you are sending it, or how to weight it--the file type will be automatically determined, and the appropriate flags set. During the FNESpectrumAna.fcl step, different contributions will be automatically weighted to reflect the POT of the FD and ND data, as appropriate.

All that you need to do, is make certain that you have run over all six types of file--and that you have collected the "-T" output files from all processed files into a single directory, as described in the next section, FNESpectrumAna.fcl.

FNESpectrumAna.fcl:

Once you have run fnespectrumprodjob.fcl over all six types of file as described in the previous section, you are ready to perform the actual Far/Near extrapolation. First, make certain that the "-T" output files for each of your six file types is in one directory, e.g., FNESpectrumProd/FNESpectrumProdHIsts. You can have more than six such files (e.g., if you run on grid and have 100s of output files), and you needn't even have them named in any particular way. However, your extrapolation may not work as expected if you have not included all six file types.

Next, you'll want to modify a few variables in your FNESpectrumAna.fcl file:

    EnergyBinLowest:     0.0     // Low limit for your reco energy distribution
    EnergyBinHighest:    3.5     // High limit for your reco energy distribution
    EnergyBinIncrement:  0.125   // Bin width for your reco energy distribution
    FNESetupEnumeration: 0       // The enumerator for the FNESetup template that you want to use
    FNEExtrapEnumeration: 1      // The type of extrapolation job that you want to run (details in next section)
    FNEProdFileFolder: "FNEWorkspace/FNESpectrumProdHists"       // The folder containing the "-T" output files from your fnespectrumprodjob.fcl jobs
    FNEAnaFileFolder:  "FNEWorkspace/FNESpectrumAnaHists"        // The folder that will contain the final extrapolated output THStack objects

You should make certain that FNESetupEnumeration is set to the same value as in your FNESpectrumProd.fcl file. You do not need your EnergyBin* variables to be set to the same values as in your FNESpectrumProd.fcl file. The energy distribution plots are generated anew for each the fnespectrumprodjob.fcl and fnespectrumanajob.fcl jobs. FNEProdFileFolder should be the name of the folder containing your "-T" output files from the fnespectrumprodjob.fcl jobs. FNEAnaFileFolder should be the name of the folder in which you want your final results to be output. Here, we choose the same output directory to which the "-T" output of the fnespectrumanajob.fcl job will be sent, to keep things neat.

The FNEExtrapEnumeration value describes what type of extrapolation job you would like to perform. Current options include:

    0: Standard extrapolation
    1: MC 1-to-1 test (ND and FD "data" is copied directly from MC plots)
    2: MC 1/2 and 1/2 test (Half of MC is treated as MC; half is treated as data) 

Note that for MC test cases, you need not run over any ART event data files. As long as your FNEProdFileFolder contains all four types of MC file, the extrapolation produced will be correct. An up-to-date list of all extrapolation job options can also be found in the extrap_mode enumerator found in FNEPackage/FNESpectrumExtrapolator.h.

Once your FNESpectrumAna.fcl file has been set up, you can run the extrapolation job. Execute the command:

nova -c job/fnespectrumanajob.fcl \
        -s FNEWorkspace/FNEProdHistFiles/any_file_in_this_directory.root \
        -o FNEWorkspace/FNEAnaARTFiles/fnespectrumanajob_ART.root \
        -T FNEWorkspace/FNEAnaHistFiles/fnespectrumanajob_Hist.root

As stated in the code block above, you can assign any file in the input directory to your "-s" option. When the job has finished running, final results can be found in the FNEAnaFileFolder specified in your FNESpectrumAna.fcl file:

Structure of the final results directory FNEAnaHistFiles

The file ExtrapStacks.root contains THStack objects which display true and reconstructed energies for Near and Far Detector Monte Carlo events (Stack_*). It also contains TCanvas objects which compare reconstructed energy plots between data and Monte Carlo events (e.g., Far_MC_vs_DATA, Near_MC_vs_DATA, Far_Extrap_vs_DATA). The latter three plots are shown below, for the MC 1 to 1 extrapolation option: the only cut applied is that neutrino interactions must be in the fiducial region of the detector:

Near Det RecoE distribution, from MC 1 to 1 run Far Det RecoE distribution, from MC 1 to 1 run

The file BestFit.root contains the same objects as ExtrapStacks.root, but with the Monte Carlo events reweighted to reflect the best found fit between data, and the extrapolated Far Detector reconstructed energy spectrum. In both cases, the oscillation parameters used to weight the Monte Carlo events are displayed in the upper-right corner of the Far_Extrap_vs_DATA canvas. For the plots shown here, we used the MC 1 to 1 extrapolation object, and so the best fit plot is identical to the input plot.

The file fnespectrumanajob_Hist.root contains the "basic" histograms used to construct the THStack and TCanvas objects in ExtrapStacks.root and BestFit.root, and is useful for debug purposes. The file structure looks as follows:

Structure of the fnespectrumanajob_Hist debug file

The folder FNESpectrumTObjects contains FNESpectrum ART objects saved as TObjects; you will not need to work with this.

The folder PreExtrap_BasicPlots contains individual reconstructed and true energy plots for individual types of event, e.g., Far Detector Monte Carlo events of type nu_mu --> nu_e. This includes the unweighted distributions (exactly as constructed from event files); the weighted distributions (weighted by the oscillation probability on an event-by-event basis); and the normalized distributions (weighted by oscillation probability, and weighted by POT to match up with the POT from all processed data events).

The folder PreExtrap_CombinedPlots contains Near Det and Far Det Monte Carlo "summary" plots, will all events weighted by oscillation probability and by POT (as described above). All contributions to Near Det or Far Det distributions (e.g., all types of Monte Carlo event) are included.

Finally, the folder ExtrapolatedPlots contains the ratio of combined Monte Carlo reconstructed energy distributions to data, for both Near and Far Det distributions; as well as the Far Det extrapolated reconstructed energy spectrum, compared to data.

If something does not look quite right in ExtrapStacks.root and BestFit.root, you can investigate in fnespectrumanajob_Hist.root to determine where things went wrong. As an example, if you had forgotten to include nu_mu --> nu_e type events in our analysis (from the "Swap" class of Monte Carlo event files), then you would see that all plots in the BasicPlots[fd][mc_me] directory were empty.

Under construction

Bang bang clank clank rattle-tattle-tat.