Adding In-repository Documentation

.github/workflows/docs.yml

@@ -0,0 +1,59 @@
+name: docs
+
+# build the documentation whenever there are new commits on main
+on:
+  push:
+    branches:
+      - main
+# build documentation for tags.
+# on:
+#   push:
+#     tags:
+#       - '*'
+
+# security: restrict permissions for CI jobs.
+permissions:
+  contents: read
+
+jobs:
+  # Build the documentation and upload the static HTML files as an artifact.
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: "pyproject.toml"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          version: 0.8.9
+
+      - name: Install project
+        run: uv sync --locked --all-extras --dev
+
+      - name: build docs
+        run: |
+          uv run sphinx-build -M dirhtml docs/source docs/build
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/build/dirhtml
+
+  # Deploy the artifact to GitHub pages.
+  # This is a separate job so that only actions/deploy-pages has the necessary permissions.
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -9,3 +9,6 @@ Unfolding/Unfolder
 stv_root_dict_rdict.pcm
 *.o
 *~
+
+# documentation build paths
+docs/build

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= uv run sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/source/adding-selection.rst

@@ -0,0 +1,143 @@
+Writing Your Own Selection
+==========================
+
+.. attention::
+
+   This documentation page is incomplete. Please view tutorial materiel for
+   this framework for now.
+
+Organising Your Selection
+-------------------------
+
+Here we describe a selection called ``YourSelection``. This looks like a class that
+
+.. cpp:class:: YourSelection : SelectionBase
+
+   YourSelection is a class that implements all of the required methods
+   (described below) that SelectionBase and the framework requires to operate a
+   cross-section analysis.
+
+   This class should also have member variables added that correspond to any
+   desired additional branches you'd like available in the output tree.
+
+   .. cpp:function:: void define_constants()
+
+      Here you should define any particular constants that might be helpful,
+      e.g.
+
+      - Threshold values that your selection cuts depends upon.
+      - PDG codes of interest.
+
+   .. cpp:function:: bool define_signal(AnalysisEvent* event)
+
+      This method returns a boolean indicating if :cpp:var:`event` passed a
+      signal definition.
+
+      Truth information should be used to define the signal.
+
+   .. cpp:function:: int categorize_event(AnalysisEvent* event)
+
+      Here you can add logic that classifies events via their
+      truth-information.
+
+      A classification scheme can be as coarse or finely defined as you want,
+      using MC interaction codes, final-state particles or a combination of
+      both.
+
+   .. cpp:function:: bool selection(AnalysisEvent* event)
+
+      This method should contain logic to operate your selection cut on an
+      event.
+
+      This method can be run for files with and without truth-information.
+
+   .. cpp:function:: void compute_reco_observables(AnalysisEvent* event)
+   .. cpp:function:: void compute_true_observables(AnalysisEvent* event)
+   .. cpp:function:: void define_output_branches()
+   .. cpp:function:: void reset()
+
+      Run after each event is processed, this should reset any class variables
+      to default values so the values for the previous event are not persisted
+      into the new event.
+
+
+Event Variables in ``AnalysisEvent``
+------------------------------------
+
+.. rubric:: ``include/XSecAnalyzer/AnalysisEvent.hh``
+
+.. cpp:class:: AnalysisEvent
+
+   Represents a single interaction event with all the associated event
+   variables as class instance members.
+
+   Initially read from the PeLEE ntuples.
+
+   .. cpp:member:: float topological_score_
+   .. cpp:member:: float cosmic_impact_parameter_
+   .. cpp:member:: float contained_fraction_
+
+   .. cpp:member:: float nu_completeness_from_pfp_
+   .. cpp:member:: float nu_purity_from_pfp_
+   .. cpp:member:: int nu_pdg_
+
+   .. cpp:member:: int nslice_
+
+      Number of neutrino slices identified by the SliceID. Allowed values
+      are zero or one.
+
+   .. cpp:member:: float nu_vx_
+
+      Reco neutrino vertex coordinates (cm). Space charge corrections have
+      been applied for these.
+   .. cpp:member:: float nu_vy_
+   .. cpp:member:: float nu_vz_
+
+   .. cpp:member:: int num_pf_particles_
+   .. cpp:member:: int num_tracks_
+   .. cpp:member:: int num_showers_
+
+NuMI-Specific Configuration
+---------------------------
+
+Several changes need to be made to change from the default BNB-specific
+operating mode to a NuMI-specific mode.
+
+Beamline Geometry Weights
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+NuMI flux systematics have additional variations on the beamline geometry (such
+as the state of the focussing horns and the target positioning). These are
+reflected in the appropriate NuMI systematics definition configuration at
+:file:`configs/systcalc_numi.conf`.
+
+The process of adding these weights requires a ROOT file containing the
+systematic variations as a function of neutrino flavour, energy and
+beamline-neutrino angle. That can be used in tandem with the
+:ref:`exec-addbeamlinegeometryweights` program to add beamline geometry weights
+to PeLEE ntuples. This should be done for all PeLEE ntuple files before
+processing them with ``ProcessNTuples``.
+
+Adding Mock Weights to NuMI Dirt
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+NuMI Dirt files must have additional mock systematic weights added.
+``xsec_analyzer`` expects a full set of systematic weights for all input PeLEE
+ntuples. While BNB dirt files have a full set of weights included, NuMI dirt
+files do not (instead a large uncertainty is applied).
+
+In order to apply these additional mock weights to NuMI dirt files, the
+:ref:`exec-addfakeweights` program can be invoked. The new dirt file should be
+used in the remaining workflow.
+
+Compile Time Switch
+^^^^^^^^^^^^^^^^^^^
+
+At compile-time a variable should be changed in the framework:
+
+.. rubric:: ``include/XSecAnalyzer/Constants.hh``
+
+.. cpp:var:: bool useNuMI = true
+   :no-contents-entry:
+
+   Enable NuMI processing mode for the framework.

docs/source/conf.py

@@ -0,0 +1,75 @@
+from datetime import datetime
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'xsec_analyzer'
+copyright = f'{datetime.now().year}, Steven Gardiner, Burke Irwin, Liang Lu, et. al.'
+author = 'Steven Gardiner, Burke Irwin, Liang Lu, et. al.'
+
+show_authors = True
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.extlinks',
+]
+
+extlinks = {
+    'github': ('https://github.com/%s',
+               None),
+    'docdb': (
+        'https://microboone-docdb.fnal.gov/cgi-bin/sso/ShowDocument?docid=%s',
+        None
+    )
+}
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+# hawkmoth_root = os.path.abspath('../../include/')
+# hawkmoth_clang = [
+#     '-I/home/niam/phd/code/xsec_analyzer/include',
+#     '-I/home/niam/Downloads/root/include'
+# ]
+# hawkmoth_source_uri = "https://github.com/uboone/xsec_analyzer/tree/main/include/{source}#L{line}"
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'furo'
+html_static_path = ['_static']
+html_theme_options = {
+    "source_repository": "https://github.com/uboone/xsec_analyzer/",
+    "source_branch": "main",
+    "source_directory": "docs/source/"
+}
+
+
+# -- For theme = 'alabaster' -----------
+# html_theme = 'alabaster'
+# html_static_path = ['_static']
+# html_sidebars = {
+#     '**': [
+#         'about.html',
+#         'navigation.html',
+#         'relations.html',
+#         'searchfield.html',
+#     ]
+# }
+# html_theme_options = {
+#     'description': 'A framework for MicroBooNE cross-sections',
+#     'github_user': 'uboone',
+#     'github_repo': 'xsec_analyzer',
+#     'page_width': '60rem',
+#     'sidebar_width': '15rem',
+#     'extra_nav_links': {
+#         "GitHub Repository": "https://github.com/uboone/xsec_analyzer"
+#     }
+# }