From 4c049c4b0b9510fa83c019f5dd05c79f99deef62 Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Fri, 6 Nov 2026 10:36:38 +0100 Subject: [PATCH 01/53] added explore data tutorial --- docs/source/index.rst | 1 + docs/source/tutorials.rst | 27 ++ examples/tutorials/explore_public_data.py | 313 ++++++++++++++++++++++ 3 files changed, 341 insertions(+) create mode 100644 docs/source/tutorials.rst create mode 100644 examples/tutorials/explore_public_data.py diff --git a/docs/source/index.rst b/docs/source/index.rst index 08ae36ed..18adbb03 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -24,6 +24,7 @@ CTLearn: Deep Learning for IACT Event Reconstruction installation usage + tutorials supplementary modules changelog diff --git a/docs/source/tutorials.rst b/docs/source/tutorials.rst new file mode 100644 index 00000000..3a519af4 --- /dev/null +++ b/docs/source/tutorials.rst @@ -0,0 +1,27 @@ +********* +Tutorials +********* + +Public CTAO data exploration +============================ + +This tutorial follows the executable Python-script style used by ctapipe's +tutorials. It downloads a small SimTel sample for the monoscopic examples and +four CTAO simulation files from `Zenodo record 7298569 +`_ for the stereo example. The four Zenodo +files require about 3.5 GB of disk space. Downloaded and converted files are +reused on subsequent runs. + +To run the complete tutorial from the CTLearn repository root, install CTLearn +with its development dependencies and execute: + +.. code-block:: console + + python examples/tutorials/explore_public_data.py + +The source is included below for reading and copying. Building the +documentation does not execute the script or download the data. + +.. literalinclude:: ../../examples/tutorials/explore_public_data.py + :language: python + :linenos: diff --git a/examples/tutorials/explore_public_data.py b/examples/tutorials/explore_public_data.py new file mode 100644 index 00000000..877d7b28 --- /dev/null +++ b/examples/tutorials/explore_public_data.py @@ -0,0 +1,313 @@ +""" +Explore Public CTAO Data +======================= + +Download public CTAO simulation data, convert it with ctapipe, and explore +waveforms and images using DL1DataHandler. + +The four Zenodo files used for the stereo example total about 3.5 GB. They are +downloaded only when this script is run, and existing downloads and converted +files are reused. +""" + +from pathlib import Path + +from ctapipe import __version__ as ctapipe_version +from ctapipe.core import run_tool +from ctapipe.tools.process import ProcessorTool +from ctapipe.utils.download import download_file +from dl1_data_handler.reader import DLImageReader, DLWaveformReader +from matplotlib import animation as ani +from matplotlib import pyplot as plt +from traitlets.config.loader import Config + +try: + from ctapipe.io.metadata import ProductMetadata +except ImportError: + ProductMetadata = None + +plt.style.use("ggplot") +print_log = True + +TESTDATA_DIR = Path(__file__).resolve().parents[2] / "testdata" +TESTDATA_DIR.mkdir(parents=True, exist_ok=True) + +###################################################################### +# Download and process a small SimTel sample +# ------------------------------------------ +# +# First, download a small public gamma-ray simulation and process it to +# produce calibrated waveforms and images for the monoscopic examples. + +SIMTEL_URL = ( + "https://minio-cta.zeuthen.desy.de/dpps-testdata-public/data/" + "ctapipe-test-data/v1.1.0/gamma_prod5.simtel.zst" +) +simtel_path = TESTDATA_DIR / "gamma_prod5.simtel.zst" +gamma_dl1_path = TESTDATA_DIR / "gamma_prod5.r1.dl1.h5" + +if not simtel_path.is_file(): + download_file(SIMTEL_URL, simtel_path, progress=True) +else: + print(f"Using existing download: {simtel_path}") + +if not gamma_dl1_path.is_file(): + argv = [ + f"--input={simtel_path}", + f"--output={gamma_dl1_path}", + "--write-images", + "--DataWriter.write_r1_waveforms=True", + "--SimTelEventSource.focal_length_choice=EQUIVALENT", + "--overwrite", + ] + if ProductMetadata is not None: + argv.append("--ProductMetadata.instance=site_id=CTAO-South") + result = run_tool(ProcessorTool(), argv=argv, cwd=str(TESTDATA_DIR)) + if result != 0: + raise RuntimeError(f"ctapipe-process failed for {simtel_path}") +else: + print(f"Using existing processed file: {gamma_dl1_path}") + +###################################################################### +# Read calibrated waveforms +# ------------------------- +# +# DL1DataHandler can read calibrated waveforms and map each camera into a +# regular image. Here we display an animation of the waveform samples for +# each telescope type. + +telescope_types = { + "LST": [3, 4], + "MST_FlashCam": [8, 9, 14], + "MST_NectarCam": [109, 112, 118, 119, 121, 122, 124], + "SST": [43, 46, 53, 57, 92, 98], +} + +image_mapper_types = { + "LST": "BilinearMapper", + "MST_FlashCam": "OversamplingMapper", + "MST_NectarCam": "AxialMapper", + "SST": "SquareMapper", +} + +for tel_type, allowed_tels in telescope_types.items(): + config = Config( + { + "TableQualityQuery": { + "quality_criteria": [("> 50 phe", "hillas_intensity > 50")], + }, + "DLWaveformReader": { + "allowed_tels": allowed_tels, + "image_mapper_type": image_mapper_types[tel_type], + "sequence_length": None, + "sequence_position": "center", + "cleaning_type": None, + "focal_length_choice": "EQUIVALENT", + }, + }, + ) + waveform_reader = DLWaveformReader( + input_url_signal=[str(gamma_dl1_path)], + config=config, + ) + batch = waveform_reader.generate_mono_batch(0) + + if print_log: + print(f"DLWaveformReader: {waveform_reader}") + print(f"Subarray information for {tel_type}:") + print(waveform_reader.subarray.info()) + print(f"Number of gamma events: {waveform_reader.n_signal_events}") + print("First batch:") + print("\n".join(batch.pformat(max_lines=-1, max_width=-1))) + + calibrated_waveforms = batch["features"][0] + fig, ax = plt.subplots(figsize=(5, 5)) + camera_image = calibrated_waveforms[:, :, 0] + image = ax.imshow(camera_image, cmap="viridis", interpolation="nearest") + ax.grid(False) + colorbar = fig.colorbar(image, ax=ax, fraction=0.046, pad=0.04) + colorbar.set_label("p.e.", fontsize=10) + title = ax.set_title(f"{tel_type}: calibrated waveform (t = 0 ns)") + + def update(frame): + frame_image = calibrated_waveforms[:, :, frame] + image.set_data(frame_image) + image.set_clim(frame_image.min(), frame_image.max()) + title.set_text(f"{tel_type}: calibrated waveform (t = {frame} ns)") + return image, title + + waveform_animation = ani.FuncAnimation( + fig, + update, + frames=calibrated_waveforms.shape[-1], + interval=500, + blit=False, + ) + plt.show() + plt.close(fig) + +###################################################################### +# Read monoscopic images +# ---------------------- +# +# The image reader returns integrated charge and relative peak-time images. +# The mapper is selected for each camera type. + +for tel_type, allowed_tels in telescope_types.items(): + config = Config( + { + "TableQualityQuery": { + "quality_criteria": [("> 50 phe", "hillas_intensity > 50")], + }, + "DLImageReader": { + "allowed_tels": allowed_tels, + "channels": ["image", "relative_peak_time"], + "image_mapper_type": image_mapper_types[tel_type], + "focal_length_choice": "EQUIVALENT", + }, + }, + ) + image_reader = DLImageReader( + input_url_signal=[str(gamma_dl1_path)], + config=config, + ) + batch = image_reader.generate_mono_batch(0) + + if print_log: + print(f"DLImageReader: {image_reader}") + print(f"Subarray information for {tel_type}:") + print(image_reader.subarray.info()) + print(f"Number of gamma events: {image_reader.n_signal_events}") + print("First batch:") + print("\n".join(batch.pformat(max_lines=-1, max_width=-1))) + + for channel_index, channel_name, unit in [ + (0, "charge image", "p.e."), + (1, "relative peak arrival time", "ns"), + ]: + fig, ax = plt.subplots(figsize=(5, 5)) + image = ax.imshow(batch["features"][0, :, :, channel_index], cmap="viridis") + ax.set_title(f"{tel_type} - {channel_name}") + ax.grid(False) + colorbar = fig.colorbar(image, ax=ax, fraction=0.046, pad=0.04) + colorbar.set_label(unit, fontsize=12) + plt.show() + +###################################################################### +# Download and convert the stereo data +# ------------------------------------ +# +# The Zenodo files contain CTAO open-source gamma and proton simulations. +# Convert each file with the installed ctapipe version, and store converted +# outputs in a version-specific directory so they are not confused with the +# original downloads. + +ZENODO_FILES = [ + "gamma-diffuse_with_images_00.dl2.h5", + "gamma-diffuse_with_images_01.dl2.h5", + "proton_with_images_00.dl2.h5", + "proton_with_images_01.dl2.h5", +] +ZENODO_FILES_URL = "https://zenodo.org/api/records/7298569/files" +converted_path = TESTDATA_DIR / f"ctapipe-{ctapipe_version}" +converted_path.mkdir(parents=True, exist_ok=True) + +for filename in ZENODO_FILES: + source_path = TESTDATA_DIR / filename + if not source_path.is_file(): + download_file( + url=f"{ZENODO_FILES_URL}/{filename}/content", + path=source_path, + progress=True, + ) + else: + print(f"Using existing download: {source_path}") + + output_path = converted_path / filename + if not output_path.is_file(): + temporary_output = converted_path / f".{filename}.processing.h5" + argv = [ + f"--input={source_path}", + f"--output={temporary_output}", + "--write-images", + "--write-parameters", + "--write-showers", + "--overwrite", + ] + if ProductMetadata is not None: + argv.append("--ProductMetadata.instance=site_id=CTAO-North") + result = run_tool(ProcessorTool(), argv=argv, cwd=str(TESTDATA_DIR)) + if result != 0: + raise RuntimeError(f"ctapipe-process failed for {source_path}") + temporary_output.replace(output_path) + else: + print(f"Using existing ctapipe output: {output_path}") + +###################################################################### +# Read stereo images +# ------------------ +# +# Finally, combine gamma and proton events in stereo mode and plot the +# integrated charge and relative peak-time image from each telescope. + +gamma_stereo_path = converted_path / "gamma-diffuse_with_images_00.dl2.h5" +proton_stereo_path = converted_path / "proton_with_images_00.dl2.h5" + +for tel_type in ["LST_LST_LSTCam", "MST_MST_NectarCam"]: + config = Config( + { + "TableQualityQuery": { + "quality_criteria": [("> 500 phe", "hillas_intensity > 500")], + }, + "DLImageReader": { + "mode": "stereo", + "allowed_tel_types": [tel_type], + "min_telescopes": 4, + "channels": ["image", "relative_peak_time"], + "image_mapper_type": "BilinearMapper", + }, + }, + ) + stereo_reader = DLImageReader( + input_url_signal=[str(gamma_stereo_path)], + input_url_background=[str(proton_stereo_path)], + config=config, + ) + stereo_reader.subarray.peek() + batch = stereo_reader.generate_stereo_batch(0) + + if print_log: + print(f"DLImageReader: {stereo_reader}") + print("Subarray information:") + print(stereo_reader.subarray.info()) + print(f"Number of gamma events: {stereo_reader.n_signal_events}") + print(f"Number of proton events: {stereo_reader.n_bkg_events}") + print("First batch:") + print("\n".join(batch.pformat(max_lines=-1, max_width=-1))) + + fig, axes = plt.subplots( + 2, + len(batch["tel_id"]), + figsize=(24, 14), + constrained_layout=True, + squeeze=False, + ) + for telescope_index, tel_id in enumerate(batch["tel_id"]): + for channel_index, label, unit in [ + (0, "Charge image", "p.e."), + (1, "Peak arrival time", "ns"), + ]: + image = axes[channel_index, telescope_index].imshow( + batch["features"][telescope_index, :, :, channel_index], + cmap="viridis", + ) + axes[channel_index, telescope_index].set_title(f"Tel-{tel_id} - {label}") + axes[channel_index, telescope_index].grid(False) + colorbar = fig.colorbar( + image, + ax=axes[channel_index, telescope_index], + fraction=0.046, + pad=0.04, + ) + colorbar.set_label(unit, fontsize=12) + plt.show() From 3b52474ee52168304f3885d2a61a76be1321fe28 Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Fri, 6 Nov 2026 10:55:10 +0100 Subject: [PATCH 02/53] cache tutorial data before and read it from there in the tutorials --- .github/workflows/ci.yml | 119 ++++++++++++++++++++-- .gitignore | 2 + docs/requirements.txt | 2 + docs/source/conf.py | 9 ++ docs/source/tutorials.rst | 21 ++-- examples/tutorials/GALLERY_HEADER.rst | 5 + examples/tutorials/explore_public_data.py | 28 +++-- pyproject.toml | 1 + 8 files changed, 165 insertions(+), 22 deletions(-) create mode 100644 examples/tutorials/GALLERY_HEADER.rst diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 25585186..f3979322 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -28,9 +28,6 @@ jobs: cache-test-data: needs: lint - if: >- - github.event_name != 'pull_request' || - !contains(github.event.pull_request.labels.*.name, 'documentation-only') runs-on: ubuntu-24.04 steps: - name: Cache ctapipe data @@ -40,21 +37,131 @@ jobs: path: ~/.cache/ctapipe key: ctapipe-data-${{ runner.os }}-v1 + - name: Cache tutorial data + id: cache-tutorial-data + uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 + with: + path: ~/.cache/ctlearn/tutorial-data + key: ctlearn-tutorial-data-${{ runner.os }}-v2 + - name: Set up Python - if: steps.cache-ctapipe.outputs.cache-hit != 'true' + if: >- + steps.cache-ctapipe.outputs.cache-hit != 'true' || + steps.cache-tutorial-data.outputs.cache-hit != 'true' uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5 with: python-version: '3.12' - name: Install ctapipe - if: steps.cache-ctapipe.outputs.cache-hit != 'true' + if: >- + steps.cache-ctapipe.outputs.cache-hit != 'true' || + steps.cache-tutorial-data.outputs.cache-hit != 'true' run: pip install ctapipe - - name: Download test data + - name: Download ctapipe test data if: steps.cache-ctapipe.outputs.cache-hit != 'true' run: | python -c "from ctapipe.utils import get_dataset_path; get_dataset_path('gamma_test_large.simtel.gz'); get_dataset_path('proton_20deg_0deg_run4___cta-prod5-paranal_desert-2147m-Paranal-dark-100evts.simtel.zst')" + - name: Download tutorial data + if: steps.cache-tutorial-data.outputs.cache-hit != 'true' + run: | + python - <<'PY' + from pathlib import Path + from ctapipe.utils.download import download_file + + cache_dir = Path.home() / ".cache" / "ctlearn" / "tutorial-data" + files = { + "gamma_prod5.simtel.zst": ( + "https://minio-cta.zeuthen.desy.de/dpps-testdata-public/data/" + "ctapipe-test-data/v1.1.0/gamma_prod5.simtel.zst" + ), + "gamma-diffuse_with_images_00.dl2.h5": ( + "https://zenodo.org/api/records/7298569/files/" + "gamma-diffuse_with_images_00.dl2.h5/content" + ), + "gamma-diffuse_with_images_01.dl2.h5": ( + "https://zenodo.org/api/records/7298569/files/" + "gamma-diffuse_with_images_01.dl2.h5/content" + ), + "proton_with_images_00.dl2.h5": ( + "https://zenodo.org/api/records/7298569/files/" + "proton_with_images_00.dl2.h5/content" + ), + "proton_with_images_01.dl2.h5": ( + "https://zenodo.org/api/records/7298569/files/" + "proton_with_images_01.dl2.h5/content" + ), + } + for name, url in files.items(): + download_file(url=url, path=cache_dir / name, progress=True) + PY + + docs: + needs: cache-test-data + runs-on: ubuntu-24.04 + permissions: + contents: read + steps: + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + with: + fetch-depth: 0 + + - name: Set up Python + uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5 + with: + python-version: "3.12" + + - name: Cache documentation dependencies + uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 + with: + path: ~/.cache/pip + key: ${{ runner.os }}-docs-pip-py312-v1 + + - name: Install documentation dependencies + run: | + python -m pip install --upgrade pip + python -m pip install --no-deps . + python -m pip install -r docs/requirements.txt + python -m pip install sphinx sphinx-rtd-theme sphinx-changelog sphinx-design + + - name: Get ctapipe version for processed-data cache + id: ctapipe-version + run: echo "version=$(python -c 'import ctapipe; print(ctapipe.__version__)')" >> "$GITHUB_OUTPUT" + + - name: Restore processed tutorial data + uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 + with: + path: | + ~/.cache/ctlearn/tutorial-data/gamma_prod5.r1.dl1.h5 + ~/.cache/ctlearn/tutorial-data/ctapipe-* + key: >- + ctlearn-tutorial-processed-${{ runner.os }}-${{ steps.ctapipe-version.outputs.version }}-${{ hashFiles('examples/tutorials/explore_public_data.py', 'docs/requirements.txt', 'pyproject.toml') }} + + - name: Build documentation and execute tutorials + run: python -m sphinx -b html --keep-going docs/source docs/build/html + + - name: Upload GitHub Pages artifact + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3 + with: + path: docs/build/html + + deploy-docs: + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + needs: docs + runs-on: ubuntu-24.04 + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Deploy documentation to GitHub Pages + id: deployment + uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4 + pixi: needs: cache-test-data if: >- diff --git a/.gitignore b/.gitignore index caef8952..5c9e21c4 100644 --- a/.gitignore +++ b/.gitignore @@ -31,6 +31,8 @@ dist .pytest_cache/*.log # Sphinx documentation docs/build/ +docs/source/auto_tutorials/ +docs/source/sg_execution_times.rst build/ # Default pytorch output run/ diff --git a/docs/requirements.txt b/docs/requirements.txt index 6d40c4f6..06ce9368 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -6,3 +6,5 @@ sphinx-design # The heavy ML frameworks (TensorFlow, PyTorch, ...) are mocked in conf.py. ctapipe>=0.29 dl1_data_handler>=0.14.12 +matplotlib +sphinx-gallery>=0.16.0 diff --git a/docs/source/conf.py b/docs/source/conf.py index 93253eb5..3d00342b 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -55,8 +55,17 @@ "sphinx.ext.githubpages", "sphinx_changelog", "sphinx_design", + "sphinx_gallery.gen_gallery", ] +sphinx_gallery_conf = { + "examples_dirs": "../../examples/tutorials", + "gallery_dirs": "auto_tutorials", + "filename_pattern": r"explore_public_data\.py$", + "plot_gallery": "READTHEDOCS" not in os.environ, + "abort_on_example_error": True, +} + # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] diff --git a/docs/source/tutorials.rst b/docs/source/tutorials.rst index 3a519af4..e6823172 100644 --- a/docs/source/tutorials.rst +++ b/docs/source/tutorials.rst @@ -10,18 +10,23 @@ tutorials. It downloads a small SimTel sample for the monoscopic examples and four CTAO simulation files from `Zenodo record 7298569 `_ for the stereo example. The four Zenodo files require about 3.5 GB of disk space. Downloaded and converted files are -reused on subsequent runs. +reused on subsequent runs. By default, data are stored under +``~/.cache/ctlearn/tutorial-data``; set ``CTLEARN_TUTORIAL_DATA_DIR`` to use a +different directory. The CI workflow preloads the source files and caches the +converted products. The documentation build executes the tutorial and embeds +its output; it does not download the data when built by Read the Docs. -To run the complete tutorial from the CTLearn repository root, install CTLearn -with its development dependencies and execute: +To run the complete tutorial locally from the CTLearn repository root, install +CTLearn with its development dependencies and execute: .. code-block:: console python examples/tutorials/explore_public_data.py -The source is included below for reading and copying. Building the -documentation does not execute the script or download the data. +The rendered tutorial, including its code and figures, is generated by +Sphinx-Gallery: -.. literalinclude:: ../../examples/tutorials/explore_public_data.py - :language: python - :linenos: +.. toctree:: + :maxdepth: 1 + + auto_tutorials/index diff --git a/examples/tutorials/GALLERY_HEADER.rst b/examples/tutorials/GALLERY_HEADER.rst new file mode 100644 index 00000000..bde7b10b --- /dev/null +++ b/examples/tutorials/GALLERY_HEADER.rst @@ -0,0 +1,5 @@ +CTLearn tutorials +================= + +Step-by-step examples for downloading public CTAO data and exploring +waveforms and images with CTLearn's data-reading tools. diff --git a/examples/tutorials/explore_public_data.py b/examples/tutorials/explore_public_data.py index 877d7b28..78429b6b 100644 --- a/examples/tutorials/explore_public_data.py +++ b/examples/tutorials/explore_public_data.py @@ -1,6 +1,6 @@ """ Explore Public CTAO Data -======================= +======================== Download public CTAO simulation data, convert it with ctapipe, and explore waveforms and images using DL1DataHandler. @@ -10,6 +10,7 @@ files are reused. """ +import os from pathlib import Path from ctapipe import __version__ as ctapipe_version @@ -29,7 +30,12 @@ plt.style.use("ggplot") print_log = True -TESTDATA_DIR = Path(__file__).resolve().parents[2] / "testdata" +TESTDATA_DIR = Path( + os.environ.get( + "CTLEARN_TUTORIAL_DATA_DIR", + str(Path.home() / ".cache" / "ctlearn" / "tutorial-data"), + ) +) TESTDATA_DIR.mkdir(parents=True, exist_ok=True) ###################################################################### @@ -129,12 +135,18 @@ colorbar.set_label("p.e.", fontsize=10) title = ax.set_title(f"{tel_type}: calibrated waveform (t = 0 ns)") - def update(frame): - frame_image = calibrated_waveforms[:, :, frame] - image.set_data(frame_image) - image.set_clim(frame_image.min(), frame_image.max()) - title.set_text(f"{tel_type}: calibrated waveform (t = {frame} ns)") - return image, title + def update( + frame, + waveform=calibrated_waveforms, + image_artist=image, + title_artist=title, + telescope_type=tel_type, + ): + frame_image = waveform[:, :, frame] + image_artist.set_data(frame_image) + image_artist.set_clim(frame_image.min(), frame_image.max()) + title_artist.set_text(f"{telescope_type}: calibrated waveform (t = {frame} ns)") + return image_artist, title_artist waveform_animation = ani.FuncAnimation( fig, diff --git a/pyproject.toml b/pyproject.toml index 9f0a12c0..ca0ddf01 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -87,6 +87,7 @@ tests = [ docs = [ "ctlearn[all]", "sphinx", + "sphinx-gallery >= 0.16.0", "sphinx-changelog", "sphinx-design", "sphinx-rtd-theme", From ac9ce8a56ac1ed5eee9eca0e83248accbbec66e8 Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Fri, 6 Nov 2026 10:59:15 +0100 Subject: [PATCH 03/53] added changelog --- docs/changes/322.maintenance.rst | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 docs/changes/322.maintenance.rst diff --git a/docs/changes/322.maintenance.rst b/docs/changes/322.maintenance.rst new file mode 100644 index 00000000..600a01f4 --- /dev/null +++ b/docs/changes/322.maintenance.rst @@ -0,0 +1,3 @@ +Build and publish the documentation with GitHub Actions. The CI documentation +job executes the Sphinx-Gallery tutorial, reuses cached tutorial data, and +deploys the generated HTML to GitHub Pages on pushes to ``main``. From 53bcce423b0f078d5bf4717fb42c5f58cca8f4eb Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Fri, 6 Nov 2026 12:47:11 +0100 Subject: [PATCH 04/53] upload docs build to artifacts and let RTD execute tutorials --- .github/workflows/ci.yml | 36 +++++++++++------------ docs/source/conf.py | 6 +++- docs/source/tutorials.rst | 7 +++-- examples/tutorials/explore_public_data.py | 30 +++++++++++++++++-- 4 files changed, 55 insertions(+), 24 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f3979322..15201246 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -129,38 +129,36 @@ jobs: id: ctapipe-version run: echo "version=$(python -c 'import ctapipe; print(ctapipe.__version__)')" >> "$GITHUB_OUTPUT" + - name: Restore tutorial input data + uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 + with: + path: ~/.cache/ctlearn/tutorial-data + key: ctlearn-tutorial-data-${{ runner.os }}-v2 + - name: Restore processed tutorial data uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 with: path: | - ~/.cache/ctlearn/tutorial-data/gamma_prod5.r1.dl1.h5 + ~/.cache/ctlearn/tutorial-data/gamma_prod5-max100.r1.dl1.h5 ~/.cache/ctlearn/tutorial-data/ctapipe-* key: >- ctlearn-tutorial-processed-${{ runner.os }}-${{ steps.ctapipe-version.outputs.version }}-${{ hashFiles('examples/tutorials/explore_public_data.py', 'docs/requirements.txt', 'pyproject.toml') }} - name: Build documentation and execute tutorials + env: + CTLEARN_TUTORIAL_MAX_EVENTS: "100" run: python -m sphinx -b html --keep-going docs/source docs/build/html - - name: Upload GitHub Pages artifact - if: github.event_name == 'push' && github.ref == 'refs/heads/main' - uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3 + - name: Upload rendered documentation for review + if: >- + always() && + (github.event_name == 'pull_request' || github.event_name == 'push') + uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 with: + name: docs-${{ github.event_name }}-${{ github.run_id }}-${{ github.run_attempt }} path: docs/build/html - - deploy-docs: - if: github.event_name == 'push' && github.ref == 'refs/heads/main' - needs: docs - runs-on: ubuntu-24.04 - permissions: - pages: write - id-token: write - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - steps: - - name: Deploy documentation to GitHub Pages - id: deployment - uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4 + retention-days: 14 + if-no-files-found: warn pixi: needs: cache-test-data diff --git a/docs/source/conf.py b/docs/source/conf.py index 3d00342b..d2fa15ac 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -26,6 +26,10 @@ import ctlearn +# Read the full Zenodo inputs on Read the Docs, but bound processing time. +if "READTHEDOCS" in os.environ: + os.environ.setdefault("CTLEARN_TUTORIAL_MAX_EVENTS", "100") + # -- Project information ----------------------------------------------------- project = "CTLearn" @@ -62,7 +66,7 @@ "examples_dirs": "../../examples/tutorials", "gallery_dirs": "auto_tutorials", "filename_pattern": r"explore_public_data\.py$", - "plot_gallery": "READTHEDOCS" not in os.environ, + "plot_gallery": True, "abort_on_example_error": True, } diff --git a/docs/source/tutorials.rst b/docs/source/tutorials.rst index e6823172..a374d9ae 100644 --- a/docs/source/tutorials.rst +++ b/docs/source/tutorials.rst @@ -13,8 +13,11 @@ files require about 3.5 GB of disk space. Downloaded and converted files are reused on subsequent runs. By default, data are stored under ``~/.cache/ctlearn/tutorial-data``; set ``CTLEARN_TUTORIAL_DATA_DIR`` to use a different directory. The CI workflow preloads the source files and caches the -converted products. The documentation build executes the tutorial and embeds -its output; it does not download the data when built by Read the Docs. +converted products. The CI docs build limits processing to 100 events per +input file to keep builds bounded; running the tutorial locally without that +environment variable processes the full files. The documentation build +executes the tutorial and embeds its output, including when built by Read the +Docs. Read the Docs builds limit processing to 100 events per input file. To run the complete tutorial locally from the CTLearn repository root, install CTLearn with its development dependencies and execute: diff --git a/examples/tutorials/explore_public_data.py b/examples/tutorials/explore_public_data.py index 78429b6b..e91438d9 100644 --- a/examples/tutorials/explore_public_data.py +++ b/examples/tutorials/explore_public_data.py @@ -10,6 +10,13 @@ files are reused. """ +###################################################################### +# Imports +# ------- +# +# Import the tools used to download and process the public data, then read +# and visualize the resulting images and waveforms. + import os from pathlib import Path @@ -27,9 +34,24 @@ except ImportError: ProductMetadata = None +###################################################################### +# Set a limit on the number of events (optional) +# ---------------------------------------------- +# +# By default, the tutorial processes all events. To speed up a test run, +# set ``CTLEARN_TUTORIAL_MAX_EVENTS`` to a positive integer before running +# this script, for example ``CTLEARN_TUTORIAL_MAX_EVENTS=100``. The limit +# applies to each input file. Leave the variable unset to process all events. + plt.style.use("ggplot") print_log = True +MAX_EVENTS = os.environ.get("CTLEARN_TUTORIAL_MAX_EVENTS") +if MAX_EVENTS is not None and int(MAX_EVENTS) < 1: + raise ValueError("CTLEARN_TUTORIAL_MAX_EVENTS must be a positive integer") +MAX_EVENTS_ARGUMENT = f"--max-events={MAX_EVENTS}" if MAX_EVENTS is not None else None +MAX_EVENTS_SUFFIX = f"-max{MAX_EVENTS}" if MAX_EVENTS is not None else "" + TESTDATA_DIR = Path( os.environ.get( "CTLEARN_TUTORIAL_DATA_DIR", @@ -50,7 +72,7 @@ "ctapipe-test-data/v1.1.0/gamma_prod5.simtel.zst" ) simtel_path = TESTDATA_DIR / "gamma_prod5.simtel.zst" -gamma_dl1_path = TESTDATA_DIR / "gamma_prod5.r1.dl1.h5" +gamma_dl1_path = TESTDATA_DIR / f"gamma_prod5{MAX_EVENTS_SUFFIX}.r1.dl1.h5" if not simtel_path.is_file(): download_file(SIMTEL_URL, simtel_path, progress=True) @@ -66,6 +88,8 @@ "--SimTelEventSource.focal_length_choice=EQUIVALENT", "--overwrite", ] + if MAX_EVENTS_ARGUMENT is not None: + argv.append(MAX_EVENTS_ARGUMENT) if ProductMetadata is not None: argv.append("--ProductMetadata.instance=site_id=CTAO-South") result = run_tool(ProcessorTool(), argv=argv, cwd=str(TESTDATA_DIR)) @@ -221,7 +245,7 @@ def update( "proton_with_images_01.dl2.h5", ] ZENODO_FILES_URL = "https://zenodo.org/api/records/7298569/files" -converted_path = TESTDATA_DIR / f"ctapipe-{ctapipe_version}" +converted_path = TESTDATA_DIR / f"ctapipe-{ctapipe_version}{MAX_EVENTS_SUFFIX}" converted_path.mkdir(parents=True, exist_ok=True) for filename in ZENODO_FILES: @@ -246,6 +270,8 @@ def update( "--write-showers", "--overwrite", ] + if MAX_EVENTS_ARGUMENT is not None: + argv.append(MAX_EVENTS_ARGUMENT) if ProductMetadata is not None: argv.append("--ProductMetadata.instance=site_id=CTAO-North") result = run_tool(ProcessorTool(), argv=argv, cwd=str(TESTDATA_DIR)) From fc05fc81b077818260c0f6aa6d9c4bfa379a8cdd Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Fri, 6 Nov 2026 13:57:00 +0100 Subject: [PATCH 05/53] make animations in docs --- docs/source/conf.py | 1 + docs/source/tutorials.rst | 4 ++-- examples/tutorials/explore_public_data.py | 3 ++- 3 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index d2fa15ac..f7ce2a04 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -67,6 +67,7 @@ "gallery_dirs": "auto_tutorials", "filename_pattern": r"explore_public_data\.py$", "plot_gallery": True, + "matplotlib_animations": (True, "jshtml"), "abort_on_example_error": True, } diff --git a/docs/source/tutorials.rst b/docs/source/tutorials.rst index a374d9ae..fd53fc64 100644 --- a/docs/source/tutorials.rst +++ b/docs/source/tutorials.rst @@ -26,8 +26,8 @@ CTLearn with its development dependencies and execute: python examples/tutorials/explore_public_data.py -The rendered tutorial, including its code and figures, is generated by -Sphinx-Gallery: +The rendered tutorial, including its code, figures, and playable waveform +animations, is generated by Sphinx-Gallery: .. toctree:: :maxdepth: 1 diff --git a/examples/tutorials/explore_public_data.py b/examples/tutorials/explore_public_data.py index e91438d9..a91bb387 100644 --- a/examples/tutorials/explore_public_data.py +++ b/examples/tutorials/explore_public_data.py @@ -179,8 +179,9 @@ def update( interval=500, blit=False, ) + # Sphinx-Gallery scrapes animations from module globals after execution. + globals()[f"{tel_type.lower()}_waveform_animation"] = waveform_animation plt.show() - plt.close(fig) ###################################################################### # Read monoscopic images From 2e6b5d2bfabd732e1e8fd8cc5b4c72bdeb098661 Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Fri, 6 Nov 2026 15:37:02 +0100 Subject: [PATCH 06/53] deploy github pages for the docs and remove readthedocs --- .github/workflows/ci.yml | 33 +++++++++++++++++++++++++++++++++ .readthedocs.yaml | 16 ---------------- README.rst | 4 ++-- docs/source/conf.py | 4 ---- docs/source/index.rst | 2 +- docs/source/tutorials.rst | 12 ++++++------ pyproject.toml | 2 +- 7 files changed, 43 insertions(+), 30 deletions(-) delete mode 100644 .readthedocs.yaml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 15201246..eafdceee 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -160,6 +160,39 @@ jobs: retention-days: 14 if-no-files-found: warn + deploy-docs: + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + needs: docs + runs-on: ubuntu-24.04 + permissions: + contents: read + pages: write + id-token: write + concurrency: + group: github-pages + cancel-in-progress: false + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Configure GitHub Pages + uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5 + + - name: Download rendered documentation + uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4 + with: + name: docs-${{ github.event_name }}-${{ github.run_id }}-${{ github.run_attempt }} + path: docs/build/html + + - name: Upload GitHub Pages artifact + uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4 + with: + path: docs/build/html + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4 + pixi: needs: cache-test-data if: >- diff --git a/.readthedocs.yaml b/.readthedocs.yaml deleted file mode 100644 index ecea7c5b..00000000 --- a/.readthedocs.yaml +++ /dev/null @@ -1,16 +0,0 @@ -version: 2 - -sphinx: - configuration: docs/source/conf.py - -build: - os: ubuntu-24.04 - tools: - python: "3.12" - jobs: - post_install: - # Installs ctlearn without downloading heavy PyTorch/TensorFlow binaries - - pip install --no-deps . -python: - install: - - requirements: docs/requirements.txt diff --git a/README.rst b/README.rst index db0599c2..260b30d9 100644 --- a/README.rst +++ b/README.rst @@ -30,7 +30,7 @@ CTLearn: Deep Learning for IACT Event Reconstruction CTLearn is a package under active development to run deep learning models to analyze data from all major current and future arrays of imaging atmospheric Cherenkov telescopes (IACTs). CTLearn can load R1/DL0/DL1 data from `CTAO `_ (Cherenkov Telescope Array Observatory), `FACT `_\ , `H.E.S.S. `_\ , `LST-1 `_\ , `MAGIC `_\ , and `VERITAS `_ telescopes reduced by `ctapipe `_ and processed by `DL1DataHandler `_. * Code, feature requests, bug reports, pull requests: https://github.com/ctlearn-project/ctlearn -* Documentation: https://ctlearn.readthedocs.io +* Documentation: https://ctlearn-project.github.io/ctlearn/ * License: BSD-3 Installation @@ -53,7 +53,7 @@ The latest version of this package can be installed via pip: pip install ctlearn -See the documentation for further information like `installation instructions for the IT-cluster `_, `installation instructions for developers `_, `package usage `_, and `dependencies `_ among other topics. +See the documentation for further information like `installation instructions for the IT-cluster `_, `installation instructions for developers `_, `package usage `_, and `dependencies `_ among other topics. Citing this software diff --git a/docs/source/conf.py b/docs/source/conf.py index f7ce2a04..ac4483a6 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -26,10 +26,6 @@ import ctlearn -# Read the full Zenodo inputs on Read the Docs, but bound processing time. -if "READTHEDOCS" in os.environ: - os.environ.setdefault("CTLEARN_TUTORIAL_MAX_EVENTS", "100") - # -- Project information ----------------------------------------------------- project = "CTLearn" diff --git a/docs/source/index.rst b/docs/source/index.rst index 18adbb03..e5099415 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -15,7 +15,7 @@ CTLearn: Deep Learning for IACT Event Reconstruction before a 1.0 release arrives. * Code, feature requests, bug reports, pull requests: https://github.com/ctlearn-project/ctlearn -* Documentation: https://ctlearn.readthedocs.io +* Documentation: https://ctlearn-project.github.io/ctlearn/ * License: BSD-3 .. toctree:: diff --git a/docs/source/tutorials.rst b/docs/source/tutorials.rst index fd53fc64..0a6332b6 100644 --- a/docs/source/tutorials.rst +++ b/docs/source/tutorials.rst @@ -12,12 +12,12 @@ four CTAO simulation files from `Zenodo record 7298569 files require about 3.5 GB of disk space. Downloaded and converted files are reused on subsequent runs. By default, data are stored under ``~/.cache/ctlearn/tutorial-data``; set ``CTLEARN_TUTORIAL_DATA_DIR`` to use a -different directory. The CI workflow preloads the source files and caches the -converted products. The CI docs build limits processing to 100 events per -input file to keep builds bounded; running the tutorial locally without that -environment variable processes the full files. The documentation build -executes the tutorial and embeds its output, including when built by Read the -Docs. Read the Docs builds limit processing to 100 events per input file. +different directory. The CI workflow preloads the source files, caches the +converted products, and limits processing to 100 events per input file to keep +the documentation build bounded. Running the tutorial locally without that +environment variable processes the full files. The CI build executes the +tutorial and embeds its output; successful builds from pushes to ``main`` are +deployed to GitHub Pages. To run the complete tutorial locally from the CTLearn repository root, install CTLearn with its development dependencies and execute: diff --git a/pyproject.toml b/pyproject.toml index ca0ddf01..32abf344 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -104,7 +104,7 @@ dev = [ [project.urls] repository = "https://github.com/ctlearn-project/ctlearn" -documentation = "https://ctlearn.readthedocs.io/en/latest/" +documentation = "https://ctlearn-project.github.io/ctlearn/" [project.scripts] ctlearn-train-keras-model = "ctlearn.tools.keras.train_model:main" From a6a3407c4f5ba6b54acf2428851413ae044a1d81 Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Mon, 9 Nov 2026 10:51:36 +0100 Subject: [PATCH 07/53] add tutorialfor training the models --- docs/source/conf.py | 13 +- docs/source/tutorials.rst | 70 +++ examples/tutorials/train_ctlearn_model.py | 651 ++++++++++++++++++++++ 3 files changed, 733 insertions(+), 1 deletion(-) create mode 100644 examples/tutorials/train_ctlearn_model.py diff --git a/docs/source/conf.py b/docs/source/conf.py index ac4483a6..229fdf51 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -23,6 +23,7 @@ # Import ctapipe.reco before autodoc mocks torch: it walks all scikit-learn # submodules, and the scikit-learn torch compatibility layer fails on a mock. import ctapipe.reco # noqa: F401 +from sphinx_gallery.sorting import FunctionSortKey import ctlearn @@ -38,6 +39,15 @@ release = version +def _tutorial_order(filename): + priority = { + "explore_public_data.py": 0, + "train_ctlearn_model.py": 1, + } + name = os.path.basename(filename) + return priority.get(name, 2), name + + # -- General configuration --------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. @@ -61,7 +71,8 @@ sphinx_gallery_conf = { "examples_dirs": "../../examples/tutorials", "gallery_dirs": "auto_tutorials", - "filename_pattern": r"explore_public_data\.py$", + "filename_pattern": r"(explore_public_data|train_ctlearn_model)\.py$", + "within_subsection_order": FunctionSortKey(_tutorial_order), "plot_gallery": True, "matplotlib_animations": (True, "jshtml"), "abort_on_example_error": True, diff --git a/docs/source/tutorials.rst b/docs/source/tutorials.rst index 0a6332b6..169ddc68 100644 --- a/docs/source/tutorials.rst +++ b/docs/source/tutorials.rst @@ -29,6 +29,76 @@ CTLearn with its development dependencies and execute: The rendered tutorial, including its code, figures, and playable waveform animations, is generated by Sphinx-Gallery: +Training a CTLearn model +======================== + +The training tutorial documents monoscopic energy and direction regression, +gamma/proton classification, custom ``SingleCNN`` and ``ResNet`` architectures, +transfer learning with ``LoadedModel``, stereo image stacking, and waveform +training. It uses only the converted gamma-ray and proton ``00`` files for the +image examples and leaves the ``01`` files untouched for later evaluation. +The three example JSON configs are copied into +``docs/source/config``. The tutorial uses the descriptions +from the training notebook and runs every example sequentially, including +during a Sphinx-Gallery build. Training all examples requires a working +TensorFlow and PyTorch installation and can take substantial time and compute +resources. +Run the data exploration tutorial first, then execute the training tutorial +from the repository root: + +.. code-block:: console + + python examples/tutorials/train_ctlearn_model.py + +The script presents each example as its own explanation followed by a literal +``ctlearn-train-keras-model`` command and then its PyTorch equivalent, +``ctlearn-train-pytorch-model``. The commands run in order; each +transfer-learning command uses the ``SingleCNN`` checkpoint from the same +framework's preceding architecture example. To use a different cache or output +location, set ``CTLEARN_TUTORIAL_DATA_DIR`` or +``CTLEARN_TUTORIAL_OUTPUT_DIR``. Training output defaults to +``~/.cache/ctlearn/tutorial-training``; use a new output directory for each +run because existing Keras and PyTorch model output directories are not +overwritten. + +To run classification directly in a terminal, set ``TRAIN_DIR`` to the +converted cache directory printed by the data exploration tutorial: + +.. code-block:: console + + TRAIN_DIR="$HOME/.cache/ctlearn/tutorial-data/ctapipe-" + ctlearn-train-keras-model \ + --signal "$TRAIN_DIR" \ + --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \ + --background "$TRAIN_DIR" \ + --pattern-background "proton_with_images_00.dl2.h5" \ + --output "$HOME/.cache/ctlearn/tutorial-training/keras-classification" \ + --config docs/source/config/dl1dh_example_config.json \ + --config docs/source/config/ctlearn_train_model_example_config.json \ + --reco type \ + --DLImageReader.focal_length_choice EQUIVALENT \ + --TrainCTLearnModel.n_epochs 5 \ + --TrainCTLearnModel.batch_size 32 + + # PyTorch equivalent: use the same arguments with the PyTorch command and output directory. + ctlearn-train-pytorch-model \ + --signal "$TRAIN_DIR" \ + --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \ + --background "$TRAIN_DIR" \ + --pattern-background "proton_with_images_00.dl2.h5" \ + --output "$HOME/.cache/ctlearn/tutorial-training/pytorch-classification" \ + --config docs/source/config/dl1dh_example_config.json \ + --config docs/source/config/ctlearn_train_model_example_config.json \ + --reco type \ + --DLImageReader.focal_length_choice EQUIVALENT \ + --TrainCTLearnModel.n_epochs 5 \ + --TrainCTLearnModel.batch_size 32 + +In a Jupyter notebook, prefix the same command with ``!``. For the other +examples, run the script to execute the commands in sequence. Start +TensorBoard for the resulting metrics with +``tensorboard --logdir ~/.cache/ctlearn/tutorial-training/``. + .. toctree:: :maxdepth: 1 diff --git a/examples/tutorials/train_ctlearn_model.py b/examples/tutorials/train_ctlearn_model.py new file mode 100644 index 00000000..f2e58a70 --- /dev/null +++ b/examples/tutorials/train_ctlearn_model.py @@ -0,0 +1,651 @@ +""" +Train CTLearn models +==================== + +Train models for CTAO image and waveform data with CTLearn. The image +examples use only the gamma-ray and proton ``00`` files; the ``01`` files +remain untouched for future evaluation tutorials. + +Each section explains a training task followed immediately by its literal +command-line example. Running this script executes every example in order. +""" + +###################################################################### +# Inspect the training environment and cached input data +# ------------------------------------------------------ +# +# Run ``explore_public_data.py`` first to download and convert the shared +# tutorial data. The converted directory is keyed by the ctapipe version and +# the optional event limit, matching the cache layout used by that tutorial. + +import importlib.metadata +import os +import subprocess +from pathlib import Path + +from ctapipe import __version__ as ctapipe_version + +MAX_EVENTS = os.environ.get("CTLEARN_TUTORIAL_MAX_EVENTS") +if MAX_EVENTS is not None and int(MAX_EVENTS) < 1: + raise ValueError("CTLEARN_TUTORIAL_MAX_EVENTS must be a positive integer") +MAX_EVENTS_SUFFIX = f"-max{MAX_EVENTS}" if MAX_EVENTS is not None else "" + +TESTDATA_DIR = ( + Path( + os.environ.get( + "CTLEARN_TUTORIAL_DATA_DIR", + str(Path.home() / ".cache" / "ctlearn" / "tutorial-data"), + ) + ) + .expanduser() + .resolve() +) +CONVERTED_DIR = TESTDATA_DIR / f"ctapipe-{ctapipe_version}{MAX_EVENTS_SUFFIX}" +GAMMA_FILE = CONVERTED_DIR / "gamma-diffuse_with_images_00.dl2.h5" +PROTON_FILE = CONVERTED_DIR / "proton_with_images_00.dl2.h5" +WAVEFORM_FILE = TESTDATA_DIR / f"gamma_prod5{MAX_EVENTS_SUFFIX}.r1.dl1.h5" + +print("Training environment:") +for distribution in ("ctapipe", "ctlearn", "dl1-data-handler", "keras", "tensorflow"): + try: + version = importlib.metadata.version(distribution) + except importlib.metadata.PackageNotFoundError: + version = "not installed" + print(f" {distribution}: {version}") + +missing_files = [path for path in (GAMMA_FILE, PROTON_FILE) if not path.is_file()] +if missing_files: + missing = "\n".join(f" - {path}" for path in missing_files) + raise FileNotFoundError( + "Cached stereo training data is missing. Run " + "examples/tutorials/explore_public_data.py first. Missing files:\n" + f"{missing}" + ) + +print("\nCached input files:") +for path in (GAMMA_FILE, PROTON_FILE): + print(f" {path.name}: {path.stat().st_size / 1024**2:.1f} MiB") +print("Only the _00 image files are selected; the _01 files are reserved.") + +###################################################################### +# Training commands, configs, and outputs +# --------------------------------------- +# +# CTLearn provides ``ctlearn-train-keras-model`` and +# ``ctlearn-train-pytorch-model`` command-line tools. Use ``--help`` or +# ``--help-all`` to inspect their options. Each example has a Keras command +# followed immediately by the equivalent PyTorch command. In a notebook, +# prefix either command with ``!``. +# +# The three JSON configuration files shipped beside this tutorial are copies +# of the workshop examples: +# +# - ``docs/source/config/dl1dh_example_config.json`` selects LST/LSTCam images, +# the image and relative peak-time channels, bilinear mapping, and an +# example 50,000 p.e. intensity cut. It also specifies NectarCam waveform +# settings. +# - ``docs/source/config/ctlearn_train_model_example_config.json`` sets the +# reader, epoch and batch defaults, validation split, Adam optimizer and +# learning rate, checkpointing, learning-rate reduction, random seed, and +# early stopping. +# - ``docs/source/config/ctlearn_models_example_config.json`` defines the +# prediction heads, attention settings, custom ``SingleCNN`` and ``ResNet`` +# architectures, and ``LoadedModel`` transfer-learning options. + +CONFIG_DIR = Path(__file__).resolve().parents[2] / "docs" / "source" / "config" +DL1DH_CONFIG = CONFIG_DIR / "dl1dh_example_config.json" +TRAINING_CONFIG = CONFIG_DIR / "ctlearn_train_model_example_config.json" +MODEL_CONFIG = CONFIG_DIR / "ctlearn_models_example_config.json" +for config_path in (DL1DH_CONFIG, TRAINING_CONFIG, MODEL_CONFIG): + if not config_path.is_file(): + raise FileNotFoundError(f"Tutorial configuration is missing: {config_path}") + +OUTPUT_DIR = ( + Path( + os.environ.get( + "CTLEARN_TUTORIAL_OUTPUT_DIR", + str(Path.home() / ".cache" / "ctlearn" / "tutorial-training"), + ) + ) + .expanduser() + .resolve() +) +TRAINING_OUTPUTS = ( + "keras-energy", + "pytorch-energy", + "keras-cameradirection", + "pytorch-cameradirection", + "keras-skydirection", + "pytorch-skydirection", + "keras-classification", + "pytorch-classification", + "keras-singlecnn-energy", + "pytorch-singlecnn-energy", + "keras-resnet-energy", + "pytorch-resnet-energy", + "keras-transfer-learning-energy", + "pytorch-transfer-learning-energy", + "keras-stereo-energy", + "pytorch-stereo-energy", + "keras-waveform-energy", + "pytorch-waveform-energy", +) +existing_outputs = [ + OUTPUT_DIR / name for name in TRAINING_OUTPUTS if (OUTPUT_DIR / name).exists() +] +if existing_outputs: + existing = "\n".join(f" - {path}" for path in existing_outputs) + raise FileExistsError( + "Training output directories already exist. Set " + "CTLEARN_TUTORIAL_OUTPUT_DIR to a new directory before running all " + f"examples:\n{existing}" + ) + +os.environ["CTLEARN_TUTORIAL_DATA_DIR"] = str(TESTDATA_DIR) +os.environ["CTLEARN_TUTORIAL_CONVERTED_DIR"] = str(CONVERTED_DIR) +os.environ["CTLEARN_TUTORIAL_CONFIG_DIR"] = str(CONFIG_DIR.resolve()) +os.environ["CTLEARN_TUTORIAL_OUTPUT_DIR"] = str(OUTPUT_DIR) +os.environ["CTLEARN_TUTORIAL_MAX_EVENTS_SUFFIX"] = MAX_EVENTS_SUFFIX + +print(f"\nTraining outputs: {OUTPUT_DIR}") + +###################################################################### +# Part A +# +# Monoscopic CNN-based model training +# ----------------------------------- +# +# We first train a basic monoscopic CNN-based model using the default CTLearn +# model configuration. The model uses a **ThinResNet** backbone for feature +# extraction and a standard MLP head for the task-specific prediction. We +# consider three different reconstruction tasks, each trained separately: + +###################################################################### +# 1. Primary particle energy regression +# -------------------------------------- +# +# The model reconstructs the energy of the primary particle as a continuous +# value. Internally, CTLearn performs the regression on the energy in TeV and +# on a logarithmic scale, since the primary-particle energy spans a very wide +# range. Working in logarithmic space has been found to be more efficient for +# the regression and is therefore a fixed, non-configurable aspect of the +# energy reconstruction. During inference, the prediction tool converts the +# predicted values back from logarithmic space to the original linear energy +# scale in TeV. + +subprocess.run( + """ctlearn-train-keras-model \\ + --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ + --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ + --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-energy" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/dl1dh_example_config.json" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/ctlearn_train_model_example_config.json" \\ + --reco energy \\ + --DLImageReader.focal_length_choice EQUIVALENT \\ + --TrainCTLearnModel.n_epochs 10 \\ + --TrainCTLearnModel.batch_size 32""", + shell=True, + check=True, +) + +subprocess.run( + """ctlearn-train-pytorch-model \\ + --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ + --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ + --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-energy" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/dl1dh_example_config.json" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/ctlearn_train_model_example_config.json" \\ + --reco energy \\ + --DLImageReader.focal_length_choice EQUIVALENT \\ + --TrainCTLearnModel.n_epochs 10 \\ + --TrainCTLearnModel.batch_size 32""", + shell=True, + check=True, +) + +###################################################################### +# 2. Arrival direction regression +# ------------------------------- +# +# The model reconstructs the arrival direction of the primary particle. +# This can be done in two ways: either using the **cameradirection** task, +# which transforms the particle origin into the camera frame and performs +# the regression in camera coordinates, with distances expressed in meters; +# or using the **skydirection** task, which performs the regression in the +# sky frame, with field-of-view offsets expressed in degrees. For monoscopic +# CNN-based models, we generally recommend using the **cameradirection** +# task. During inference, the prediction tool converts the reconstructed +# camera coordinates back to the original Alt/Az representation, with the +# final direction expressed in degrees. + +# Camera coordinates +subprocess.run( + """ctlearn-train-keras-model \\ + --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ + --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ + --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-cameradirection" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/dl1dh_example_config.json" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/ctlearn_train_model_example_config.json" \\ + --reco cameradirection \\ + --DLImageReader.focal_length_choice EQUIVALENT \\ + --TrainCTLearnModel.n_epochs 5 \\ + --TrainCTLearnModel.batch_size 32""", + shell=True, + check=True, +) + +subprocess.run( + """ctlearn-train-pytorch-model \\ + --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ + --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ + --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-cameradirection" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/dl1dh_example_config.json" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/ctlearn_train_model_example_config.json" \\ + --reco cameradirection \\ + --DLImageReader.focal_length_choice EQUIVALENT \\ + --TrainCTLearnModel.n_epochs 5 \\ + --TrainCTLearnModel.batch_size 32""", + shell=True, + check=True, +) + +# Sky coordinates +subprocess.run( + """ctlearn-train-keras-model \\ + --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ + --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ + --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-skydirection" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/dl1dh_example_config.json" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/ctlearn_train_model_example_config.json" \\ + --reco skydirection \\ + --DLImageReader.focal_length_choice EQUIVALENT \\ + --TrainCTLearnModel.n_epochs 5 \\ + --TrainCTLearnModel.batch_size 32""", + shell=True, + check=True, +) + +subprocess.run( + """ctlearn-train-pytorch-model \\ + --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ + --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ + --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-skydirection" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/dl1dh_example_config.json" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/ctlearn_train_model_example_config.json" \\ + --reco skydirection \\ + --DLImageReader.focal_length_choice EQUIVALENT \\ + --TrainCTLearnModel.n_epochs 5 \\ + --TrainCTLearnModel.batch_size 32""", + shell=True, + check=True, +) + +###################################################################### +# 3. Primary particle type classification +# --------------------------------------- +# +# The model performs binary classification of the primary particle type, +# learning to distinguish between the two particle classes: signal +# (gamma-ray events) and background (proton events), based on the information +# contained in the camera image. The input directory containing the signal +# events can be specified using *--TrainCTLearnModel.input_dir_signal* or the +# shorthand *--signal*. One or more file patterns can be provided using +# *--TrainCTLearnModel.file_pattern_signal* or *--pattern-signal*. The +# corresponding options for the background events are +# *--TrainCTLearnModel.input_dir_background* / *--background* and +# *--TrainCTLearnModel.file_pattern_background* / *--pattern-background*. +# +# It is recommended to approximately balance the training dataset before +# training. The training log reports the number of signal and background +# events remaining after the selection cuts, which can be used to check the +# class balance. If a significant imbalance is present, the input file +# patterns should be adjusted to include a more balanced selection of +# gamma-ray and proton events. CTLearn includes a standard, fixed mechanism +# that computes class weights and incorporates them into the loss +# calculation to compensate for differences in the number of signal and +# background events. However, class weighting is only effective up to a +# certain degree of class imbalance. It is therefore important to monitor +# the training carefully, particularly when the input samples are not well +# balanced. The training logs and learning curves should be inspected +# throughout the training. In particular, the evolution of metrics such as +# loss, accuracy, and AUC on a per-epoch basis can help identify potential +# issues arising from class imbalance or other training problems. + +subprocess.run( + """ctlearn-train-keras-model \\ + --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ + --pattern-signal "gamma-diffuse_with_images_00.dl2.h*" \\ + --background "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ + --pattern-background "proton_with_images_00.dl2.h*" \\ + --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-classification" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/dl1dh_example_config.json" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/ctlearn_train_model_example_config.json" \\ + --reco type \\ + --DLImageReader.focal_length_choice EQUIVALENT \\ + --TrainCTLearnModel.n_epochs 5 \\ + --TrainCTLearnModel.batch_size 32""", + shell=True, + check=True, +) + +subprocess.run( + """ctlearn-train-pytorch-model \\ + --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ + --pattern-signal "gamma-diffuse_with_images_00.dl2.h*" \\ + --background "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ + --pattern-background "proton_with_images_00.dl2.h*" \\ + --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-classification" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/dl1dh_example_config.json" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/ctlearn_train_model_example_config.json" \\ + --reco type \\ + --DLImageReader.focal_length_choice EQUIVALENT \\ + --TrainCTLearnModel.n_epochs 5 \\ + --TrainCTLearnModel.batch_size 32""", + shell=True, + check=True, +) + +###################################################################### +# Part B +# +# Customizing the CTLearn model architecture +# ------------------------------------------ +# +# CTLearn provides a flexible configuration system that allows users to +# customize the neural network architecture. +# +# Two main CNN-based architectures are currently implemented: **SingleCNN** +# and **ResNet**, which can bet set by *--TrainCTLearnModel.model_type*. +# +# The **SingleCNN** component implements a plain convolutional neural +# network consisting of configurable convolutional layers. It can be used +# to construct very simple and lightweight models, but it can also be +# configured to create deeper architectures, such as VGG-like networks. +# This architecture represents the more legacy model structure in CTLearn +# and was the starting point for early proof-of-concept studies exploring +# the applicability of CNNs to the problem. For applications closer to the +# camera hardware and its readout (for the trigger system), particularly +# where predictions need to be made at very high rates and with very low +# latency, computational efficiency becomes increasingly important. + +subprocess.run( + """ctlearn-train-keras-model \\ + --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ + --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ + --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-singlecnn-energy" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/dl1dh_example_config.json" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/ctlearn_train_model_example_config.json" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/ctlearn_models_example_config.json" \\ + --reco energy \\ + --DLImageReader.focal_length_choice EQUIVALENT \\ + --TrainCTLearnModel.model_type SingleCNN""", + shell=True, + check=True, +) + +subprocess.run( + """ctlearn-train-pytorch-model \\ + --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ + --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ + --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-singlecnn-energy" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/dl1dh_example_config.json" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/ctlearn_train_model_example_config.json" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/ctlearn_models_example_config.json" \\ + --reco energy \\ + --DLImageReader.focal_length_choice EQUIVALENT \\ + --TrainCTLearnModel.model_type SingleCNN""", + shell=True, + check=True, +) + +# +# The **ResNet** component provides the currently preferred architecture for +# constructing deeper CNN models. Residual networks allow substantially +# deeper architectures while maintaining efficient training and inference, +# and they generally provide improved performance compared with the simpler +# plain CNN architecture. The architecture, number of layers or blocks, +# number of filters, and other relevant parameters can therefore be +# configured directly through the CTLearn configuration system, allowing +# the model complexity to be adapted to the requirements of a particular +# application. For ResNet architectures, CTLearn currently supports two +# types of residual blocks: +# +# - Basic blocks, which use the simpler residual block structure and are +# suitable for relatively lightweight networks. +# - Bottleneck blocks, which use a more compact sequence of convolutions to +# enable deeper networks while controlling the computational cost. + +subprocess.run( + """ctlearn-train-keras-model \\ + --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ + --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ + --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-resnet-energy" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/dl1dh_example_config.json" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/ctlearn_train_model_example_config.json" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/ctlearn_models_example_config.json" \\ + --reco energy \\ + --DLImageReader.focal_length_choice EQUIVALENT \\ + --TrainCTLearnModel.model_type ResNet \\ + --TrainCTLearnModel.n_epochs 2 \\ + --TrainCTLearnModel.batch_size 16""", + shell=True, + check=True, +) + +subprocess.run( + """ctlearn-train-pytorch-model \\ + --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ + --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ + --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-resnet-energy" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/dl1dh_example_config.json" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/ctlearn_train_model_example_config.json" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/ctlearn_models_example_config.json" \\ + --reco energy \\ + --DLImageReader.focal_length_choice EQUIVALENT \\ + --TrainCTLearnModel.model_type ResNet \\ + --TrainCTLearnModel.n_epochs 2 \\ + --TrainCTLearnModel.batch_size 16""", + shell=True, + check=True, +) + +###################################################################### +# Using a pre-trained model and transfer learning +# ----------------------------------------------- +# +# The LoadedModel component allows a previously trained model following +# the CTLearnModel structure to be loaded for either resuming training or +# transfer learning. Transfer learning reuses the learned features of an +# existing model and adapts them to new, but related, data or tasks. This +# can reduce training time compared with training a model from scratch. +# +# Two parameters are particularly important: +# +# - *--LoadedModel.trainable_backbone* controls whether the pre-trained +# backbone is frozen (false) or trainable (true). +# - *--LoadedModel.overwrite_head* controls whether the structure of the +# original prediction head is reused (false) or replaced with a new MLP +# tailored to the new task or data (true). +# +# The preceding SingleCNN command trains the model loaded below. The copied +# configuration keeps its prediction head and leaves the backbone trainable. + +subprocess.run( + """ctlearn-train-keras-model \\ + --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ + --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ + --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-transfer-learning-energy" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/dl1dh_example_config.json" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/ctlearn_train_model_example_config.json" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/ctlearn_models_example_config.json" \\ + --reco energy \\ + --DLImageReader.focal_length_choice EQUIVALENT \\ + --TrainCTLearnModel.model_type LoadedModel \\ + --LoadedModel.load_model_from "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-singlecnn-energy/ctlearn_model.keras" \\ + --TrainCTLearnModel.n_epochs 2""", + shell=True, + check=True, +) + +subprocess.run( + """ctlearn-train-pytorch-model \\ + --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ + --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ + --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-transfer-learning-energy" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/dl1dh_example_config.json" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/ctlearn_train_model_example_config.json" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/ctlearn_models_example_config.json" \\ + --reco energy \\ + --DLImageReader.focal_length_choice EQUIVALENT \\ + --TrainCTLearnModel.model_type LoadedModel \\ + --PyTorchLoadedModel.load_model_from "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-singlecnn-energy/ctlearn_model.pt" \\ + --TrainCTLearnModel.n_epochs 2""", + shell=True, + check=True, +) + +###################################################################### +# Stereoscopic CNN-based model training +# ------------------------------------- +# +# CTLearn currently provides a basic approach for stereoscopic CNN-based +# model training. The images from the different telescopes are concatenated +# channel-wise and then passed to a standard, monoscopic CNN backbone as +# above. In this way, the network can process the combined input while +# retaining stereoscopic information. An earlier version of CTLearn also +# included a CNN-RNN architecture, using recurrent neural networks to +# explicitly handle information from multiple telescopes dynamically. This +# model has not yet been migrated to the latest CTLearn version based on +# TensorFlow 2 and Keras 3, so this tutorial focuses on the channel-wise +# concatenation approach. +# +# The main configuration parameters for stereoscopic training are: +# +# - *--DLImageReader.mode*: set to "stereo" to enable stereoscopic image +# reading +# - *--DLImageReader.min_telescopes*: defines the minimum number of +# telescopes that must participate in an event after the quality cuts. +# - *--TrainCTLearnModel.stack_telescope_images*: set to true to +# stack/concatenate the images from the telescopes. +# +# Since the resulting input contains information from multiple telescopes +# and is therefore larger than the corresponding monoscopic input, it is +# recommended to reduce the batch size using +# *--TrainCTLearnModel.batch_size* to account for the increased memory +# consumption. + +subprocess.run( + """ctlearn-train-keras-model \\ + --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ + --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ + --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-stereo-energy" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/dl1dh_example_config.json" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/ctlearn_train_model_example_config.json" \\ + --reco energy \\ + --DLImageReader.mode stereo \\ + --DLImageReader.min_telescopes 2 \\ + --TrainCTLearnModel.stack_telescope_images True \\ + --TrainCTLearnModel.n_epochs 5 \\ + --TrainCTLearnModel.batch_size 16""", + shell=True, + check=True, +) + +subprocess.run( + """ctlearn-train-pytorch-model \\ + --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ + --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ + --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-stereo-energy" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/dl1dh_example_config.json" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/ctlearn_train_model_example_config.json" \\ + --reco energy \\ + --DLImageReader.mode stereo \\ + --DLImageReader.min_telescopes 2 \\ + --TrainCTLearnModel.stack_telescope_images True \\ + --TrainCTLearnModel.n_epochs 5 \\ + --TrainCTLearnModel.batch_size 16""", + shell=True, + check=True, +) + +###################################################################### +# CNN-based model training using waveform data +# -------------------------------------------- +# +# The final example demonstrates training directly on waveform data. The +# example dataset used in this tutorial is intentionally very small, so +# only a few events are available for training. In practical applications, +# waveform datasets can be very large, often reaching several terabytes, +# and processing the full waveforms also requires substantial RAM and +# computational resources. Because the example dataset is so small, the +# training configuration needs to be adjusted accordingly. We use a very +# small batch size and increase the validation split to ensure that at +# least one batch is available for validation. For this example, we select +# the MST equipped with the NectarCam camera and disable the quality +# selection, leaving only 10 events. These are divided into 5 batches of 2 +# events, with 20% of the data reserved for validation, corresponding to +# one validation batch. +# +# An important configuration change is required to read waveform data: the +# *--TrainCTLearnModel.dl1dh_reader_type* option must be set to the +# appropriate DL1 data reader component for waveform reading +# (**DLWaveformReader**) rather than the default image reader. + +if not WAVEFORM_FILE.is_file(): + raise FileNotFoundError( + f"Cached waveform data is missing: {WAVEFORM_FILE}. " + "Run examples/tutorials/explore_public_data.py first." + ) +subprocess.run( + """ctlearn-train-keras-model \\ + --signal "$CTLEARN_TUTORIAL_DATA_DIR" \\ + --pattern-signal "gamma_prod5${CTLEARN_TUTORIAL_MAX_EVENTS_SUFFIX}.r1.dl1.h5" \\ + --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-waveform-energy" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/ctlearn_train_model_example_config.json" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/dl1dh_example_config.json" \\ + --reco energy \\ + --TrainCTLearnModel.n_epochs 5 \\ + --TrainCTLearnModel.batch_size 2 \\ + --TrainCTLearnModel.validation_split 0.2 \\ + --TrainCTLearnModel.dl1dh_reader_type DLWaveformReader \\ + --DLWaveformReader.focal_length_choice EQUIVALENT \\ + --TableQualityQuery.quality_criteria []""", + shell=True, + check=True, +) + +subprocess.run( + """ctlearn-train-pytorch-model \\ + --signal "$CTLEARN_TUTORIAL_DATA_DIR" \\ + --pattern-signal "gamma_prod5${CTLEARN_TUTORIAL_MAX_EVENTS_SUFFIX}.r1.dl1.h5" \\ + --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-waveform-energy" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/ctlearn_train_model_example_config.json" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/dl1dh_example_config.json" \\ + --reco energy \\ + --TrainCTLearnModel.n_epochs 5 \\ + --TrainCTLearnModel.batch_size 2 \\ + --TrainCTLearnModel.validation_split 0.2 \\ + --TrainCTLearnModel.dl1dh_reader_type DLWaveformReader \\ + --DLWaveformReader.focal_length_choice EQUIVALENT \\ + --TableQualityQuery.quality_criteria []""", + shell=True, + check=True, +) + +###################################################################### +# Monitoring training with TensorBoard +# ------------------------------------ +# +# TensorBoard can be used to monitor the training process live. CTLearn +# writes training metrics to the output directory, which can then be +# visualized with TensorBoard. Once started, TensorBoard provides an +# interactive web interface where metrics such as loss, accuracy, and AUC +# can be monitored over the course of training. This is useful for checking +# the training progress and identifying issues such as overfitting or +# unstable training. The command can also be run directly from a terminal +# or on a remote/cluster environment, where the TensorBoard web interface +# can be accessed through the appropriate port forwarding. +# +# Start TensorBoard in a separate terminal to compare the completed runs: +# +# ``tensorboard --logdir ~/.cache/ctlearn/tutorial-training/`` From 29cec923565e741b9b7ee26268a5befd8e9da737 Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Fri, 6 Nov 2026 23:43:01 +0100 Subject: [PATCH 08/53] support data format v8 --- src/ctlearn/conftest.py | 18 ++++++++++++++++- src/ctlearn/tools/predict_model.py | 24 +++++++++++++++++++---- src/ctlearn/tools/predict_mono_model.py | 3 +-- src/ctlearn/tools/predict_stereo_model.py | 3 +-- 4 files changed, 39 insertions(+), 9 deletions(-) diff --git a/src/ctlearn/conftest.py b/src/ctlearn/conftest.py index 809acbe9..0991f5dc 100644 --- a/src/ctlearn/conftest.py +++ b/src/ctlearn/conftest.py @@ -24,6 +24,10 @@ from traitlets.config.loader import Config # TODO: Bump minimum ctapipe version to v0.33.0. Clean up imports! +try: + from ctapipe.io.hdf5dataformat import DL0_TEL_TRIGGER_TABLE +except ImportError: + DL0_TEL_TRIGGER_TABLE = "/dl0/event/telescope/trigger" try: from ctapipe.io.metadata import ProductMetadata as _ProductMetadata except ImportError: @@ -212,7 +216,19 @@ def dl1_obs_mock_file(dl1_tmp_path, dl1_gamma_file): output = dl1_tmp_path / "dl1_obs_mock_file.dl1.h5" shutil.copy(dl1_gamma_file, output) # Read the trigger table to get the unique telescope IDs and their pointing information - trigger_table = read_table(dl1_gamma_file, path=DL1_TEL_TRIGGER_TABLE) + # TODO: Bump minimum ctapipe version to v0.33.0. Clean up here! + with tables.open_file(output, mode="r") as h5_file: + file_attrs = h5_file.root._v_attrs + if "data.type" in file_attrs: + data_format_version = file_attrs["model.version"] + elif "CTA PROCESS TYPE" in file_attrs: + data_format_version = file_attrs["CTA PRODUCT DATA MODEL VERSION"] + else: + raise IOError("Unsupported or missing reference metadata") + if int(data_format_version.split(".")[0].replace("v", "")) >= 8: + trigger_table = read_table(dl1_gamma_file, path=DL0_TEL_TRIGGER_TABLE) + else: + trigger_table = read_table(dl1_gamma_file, path=DL1_TEL_TRIGGER_TABLE) tel_ids = np.unique(trigger_table["tel_id"]) time = trigger_table["time"][[0, -1]] # Mimic an observation of 20 mins duration by adjusting the time range for the tel pointing tables diff --git a/src/ctlearn/tools/predict_model.py b/src/ctlearn/tools/predict_model.py index 7d0a54c4..3ad67553 100644 --- a/src/ctlearn/tools/predict_model.py +++ b/src/ctlearn/tools/predict_model.py @@ -60,6 +60,14 @@ ) # TODO: Bump minimum ctapipe version to v0.33.0. Clean up imports! +try: + from ctapipe.io.hdf5dataformat import ( + DL0_SUBARRAY_TRIGGER_TABLE, + DL0_TEL_TRIGGER_TABLE, + ) +except ImportError: + DL0_SUBARRAY_TRIGGER_TABLE = "/dl0/event/subarray/trigger" + DL0_TEL_TRIGGER_TABLE = "/dl0/event/telescope/trigger" try: from ctao_datamodel.models.dataproducts import Software from ctapipe.io.metadata import ( @@ -472,6 +480,15 @@ def setup(self): input_url_signal=[self.input_url], parent=self, ) + if ( + int(self.dl1dh_reader.data_format_version.split(".")[0].replace("v", "")) + >= 8 + ): + self.subarray_trigger_table_path = DL0_SUBARRAY_TRIGGER_TABLE + self.tel_trigger_table_path = DL0_TEL_TRIGGER_TABLE + else: + self.subarray_trigger_table_path = DL1_SUBARRAY_TRIGGER_TABLE + self.tel_trigger_table_path = DL1_TEL_TRIGGER_TABLE self.log.info("Number of events loaded: %s", self.dl1dh_reader.get_n_events()) # Check if the number of events is enough to form a batch if self.dl1dh_reader.get_n_events() < self.batch_size: @@ -596,10 +613,9 @@ def _ensure_subarray_consistency(self): ) selected_subarray.to_hdf(self.output_path) self.log.info("SubarrayDescription was stored in '%s'", self.output_path) - tel_trigger_table = read_table( self.output_path, - DL1_TEL_TRIGGER_TABLE, + self.tel_trigger_table_path, ) mask = np.isin(tel_trigger_table["tel_id"], self.dl1dh_reader.tel_ids) tel_trigger_table = tel_trigger_table[mask] @@ -608,7 +624,7 @@ def _ensure_subarray_consistency(self): write_table( tel_trigger_table, self.output_path, - DL1_TEL_TRIGGER_TABLE, + self.tel_trigger_table_path, overwrite=True, ) @@ -639,7 +655,7 @@ def _ensure_subarray_consistency(self): write_table( subarray_trigger_table, self.output_path, - DL1_SUBARRAY_TRIGGER_TABLE, + self.subarray_trigger_table_path, overwrite=True, ) # Update the simulation shower table to keep only events present in the subarray trigger table diff --git a/src/ctlearn/tools/predict_mono_model.py b/src/ctlearn/tools/predict_mono_model.py index 3022d73b..dca6e69a 100644 --- a/src/ctlearn/tools/predict_mono_model.py +++ b/src/ctlearn/tools/predict_mono_model.py @@ -23,7 +23,6 @@ from ctapipe.io.hdf5dataformat import ( DL1_TEL_GROUP, DL1_TEL_POINTING_GROUP, - DL1_TEL_TRIGGER_TABLE, DL2_EVENT_STATISTICS_GROUP, DL2_SUBARRAY_ENERGY_GROUP, DL2_SUBARRAY_GEOMETRY_GROUP, @@ -126,7 +125,7 @@ def start(self): example_identifiers.keep_columns(TEL_EVENT_KEYS) all_identifiers = read_table( self.output_path, - DL1_TEL_TRIGGER_TABLE, + self.tel_trigger_table_path, ) all_identifiers.keep_columns(TEL_EVENT_KEYS + ["time"]) nonexample_identifiers = setdiff( diff --git a/src/ctlearn/tools/predict_stereo_model.py b/src/ctlearn/tools/predict_stereo_model.py index 300440c8..645a8ac0 100644 --- a/src/ctlearn/tools/predict_stereo_model.py +++ b/src/ctlearn/tools/predict_stereo_model.py @@ -23,7 +23,6 @@ from ctapipe.io.hdf5dataformat import ( DL1_SUBARRAY_GROUP, DL1_SUBARRAY_POINTING_GROUP, - DL1_TEL_TRIGGER_TABLE, DL2_EVENT_STATISTICS_GROUP, DL2_SUBARRAY_ENERGY_GROUP, DL2_SUBARRAY_GEOMETRY_GROUP, @@ -100,7 +99,7 @@ def start(self): example_identifiers.keep_columns(SUBARRAY_EVENT_KEYS) all_identifiers = read_table( self.output_path, - DL1_TEL_TRIGGER_TABLE, + self.tel_trigger_table_path, ) all_identifiers.keep_columns(SUBARRAY_EVENT_KEYS + ["time"]) # Unique example identifiers by events From 6f027561b26d2fae76b941c2f8c5ec50c9784faa Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Fri, 6 Nov 2026 23:47:17 +0100 Subject: [PATCH 09/53] add changelog --- docs/changes/323.datamodel.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/changes/323.datamodel.rst diff --git a/docs/changes/323.datamodel.rst b/docs/changes/323.datamodel.rst new file mode 100644 index 00000000..d377f29f --- /dev/null +++ b/docs/changes/323.datamodel.rst @@ -0,0 +1 @@ +Added support for ctapipe HDF5 data format v8.0.0, using the updated DL0 trigger-table paths while preserving compatibility with earlier data formats. From dc86da2cc7f3d8712a54e85465602058719b7d17 Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Mon, 9 Nov 2026 11:11:25 +0100 Subject: [PATCH 10/53] added the config example files --- .gitignore | 2 + .../config/ctlearn_models_example_config.json | 74 +++++++++++++++++++ .../ctlearn_train_model_example_config.json | 22 ++++++ docs/source/config/dl1dh_example_config.json | 19 +++++ 4 files changed, 117 insertions(+) create mode 100644 docs/source/config/ctlearn_models_example_config.json create mode 100644 docs/source/config/ctlearn_train_model_example_config.json create mode 100644 docs/source/config/dl1dh_example_config.json diff --git a/.gitignore b/.gitignore index 5c9e21c4..a1cef398 100644 --- a/.gitignore +++ b/.gitignore @@ -45,3 +45,5 @@ test/ *.sh output* config* +!docs/source/config/ +!docs/source/config/*.json diff --git a/docs/source/config/ctlearn_models_example_config.json b/docs/source/config/ctlearn_models_example_config.json new file mode 100644 index 00000000..516f7cba --- /dev/null +++ b/docs/source/config/ctlearn_models_example_config.json @@ -0,0 +1,74 @@ +{ + "CTLearnModel": { + "init_padding": 0, + "head_layers": { + "type": [512, 256, 2], + "energy": [512, 256, 1], + "cameradirection": [512, 256, 2], + "skydirection": [512, 256, 2] + }, + "head_activation_function": { + "type": "relu", + "energy": "relu", + "cameradirection": "tanh", + "skydirection": "tanh" + }, + "attention_mechanism": "Dual-SE", + "attention_reduction_ratio": 16 + }, + "SingleCNN": { + "name": "My_own_plain_CNN_model", + "architecture": [ + { + "filters": 16, + "kernel_size": 3, + "number": 2 + }, + { + "filters": 32, + "kernel_size": 3, + "number": 2 + }, + { + "filters": 64, + "kernel_size": 3, + "number": 2 + } + ], + "pooling_type": "max", + "pooling_parameters": { + "size": 2, + "strides": 2 + }, + "batchnorm": false, + "bottleneck_filters": null + }, + "ResNet": { + "name": "My_own_ResNet50_model", + "init_layer": null, + "init_max_pool": null, + "residual_block_type": "bottleneck", + "architecture": [ + { + "filters": 64, + "blocks": 3 + }, + { + "filters": 128, + "blocks": 4 + }, + { + "filters": 256, + "blocks": 6 + }, + { + "filters": 512, + "blocks": 3 + } + ] + }, + "LoadedModel": { + "overwrite_head": false, + "trainable_backbone": true + } +} diff --git a/docs/source/config/ctlearn_train_model_example_config.json b/docs/source/config/ctlearn_train_model_example_config.json new file mode 100644 index 00000000..08e00587 --- /dev/null +++ b/docs/source/config/ctlearn_train_model_example_config.json @@ -0,0 +1,22 @@ +{ + "TrainCTLearnModel": { + "dl1dh_reader_type": "DLImageReader", + "n_epochs": 10, + "batch_size": 64, + "validation_split": 0.1, + "save_best_validation_only": true, + "optimizer": { + "name": "Adam", + "base_learning_rate": 0.0001, + "adam_epsilon": 1.0e-8 + }, + "lr_reducing": { + "factor": 0.5, + "patience": 5, + "min_delta": 0.01, + "min_lr": 0.000001 + }, + "random_seed": 1234, + "early_stopping": null + } +} diff --git a/docs/source/config/dl1dh_example_config.json b/docs/source/config/dl1dh_example_config.json new file mode 100644 index 00000000..7adf5270 --- /dev/null +++ b/docs/source/config/dl1dh_example_config.json @@ -0,0 +1,19 @@ +{ + "TableQualityQuery": { + "quality_criteria": [ + ["> 50000 phe", "hillas_intensity > 50000"] + ] + }, + "DLImageReader": { + "allowed_tel_types": "LST_LST_LSTCam", + "channels": ["image", "relative_peak_time"], + "image_mapper_type": "BilinearMapper" + }, + "DLWaveformReader": { + "allowed_tels": [109, 112, 118, 119, 121, 122, 124], + "sequence_length": 5, + "sequence_position": "center", + "cleaning_type": null, + "image_mapper_type": "BilinearMapper" + } +} From d8d7ae09ffc586124b46c7e6e1d93e9444f2ebec Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Mon, 9 Nov 2026 11:16:01 +0100 Subject: [PATCH 11/53] fix docs --- examples/tutorials/train_ctlearn_model.py | 26 ++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/examples/tutorials/train_ctlearn_model.py b/examples/tutorials/train_ctlearn_model.py index f2e58a70..2d6e7adc 100644 --- a/examples/tutorials/train_ctlearn_model.py +++ b/examples/tutorials/train_ctlearn_model.py @@ -92,7 +92,31 @@ # prediction heads, attention settings, custom ``SingleCNN`` and ``ResNet`` # architectures, and ``LoadedModel`` transfer-learning options. -CONFIG_DIR = Path(__file__).resolve().parents[2] / "docs" / "source" / "config" +def find_config_dir(): + roots = [] + script_path = globals().get("__file__") + if script_path is not None: + roots.append(Path(script_path).resolve().parents[2]) + roots.extend((Path.cwd(), *Path.cwd().parents)) + + config_names = ( + "dl1dh_example_config.json", + "ctlearn_train_model_example_config.json", + "ctlearn_models_example_config.json", + ) + for root in roots: + config_dir = root / "docs" / "source" / "config" + if all((config_dir / name).is_file() for name in config_names): + return config_dir + + raise FileNotFoundError( + "Could not locate tutorial configs under docs/source/config. " + "Run this tutorial from the CTLearn repository or build it with " + "Sphinx-Gallery." + ) + + +CONFIG_DIR = find_config_dir() DL1DH_CONFIG = CONFIG_DIR / "dl1dh_example_config.json" TRAINING_CONFIG = CONFIG_DIR / "ctlearn_train_model_example_config.json" MODEL_CONFIG = CONFIG_DIR / "ctlearn_models_example_config.json" From f65e878f66cea2bb4b1f81fb5f0b1e0f5c791b8c Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Mon, 9 Nov 2026 11:17:58 +0100 Subject: [PATCH 12/53] fix lint --- examples/tutorials/train_ctlearn_model.py | 1 + 1 file changed, 1 insertion(+) diff --git a/examples/tutorials/train_ctlearn_model.py b/examples/tutorials/train_ctlearn_model.py index 2d6e7adc..f469da19 100644 --- a/examples/tutorials/train_ctlearn_model.py +++ b/examples/tutorials/train_ctlearn_model.py @@ -92,6 +92,7 @@ # prediction heads, attention settings, custom ``SingleCNN`` and ``ResNet`` # architectures, and ``LoadedModel`` transfer-learning options. + def find_config_dir(): roots = [] script_path = globals().get("__file__") From 524b78d593593f9131ff827e251ac72ad0ccb87a Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Mon, 9 Nov 2026 11:29:20 +0100 Subject: [PATCH 13/53] remove mocking the installation of DL frameworks --- .github/workflows/ci.yml | 4 +++- docs/source/conf.py | 14 -------------- docs/source/tutorials.rst | 7 +++---- 3 files changed, 6 insertions(+), 19 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index eafdceee..987f6914 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -102,6 +102,8 @@ jobs: runs-on: ubuntu-24.04 permissions: contents: read + env: + PIP_EXTRA_INDEX_URL: "https://download.pytorch.org/whl/cpu" steps: - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 with: @@ -121,7 +123,7 @@ jobs: - name: Install documentation dependencies run: | python -m pip install --upgrade pip - python -m pip install --no-deps . + python -m pip install . python -m pip install -r docs/requirements.txt python -m pip install sphinx sphinx-rtd-theme sphinx-changelog sphinx-design diff --git a/docs/source/conf.py b/docs/source/conf.py index 229fdf51..d99c5bbe 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -210,17 +210,3 @@ def _tutorial_order(filename): # -- Extension configuration ------------------------------------------------- - -# The heavy ML frameworks are not installed in the docs build environment -# (see .readthedocs.yaml), so they are mocked to let autodoc import ctlearn. -autodoc_mock_imports = [ - "torch", - "torchvision", - "torchmetrics", - "pytorch_lightning", - "tensorflow", - "tensorboard", - "keras", - "keras_hexagdly", - "pytorch_hexagdly", -] diff --git a/docs/source/tutorials.rst b/docs/source/tutorials.rst index 169ddc68..b6424771 100644 --- a/docs/source/tutorials.rst +++ b/docs/source/tutorials.rst @@ -39,10 +39,9 @@ training. It uses only the converted gamma-ray and proton ``00`` files for the image examples and leaves the ``01`` files untouched for later evaluation. The three example JSON configs are copied into ``docs/source/config``. The tutorial uses the descriptions -from the training notebook and runs every example sequentially, including -during a Sphinx-Gallery build. Training all examples requires a working -TensorFlow and PyTorch installation and can take substantial time and compute -resources. +from the training notebook and executes every example sequentially during +the documentation build. This requires working TensorFlow and PyTorch +installations and can take substantial time and compute resources. Run the data exploration tutorial first, then execute the training tutorial from the repository root: From 56ca4038f9ea79370d86e3c87d1299c38870f789 Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Mon, 9 Nov 2026 11:41:01 +0100 Subject: [PATCH 14/53] use more events and reduce batch size --- .github/workflows/ci.yml | 2 +- examples/tutorials/train_ctlearn_model.py | 32 +++++++++++++---------- 2 files changed, 19 insertions(+), 15 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 987f6914..ae43ab81 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -148,7 +148,7 @@ jobs: - name: Build documentation and execute tutorials env: - CTLEARN_TUTORIAL_MAX_EVENTS: "100" + CTLEARN_TUTORIAL_MAX_EVENTS: "1000" run: python -m sphinx -b html --keep-going docs/source docs/build/html - name: Upload rendered documentation for review diff --git a/examples/tutorials/train_ctlearn_model.py b/examples/tutorials/train_ctlearn_model.py index f469da19..fb1a2672 100644 --- a/examples/tutorials/train_ctlearn_model.py +++ b/examples/tutorials/train_ctlearn_model.py @@ -208,7 +208,7 @@ def find_config_dir(): --reco energy \\ --DLImageReader.focal_length_choice EQUIVALENT \\ --TrainCTLearnModel.n_epochs 10 \\ - --TrainCTLearnModel.batch_size 32""", + --TrainCTLearnModel.batch_size 16""", shell=True, check=True, ) @@ -223,7 +223,7 @@ def find_config_dir(): --reco energy \\ --DLImageReader.focal_length_choice EQUIVALENT \\ --TrainCTLearnModel.n_epochs 10 \\ - --TrainCTLearnModel.batch_size 32""", + --TrainCTLearnModel.batch_size 16""", shell=True, check=True, ) @@ -254,7 +254,7 @@ def find_config_dir(): --reco cameradirection \\ --DLImageReader.focal_length_choice EQUIVALENT \\ --TrainCTLearnModel.n_epochs 5 \\ - --TrainCTLearnModel.batch_size 32""", + --TrainCTLearnModel.batch_size 16""", shell=True, check=True, ) @@ -269,7 +269,7 @@ def find_config_dir(): --reco cameradirection \\ --DLImageReader.focal_length_choice EQUIVALENT \\ --TrainCTLearnModel.n_epochs 5 \\ - --TrainCTLearnModel.batch_size 32""", + --TrainCTLearnModel.batch_size 16""", shell=True, check=True, ) @@ -285,7 +285,7 @@ def find_config_dir(): --reco skydirection \\ --DLImageReader.focal_length_choice EQUIVALENT \\ --TrainCTLearnModel.n_epochs 5 \\ - --TrainCTLearnModel.batch_size 32""", + --TrainCTLearnModel.batch_size 16""", shell=True, check=True, ) @@ -300,7 +300,7 @@ def find_config_dir(): --reco skydirection \\ --DLImageReader.focal_length_choice EQUIVALENT \\ --TrainCTLearnModel.n_epochs 5 \\ - --TrainCTLearnModel.batch_size 32""", + --TrainCTLearnModel.batch_size 16""", shell=True, check=True, ) @@ -348,7 +348,7 @@ def find_config_dir(): --reco type \\ --DLImageReader.focal_length_choice EQUIVALENT \\ --TrainCTLearnModel.n_epochs 5 \\ - --TrainCTLearnModel.batch_size 32""", + --TrainCTLearnModel.batch_size 16""", shell=True, check=True, ) @@ -365,7 +365,7 @@ def find_config_dir(): --reco type \\ --DLImageReader.focal_length_choice EQUIVALENT \\ --TrainCTLearnModel.n_epochs 5 \\ - --TrainCTLearnModel.batch_size 32""", + --TrainCTLearnModel.batch_size 16""", shell=True, check=True, ) @@ -403,7 +403,8 @@ def find_config_dir(): --config "$CTLEARN_TUTORIAL_CONFIG_DIR/ctlearn_models_example_config.json" \\ --reco energy \\ --DLImageReader.focal_length_choice EQUIVALENT \\ - --TrainCTLearnModel.model_type SingleCNN""", + --TrainCTLearnModel.model_type SingleCNN \\ + --TrainCTLearnModel.batch_size 16""", shell=True, check=True, ) @@ -418,7 +419,8 @@ def find_config_dir(): --config "$CTLEARN_TUTORIAL_CONFIG_DIR/ctlearn_models_example_config.json" \\ --reco energy \\ --DLImageReader.focal_length_choice EQUIVALENT \\ - --TrainCTLearnModel.model_type SingleCNN""", + --TrainCTLearnModel.model_type SingleCNN \\ + --TrainCTLearnModel.batch_size 16""", shell=True, check=True, ) @@ -507,7 +509,8 @@ def find_config_dir(): --DLImageReader.focal_length_choice EQUIVALENT \\ --TrainCTLearnModel.model_type LoadedModel \\ --LoadedModel.load_model_from "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-singlecnn-energy/ctlearn_model.keras" \\ - --TrainCTLearnModel.n_epochs 2""", + --TrainCTLearnModel.n_epochs 2 \\ + --TrainCTLearnModel.batch_size 16""", shell=True, check=True, ) @@ -524,7 +527,8 @@ def find_config_dir(): --DLImageReader.focal_length_choice EQUIVALENT \\ --TrainCTLearnModel.model_type LoadedModel \\ --PyTorchLoadedModel.load_model_from "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-singlecnn-energy/ctlearn_model.pt" \\ - --TrainCTLearnModel.n_epochs 2""", + --TrainCTLearnModel.n_epochs 2 \\ + --TrainCTLearnModel.batch_size 16""", shell=True, check=True, ) @@ -571,7 +575,7 @@ def find_config_dir(): --DLImageReader.min_telescopes 2 \\ --TrainCTLearnModel.stack_telescope_images True \\ --TrainCTLearnModel.n_epochs 5 \\ - --TrainCTLearnModel.batch_size 16""", + --TrainCTLearnModel.batch_size 8""", shell=True, check=True, ) @@ -588,7 +592,7 @@ def find_config_dir(): --DLImageReader.min_telescopes 2 \\ --TrainCTLearnModel.stack_telescope_images True \\ --TrainCTLearnModel.n_epochs 5 \\ - --TrainCTLearnModel.batch_size 16""", + --TrainCTLearnModel.batch_size 8""", shell=True, check=True, ) From 661296ec66c7259eccc3820d6b039e3c0a13a98e Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Mon, 9 Nov 2026 11:44:53 +0100 Subject: [PATCH 15/53] fix label for docs only to not execute all CI jobs --- docs/source/tutorials.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/tutorials.rst b/docs/source/tutorials.rst index b6424771..a4f9958d 100644 --- a/docs/source/tutorials.rst +++ b/docs/source/tutorials.rst @@ -13,7 +13,7 @@ files require about 3.5 GB of disk space. Downloaded and converted files are reused on subsequent runs. By default, data are stored under ``~/.cache/ctlearn/tutorial-data``; set ``CTLEARN_TUTORIAL_DATA_DIR`` to use a different directory. The CI workflow preloads the source files, caches the -converted products, and limits processing to 100 events per input file to keep +converted products, and limits processing to 1000 events per input file to keep the documentation build bounded. Running the tutorial locally without that environment variable processes the full files. The CI build executes the tutorial and embeds its output; successful builds from pushes to ``main`` are From e8a64f89cd2323bc813861c81fb4b811b1e8f7ba Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Mon, 9 Nov 2026 11:45:53 +0100 Subject: [PATCH 16/53] fix docs label --- .github/workflows/ci.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ae43ab81..ab61e391 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -12,6 +12,9 @@ on: jobs: lint: + if: >- + github.event_name != 'pull_request' || + !contains(github.event.pull_request.labels.*.name, 'documentation-only') runs-on: ubuntu-24.04 steps: - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 From a0d1775745856031ad96c3050a8eaf76894113bd Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Mon, 9 Nov 2026 12:03:41 +0100 Subject: [PATCH 17/53] increase further the stats --- .github/workflows/ci.yml | 2 +- docs/source/tutorials.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ab61e391..7b20ad60 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -151,7 +151,7 @@ jobs: - name: Build documentation and execute tutorials env: - CTLEARN_TUTORIAL_MAX_EVENTS: "1000" + CTLEARN_TUTORIAL_MAX_EVENTS: "10000" run: python -m sphinx -b html --keep-going docs/source docs/build/html - name: Upload rendered documentation for review diff --git a/docs/source/tutorials.rst b/docs/source/tutorials.rst index a4f9958d..3ca73ac0 100644 --- a/docs/source/tutorials.rst +++ b/docs/source/tutorials.rst @@ -13,7 +13,7 @@ files require about 3.5 GB of disk space. Downloaded and converted files are reused on subsequent runs. By default, data are stored under ``~/.cache/ctlearn/tutorial-data``; set ``CTLEARN_TUTORIAL_DATA_DIR`` to use a different directory. The CI workflow preloads the source files, caches the -converted products, and limits processing to 1000 events per input file to keep +converted products, and limits processing to 10000 events per input file to keep the documentation build bounded. Running the tutorial locally without that environment variable processes the full files. The CI build executes the tutorial and embeds its output; successful builds from pushes to ``main`` are From f1a434533593406620d2bdfa30a93484416d6ce1 Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Mon, 9 Nov 2026 12:45:50 +0100 Subject: [PATCH 18/53] increase stats and reduce batch size further --- .github/workflows/ci.yml | 4 +-- docs/source/tutorials.rst | 2 +- examples/tutorials/train_ctlearn_model.py | 32 +++++++++++------------ 3 files changed, 19 insertions(+), 19 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 7b20ad60..2406f249 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -144,14 +144,14 @@ jobs: uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 with: path: | - ~/.cache/ctlearn/tutorial-data/gamma_prod5-max100.r1.dl1.h5 + ~/.cache/ctlearn/tutorial-data/gamma_prod5-max25000.r1.dl1.h5 ~/.cache/ctlearn/tutorial-data/ctapipe-* key: >- ctlearn-tutorial-processed-${{ runner.os }}-${{ steps.ctapipe-version.outputs.version }}-${{ hashFiles('examples/tutorials/explore_public_data.py', 'docs/requirements.txt', 'pyproject.toml') }} - name: Build documentation and execute tutorials env: - CTLEARN_TUTORIAL_MAX_EVENTS: "10000" + CTLEARN_TUTORIAL_MAX_EVENTS: "25000" run: python -m sphinx -b html --keep-going docs/source docs/build/html - name: Upload rendered documentation for review diff --git a/docs/source/tutorials.rst b/docs/source/tutorials.rst index 3ca73ac0..2aed12be 100644 --- a/docs/source/tutorials.rst +++ b/docs/source/tutorials.rst @@ -13,7 +13,7 @@ files require about 3.5 GB of disk space. Downloaded and converted files are reused on subsequent runs. By default, data are stored under ``~/.cache/ctlearn/tutorial-data``; set ``CTLEARN_TUTORIAL_DATA_DIR`` to use a different directory. The CI workflow preloads the source files, caches the -converted products, and limits processing to 10000 events per input file to keep +converted products, and limits processing to 25000 events per input file to keep the documentation build bounded. Running the tutorial locally without that environment variable processes the full files. The CI build executes the tutorial and embeds its output; successful builds from pushes to ``main`` are diff --git a/examples/tutorials/train_ctlearn_model.py b/examples/tutorials/train_ctlearn_model.py index fb1a2672..f1bf2a03 100644 --- a/examples/tutorials/train_ctlearn_model.py +++ b/examples/tutorials/train_ctlearn_model.py @@ -208,7 +208,7 @@ def find_config_dir(): --reco energy \\ --DLImageReader.focal_length_choice EQUIVALENT \\ --TrainCTLearnModel.n_epochs 10 \\ - --TrainCTLearnModel.batch_size 16""", + --TrainCTLearnModel.batch_size 4""", shell=True, check=True, ) @@ -223,7 +223,7 @@ def find_config_dir(): --reco energy \\ --DLImageReader.focal_length_choice EQUIVALENT \\ --TrainCTLearnModel.n_epochs 10 \\ - --TrainCTLearnModel.batch_size 16""", + --TrainCTLearnModel.batch_size 4""", shell=True, check=True, ) @@ -254,7 +254,7 @@ def find_config_dir(): --reco cameradirection \\ --DLImageReader.focal_length_choice EQUIVALENT \\ --TrainCTLearnModel.n_epochs 5 \\ - --TrainCTLearnModel.batch_size 16""", + --TrainCTLearnModel.batch_size 4""", shell=True, check=True, ) @@ -269,7 +269,7 @@ def find_config_dir(): --reco cameradirection \\ --DLImageReader.focal_length_choice EQUIVALENT \\ --TrainCTLearnModel.n_epochs 5 \\ - --TrainCTLearnModel.batch_size 16""", + --TrainCTLearnModel.batch_size 4""", shell=True, check=True, ) @@ -285,7 +285,7 @@ def find_config_dir(): --reco skydirection \\ --DLImageReader.focal_length_choice EQUIVALENT \\ --TrainCTLearnModel.n_epochs 5 \\ - --TrainCTLearnModel.batch_size 16""", + --TrainCTLearnModel.batch_size 4""", shell=True, check=True, ) @@ -300,7 +300,7 @@ def find_config_dir(): --reco skydirection \\ --DLImageReader.focal_length_choice EQUIVALENT \\ --TrainCTLearnModel.n_epochs 5 \\ - --TrainCTLearnModel.batch_size 16""", + --TrainCTLearnModel.batch_size 4""", shell=True, check=True, ) @@ -348,7 +348,7 @@ def find_config_dir(): --reco type \\ --DLImageReader.focal_length_choice EQUIVALENT \\ --TrainCTLearnModel.n_epochs 5 \\ - --TrainCTLearnModel.batch_size 16""", + --TrainCTLearnModel.batch_size 4""", shell=True, check=True, ) @@ -365,7 +365,7 @@ def find_config_dir(): --reco type \\ --DLImageReader.focal_length_choice EQUIVALENT \\ --TrainCTLearnModel.n_epochs 5 \\ - --TrainCTLearnModel.batch_size 16""", + --TrainCTLearnModel.batch_size 4""", shell=True, check=True, ) @@ -404,7 +404,7 @@ def find_config_dir(): --reco energy \\ --DLImageReader.focal_length_choice EQUIVALENT \\ --TrainCTLearnModel.model_type SingleCNN \\ - --TrainCTLearnModel.batch_size 16""", + --TrainCTLearnModel.batch_size 4""", shell=True, check=True, ) @@ -420,7 +420,7 @@ def find_config_dir(): --reco energy \\ --DLImageReader.focal_length_choice EQUIVALENT \\ --TrainCTLearnModel.model_type SingleCNN \\ - --TrainCTLearnModel.batch_size 16""", + --TrainCTLearnModel.batch_size 4""", shell=True, check=True, ) @@ -454,7 +454,7 @@ def find_config_dir(): --DLImageReader.focal_length_choice EQUIVALENT \\ --TrainCTLearnModel.model_type ResNet \\ --TrainCTLearnModel.n_epochs 2 \\ - --TrainCTLearnModel.batch_size 16""", + --TrainCTLearnModel.batch_size 4""", shell=True, check=True, ) @@ -471,7 +471,7 @@ def find_config_dir(): --DLImageReader.focal_length_choice EQUIVALENT \\ --TrainCTLearnModel.model_type ResNet \\ --TrainCTLearnModel.n_epochs 2 \\ - --TrainCTLearnModel.batch_size 16""", + --TrainCTLearnModel.batch_size 4""", shell=True, check=True, ) @@ -510,7 +510,7 @@ def find_config_dir(): --TrainCTLearnModel.model_type LoadedModel \\ --LoadedModel.load_model_from "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-singlecnn-energy/ctlearn_model.keras" \\ --TrainCTLearnModel.n_epochs 2 \\ - --TrainCTLearnModel.batch_size 16""", + --TrainCTLearnModel.batch_size 4""", shell=True, check=True, ) @@ -528,7 +528,7 @@ def find_config_dir(): --TrainCTLearnModel.model_type LoadedModel \\ --PyTorchLoadedModel.load_model_from "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-singlecnn-energy/ctlearn_model.pt" \\ --TrainCTLearnModel.n_epochs 2 \\ - --TrainCTLearnModel.batch_size 16""", + --TrainCTLearnModel.batch_size 4""", shell=True, check=True, ) @@ -575,7 +575,7 @@ def find_config_dir(): --DLImageReader.min_telescopes 2 \\ --TrainCTLearnModel.stack_telescope_images True \\ --TrainCTLearnModel.n_epochs 5 \\ - --TrainCTLearnModel.batch_size 8""", + --TrainCTLearnModel.batch_size 2""", shell=True, check=True, ) @@ -592,7 +592,7 @@ def find_config_dir(): --DLImageReader.min_telescopes 2 \\ --TrainCTLearnModel.stack_telescope_images True \\ --TrainCTLearnModel.n_epochs 5 \\ - --TrainCTLearnModel.batch_size 8""", + --TrainCTLearnModel.batch_size 2""", shell=True, check=True, ) From bd6fbb95dbc32c130099fe219b5840403d5e4b28 Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Mon, 9 Nov 2026 12:48:12 +0100 Subject: [PATCH 19/53] fix docs only label --- .github/workflows/ci.yml | 3 --- 1 file changed, 3 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2406f249..3a47e500 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -12,9 +12,6 @@ on: jobs: lint: - if: >- - github.event_name != 'pull_request' || - !contains(github.event.pull_request.labels.*.name, 'documentation-only') runs-on: ubuntu-24.04 steps: - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 From a92eb46bf966a341f1305448ae79a03215d48d67 Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Mon, 9 Nov 2026 13:24:42 +0100 Subject: [PATCH 20/53] added a section for plotting the training curves and fixing the pt -> pth suffix for pytorch transfer learning models reduce the stats since it is too long in the CI --- .github/workflows/ci.yml | 4 +- examples/tutorials/train_ctlearn_model.py | 142 ++++++++++++++++++++-- 2 files changed, 132 insertions(+), 14 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3a47e500..d7e037db 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -141,14 +141,14 @@ jobs: uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 with: path: | - ~/.cache/ctlearn/tutorial-data/gamma_prod5-max25000.r1.dl1.h5 + ~/.cache/ctlearn/tutorial-data/gamma_prod5-max10000.r1.dl1.h5 ~/.cache/ctlearn/tutorial-data/ctapipe-* key: >- ctlearn-tutorial-processed-${{ runner.os }}-${{ steps.ctapipe-version.outputs.version }}-${{ hashFiles('examples/tutorials/explore_public_data.py', 'docs/requirements.txt', 'pyproject.toml') }} - name: Build documentation and execute tutorials env: - CTLEARN_TUTORIAL_MAX_EVENTS: "25000" + CTLEARN_TUTORIAL_MAX_EVENTS: "10000" run: python -m sphinx -b html --keep-going docs/source docs/build/html - name: Upload rendered documentation for review diff --git a/examples/tutorials/train_ctlearn_model.py b/examples/tutorials/train_ctlearn_model.py index f1bf2a03..0337413c 100644 --- a/examples/tutorials/train_ctlearn_model.py +++ b/examples/tutorials/train_ctlearn_model.py @@ -24,6 +24,8 @@ from pathlib import Path from ctapipe import __version__ as ctapipe_version +import matplotlib.pyplot as plt +import pandas as pd MAX_EVENTS = os.environ.get("CTLEARN_TUTORIAL_MAX_EVENTS") if MAX_EVENTS is not None and int(MAX_EVENTS) < 1: @@ -526,7 +528,7 @@ def find_config_dir(): --reco energy \\ --DLImageReader.focal_length_choice EQUIVALENT \\ --TrainCTLearnModel.model_type LoadedModel \\ - --PyTorchLoadedModel.load_model_from "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-singlecnn-energy/ctlearn_model.pt" \\ + --PyTorchLoadedModel.load_model_from "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-singlecnn-energy/ctlearn_model.pth" \\ --TrainCTLearnModel.n_epochs 2 \\ --TrainCTLearnModel.batch_size 4""", shell=True, @@ -661,20 +663,136 @@ def find_config_dir(): check=True, ) +###################################################################### +# Comparing training curves +# ------------------------- +# +# Each training run writes its metrics to ``training_log.csv``. Compare the +# baseline energy, direction, and classification runs below. Camera and sky +# direction errors use different units, so they share a panel but have +# separate y-axes. The figure is also saved in the training output directory. + +training_logs = {} +for run_name in ( + "keras-energy", + "pytorch-energy", + "keras-cameradirection", + "pytorch-cameradirection", + "keras-skydirection", + "pytorch-skydirection", + "keras-classification", + "pytorch-classification", +): + log_path = OUTPUT_DIR / run_name / "training_log.csv" + if not log_path.is_file(): + raise FileNotFoundError(f"Training log is missing: {log_path}") + training_logs[run_name] = pd.read_csv(log_path) + +frameworks = ( + ("Keras", "keras", "tab:blue"), + ("PyTorch", "pytorch", "tab:orange"), +) +splits = (("", "train", "-"), ("val_", "validation", "--")) + + +def plot_metric(ax, run_name, metric, label, color, **kwargs): + log = training_logs[run_name] + for prefix, split_name, split_style in splits: + column = f"{prefix}{metric}" + if column not in log: + raise ValueError(f"Column {column!r} is missing from {run_name}/training_log.csv") + ax.plot( + log["epoch"] + 1, + log[column], + color=color, + linestyle=split_style, + label=f"{label} - {split_name}", + **kwargs, + ) + + +fig, (energy_ax, direction_ax, type_ax) = plt.subplots( + 1, 3, figsize=(19, 6), constrained_layout=True +) +fig.suptitle("CTLearn training curves", fontsize=16) + +for display_name, framework, color in frameworks: + plot_metric( + energy_ax, + f"{framework}-energy", + "mae_energy", + display_name, + color, + marker="o", + ) +energy_ax.set_title("Energy") +energy_ax.set_xlabel("Epoch") +energy_ax.set_ylabel("Mean absolute error") +energy_ax.grid(True, alpha=0.3) +energy_ax.legend(fontsize=8) + +sky_ax = direction_ax.twinx() +for display_name, framework, color in frameworks: + plot_metric( + direction_ax, + f"{framework}-cameradirection", + "mae_cameradirection", + f"{display_name} camera", + color, + marker="o", + ) + plot_metric( + sky_ax, + f"{framework}-skydirection", + "mae_skydirection", + f"{display_name} sky", + color, + marker="s", + ) +direction_ax.set_title("Direction") +direction_ax.set_xlabel("Epoch") +direction_ax.set_ylabel("Camera direction MAE [m]") +sky_ax.set_ylabel("Sky direction MAE [deg]") +direction_ax.grid(True, alpha=0.3) +direction_ax.legend(loc="upper left", title="Camera", fontsize=8) +sky_ax.legend(loc="upper right", title="Sky", fontsize=8) + +for display_name, framework, color in frameworks: + for metric, marker in (("accuracy", "o"), ("auc", "s")): + plot_metric( + type_ax, + f"{framework}-classification", + metric, + f"{display_name} {metric}", + color, + marker=marker, + ) +type_ax.set_title("Particle type") +type_ax.set_xlabel("Epoch") +type_ax.set_ylabel("Score") +type_ax.set_ylim(0, 1) +type_ax.grid(True, alpha=0.3) +type_ax.legend(fontsize=8, ncol=2) + +training_curves_path = OUTPUT_DIR / "training-curves.png" +fig.savefig(training_curves_path, dpi=350) +print(f"\nTraining curves saved to {training_curves_path}") +plt.show() + ###################################################################### # Monitoring training with TensorBoard # ------------------------------------ # -# TensorBoard can be used to monitor the training process live. CTLearn -# writes training metrics to the output directory, which can then be -# visualized with TensorBoard. Once started, TensorBoard provides an -# interactive web interface where metrics such as loss, accuracy, and AUC -# can be monitored over the course of training. This is useful for checking -# the training progress and identifying issues such as overfitting or -# unstable training. The command can also be run directly from a terminal -# or on a remote/cluster environment, where the TensorBoard web interface -# can be accessed through the appropriate port forwarding. +# CTLearn also writes TensorBoard event files, which are useful for monitoring +# metrics live or exploring additional details after training. The tutorial +# does not launch TensorBoard; to monitor a run while it is training, start it +# in a separate terminal and point it at the tutorial output directory: +# +# .. code-block:: console # -# Start TensorBoard in a separate terminal to compare the completed runs: +# tensorboard --logdir "$HOME/.cache/ctlearn/tutorial-training/" # -# ``tensorboard --logdir ~/.cache/ctlearn/tutorial-training/`` +# Open the URL printed by TensorBoard in a browser. If you set +# ``CTLEARN_TUTORIAL_OUTPUT_DIR`` to a different location, use that directory +# in the command instead. On a remote or cluster environment, use the +# appropriate port forwarding to access the TensorBoard web interface. From 9c243911cca0628a63d424d787ced6134037676f Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Mon, 9 Nov 2026 13:25:29 +0100 Subject: [PATCH 21/53] fix pre-commit hooks --- examples/tutorials/train_ctlearn_model.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/examples/tutorials/train_ctlearn_model.py b/examples/tutorials/train_ctlearn_model.py index 0337413c..518105f5 100644 --- a/examples/tutorials/train_ctlearn_model.py +++ b/examples/tutorials/train_ctlearn_model.py @@ -23,9 +23,9 @@ import subprocess from pathlib import Path -from ctapipe import __version__ as ctapipe_version import matplotlib.pyplot as plt import pandas as pd +from ctapipe import __version__ as ctapipe_version MAX_EVENTS = os.environ.get("CTLEARN_TUTORIAL_MAX_EVENTS") if MAX_EVENTS is not None and int(MAX_EVENTS) < 1: @@ -700,7 +700,9 @@ def plot_metric(ax, run_name, metric, label, color, **kwargs): for prefix, split_name, split_style in splits: column = f"{prefix}{metric}" if column not in log: - raise ValueError(f"Column {column!r} is missing from {run_name}/training_log.csv") + raise ValueError( + f"Column {column!r} is missing from {run_name}/training_log.csv" + ) ax.plot( log["epoch"] + 1, log[column], From a0078b265ac8eb3b480dafec01d3faa00c79ebcc Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Mon, 9 Nov 2026 14:18:03 +0100 Subject: [PATCH 22/53] move back to more stats to run tutorial properly --- .github/workflows/ci.yml | 4 ++-- examples/tutorials/explore_public_data.py | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d7e037db..3a47e500 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -141,14 +141,14 @@ jobs: uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 with: path: | - ~/.cache/ctlearn/tutorial-data/gamma_prod5-max10000.r1.dl1.h5 + ~/.cache/ctlearn/tutorial-data/gamma_prod5-max25000.r1.dl1.h5 ~/.cache/ctlearn/tutorial-data/ctapipe-* key: >- ctlearn-tutorial-processed-${{ runner.os }}-${{ steps.ctapipe-version.outputs.version }}-${{ hashFiles('examples/tutorials/explore_public_data.py', 'docs/requirements.txt', 'pyproject.toml') }} - name: Build documentation and execute tutorials env: - CTLEARN_TUTORIAL_MAX_EVENTS: "10000" + CTLEARN_TUTORIAL_MAX_EVENTS: "25000" run: python -m sphinx -b html --keep-going docs/source docs/build/html - name: Upload rendered documentation for review diff --git a/examples/tutorials/explore_public_data.py b/examples/tutorials/explore_public_data.py index a91bb387..13f166b8 100644 --- a/examples/tutorials/explore_public_data.py +++ b/examples/tutorials/explore_public_data.py @@ -40,7 +40,7 @@ # # By default, the tutorial processes all events. To speed up a test run, # set ``CTLEARN_TUTORIAL_MAX_EVENTS`` to a positive integer before running -# this script, for example ``CTLEARN_TUTORIAL_MAX_EVENTS=100``. The limit +# this script, for example ``CTLEARN_TUTORIAL_MAX_EVENTS=25000``. The limit # applies to each input file. Leave the variable unset to process all events. plt.style.use("ggplot") From 8dc38501efc3fad6ed039dc50607159a6a1350d9 Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Mon, 9 Nov 2026 15:20:31 +0100 Subject: [PATCH 23/53] use normal size cuts in example config; reduce stats --- .github/workflows/ci.yml | 4 ++-- docs/source/config/dl1dh_example_config.json | 2 +- docs/source/tutorials.rst | 2 +- examples/tutorials/explore_public_data.py | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3a47e500..987f6914 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -141,14 +141,14 @@ jobs: uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 with: path: | - ~/.cache/ctlearn/tutorial-data/gamma_prod5-max25000.r1.dl1.h5 + ~/.cache/ctlearn/tutorial-data/gamma_prod5-max100.r1.dl1.h5 ~/.cache/ctlearn/tutorial-data/ctapipe-* key: >- ctlearn-tutorial-processed-${{ runner.os }}-${{ steps.ctapipe-version.outputs.version }}-${{ hashFiles('examples/tutorials/explore_public_data.py', 'docs/requirements.txt', 'pyproject.toml') }} - name: Build documentation and execute tutorials env: - CTLEARN_TUTORIAL_MAX_EVENTS: "25000" + CTLEARN_TUTORIAL_MAX_EVENTS: "100" run: python -m sphinx -b html --keep-going docs/source docs/build/html - name: Upload rendered documentation for review diff --git a/docs/source/config/dl1dh_example_config.json b/docs/source/config/dl1dh_example_config.json index 7adf5270..49f56e0d 100644 --- a/docs/source/config/dl1dh_example_config.json +++ b/docs/source/config/dl1dh_example_config.json @@ -1,7 +1,7 @@ { "TableQualityQuery": { "quality_criteria": [ - ["> 50000 phe", "hillas_intensity > 50000"] + ["> 50 phe", "hillas_intensity > 50"] ] }, "DLImageReader": { diff --git a/docs/source/tutorials.rst b/docs/source/tutorials.rst index 2aed12be..b6424771 100644 --- a/docs/source/tutorials.rst +++ b/docs/source/tutorials.rst @@ -13,7 +13,7 @@ files require about 3.5 GB of disk space. Downloaded and converted files are reused on subsequent runs. By default, data are stored under ``~/.cache/ctlearn/tutorial-data``; set ``CTLEARN_TUTORIAL_DATA_DIR`` to use a different directory. The CI workflow preloads the source files, caches the -converted products, and limits processing to 25000 events per input file to keep +converted products, and limits processing to 100 events per input file to keep the documentation build bounded. Running the tutorial locally without that environment variable processes the full files. The CI build executes the tutorial and embeds its output; successful builds from pushes to ``main`` are diff --git a/examples/tutorials/explore_public_data.py b/examples/tutorials/explore_public_data.py index 13f166b8..a91bb387 100644 --- a/examples/tutorials/explore_public_data.py +++ b/examples/tutorials/explore_public_data.py @@ -40,7 +40,7 @@ # # By default, the tutorial processes all events. To speed up a test run, # set ``CTLEARN_TUTORIAL_MAX_EVENTS`` to a positive integer before running -# this script, for example ``CTLEARN_TUTORIAL_MAX_EVENTS=25000``. The limit +# this script, for example ``CTLEARN_TUTORIAL_MAX_EVENTS=100``. The limit # applies to each input file. Leave the variable unset to process all events. plt.style.use("ggplot") From 74735245448633dd91d585bb9fb0205d331cbe08 Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Mon, 9 Nov 2026 16:34:05 +0100 Subject: [PATCH 24/53] fixs docs --- .github/workflows/ci.yml | 6 +++--- docs/source/tutorials.rst | 2 +- examples/tutorials/explore_public_data.py | 2 +- examples/tutorials/train_ctlearn_model.py | 6 ++++-- 4 files changed, 9 insertions(+), 7 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 987f6914..14ebbede 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -141,14 +141,14 @@ jobs: uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 with: path: | - ~/.cache/ctlearn/tutorial-data/gamma_prod5-max100.r1.dl1.h5 + ~/.cache/ctlearn/tutorial-data/gamma_prod5-max500.r1.dl1.h5 ~/.cache/ctlearn/tutorial-data/ctapipe-* key: >- - ctlearn-tutorial-processed-${{ runner.os }}-${{ steps.ctapipe-version.outputs.version }}-${{ hashFiles('examples/tutorials/explore_public_data.py', 'docs/requirements.txt', 'pyproject.toml') }} + ctlearn-tutorial-processed-${{ runner.os }}-v2-max500-${{ steps.ctapipe-version.outputs.version }}-${{ hashFiles('examples/tutorials/explore_public_data.py', 'docs/requirements.txt', 'pyproject.toml') }} - name: Build documentation and execute tutorials env: - CTLEARN_TUTORIAL_MAX_EVENTS: "100" + CTLEARN_TUTORIAL_MAX_EVENTS: "500" run: python -m sphinx -b html --keep-going docs/source docs/build/html - name: Upload rendered documentation for review diff --git a/docs/source/tutorials.rst b/docs/source/tutorials.rst index b6424771..6759f427 100644 --- a/docs/source/tutorials.rst +++ b/docs/source/tutorials.rst @@ -13,7 +13,7 @@ files require about 3.5 GB of disk space. Downloaded and converted files are reused on subsequent runs. By default, data are stored under ``~/.cache/ctlearn/tutorial-data``; set ``CTLEARN_TUTORIAL_DATA_DIR`` to use a different directory. The CI workflow preloads the source files, caches the -converted products, and limits processing to 100 events per input file to keep +converted products, and limits processing to 500 events per input file to keep the documentation build bounded. Running the tutorial locally without that environment variable processes the full files. The CI build executes the tutorial and embeds its output; successful builds from pushes to ``main`` are diff --git a/examples/tutorials/explore_public_data.py b/examples/tutorials/explore_public_data.py index a91bb387..4f6736c6 100644 --- a/examples/tutorials/explore_public_data.py +++ b/examples/tutorials/explore_public_data.py @@ -40,7 +40,7 @@ # # By default, the tutorial processes all events. To speed up a test run, # set ``CTLEARN_TUTORIAL_MAX_EVENTS`` to a positive integer before running -# this script, for example ``CTLEARN_TUTORIAL_MAX_EVENTS=100``. The limit +# this script, for example ``CTLEARN_TUTORIAL_MAX_EVENTS=500``. The limit # applies to each input file. Leave the variable unset to process all events. plt.style.use("ggplot") diff --git a/examples/tutorials/train_ctlearn_model.py b/examples/tutorials/train_ctlearn_model.py index 518105f5..ed6f32b0 100644 --- a/examples/tutorials/train_ctlearn_model.py +++ b/examples/tutorials/train_ctlearn_model.py @@ -577,7 +577,8 @@ def find_config_dir(): --DLImageReader.min_telescopes 2 \\ --TrainCTLearnModel.stack_telescope_images True \\ --TrainCTLearnModel.n_epochs 5 \\ - --TrainCTLearnModel.batch_size 2""", + --TrainCTLearnModel.batch_size 2 \\ + --TableQualityQuery.quality_criteria []""", shell=True, check=True, ) @@ -594,7 +595,8 @@ def find_config_dir(): --DLImageReader.min_telescopes 2 \\ --TrainCTLearnModel.stack_telescope_images True \\ --TrainCTLearnModel.n_epochs 5 \\ - --TrainCTLearnModel.batch_size 2""", + --TrainCTLearnModel.batch_size 2 \\ + --TableQualityQuery.quality_criteria []""", shell=True, check=True, ) From baa440884567661ca1567d2ecfa144438a737f1c Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Mon, 9 Nov 2026 17:56:08 +0100 Subject: [PATCH 25/53] speed up doc building --- docs/source/config/dl1dh_example_config.json | 2 +- examples/tutorials/train_ctlearn_model.py | 44 +++++++++++--------- 2 files changed, 25 insertions(+), 21 deletions(-) diff --git a/docs/source/config/dl1dh_example_config.json b/docs/source/config/dl1dh_example_config.json index 49f56e0d..0994644c 100644 --- a/docs/source/config/dl1dh_example_config.json +++ b/docs/source/config/dl1dh_example_config.json @@ -1,7 +1,7 @@ { "TableQualityQuery": { "quality_criteria": [ - ["> 50 phe", "hillas_intensity > 50"] + ["> 1000 phe", "hillas_intensity > 1000"] ] }, "DLImageReader": { diff --git a/examples/tutorials/train_ctlearn_model.py b/examples/tutorials/train_ctlearn_model.py index ed6f32b0..8c04ef55 100644 --- a/examples/tutorials/train_ctlearn_model.py +++ b/examples/tutorials/train_ctlearn_model.py @@ -209,7 +209,7 @@ def find_config_dir(): --config "$CTLEARN_TUTORIAL_CONFIG_DIR/ctlearn_train_model_example_config.json" \\ --reco energy \\ --DLImageReader.focal_length_choice EQUIVALENT \\ - --TrainCTLearnModel.n_epochs 10 \\ + --TrainCTLearnModel.n_epochs 5 \\ --TrainCTLearnModel.batch_size 4""", shell=True, check=True, @@ -224,7 +224,7 @@ def find_config_dir(): --config "$CTLEARN_TUTORIAL_CONFIG_DIR/ctlearn_train_model_example_config.json" \\ --reco energy \\ --DLImageReader.focal_length_choice EQUIVALENT \\ - --TrainCTLearnModel.n_epochs 10 \\ + --TrainCTLearnModel.n_epochs 5 \\ --TrainCTLearnModel.batch_size 4""", shell=True, check=True, @@ -349,7 +349,7 @@ def find_config_dir(): --config "$CTLEARN_TUTORIAL_CONFIG_DIR/ctlearn_train_model_example_config.json" \\ --reco type \\ --DLImageReader.focal_length_choice EQUIVALENT \\ - --TrainCTLearnModel.n_epochs 5 \\ + --TrainCTLearnModel.n_epochs 3 \\ --TrainCTLearnModel.batch_size 4""", shell=True, check=True, @@ -366,7 +366,7 @@ def find_config_dir(): --config "$CTLEARN_TUTORIAL_CONFIG_DIR/ctlearn_train_model_example_config.json" \\ --reco type \\ --DLImageReader.focal_length_choice EQUIVALENT \\ - --TrainCTLearnModel.n_epochs 5 \\ + --TrainCTLearnModel.n_epochs 3 \\ --TrainCTLearnModel.batch_size 4""", shell=True, check=True, @@ -406,6 +406,7 @@ def find_config_dir(): --reco energy \\ --DLImageReader.focal_length_choice EQUIVALENT \\ --TrainCTLearnModel.model_type SingleCNN \\ + --TrainCTLearnModel.n_epochs 2 \\ --TrainCTLearnModel.batch_size 4""", shell=True, check=True, @@ -422,6 +423,7 @@ def find_config_dir(): --reco energy \\ --DLImageReader.focal_length_choice EQUIVALENT \\ --TrainCTLearnModel.model_type SingleCNN \\ + --TrainCTLearnModel.n_epochs 2 \\ --TrainCTLearnModel.batch_size 4""", shell=True, check=True, @@ -637,7 +639,7 @@ def find_config_dir(): --config "$CTLEARN_TUTORIAL_CONFIG_DIR/ctlearn_train_model_example_config.json" \\ --config "$CTLEARN_TUTORIAL_CONFIG_DIR/dl1dh_example_config.json" \\ --reco energy \\ - --TrainCTLearnModel.n_epochs 5 \\ + --TrainCTLearnModel.n_epochs 2 \\ --TrainCTLearnModel.batch_size 2 \\ --TrainCTLearnModel.validation_split 0.2 \\ --TrainCTLearnModel.dl1dh_reader_type DLWaveformReader \\ @@ -655,7 +657,7 @@ def find_config_dir(): --config "$CTLEARN_TUTORIAL_CONFIG_DIR/ctlearn_train_model_example_config.json" \\ --config "$CTLEARN_TUTORIAL_CONFIG_DIR/dl1dh_example_config.json" \\ --reco energy \\ - --TrainCTLearnModel.n_epochs 5 \\ + --TrainCTLearnModel.n_epochs 2 \\ --TrainCTLearnModel.batch_size 2 \\ --TrainCTLearnModel.validation_split 0.2 \\ --TrainCTLearnModel.dl1dh_reader_type DLWaveformReader \\ @@ -715,8 +717,8 @@ def plot_metric(ax, run_name, metric, label, color, **kwargs): ) -fig, (energy_ax, direction_ax, type_ax) = plt.subplots( - 1, 3, figsize=(19, 6), constrained_layout=True +fig, (energy_ax, camera_ax, sky_ax, type_ax) = plt.subplots( + 1, 4, figsize=(24, 6), constrained_layout=True ) fig.suptitle("CTLearn training curves", fontsize=16) @@ -735,13 +737,12 @@ def plot_metric(ax, run_name, metric, label, color, **kwargs): energy_ax.grid(True, alpha=0.3) energy_ax.legend(fontsize=8) -sky_ax = direction_ax.twinx() for display_name, framework, color in frameworks: plot_metric( - direction_ax, + camera_ax, f"{framework}-cameradirection", "mae_cameradirection", - f"{display_name} camera", + display_name, color, marker="o", ) @@ -749,17 +750,20 @@ def plot_metric(ax, run_name, metric, label, color, **kwargs): sky_ax, f"{framework}-skydirection", "mae_skydirection", - f"{display_name} sky", + display_name, color, marker="s", ) -direction_ax.set_title("Direction") -direction_ax.set_xlabel("Epoch") -direction_ax.set_ylabel("Camera direction MAE [m]") +camera_ax.set_title("Camera direction") +camera_ax.set_xlabel("Epoch") +camera_ax.set_ylabel("Mean absolute error [m]") +camera_ax.grid(True, alpha=0.3) +camera_ax.legend(fontsize=8) +sky_ax.set_title("Sky direction") +sky_ax.set_xlabel("Epoch") sky_ax.set_ylabel("Sky direction MAE [deg]") -direction_ax.grid(True, alpha=0.3) -direction_ax.legend(loc="upper left", title="Camera", fontsize=8) -sky_ax.legend(loc="upper right", title="Sky", fontsize=8) +sky_ax.grid(True, alpha=0.3) +sky_ax.legend(fontsize=8) for display_name, framework, color in frameworks: for metric, marker in (("accuracy", "o"), ("auc", "s")): @@ -774,9 +778,9 @@ def plot_metric(ax, run_name, metric, label, color, **kwargs): type_ax.set_title("Particle type") type_ax.set_xlabel("Epoch") type_ax.set_ylabel("Score") -type_ax.set_ylim(0, 1) +type_ax.set_ylim(0.4, 0.7) type_ax.grid(True, alpha=0.3) -type_ax.legend(fontsize=8, ncol=2) +type_ax.legend(fontsize=6, ncol=2, loc="best") training_curves_path = OUTPUT_DIR / "training-curves.png" fig.savefig(training_curves_path, dpi=350) From 3be3c98487f9fcabb7e24befe36eefc506180098 Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Mon, 9 Nov 2026 17:59:25 +0100 Subject: [PATCH 26/53] enforce explicit order of tutorials --- docs/source/conf.py | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index d99c5bbe..956444a7 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -23,7 +23,7 @@ # Import ctapipe.reco before autodoc mocks torch: it walks all scikit-learn # submodules, and the scikit-learn torch compatibility layer fails on a mock. import ctapipe.reco # noqa: F401 -from sphinx_gallery.sorting import FunctionSortKey +from sphinx_gallery.sorting import ExplicitOrder import ctlearn @@ -39,15 +39,6 @@ release = version -def _tutorial_order(filename): - priority = { - "explore_public_data.py": 0, - "train_ctlearn_model.py": 1, - } - name = os.path.basename(filename) - return priority.get(name, 2), name - - # -- General configuration --------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. @@ -72,7 +63,13 @@ def _tutorial_order(filename): "examples_dirs": "../../examples/tutorials", "gallery_dirs": "auto_tutorials", "filename_pattern": r"(explore_public_data|train_ctlearn_model)\.py$", - "within_subsection_order": FunctionSortKey(_tutorial_order), + "within_subsection_order": ExplicitOrder( + [ + "explore_public_data.py", + "train_ctlearn_model.py", + "*", + ] + ), "plot_gallery": True, "matplotlib_animations": (True, "jshtml"), "abort_on_example_error": True, From d22aba4e824eff960f77f18af38b2b115624ef27 Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Mon, 9 Nov 2026 18:06:33 +0100 Subject: [PATCH 27/53] add disclaimer for non optimal training curves; just for showing the training workflow --- examples/tutorials/train_ctlearn_model.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/examples/tutorials/train_ctlearn_model.py b/examples/tutorials/train_ctlearn_model.py index 8c04ef55..345f600e 100644 --- a/examples/tutorials/train_ctlearn_model.py +++ b/examples/tutorials/train_ctlearn_model.py @@ -675,6 +675,10 @@ def find_config_dir(): # baseline energy, direction, and classification runs below. Camera and sky # direction errors use different units, so they share a panel but have # separate y-axes. The figure is also saved in the training output directory. +# The statistics of the training runs are intentionally very limited, so the +# training curves are not expected to be smooth or to converge to optimal values. +# The purpose of this tutorial is to demonstrate the training workflow and the use +# of CTLearn, rather than to achieve optimal performance on the example dataset. training_logs = {} for run_name in ( From 4f93a2b277cba4ae0af02f76b4455b60b3590ae5 Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Mon, 9 Nov 2026 18:47:54 +0100 Subject: [PATCH 28/53] added verbose --- examples/tutorials/train_ctlearn_model.py | 38 +++++++++++------------ 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/examples/tutorials/train_ctlearn_model.py b/examples/tutorials/train_ctlearn_model.py index 345f600e..900ee214 100644 --- a/examples/tutorials/train_ctlearn_model.py +++ b/examples/tutorials/train_ctlearn_model.py @@ -201,7 +201,7 @@ def find_config_dir(): # scale in TeV. subprocess.run( - """ctlearn-train-keras-model \\ + """ctlearn-train-keras-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-energy" \\ @@ -216,7 +216,7 @@ def find_config_dir(): ) subprocess.run( - """ctlearn-train-pytorch-model \\ + """ctlearn-train-pytorch-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-energy" \\ @@ -247,7 +247,7 @@ def find_config_dir(): # Camera coordinates subprocess.run( - """ctlearn-train-keras-model \\ + """ctlearn-train-keras-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-cameradirection" \\ @@ -262,7 +262,7 @@ def find_config_dir(): ) subprocess.run( - """ctlearn-train-pytorch-model \\ + """ctlearn-train-pytorch-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-cameradirection" \\ @@ -278,7 +278,7 @@ def find_config_dir(): # Sky coordinates subprocess.run( - """ctlearn-train-keras-model \\ + """ctlearn-train-keras-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-skydirection" \\ @@ -293,7 +293,7 @@ def find_config_dir(): ) subprocess.run( - """ctlearn-train-pytorch-model \\ + """ctlearn-train-pytorch-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-skydirection" \\ @@ -339,7 +339,7 @@ def find_config_dir(): # issues arising from class imbalance or other training problems. subprocess.run( - """ctlearn-train-keras-model \\ + """ctlearn-train-keras-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h*" \\ --background "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ @@ -356,7 +356,7 @@ def find_config_dir(): ) subprocess.run( - """ctlearn-train-pytorch-model \\ + """ctlearn-train-pytorch-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h*" \\ --background "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ @@ -396,7 +396,7 @@ def find_config_dir(): # latency, computational efficiency becomes increasingly important. subprocess.run( - """ctlearn-train-keras-model \\ + """ctlearn-train-keras-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-singlecnn-energy" \\ @@ -413,7 +413,7 @@ def find_config_dir(): ) subprocess.run( - """ctlearn-train-pytorch-model \\ + """ctlearn-train-pytorch-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-singlecnn-energy" \\ @@ -447,7 +447,7 @@ def find_config_dir(): # enable deeper networks while controlling the computational cost. subprocess.run( - """ctlearn-train-keras-model \\ + """ctlearn-train-keras-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-resnet-energy" \\ @@ -464,7 +464,7 @@ def find_config_dir(): ) subprocess.run( - """ctlearn-train-pytorch-model \\ + """ctlearn-train-pytorch-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-resnet-energy" \\ @@ -502,7 +502,7 @@ def find_config_dir(): # configuration keeps its prediction head and leaves the backbone trainable. subprocess.run( - """ctlearn-train-keras-model \\ + """ctlearn-train-keras-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-transfer-learning-energy" \\ @@ -520,7 +520,7 @@ def find_config_dir(): ) subprocess.run( - """ctlearn-train-pytorch-model \\ + """ctlearn-train-pytorch-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-transfer-learning-energy" \\ @@ -568,7 +568,7 @@ def find_config_dir(): # consumption. subprocess.run( - """ctlearn-train-keras-model \\ + """ctlearn-train-keras-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-stereo-energy" \\ @@ -586,7 +586,7 @@ def find_config_dir(): ) subprocess.run( - """ctlearn-train-pytorch-model \\ + """ctlearn-train-pytorch-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-stereo-energy" \\ @@ -632,7 +632,7 @@ def find_config_dir(): "Run examples/tutorials/explore_public_data.py first." ) subprocess.run( - """ctlearn-train-keras-model \\ + """ctlearn-train-keras-model --verbose \\ --signal "$CTLEARN_TUTORIAL_DATA_DIR" \\ --pattern-signal "gamma_prod5${CTLEARN_TUTORIAL_MAX_EVENTS_SUFFIX}.r1.dl1.h5" \\ --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-waveform-energy" \\ @@ -650,7 +650,7 @@ def find_config_dir(): ) subprocess.run( - """ctlearn-train-pytorch-model \\ + """ctlearn-train-pytorch-model --verbose \\ --signal "$CTLEARN_TUTORIAL_DATA_DIR" \\ --pattern-signal "gamma_prod5${CTLEARN_TUTORIAL_MAX_EVENTS_SUFFIX}.r1.dl1.h5" \\ --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-waveform-energy" \\ @@ -784,7 +784,7 @@ def plot_metric(ax, run_name, metric, label, color, **kwargs): type_ax.set_ylabel("Score") type_ax.set_ylim(0.4, 0.7) type_ax.grid(True, alpha=0.3) -type_ax.legend(fontsize=6, ncol=2, loc="best") +type_ax.legend(fontsize=8, ncol=2, loc="best") training_curves_path = OUTPUT_DIR / "training-curves.png" fig.savefig(training_curves_path, dpi=350) From 4e522f3ecd86f4527fb9fdc04643b8fe71afa2d3 Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Mon, 9 Nov 2026 19:21:16 +0100 Subject: [PATCH 29/53] added verbose on stdou on the PIPE --- examples/tutorials/train_ctlearn_model.py | 85 +++++++++-------------- 1 file changed, 31 insertions(+), 54 deletions(-) diff --git a/examples/tutorials/train_ctlearn_model.py b/examples/tutorials/train_ctlearn_model.py index 900ee214..bfceee2f 100644 --- a/examples/tutorials/train_ctlearn_model.py +++ b/examples/tutorials/train_ctlearn_model.py @@ -176,6 +176,19 @@ def find_config_dir(): print(f"\nTraining outputs: {OUTPUT_DIR}") + +def run_training_command(command): + result = subprocess.run( + command, + shell=True, + stdout=subprocess.PIPE, + stderr=subprocess.STDOUT, + text=True, + ) + print(result.stdout, end="") + result.check_returncode() + + ###################################################################### # Part A # @@ -200,7 +213,7 @@ def find_config_dir(): # predicted values back from logarithmic space to the original linear energy # scale in TeV. -subprocess.run( +run_training_command( """ctlearn-train-keras-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ @@ -211,11 +224,9 @@ def find_config_dir(): --DLImageReader.focal_length_choice EQUIVALENT \\ --TrainCTLearnModel.n_epochs 5 \\ --TrainCTLearnModel.batch_size 4""", - shell=True, - check=True, ) -subprocess.run( +run_training_command( """ctlearn-train-pytorch-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ @@ -226,8 +237,6 @@ def find_config_dir(): --DLImageReader.focal_length_choice EQUIVALENT \\ --TrainCTLearnModel.n_epochs 5 \\ --TrainCTLearnModel.batch_size 4""", - shell=True, - check=True, ) ###################################################################### @@ -246,7 +255,7 @@ def find_config_dir(): # final direction expressed in degrees. # Camera coordinates -subprocess.run( +run_training_command( """ctlearn-train-keras-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ @@ -257,11 +266,9 @@ def find_config_dir(): --DLImageReader.focal_length_choice EQUIVALENT \\ --TrainCTLearnModel.n_epochs 5 \\ --TrainCTLearnModel.batch_size 4""", - shell=True, - check=True, ) -subprocess.run( +run_training_command( """ctlearn-train-pytorch-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ @@ -272,12 +279,10 @@ def find_config_dir(): --DLImageReader.focal_length_choice EQUIVALENT \\ --TrainCTLearnModel.n_epochs 5 \\ --TrainCTLearnModel.batch_size 4""", - shell=True, - check=True, ) # Sky coordinates -subprocess.run( +run_training_command( """ctlearn-train-keras-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ @@ -288,11 +293,9 @@ def find_config_dir(): --DLImageReader.focal_length_choice EQUIVALENT \\ --TrainCTLearnModel.n_epochs 5 \\ --TrainCTLearnModel.batch_size 4""", - shell=True, - check=True, ) -subprocess.run( +run_training_command( """ctlearn-train-pytorch-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ @@ -303,8 +306,6 @@ def find_config_dir(): --DLImageReader.focal_length_choice EQUIVALENT \\ --TrainCTLearnModel.n_epochs 5 \\ --TrainCTLearnModel.batch_size 4""", - shell=True, - check=True, ) ###################################################################### @@ -338,7 +339,7 @@ def find_config_dir(): # loss, accuracy, and AUC on a per-epoch basis can help identify potential # issues arising from class imbalance or other training problems. -subprocess.run( +run_training_command( """ctlearn-train-keras-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h*" \\ @@ -351,11 +352,9 @@ def find_config_dir(): --DLImageReader.focal_length_choice EQUIVALENT \\ --TrainCTLearnModel.n_epochs 3 \\ --TrainCTLearnModel.batch_size 4""", - shell=True, - check=True, ) -subprocess.run( +run_training_command( """ctlearn-train-pytorch-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h*" \\ @@ -368,8 +367,6 @@ def find_config_dir(): --DLImageReader.focal_length_choice EQUIVALENT \\ --TrainCTLearnModel.n_epochs 3 \\ --TrainCTLearnModel.batch_size 4""", - shell=True, - check=True, ) ###################################################################### @@ -395,7 +392,7 @@ def find_config_dir(): # where predictions need to be made at very high rates and with very low # latency, computational efficiency becomes increasingly important. -subprocess.run( +run_training_command( """ctlearn-train-keras-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ @@ -408,11 +405,9 @@ def find_config_dir(): --TrainCTLearnModel.model_type SingleCNN \\ --TrainCTLearnModel.n_epochs 2 \\ --TrainCTLearnModel.batch_size 4""", - shell=True, - check=True, ) -subprocess.run( +run_training_command( """ctlearn-train-pytorch-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ @@ -425,8 +420,6 @@ def find_config_dir(): --TrainCTLearnModel.model_type SingleCNN \\ --TrainCTLearnModel.n_epochs 2 \\ --TrainCTLearnModel.batch_size 4""", - shell=True, - check=True, ) # @@ -446,7 +439,7 @@ def find_config_dir(): # - Bottleneck blocks, which use a more compact sequence of convolutions to # enable deeper networks while controlling the computational cost. -subprocess.run( +run_training_command( """ctlearn-train-keras-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ @@ -459,11 +452,9 @@ def find_config_dir(): --TrainCTLearnModel.model_type ResNet \\ --TrainCTLearnModel.n_epochs 2 \\ --TrainCTLearnModel.batch_size 4""", - shell=True, - check=True, ) -subprocess.run( +run_training_command( """ctlearn-train-pytorch-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ @@ -476,8 +467,6 @@ def find_config_dir(): --TrainCTLearnModel.model_type ResNet \\ --TrainCTLearnModel.n_epochs 2 \\ --TrainCTLearnModel.batch_size 4""", - shell=True, - check=True, ) ###################################################################### @@ -501,7 +490,7 @@ def find_config_dir(): # The preceding SingleCNN command trains the model loaded below. The copied # configuration keeps its prediction head and leaves the backbone trainable. -subprocess.run( +run_training_command( """ctlearn-train-keras-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ @@ -515,11 +504,9 @@ def find_config_dir(): --LoadedModel.load_model_from "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-singlecnn-energy/ctlearn_model.keras" \\ --TrainCTLearnModel.n_epochs 2 \\ --TrainCTLearnModel.batch_size 4""", - shell=True, - check=True, ) -subprocess.run( +run_training_command( """ctlearn-train-pytorch-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ @@ -533,8 +520,6 @@ def find_config_dir(): --PyTorchLoadedModel.load_model_from "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-singlecnn-energy/ctlearn_model.pth" \\ --TrainCTLearnModel.n_epochs 2 \\ --TrainCTLearnModel.batch_size 4""", - shell=True, - check=True, ) ###################################################################### @@ -567,7 +552,7 @@ def find_config_dir(): # *--TrainCTLearnModel.batch_size* to account for the increased memory # consumption. -subprocess.run( +run_training_command( """ctlearn-train-keras-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ @@ -581,11 +566,9 @@ def find_config_dir(): --TrainCTLearnModel.n_epochs 5 \\ --TrainCTLearnModel.batch_size 2 \\ --TableQualityQuery.quality_criteria []""", - shell=True, - check=True, ) -subprocess.run( +run_training_command( """ctlearn-train-pytorch-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ @@ -599,8 +582,6 @@ def find_config_dir(): --TrainCTLearnModel.n_epochs 5 \\ --TrainCTLearnModel.batch_size 2 \\ --TableQualityQuery.quality_criteria []""", - shell=True, - check=True, ) ###################################################################### @@ -631,7 +612,7 @@ def find_config_dir(): f"Cached waveform data is missing: {WAVEFORM_FILE}. " "Run examples/tutorials/explore_public_data.py first." ) -subprocess.run( +run_training_command( """ctlearn-train-keras-model --verbose \\ --signal "$CTLEARN_TUTORIAL_DATA_DIR" \\ --pattern-signal "gamma_prod5${CTLEARN_TUTORIAL_MAX_EVENTS_SUFFIX}.r1.dl1.h5" \\ @@ -645,11 +626,9 @@ def find_config_dir(): --TrainCTLearnModel.dl1dh_reader_type DLWaveformReader \\ --DLWaveformReader.focal_length_choice EQUIVALENT \\ --TableQualityQuery.quality_criteria []""", - shell=True, - check=True, ) -subprocess.run( +run_training_command( """ctlearn-train-pytorch-model --verbose \\ --signal "$CTLEARN_TUTORIAL_DATA_DIR" \\ --pattern-signal "gamma_prod5${CTLEARN_TUTORIAL_MAX_EVENTS_SUFFIX}.r1.dl1.h5" \\ @@ -663,8 +642,6 @@ def find_config_dir(): --TrainCTLearnModel.dl1dh_reader_type DLWaveformReader \\ --DLWaveformReader.focal_length_choice EQUIVALENT \\ --TableQualityQuery.quality_criteria []""", - shell=True, - check=True, ) ###################################################################### From fccdb651876e0905abf3cadc756cf510d506d904 Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Mon, 9 Nov 2026 19:56:34 +0100 Subject: [PATCH 30/53] Trigger CI From 4699c8cc7a3fc30c9e27a274421537b3363eabb1 Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Mon, 9 Nov 2026 21:24:29 +0100 Subject: [PATCH 31/53] polish some explanations --- examples/tutorials/train_ctlearn_model.py | 56 +++++++++++++---------- 1 file changed, 32 insertions(+), 24 deletions(-) diff --git a/examples/tutorials/train_ctlearn_model.py b/examples/tutorials/train_ctlearn_model.py index bfceee2f..ce20aca9 100644 --- a/examples/tutorials/train_ctlearn_model.py +++ b/examples/tutorials/train_ctlearn_model.py @@ -190,10 +190,8 @@ def run_training_command(command): ###################################################################### -# Part A -# -# Monoscopic CNN-based model training -# ----------------------------------- +# Part A: Monoscopic CNN-based model training +# =========================================== # # We first train a basic monoscopic CNN-based model using the default CTLearn # model configuration. The model uses a **ThinResNet** backbone for feature @@ -370,16 +368,18 @@ def run_training_command(command): ) ###################################################################### -# Part B -# -# Customizing the CTLearn model architecture -# ------------------------------------------ +# Part B: Customizing the CTLearn model architecture +# ================================================== # # CTLearn provides a flexible configuration system that allows users to # customize the neural network architecture. # # Two main CNN-based architectures are currently implemented: **SingleCNN** -# and **ResNet**, which can bet set by *--TrainCTLearnModel.model_type*. +# and **ResNet**, which can be set by *--TrainCTLearnModel.model_type*. + +###################################################################### +# 1. SingleCNN model +# ------------------ # # The **SingleCNN** component implements a plain convolutional neural # network consisting of configurable convolutional layers. It can be used @@ -422,6 +422,9 @@ def run_training_command(command): --TrainCTLearnModel.batch_size 4""", ) +###################################################################### +# 2. ResNet model +# --------------- # # The **ResNet** component provides the currently preferred architecture for # constructing deeper CNN models. Residual networks allow substantially @@ -470,8 +473,8 @@ def run_training_command(command): ) ###################################################################### -# Using a pre-trained model and transfer learning -# ----------------------------------------------- +# Part C: Using a pre-trained model and transfer learning +# ======================================================= # # The LoadedModel component allows a previously trained model following # the CTLearnModel structure to be loaded for either resuming training or @@ -523,8 +526,8 @@ def run_training_command(command): ) ###################################################################### -# Stereoscopic CNN-based model training -# ------------------------------------- +# Part D: Stereoscopic CNN-based model training +# --------------------------------------------- # # CTLearn currently provides a basic approach for stereoscopic CNN-based # model training. The images from the different telescopes are concatenated @@ -585,8 +588,8 @@ def run_training_command(command): ) ###################################################################### -# CNN-based model training using waveform data -# -------------------------------------------- +# Part E: CNN-based model training using waveform data +# ==================================================== # # The final example demonstrates training directly on waveform data. The # example dataset used in this tutorial is intentionally very small, so @@ -645,14 +648,19 @@ def run_training_command(command): ) ###################################################################### -# Comparing training curves -# ------------------------- +# Part F: Comparing training curves +# ================================= +# +# Each training run writes its metrics to ``training_log.csv`` together +# with the TensorBoard model checkpoints for training and validation, +# the final model, the configuration and provenance files. +# +# See Part G for instructions on how to monitor the training runs live using +# TensorBoard. Here, we read the training logs and plot the evolution of the +# metrics over the training epochs. The plots show the mean absolute error (MAE) for +# the regression tasks and the accuracy and AUC for the classification task. # -# Each training run writes its metrics to ``training_log.csv``. Compare the -# baseline energy, direction, and classification runs below. Camera and sky -# direction errors use different units, so they share a panel but have -# separate y-axes. The figure is also saved in the training output directory. -# The statistics of the training runs are intentionally very limited, so the +# Note: The statistics of the training runs are intentionally very limited, so the # training curves are not expected to be smooth or to converge to optimal values. # The purpose of this tutorial is to demonstrate the training workflow and the use # of CTLearn, rather than to achieve optimal performance on the example dataset. @@ -769,8 +777,8 @@ def plot_metric(ax, run_name, metric, label, color, **kwargs): plt.show() ###################################################################### -# Monitoring training with TensorBoard -# ------------------------------------ +# Part G: Monitoring training with TensorBoard +# ============================================ # # CTLearn also writes TensorBoard event files, which are useful for monitoring # metrics live or exploring additional details after training. The tutorial From f7076db2ee1a30077c24814e0c47866f99eb43d2 Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Mon, 9 Nov 2026 22:56:15 +0100 Subject: [PATCH 32/53] add a version switcher for switch to tag versions --- .github/workflows/ci.yml | 98 ----------------------- docs/source/_static/version-switcher.js | 86 ++++++++++++++++++++ docs/source/conf.py | 1 + docs/source/index.rst | 3 + examples/tutorials/train_ctlearn_model.py | 64 +++++++-------- 5 files changed, 122 insertions(+), 130 deletions(-) create mode 100644 docs/source/_static/version-switcher.js diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 14ebbede..4801fd33 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -97,104 +97,6 @@ jobs: download_file(url=url, path=cache_dir / name, progress=True) PY - docs: - needs: cache-test-data - runs-on: ubuntu-24.04 - permissions: - contents: read - env: - PIP_EXTRA_INDEX_URL: "https://download.pytorch.org/whl/cpu" - steps: - - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 - with: - fetch-depth: 0 - - - name: Set up Python - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5 - with: - python-version: "3.12" - - - name: Cache documentation dependencies - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 - with: - path: ~/.cache/pip - key: ${{ runner.os }}-docs-pip-py312-v1 - - - name: Install documentation dependencies - run: | - python -m pip install --upgrade pip - python -m pip install . - python -m pip install -r docs/requirements.txt - python -m pip install sphinx sphinx-rtd-theme sphinx-changelog sphinx-design - - - name: Get ctapipe version for processed-data cache - id: ctapipe-version - run: echo "version=$(python -c 'import ctapipe; print(ctapipe.__version__)')" >> "$GITHUB_OUTPUT" - - - name: Restore tutorial input data - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 - with: - path: ~/.cache/ctlearn/tutorial-data - key: ctlearn-tutorial-data-${{ runner.os }}-v2 - - - name: Restore processed tutorial data - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 - with: - path: | - ~/.cache/ctlearn/tutorial-data/gamma_prod5-max500.r1.dl1.h5 - ~/.cache/ctlearn/tutorial-data/ctapipe-* - key: >- - ctlearn-tutorial-processed-${{ runner.os }}-v2-max500-${{ steps.ctapipe-version.outputs.version }}-${{ hashFiles('examples/tutorials/explore_public_data.py', 'docs/requirements.txt', 'pyproject.toml') }} - - - name: Build documentation and execute tutorials - env: - CTLEARN_TUTORIAL_MAX_EVENTS: "500" - run: python -m sphinx -b html --keep-going docs/source docs/build/html - - - name: Upload rendered documentation for review - if: >- - always() && - (github.event_name == 'pull_request' || github.event_name == 'push') - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 - with: - name: docs-${{ github.event_name }}-${{ github.run_id }}-${{ github.run_attempt }} - path: docs/build/html - retention-days: 14 - if-no-files-found: warn - - deploy-docs: - if: github.event_name == 'push' && github.ref == 'refs/heads/main' - needs: docs - runs-on: ubuntu-24.04 - permissions: - contents: read - pages: write - id-token: write - concurrency: - group: github-pages - cancel-in-progress: false - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - steps: - - name: Configure GitHub Pages - uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5 - - - name: Download rendered documentation - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4 - with: - name: docs-${{ github.event_name }}-${{ github.run_id }}-${{ github.run_attempt }} - path: docs/build/html - - - name: Upload GitHub Pages artifact - uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4 - with: - path: docs/build/html - - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4 - pixi: needs: cache-test-data if: >- diff --git a/docs/source/_static/version-switcher.js b/docs/source/_static/version-switcher.js new file mode 100644 index 00000000..dfaef1e5 --- /dev/null +++ b/docs/source/_static/version-switcher.js @@ -0,0 +1,86 @@ +(() => { + const findManifest = async () => { + const pathParts = window.location.pathname.split("/").filter(Boolean); + for (let depth = 0; depth <= pathParts.length; depth += 1) { + const candidate = new URL( + `${"../".repeat(depth)}versions.json`, + window.location.href, + ); + try { + const response = await fetch(candidate); + if (!response.ok) { + continue; + } + const versions = await response.json(); + if ( + Array.isArray(versions) && + versions.some((version) => version.version === "main") + ) { + return { candidate, versions }; + } + } catch (error) { + console.warn("Could not load documentation versions.", error); + } + } + return null; + }; + + const addVersionSelector = async () => { + const search = document.querySelector(".wy-side-nav-search"); + if (!search) { + return; + } + + const manifest = await findManifest(); + if (!manifest) { + return; + } + + const sitePath = new URL(".", manifest.candidate).pathname; + const relativePath = window.location.pathname.slice(sitePath.length); + const pathParts = relativePath.split("/").filter(Boolean); + const currentVersion = manifest.versions.find( + (version) => version.path === pathParts[0], + ); + const pagePath = currentVersion ? pathParts.slice(1).join("/") : relativePath; + const selectedVersion = currentVersion?.version ?? "main"; + + const label = document.createElement("label"); + label.htmlFor = "documentation-version"; + label.textContent = "Documentation version"; + label.style.cssText = "display:block;margin:0.75em 0 0.25em;text-align:left"; + + const select = document.createElement("select"); + select.id = "documentation-version"; + select.setAttribute("aria-label", "Documentation version"); + select.style.cssText = "box-sizing:border-box;width:100%;padding:0.35em"; + + for (const version of manifest.versions) { + const option = document.createElement("option"); + option.value = version.path; + option.textContent = version.title; + option.selected = version.version === selectedVersion; + select.append(option); + } + + select.addEventListener("change", () => { + const destination = new URL(sitePath, window.location.origin); + const targetPath = [select.value, pagePath].filter(Boolean).join("/"); + destination.pathname += targetPath; + if (!pagePath || window.location.pathname.endsWith("/")) { + destination.pathname += "/"; + } + destination.search = window.location.search; + destination.hash = window.location.hash; + window.location.assign(destination); + }); + + search.append(label, select); + }; + + if (document.readyState === "loading") { + document.addEventListener("DOMContentLoaded", addVersionSelector); + } else { + addVersionSelector(); + } +})(); diff --git a/docs/source/conf.py b/docs/source/conf.py index 956444a7..9db9f43d 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -120,6 +120,7 @@ # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ["_static"] +html_js_files = ["version-switcher.js"] # Custom sidebar templates, must be a dictionary that maps document names # to template names. diff --git a/docs/source/index.rst b/docs/source/index.rst index e5099415..fc9925b5 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -18,6 +18,9 @@ CTLearn: Deep Learning for IACT Event Reconstruction * Documentation: https://ctlearn-project.github.io/ctlearn/ * License: BSD-3 +Use the version selector in the sidebar to switch between the current +``main`` documentation and published tagged releases. + .. toctree:: :maxdepth: 2 :caption: Contents: diff --git a/examples/tutorials/train_ctlearn_model.py b/examples/tutorials/train_ctlearn_model.py index ce20aca9..00f9212c 100644 --- a/examples/tutorials/train_ctlearn_model.py +++ b/examples/tutorials/train_ctlearn_model.py @@ -177,7 +177,7 @@ def find_config_dir(): print(f"\nTraining outputs: {OUTPUT_DIR}") -def run_training_command(command): +def run_command_line(command): result = subprocess.run( command, shell=True, @@ -211,7 +211,7 @@ def run_training_command(command): # predicted values back from logarithmic space to the original linear energy # scale in TeV. -run_training_command( +run_command_line( """ctlearn-train-keras-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ @@ -224,7 +224,7 @@ def run_training_command(command): --TrainCTLearnModel.batch_size 4""", ) -run_training_command( +run_command_line( """ctlearn-train-pytorch-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ @@ -253,7 +253,7 @@ def run_training_command(command): # final direction expressed in degrees. # Camera coordinates -run_training_command( +run_command_line( """ctlearn-train-keras-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ @@ -266,7 +266,7 @@ def run_training_command(command): --TrainCTLearnModel.batch_size 4""", ) -run_training_command( +run_command_line( """ctlearn-train-pytorch-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ @@ -280,7 +280,7 @@ def run_training_command(command): ) # Sky coordinates -run_training_command( +run_command_line( """ctlearn-train-keras-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ @@ -293,7 +293,7 @@ def run_training_command(command): --TrainCTLearnModel.batch_size 4""", ) -run_training_command( +run_command_line( """ctlearn-train-pytorch-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ @@ -314,12 +314,12 @@ def run_training_command(command): # learning to distinguish between the two particle classes: signal # (gamma-ray events) and background (proton events), based on the information # contained in the camera image. The input directory containing the signal -# events can be specified using *--TrainCTLearnModel.input_dir_signal* or the -# shorthand *--signal*. One or more file patterns can be provided using -# *--TrainCTLearnModel.file_pattern_signal* or *--pattern-signal*. The +# events can be specified using ``--TrainCTLearnModel.input_dir_signal`` or the +# shorthand ``--signal``. One or more file patterns can be provided using +# ``--TrainCTLearnModel.file_pattern_signal`` or ``--pattern-signal``. The # corresponding options for the background events are -# *--TrainCTLearnModel.input_dir_background* / *--background* and -# *--TrainCTLearnModel.file_pattern_background* / *--pattern-background*. +# ``--TrainCTLearnModel.input_dir_background`` / ``--background`` and +# ``--TrainCTLearnModel.file_pattern_background`` / ``--pattern-background``. # # It is recommended to approximately balance the training dataset before # training. The training log reports the number of signal and background @@ -337,7 +337,7 @@ def run_training_command(command): # loss, accuracy, and AUC on a per-epoch basis can help identify potential # issues arising from class imbalance or other training problems. -run_training_command( +run_command_line( """ctlearn-train-keras-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h*" \\ @@ -352,7 +352,7 @@ def run_training_command(command): --TrainCTLearnModel.batch_size 4""", ) -run_training_command( +run_command_line( """ctlearn-train-pytorch-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h*" \\ @@ -375,7 +375,7 @@ def run_training_command(command): # customize the neural network architecture. # # Two main CNN-based architectures are currently implemented: **SingleCNN** -# and **ResNet**, which can be set by *--TrainCTLearnModel.model_type*. +# and **ResNet**, which can be set by ``--TrainCTLearnModel.model_type``. ###################################################################### # 1. SingleCNN model @@ -392,7 +392,7 @@ def run_training_command(command): # where predictions need to be made at very high rates and with very low # latency, computational efficiency becomes increasingly important. -run_training_command( +run_command_line( """ctlearn-train-keras-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ @@ -407,7 +407,7 @@ def run_training_command(command): --TrainCTLearnModel.batch_size 4""", ) -run_training_command( +run_command_line( """ctlearn-train-pytorch-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ @@ -442,7 +442,7 @@ def run_training_command(command): # - Bottleneck blocks, which use a more compact sequence of convolutions to # enable deeper networks while controlling the computational cost. -run_training_command( +run_command_line( """ctlearn-train-keras-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ @@ -457,7 +457,7 @@ def run_training_command(command): --TrainCTLearnModel.batch_size 4""", ) -run_training_command( +run_command_line( """ctlearn-train-pytorch-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ @@ -484,16 +484,16 @@ def run_training_command(command): # # Two parameters are particularly important: # -# - *--LoadedModel.trainable_backbone* controls whether the pre-trained +# - ``--LoadedModel.trainable_backbone`` controls whether the pre-trained # backbone is frozen (false) or trainable (true). -# - *--LoadedModel.overwrite_head* controls whether the structure of the +# - ``--LoadedModel.overwrite_head`` controls whether the structure of the # original prediction head is reused (false) or replaced with a new MLP # tailored to the new task or data (true). # # The preceding SingleCNN command trains the model loaded below. The copied # configuration keeps its prediction head and leaves the backbone trainable. -run_training_command( +run_command_line( """ctlearn-train-keras-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ @@ -509,7 +509,7 @@ def run_training_command(command): --TrainCTLearnModel.batch_size 4""", ) -run_training_command( +run_command_line( """ctlearn-train-pytorch-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ @@ -542,20 +542,20 @@ def run_training_command(command): # # The main configuration parameters for stereoscopic training are: # -# - *--DLImageReader.mode*: set to "stereo" to enable stereoscopic image +# - ``--DLImageReader.mode``: set to "stereo" to enable stereoscopic image # reading -# - *--DLImageReader.min_telescopes*: defines the minimum number of +# - ``--DLImageReader.min_telescopes``: defines the minimum number of # telescopes that must participate in an event after the quality cuts. -# - *--TrainCTLearnModel.stack_telescope_images*: set to true to +# - ``--TrainCTLearnModel.stack_telescope_images``: set to true to # stack/concatenate the images from the telescopes. # # Since the resulting input contains information from multiple telescopes # and is therefore larger than the corresponding monoscopic input, it is # recommended to reduce the batch size using -# *--TrainCTLearnModel.batch_size* to account for the increased memory +# ``--TrainCTLearnModel.batch_size`` to account for the increased memory # consumption. -run_training_command( +run_command_line( """ctlearn-train-keras-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ @@ -571,7 +571,7 @@ def run_training_command(command): --TableQualityQuery.quality_criteria []""", ) -run_training_command( +run_command_line( """ctlearn-train-pytorch-model --verbose \\ --signal "$CTLEARN_TUTORIAL_CONVERTED_DIR" \\ --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \\ @@ -606,7 +606,7 @@ def run_training_command(command): # one validation batch. # # An important configuration change is required to read waveform data: the -# *--TrainCTLearnModel.dl1dh_reader_type* option must be set to the +# ``--TrainCTLearnModel.dl1dh_reader_type`` option must be set to the # appropriate DL1 data reader component for waveform reading # (**DLWaveformReader**) rather than the default image reader. @@ -615,7 +615,7 @@ def run_training_command(command): f"Cached waveform data is missing: {WAVEFORM_FILE}. " "Run examples/tutorials/explore_public_data.py first." ) -run_training_command( +run_command_line( """ctlearn-train-keras-model --verbose \\ --signal "$CTLEARN_TUTORIAL_DATA_DIR" \\ --pattern-signal "gamma_prod5${CTLEARN_TUTORIAL_MAX_EVENTS_SUFFIX}.r1.dl1.h5" \\ @@ -631,7 +631,7 @@ def run_training_command(command): --TableQualityQuery.quality_criteria []""", ) -run_training_command( +run_command_line( """ctlearn-train-pytorch-model --verbose \\ --signal "$CTLEARN_TUTORIAL_DATA_DIR" \\ --pattern-signal "gamma_prod5${CTLEARN_TUTORIAL_MAX_EVENTS_SUFFIX}.r1.dl1.h5" \\ From 9fc7fbc620e5811e982f57b5e0bed2ca1ba61859 Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Mon, 9 Nov 2026 23:09:26 +0100 Subject: [PATCH 33/53] added back the doc CIs --- .github/workflows/ci.yml | 173 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 173 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 4801fd33..3351e653 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -97,6 +97,179 @@ jobs: download_file(url=url, path=cache_dir / name, progress=True) PY + docs: + needs: cache-test-data + runs-on: ubuntu-24.04 + permissions: + contents: read + env: + PIP_EXTRA_INDEX_URL: "https://download.pytorch.org/whl/cpu" + steps: + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + with: + fetch-depth: 0 + + - name: Set up Python + uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5 + with: + python-version: "3.12" + + - name: Cache documentation dependencies + uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 + with: + path: ~/.cache/pip + key: ${{ runner.os }}-docs-pip-py312-v1 + + - name: Install documentation dependencies + run: | + python -m pip install --upgrade pip + python -m pip install . + python -m pip install -r docs/requirements.txt + python -m pip install sphinx sphinx-rtd-theme sphinx-changelog sphinx-design + + - name: Get ctapipe version for processed-data cache + id: ctapipe-version + run: echo "version=$(python -c 'import ctapipe; print(ctapipe.__version__)')" >> "$GITHUB_OUTPUT" + + - name: Restore tutorial input data + uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 + with: + path: ~/.cache/ctlearn/tutorial-data + key: ctlearn-tutorial-data-${{ runner.os }}-v2 + + - name: Restore processed tutorial data + uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 + with: + path: | + ~/.cache/ctlearn/tutorial-data/gamma_prod5-max500.r1.dl1.h5 + ~/.cache/ctlearn/tutorial-data/ctapipe-* + key: >- + ctlearn-tutorial-processed-${{ runner.os }}-v2-max500-${{ steps.ctapipe-version.outputs.version }}-${{ hashFiles('examples/tutorials/explore_public_data.py', 'docs/requirements.txt', 'pyproject.toml') }} + + - name: Build documentation and execute tutorials + env: + CTLEARN_TUTORIAL_MAX_EVENTS: "500" + run: python -m sphinx -b html --keep-going docs/source docs/build/html + + - name: Upload rendered documentation for review + if: >- + always() && + (github.event_name == 'pull_request' || github.event_name == 'push') + uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 + with: + name: docs-${{ github.event_name }}-${{ github.run_id }}-${{ github.run_attempt }} + path: docs/build/html + retention-days: 14 + if-no-files-found: warn + + deploy-docs: + if: >- + github.event_name == 'push' && + ( + github.ref == 'refs/heads/main' || + startsWith(github.ref, 'refs/tags/') + ) + needs: docs + runs-on: ubuntu-24.04 + permissions: + contents: write + pages: write + id-token: write + concurrency: + group: github-pages + cancel-in-progress: false + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Configure GitHub Pages + uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5 + + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + with: + fetch-depth: 0 + + - name: Download rendered documentation + uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4 + with: + name: docs-${{ github.event_name }}-${{ github.run_id }}-${{ github.run_attempt }} + path: docs/build/html + + - name: Merge version into Pages site + env: + VERSION: ${{ github.ref_name }} + REF: ${{ github.ref }} + run: | + site_dir="$RUNNER_TEMP/gh-pages" + if git ls-remote --exit-code origin refs/heads/gh-pages >/dev/null 2>&1; then + git fetch origin gh-pages + git worktree add -B gh-pages "$site_dir" FETCH_HEAD + else + git worktree add --orphan -b gh-pages "$site_dir" + fi + + if [[ "$REF" == "refs/heads/main" ]]; then + version_path="main" + else + version_path="${VERSION//\//--}" + fi + + mkdir -p "$site_dir/$version_path" + rsync -a --delete docs/build/html/ "$site_dir/$version_path/" + if [[ "$version_path" == "main" ]]; then + rsync -a docs/build/html/ "$site_dir/" + fi + touch "$site_dir/.nojekyll" + + python - "$site_dir/versions.json" "$VERSION" "$version_path" "$REF" <<'PY' + import json + import sys + from pathlib import Path + + manifest_path = Path(sys.argv[1]) + version, version_path, ref = sys.argv[2:] + if ref == "refs/heads/main": + version = "main" + title = "main (development)" + else: + title = version + + if manifest_path.exists(): + versions = json.loads(manifest_path.read_text()) + else: + versions = [] + + versions = [item for item in versions if item["version"] != version] + versions.append({"version": version, "path": version_path, "title": title}) + versions.sort( + key=lambda item: (item["version"] != "main", item["version"]) + ) + versions[1:] = sorted( + versions[1:], key=lambda item: item["version"], reverse=True + ) + manifest_path.write_text(json.dumps(versions, indent=2) + "\n") + PY + + git -C "$site_dir" add -A + if ! git -C "$site_dir" diff --cached --quiet; then + git -C "$site_dir" -c user.name="github-actions[bot]" \ + -c user.email="41898282+github-actions[bot]@users.noreply.github.com" \ + commit -m "Deploy documentation for $VERSION" + git push origin gh-pages + fi + + mkdir -p "$RUNNER_TEMP/pages-artifact" + rsync -a --exclude='.git' "$site_dir/" "$RUNNER_TEMP/pages-artifact/" + + - name: Upload GitHub Pages artifact + uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4 + with: + path: ${{ runner.temp }}/pages-artifact + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4 + pixi: needs: cache-test-data if: >- From 283c13b0c6a607a818099dde94fa25de92a95bd2 Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Tue, 10 Nov 2026 10:21:50 +0100 Subject: [PATCH 34/53] added tutorial 3 for prediction of CTLearn models --- .codespell-ignores | 1 + docs/requirements.txt | 6 +- docs/source/conf.py | 5 +- docs/source/tutorials.rst | 39 +- examples/tutorials/explore_public_data.py | 20 +- examples/tutorials/predict_ctlearn_model.py | 894 ++++++++++++++++++++ examples/tutorials/train_ctlearn_model.py | 7 +- pyproject.toml | 2 + 8 files changed, 956 insertions(+), 18 deletions(-) create mode 100644 examples/tutorials/predict_ctlearn_model.py diff --git a/.codespell-ignores b/.codespell-ignores index 189f8412..35ce0dac 100644 --- a/.codespell-ignores +++ b/.codespell-ignores @@ -1 +1,2 @@ CHEC +fpr diff --git a/docs/requirements.txt b/docs/requirements.txt index 06ce9368..d881992e 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -2,9 +2,11 @@ sphinx sphinx_rtd_theme sphinx-changelog sphinx-design -# Light-weight runtime dependencies needed by autodoc to import ctlearn. -# The heavy ML frameworks (TensorFlow, PyTorch, ...) are mocked in conf.py. +# Dependencies for autodoc and the executable Sphinx-Gallery tutorials. +# The Sphinx autodoc configuration mocks the heavy ML frameworks. ctapipe>=0.29 dl1_data_handler>=0.14.12 matplotlib +ctaplot +scikit-learn sphinx-gallery>=0.16.0 diff --git a/docs/source/conf.py b/docs/source/conf.py index 9db9f43d..35a3b23b 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -62,11 +62,14 @@ sphinx_gallery_conf = { "examples_dirs": "../../examples/tutorials", "gallery_dirs": "auto_tutorials", - "filename_pattern": r"(explore_public_data|train_ctlearn_model)\.py$", + "filename_pattern": ( + r"(explore_public_data|train_ctlearn_model|predict_ctlearn_model)\.py$" + ), "within_subsection_order": ExplicitOrder( [ "explore_public_data.py", "train_ctlearn_model.py", + "predict_ctlearn_model.py", "*", ] ), diff --git a/docs/source/tutorials.rst b/docs/source/tutorials.rst index 6759f427..7420ad46 100644 --- a/docs/source/tutorials.rst +++ b/docs/source/tutorials.rst @@ -3,7 +3,7 @@ Tutorials ********* Public CTAO data exploration -============================ +---------------------------- This tutorial follows the executable Python-script style used by ctapipe's tutorials. It downloads a small SimTel sample for the monoscopic examples and @@ -30,7 +30,7 @@ The rendered tutorial, including its code, figures, and playable waveform animations, is generated by Sphinx-Gallery: Training a CTLearn model -======================== +------------------------ The training tutorial documents monoscopic energy and direction regression, gamma/proton classification, custom ``SingleCNN`` and ``ResNet`` architectures, @@ -98,6 +98,41 @@ examples, run the script to execute the commands in sequence. Start TensorBoard for the resulting metrics with ``tensorboard --logdir ~/.cache/ctlearn/tutorial-training/``. +Predicting with CTLearn models +------------------------------ + +The prediction tutorial runs the Keras and PyTorch models produced by the +training tutorial on the held-out ``01`` CTAO simulation files. Each command +shows the model file path and configuration options explicitly. It plots +classification scores and ROC/AUC for both frameworks, plus regression +migration matrices and energy and angular resolution. The shared DL1 reader +configuration is shown in each command and controls telescope selection, +image channels, image mapping, and quality cuts. The tutorial also demonstrates +stereo prediction, waveform inference, and the LST-1 tool using a generated +mock DL1 file. The waveform example reuses training data only to demonstrate +the workflow; it is not an evaluation. + +Run the public data exploration tutorial and the training tutorial first, then +execute: + +.. code-block:: console + + python examples/tutorials/predict_ctlearn_model.py + +Prediction outputs are written to ``predictions`` under +``CTLEARN_TUTORIAL_OUTPUT_DIR`` (default: +``~/.cache/ctlearn/tutorial-training``). The classifier and resolution +figures are demonstrations on small samples and should not be used for +scientific conclusions or interpreted as production instrument response +functions. DL2 files are written to the same output directory and can be +inspected with ``ViTables``. The following command opens the DL2 files +in ``ViTables``: + +.. code-block:: console + + pip install vitables + vitables $HOME/.cache/ctlearn/tutorial-training/predictions/*.dl2.h5 + .. toctree:: :maxdepth: 1 diff --git a/examples/tutorials/explore_public_data.py b/examples/tutorials/explore_public_data.py index 4f6736c6..2e5b4561 100644 --- a/examples/tutorials/explore_public_data.py +++ b/examples/tutorials/explore_public_data.py @@ -1,6 +1,6 @@ """ -Explore Public CTAO Data -======================== +Tutorial 1: Explore Public CTAO Data +==================================== Download public CTAO simulation data, convert it with ctapipe, and explore waveforms and images using DL1DataHandler. @@ -99,8 +99,8 @@ print(f"Using existing processed file: {gamma_dl1_path}") ###################################################################### -# Read calibrated waveforms -# ------------------------- +# Part A: Read calibrated waveforms +# ================================= # # DL1DataHandler can read calibrated waveforms and map each camera into a # regular image. Here we display an animation of the waveform samples for @@ -184,8 +184,8 @@ def update( plt.show() ###################################################################### -# Read monoscopic images -# ---------------------- +# Part B: Read monoscopic images +# ============================== # # The image reader returns integrated charge and relative peak-time images. # The mapper is selected for each camera type. @@ -231,8 +231,8 @@ def update( plt.show() ###################################################################### -# Download and convert the stereo data -# ------------------------------------ +# Download and convert the stereoscopic simulated CTAO data +# --------------------------------------------------------- # # The Zenodo files contain CTAO open-source gamma and proton simulations. # Convert each file with the installed ctapipe version, and store converted @@ -283,8 +283,8 @@ def update( print(f"Using existing ctapipe output: {output_path}") ###################################################################### -# Read stereo images -# ------------------ +# Part C: Read stereo images +# ========================== # # Finally, combine gamma and proton events in stereo mode and plot the # integrated charge and relative peak-time image from each telescope. diff --git a/examples/tutorials/predict_ctlearn_model.py b/examples/tutorials/predict_ctlearn_model.py new file mode 100644 index 00000000..4c52df64 --- /dev/null +++ b/examples/tutorials/predict_ctlearn_model.py @@ -0,0 +1,894 @@ +""" +Tutorial 3: Perform inference with CTlearn models +================================================= + +For this notebook, one would need to download the HDF5 data files from the +CTAO opendata folder (https://cloud.iaa.es/index.php/s/77d6MK4rGfanSKx) and +the trained models of ``train_ctlearn_model.py``. +""" + +###################################################################### +# Check paths, environments, CTAO test data, and trained models +# ------------------------------------------------------------- +# +# The executable tutorial uses the shared downloaded data and the Keras and +# PyTorch models produced by ``train_ctlearn_model.py``. In a notebook, prefix +# the displayed command-line examples with ``!``. + +import os +import subprocess +from pathlib import Path + +import astropy.units as u +import ctaplot +import matplotlib.pyplot as plt +import numpy as np +from astropy.table import Column, Table +from ctapipe import __version__ as ctapipe_version +from ctapipe.io import TableLoader, write_table +from matplotlib.colors import LogNorm +from sklearn.metrics import auc, roc_curve + +from ctlearn.tools.utils import get_lst1_subarray_description + +MAX_EVENTS = os.environ.get("CTLEARN_TUTORIAL_MAX_EVENTS") +if MAX_EVENTS is not None and int(MAX_EVENTS) < 1: + raise ValueError("CTLEARN_TUTORIAL_MAX_EVENTS must be a positive integer") +MAX_EVENTS_SUFFIX = f"-max{MAX_EVENTS}" if MAX_EVENTS is not None else "" + +DATA_DIR = ( + Path( + os.environ.get( + "CTLEARN_TUTORIAL_DATA_DIR", + str(Path.home() / ".cache" / "ctlearn" / "tutorial-data"), + ) + ) + .expanduser() + .resolve() +) +CONVERTED_DIR = ( + Path( + os.environ.get( + "CTLEARN_TUTORIAL_CONVERTED_DIR", + str(DATA_DIR / f"ctapipe-{ctapipe_version}{MAX_EVENTS_SUFFIX}"), + ) + ) + .expanduser() + .resolve() +) +OUTPUT_DIR = ( + Path( + os.environ.get( + "CTLEARN_TUTORIAL_OUTPUT_DIR", + str(Path.home() / ".cache" / "ctlearn" / "tutorial-training"), + ) + ) + .expanduser() + .resolve() +) +PREDICTION_DIR = OUTPUT_DIR / "predictions" +PREDICTION_DIR.mkdir(parents=True, exist_ok=True) + + +def find_config_dir(): + roots = [] + script_path = globals().get("__file__") + if script_path is not None: + roots.append(Path(script_path).resolve().parents[2]) + roots.extend((Path.cwd(), *Path.cwd().parents)) + + for root in roots: + config_dir = root / "docs" / "source" / "config" + if (config_dir / "dl1dh_example_config.json").is_file(): + return config_dir + + raise FileNotFoundError( + "Could not locate tutorial configs under docs/source/config. " + "Run this tutorial from the CTLearn repository or build it with " + "Sphinx-Gallery." + ) + + +CONFIG_DIR = find_config_dir() +DL1DH_CONFIG = CONFIG_DIR / "dl1dh_example_config.json" +for config_path in (DL1DH_CONFIG,): + if not config_path.is_file(): + raise FileNotFoundError(f"Tutorial configuration is missing: {config_path}") + +GAMMA_FILE = CONVERTED_DIR / "gamma-diffuse_with_images_01.dl2.h5" +PROTON_FILE = CONVERTED_DIR / "proton_with_images_01.dl2.h5" +missing_files = [path for path in (GAMMA_FILE, PROTON_FILE) if not path.is_file()] +if missing_files: + missing = "\n".join(f" - {path}" for path in missing_files) + raise FileNotFoundError( + "Held-out tutorial data is missing. Run " + "examples/tutorials/explore_public_data.py first. Missing files:\n" + f"{missing}" + ) + +os.environ["CTLEARN_TUTORIAL_DATA_DIR"] = str(DATA_DIR) +os.environ["CTLEARN_TUTORIAL_CONVERTED_DIR"] = str(CONVERTED_DIR) +os.environ["CTLEARN_TUTORIAL_OUTPUT_DIR"] = str(OUTPUT_DIR) +os.environ["CTLEARN_TUTORIAL_CONFIG_DIR"] = str(CONFIG_DIR.resolve()) +os.environ["CTLEARN_TUTORIAL_MAX_EVENTS_SUFFIX"] = MAX_EVENTS_SUFFIX + +print(f"Converted held-out data: {CONVERTED_DIR}") +print(f"Trained model outputs: {OUTPUT_DIR}") +print(f"Prediction outputs: {PREDICTION_DIR}") +print(f"Reader configuration: {DL1DH_CONFIG}") + + +def run_command_line(command): + print(f"Running command: $ {command.strip()}") + result = subprocess.run( + command, + shell=True, + stdout=subprocess.PIPE, + stderr=subprocess.STDOUT, + text=True, + ) + print(result.stdout, end="") + result.check_returncode() + + +###################################################################### +# Explore the CTLearn prediction tools +# ------------------------------------ +# +# Installing CTLearn provides several command-line tools for running and +# managing different parts of the workflow. For model inference, we use the +# ``ctlearn-predict-{mono,stereo}-model`` command. The ``-h`` option displays a +# short version of the help message, showing the main command-line options and +# their usage. For a complete description of all available options, including +# the configuration parameters of the different components, use ``--help-all``. +# Although the command is executed from this Jupyter notebook for convenience +# and documentation, ``ctlearn-predict-{mono,stereo}-model`` is a +# command-line tool. In a typical workflow, the prediction command would be +# executed directly from a terminal or submitted as part of a cluster job, +# for example through sbatch on an HPC system. + +run_command_line("ctlearn-predict-mono-model -h") +run_command_line("ctlearn-predict-stereo-model -h") + +###################################################################### +# Part A: Monoscopic CNN-based model inference +# ============================================ +# +# We perform inference using the three previously trained CTLearn models from +# ``train_ctlearn_model.py``: the primary particle type (classification), +# primary particle energy (regression), and arrival direction (regression) +# models. The models are applied to both gamma-ray (signal) and proton +# (background) input data. The three inference tasks are executed sequentially +# within a single tool invocation. The prediction tool provides several +# options for selecting which data levels from the input file are copied to +# the output file. By default, the goal is to progress to the next data level +# while keeping the output file as compact as possible. However, retaining +# additional data levels can be useful for debugging and for inspecting +# individual events in more detail. The resulting file contains the model +# predictions together with the selected input data levels and follows the +# CTAO reference data model. +# +# **Important**: The same configuration settings used during training should +# be used for inference whenever applicable. In particular, the data +# preprocessing and data reader configuration must be consistent with those +# used to train the models. The ``01`` files are used here as held-out input +# data, and the paths to each model are shown directly in the commands. + +###################################################################### +# 1. Keras monoscopic model prediction +# ------------------------------------ + +run_command_line( + """ctlearn-predict-mono-model --verbose \\ + --input_url "$CTLEARN_TUTORIAL_CONVERTED_DIR/gamma-diffuse_with_images_01.dl2.h5" \\ + --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/predictions/gamma-diffuse_with_images_01.ctlearn.dl2.h5" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/dl1dh_example_config.json" \\ + --type_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-classification/ctlearn_model.keras" \\ + --energy_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-energy/ctlearn_model.keras" \\ + --cameradirection_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-cameradirection/ctlearn_model.keras" \\ + --overwrite""" +) +run_command_line( + """ctlearn-predict-mono-model --verbose \\ + --input_url "$CTLEARN_TUTORIAL_CONVERTED_DIR/proton_with_images_01.dl2.h5" \\ + --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/predictions/proton_with_images_01.ctlearn.dl2.h5" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/dl1dh_example_config.json" \\ + --type_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-classification/ctlearn_model.keras" \\ + --energy_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-energy/ctlearn_model.keras" \\ + --cameradirection_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-cameradirection/ctlearn_model.keras" \\ + --overwrite""" +) + +###################################################################### +# 2. PyTorch monoscopic model prediction +# -------------------------------------- +# +# The same prediction tasks can be run with the PyTorch models. The model +# paths below point to the corresponding PyTorch outputs from +# ``train_ctlearn_model.py``. + +run_command_line( + """ctlearn-predict-mono-model --verbose \\ + --input_url "$CTLEARN_TUTORIAL_CONVERTED_DIR/gamma-diffuse_with_images_01.dl2.h5" \\ + --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/predictions/gamma-diffuse_with_images_01.pytorch.ctlearn.dl2.h5" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/dl1dh_example_config.json" \\ + --type_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-classification/ctlearn_model.pth" \\ + --energy_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-energy/ctlearn_model.pth" \\ + --cameradirection_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-cameradirection/ctlearn_model.pth" \\ + --overwrite""" +) +run_command_line( + """ctlearn-predict-mono-model --verbose \\ + --input_url "$CTLEARN_TUTORIAL_CONVERTED_DIR/proton_with_images_01.dl2.h5" \\ + --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/predictions/proton_with_images_01.pytorch.ctlearn.dl2.h5" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/dl1dh_example_config.json" \\ + --type_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-classification/ctlearn_model.pth" \\ + --energy_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-energy/ctlearn_model.pth" \\ + --cameradirection_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-cameradirection/ctlearn_model.pth" \\ + --overwrite""" +) + +###################################################################### +# Part B: Exploring the produced CTLearn DL2 data +# =============================================== +# +# In the following cells, we will explore the DL2 predictions produced by the +# CTLearn models. Keep in mind that, for this hands-on tutorial, we trained +# the models on very small datasets with limited statistics to keep the +# training time manageable. The datasets used here represent only a tiny +# fraction of the statistics typically used for a production-level CNN-based +# analysis, where GPU resources are also used to accelerate the training +# process. Consequently, the performance metrics and resolution curves +# obtained in this tutorial should not be considered representative of a +# production analysis, compared directly with published results, or used for +# scientific conclusions. The main goal here is to understand how the +# analysis workflow is conducted: how the predictions are loaded, how the +# different performance metrics are calculated, and how the corresponding +# distributions and resolution curves are visualized. Once we are familiar +# with the complete workflow, we can increase the statistics and repeat the +# analysis using a full production of simulated data. The full production +# simulations used by the CTAO collaboration are not publicly available. +# However, the statistics available in the CTAO Open Data are sufficient to +# obtain meaningful proof-of-concept results and to explore the analysis +# workflow in much greater detail. +# +# The first cell loads the data using the **TableLoader** from ctapipe. The +# produced files follow the reference implementation of the CTAO data model, +# allowing the DL2 information to be read in a standardized format. The cell +# also selects and prepares the relevant quantities from the predictions so +# that they can be conveniently used in the following cells for plotting the +# classifier performance, energy reconstruction, angular reconstruction, and +# other performance metrics. + + +def read_valid_telescope_events(filename): + with TableLoader(input_url=filename) as loader: + telescope_events = loader.read_telescope_events( + telescopes=["LST_LST_LSTCam"], + dl1_images=False, + dl1_parameters=False, + dl1_muons=False, + dl2=True, + simulated=True, + true_images=False, + true_parameters=False, + instrument=False, + observation_info=False, + ) + return telescope_events[telescope_events["CTLearnRegressor_tel_is_valid"]] + + +gamma_keras_events = read_valid_telescope_events( + PREDICTION_DIR / "gamma-diffuse_with_images_01.ctlearn.dl2.h5" +) +proton_keras_events = read_valid_telescope_events( + PREDICTION_DIR / "proton_with_images_01.ctlearn.dl2.h5" +) +gamma_pytorch_events = read_valid_telescope_events( + PREDICTION_DIR / "gamma-diffuse_with_images_01.pytorch.ctlearn.dl2.h5" +) +proton_pytorch_events = read_valid_telescope_events( + PREDICTION_DIR / "proton_with_images_01.pytorch.ctlearn.dl2.h5" +) + +gamma_keras_predictions = np.asarray( + gamma_keras_events["CTLearnClassifier_tel_prediction"] +) +proton_keras_predictions = np.asarray( + proton_keras_events["CTLearnClassifier_tel_prediction"] +) +gamma_pytorch_predictions = np.asarray( + gamma_pytorch_events["CTLearnClassifier_tel_prediction"] +) +proton_pytorch_predictions = np.asarray( + proton_pytorch_events["CTLearnClassifier_tel_prediction"] +) +gamma_scores = gamma_keras_predictions[gamma_keras_predictions != 0.0] +proton_scores = proton_keras_predictions[proton_keras_predictions != 0.0] +gamma_pytorch_scores = gamma_pytorch_predictions[gamma_pytorch_predictions != 0.0] +proton_pytorch_scores = proton_pytorch_predictions[proton_pytorch_predictions != 0.0] + +reco_energy = np.asarray(gamma_keras_events["CTLearnRegressor_tel_energy"]) +true_energy = np.asarray(gamma_keras_events["true_energy"]) +proton_true_energy = np.asarray(proton_keras_events["true_energy"]) +reco_alt = np.asarray(gamma_keras_events["CTLearnCameraReconstructor_tel_alt"]) +true_alt = np.asarray(gamma_keras_events["true_alt"]) +reco_az = np.asarray(gamma_keras_events["CTLearnCameraReconstructor_tel_az"]) +true_az = np.asarray(gamma_keras_events["true_az"]) + +###################################################################### +# 1. Particle classification performance +# -------------------------------------- +# +# This cell visualizes the particle classification performance of the CTLearn +# model, with the goal of discriminating gamma-ray signal events from proton +# background events. Three complementary plots are shown: on the left, the +# distribution of the classifier output, or gammaness, for gamma-ray and +# proton events; in the middle, the Receiver Operating Characteristic (ROC) +# curve, which shows the trade-off between the true positive rate and the +# false positive rate as the classification threshold is varied, together +# with the corresponding Area Under the Curve (AUC); and on the right, the AUC +# as a function of true energy, showing how the classification performance +# changes across the energy range of the simulated events. Together, these +# plots provide an overview of the classifier performance, both globally and +# as a function of energy. As with the other performance metrics presented in +# this tutorial, these results are intended to illustrate the analysis +# workflow rather than provide production-level performance estimates. +# +# The same plots compare the Keras and PyTorch classifiers. + +y_true = np.concatenate([np.ones(len(gamma_scores)), np.zeros(len(proton_scores))]) +y_score = np.concatenate([gamma_scores, proton_scores]) +fpr, tpr, _ = roc_curve(y_true, y_score) +roc_auc = auc(fpr, tpr) +torch_y_true = np.concatenate( + [ + np.ones(len(gamma_pytorch_scores)), + np.zeros(len(proton_pytorch_scores)), + ] +) +torch_y_score = np.concatenate([gamma_pytorch_scores, proton_pytorch_scores]) +torch_fpr, torch_tpr, _ = roc_curve(torch_y_true, torch_y_score) +torch_roc_auc = auc(torch_fpr, torch_tpr) +gamma_energy_auc = true_energy[gamma_keras_predictions != 0.0] +proton_energy_auc = proton_true_energy[proton_keras_predictions != 0.0] +true_energy_auc = np.concatenate([gamma_energy_auc, proton_energy_auc]) +energy_bins_auc = np.logspace(np.log10(0.03), np.log10(100), 15) * u.TeV +energy_bins_auc, auc_scores = ctaplot.roc_auc_per_energy( + true_type=y_true, + gammaness=y_score, + true_energy=true_energy_auc * u.TeV, + energy_bins=energy_bins_auc, +) +gamma_pytorch_energy_auc = np.asarray(gamma_pytorch_events["true_energy"])[ + gamma_pytorch_predictions != 0.0 +] +proton_pytorch_energy_auc = np.asarray(proton_pytorch_events["true_energy"])[ + proton_pytorch_predictions != 0.0 +] +pytorch_true_energy_auc = np.concatenate( + [gamma_pytorch_energy_auc, proton_pytorch_energy_auc] +) +pytorch_energy_bins_auc, pytorch_auc_scores = ctaplot.roc_auc_per_energy( + true_type=torch_y_true, + gammaness=torch_y_score, + true_energy=pytorch_true_energy_auc * u.TeV, + energy_bins=np.logspace(np.log10(0.03), np.log10(100), 15) * u.TeV, +) + +fig, axes = plt.subplots(1, 3, figsize=(18, 5), constrained_layout=True) +score_bins = np.linspace(0, 1, 50) +axes[0].hist( + gamma_scores, + bins=score_bins, + histtype="step", + linewidth=1.5, + label="Keras signal (gamma)", +) +axes[0].hist( + proton_scores, + bins=score_bins, + histtype="step", + linewidth=1.5, + label="Keras background (proton)", +) +axes[0].hist( + gamma_pytorch_scores, + bins=score_bins, + histtype="step", + linewidth=1.5, + label="PyTorch signal (gamma)", +) +axes[0].hist( + proton_pytorch_scores, + bins=score_bins, + histtype="step", + linewidth=1.5, + label="PyTorch background (proton)", +) +axes[0].set_xlabel("Classifier value (gammaness)") +axes[0].set_ylabel("Counts") +axes[0].set_title("Gammaness distribution") +axes[0].legend(loc="upper center", fontsize="small") + +axes[1].plot(fpr, tpr, lw=2, label=f"Keras classifier (AUC = {roc_auc:.3f})") +axes[1].plot( + torch_fpr, + torch_tpr, + lw=2, + label=f"PyTorch classifier (AUC = {torch_roc_auc:.3f})", +) +axes[1].plot([0, 1], [0, 1], "k--", alpha=0.5, label="Random classifier") +axes[1].set_xlabel("False positive rate") +axes[1].set_ylabel("True positive rate") +axes[1].set_title("ROC curve") +axes[1].set_xlim(0, 1) +axes[1].set_ylim(0, 1) +axes[1].grid(alpha=0.3) +axes[1].legend(loc="lower right") + +ctaplot.plot_roc_auc_per_energy( + energy_bins=energy_bins_auc, + auc_scores=auc_scores, + label="Keras classifier", + ax=axes[2], +) +ctaplot.plot_roc_auc_per_energy( + energy_bins=pytorch_energy_bins_auc, + auc_scores=pytorch_auc_scores, + label="PyTorch classifier", + ax=axes[2], +) +axes[2].set_title("AUC vs. energy") +axes[2].set_ylim(0.5, 1.0) +axes[2].legend() +plt.show() + +###################################################################### +# 2. Regression migration matrices +# -------------------------------- +# +# The next cell shows the migration matrices for the regression tasks of the +# CTLearn model, covering the reconstructed energy and arrival direction. The +# figure contains three subplots: the energy migration matrix on the left, +# the altitude migration matrix in the middle, and the azimuth migration +# matrix on the right. In each case, the true value is shown on the x-axis and +# the reconstructed value on the y-axis, allowing us to visualize how the +# reconstructed quantities are distributed with respect to their true values. +# The azimuth is wrapped around (0º/360º) because the simulated observations +# are pointing towards the north, so (0º) and (360º) represent the same +# direction. The black diagonal lines indicate perfect reconstruction, where +# the reconstructed value is exactly equal to the true value. The closer the +# event distribution is concentrated around this diagonal, the more accurately +# the corresponding regression task reconstructs the physical quantity. + +fig, axes = plt.subplots(1, 3, figsize=(18, 5.5)) +energy_bins = np.logspace(np.log10(1), np.log10(100), 50) +hist_energy, true_energy_edges, reco_energy_edges = np.histogram2d( + true_energy, reco_energy, bins=[energy_bins, energy_bins] +) +energy_mesh = axes[0].pcolormesh( + true_energy_edges, + reco_energy_edges, + np.ma.masked_where(hist_energy == 0, hist_energy).T, + norm=LogNorm(vmin=1, vmax=hist_energy.max()), + cmap="viridis", + shading="auto", +) +axes[0].plot( + energy_bins, + energy_bins, + "k--", + linewidth=1.5, + label="Perfect reconstruction", +) +axes[0].set_xscale("log") +axes[0].set_yscale("log") +axes[0].set_xlabel("True energy [TeV]") +axes[0].set_ylabel("Reconstructed energy [TeV]") +axes[0].set_title("Energy migration") +axes[0].legend(loc="upper left") +fig.colorbar(energy_mesh, ax=axes[0]).set_label("Number of events") + +altitude_bins = np.linspace( + min(true_alt.min(), reco_alt.min()), + max(true_alt.max(), reco_alt.max()), + 50, +) +hist_altitude, true_altitude_edges, reco_altitude_edges = np.histogram2d( + true_alt, reco_alt, bins=[altitude_bins, altitude_bins] +) +altitude_mesh = axes[1].pcolormesh( + true_altitude_edges, + reco_altitude_edges, + np.ma.masked_where(hist_altitude == 0, hist_altitude).T, + norm=LogNorm(vmin=1, vmax=hist_altitude.max()), + cmap="viridis", + shading="auto", +) +axes[1].plot( + altitude_bins, + altitude_bins, + "k--", + linewidth=1.5, + label="Perfect reconstruction", +) +axes[1].set_xlabel("True altitude [deg]") +axes[1].set_ylabel("Reconstructed altitude [deg]") +axes[1].set_title("Altitude migration") +axes[1].legend(loc="upper left") +fig.colorbar(altitude_mesh, ax=axes[1]).set_label("Number of events") + +true_az_wrapped = (true_az + 180) % 360 - 180 +reco_az_wrapped = (reco_az + 180) % 360 - 180 +azimuth_bins = np.linspace(-15, 15, 61) +hist_azimuth, true_azimuth_edges, reco_azimuth_edges = np.histogram2d( + true_az_wrapped, reco_az_wrapped, bins=[azimuth_bins, azimuth_bins] +) +azimuth_mesh = axes[2].pcolormesh( + true_azimuth_edges, + reco_azimuth_edges, + np.ma.masked_where(hist_azimuth == 0, hist_azimuth).T, + norm=LogNorm(vmin=1, vmax=hist_azimuth.max()), + cmap="viridis", + shading="auto", +) +axes[2].plot( + [-15, 15], + [-15, 15], + "k--", + linewidth=1.5, + label="Perfect reconstruction", +) +axes[2].set_xlim(-15, 15) +axes[2].set_ylim(-15, 15) +axes[2].set_xlabel("True azimuth relative to 0° [deg]") +axes[2].set_ylabel("Reconstructed azimuth relative to 0° [deg]") +axes[2].set_title("Azimuth migration") +axes[2].set_xticks([-15, -10, -5, 0, 5, 10, 15]) +axes[2].set_yticks([-15, -10, -5, 0, 5, 10, 15]) +axes[2].legend(loc="upper left") +fig.colorbar(azimuth_mesh, ax=axes[2]).set_label("Number of events") +plt.tight_layout() +plt.show() + +###################################################################### +# 3. IACT-specific performance metrics +# ------------------------------------ +# +# The last cell shows some IACT-specific performance metrics, in particular +# the energy resolution and angular resolution of the reconstructed events. +# These plots provide a first visual impression of how well the model +# reconstructs the physical properties of the gamma-ray events. It is +# important to note that these are simple plots of the reconstruction +# performance without applying any selection cuts based on the gammaness +# classifier. Therefore, they should not be confused with the **Instrument +# Response Functions (IRFs)** used in standard IACT analyses. The production +# of IRFs involves a dedicated analysis workflow and additional selections +# and calculations. Separate tools within ctapipe are available to build +# these higher-level analysis products, and they can be applied directly to +# the CTLearn DL2 data because the files follow the reference implementation +# of the CTAO data model. +# +# For this tutorial, the purpose is simply to obtain a first visual impression +# of the energy and angular reconstruction performance and to become familiar +# with the corresponding analysis workflow. As emphasized throughout this +# tutorial, the available statistics are very limited, so the resulting +# curves should not be interpreted as meaningful or competitive instrument +# performance measurements, nor should they be compared directly with +# published IACT performance results. + +fig, axes = plt.subplots(1, 2, figsize=(16, 7)) +ctaplot.plot_energy_resolution( + true_energy * u.TeV, + reco_energy * u.TeV, + label="CTLearn", + ax=axes[0], +) +ctaplot.plot_energy_resolution_cta_requirement("north", ax=axes[0], color="black") +axes[0].legend() +axes[0].set_title("Energy resolution") + +ctaplot.plot_angular_resolution_per_energy( + true_alt * u.deg, + reco_alt * u.deg, + true_az * u.deg, + reco_az * u.deg, + true_energy * u.TeV, + label="CTLearn", + ax=axes[1], +) +ctaplot.plot_angular_resolution_cta_requirement("north", ax=axes[1], color="black") +axes[1].legend() +axes[1].set_title("Angular resolution") +plt.tight_layout() +plt.show() + + +###################################################################### +# 4. Browsing through the HDF5 files via ViTables +# ----------------------------------------------- +# +# Use ViTables, a convenient GUI, to explore the CTLearn DL2 predictions. The +# file follows the reference implementation of the CTAO data model. +# +# .. code-block:: console +# +# pip install vitables +# vitables $HOME/.cache/ctlearn/tutorial-training/predictions/*.dl2.h5 +# +# Note that the ViTables GUI is not available in this notebook environment, so +# the command is shown here for reference. In a local environment, you can run +# the command in a terminal to open the ViTables GUI and explore the DL2 +# predictions interactively. The GUI allows you to browse through the tables, +# view the data and metadata, and perform basic operations on the HDF5 files. +# This can be useful for inspecting individual events, checking the structure +# of the data, and verifying that the predictions are stored correctly. + +###################################################################### +# Part C: Stereoscopic CNN-based model inference +# ============================================== +# +# We perform inference with the previously trained stereoscopic energy model. +# The telescope images are combined channel-wise and passed to the CNN, +# allowing the model to use information from multiple telescopes +# simultaneously. As above, the same configuration used during training +# should be used for inference, in particular the stereoscopic image reader +# settings and telescope stacking options. Since the stereoscopic input is +# larger than the monoscopic input, a reduced batch size may be required to +# account for the increased memory consumption. +# +# The following commands run the inference with both the Keras and PyTorch +# models. + +###################################################################### +# 1. Keras stereoscopic model prediction +# -------------------------------------- + +run_command_line( + """ctlearn-predict-stereo-model --verbose \\ + --input_url "$CTLEARN_TUTORIAL_CONVERTED_DIR/gamma-diffuse_with_images_01.dl2.h5" \\ + --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/predictions/gamma-diffuse_with_images_01.ctlearn.stereo.dl2.h5" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/dl1dh_example_config.json" \\ + --energy_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-stereo-energy/ctlearn_model.keras" \\ + --DLImageReader.mode stereo --DLImageReader.min_telescopes 2 \\ + --TableQualityQuery.quality_criteria "[]" \\ + --PredictCTLearnModel.stack_telescope_images True \\ + --PredictCTLearnModel.batch_size 2 \\ + --overwrite""" +) +run_command_line( + """ctlearn-predict-stereo-model --verbose \\ + --input_url "$CTLEARN_TUTORIAL_CONVERTED_DIR/proton_with_images_01.dl2.h5" \\ + --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/predictions/proton_with_images_01.ctlearn.stereo.dl2.h5" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/dl1dh_example_config.json" \\ + --energy_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-stereo-energy/ctlearn_model.keras" \\ + --DLImageReader.mode stereo --DLImageReader.min_telescopes 2 \\ + --TableQualityQuery.quality_criteria "[]" \\ + --PredictCTLearnModel.stack_telescope_images True \\ + --PredictCTLearnModel.batch_size 2 \\ + --overwrite""" +) + +###################################################################### +# 2. PyTorch stereoscopic model prediction +# ---------------------------------------- + +run_command_line( + """ctlearn-predict-stereo-model --verbose \\ + --input_url "$CTLEARN_TUTORIAL_CONVERTED_DIR/gamma-diffuse_with_images_01.dl2.h5" \\ + --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/predictions/gamma-diffuse_with_images_01.pytorch.ctlearn.stereo.dl2.h5" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/dl1dh_example_config.json" \\ + --energy_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-stereo-energy/ctlearn_model.pth" \\ + --DLImageReader.mode stereo --DLImageReader.min_telescopes 2 \\ + --TableQualityQuery.quality_criteria "[]" \\ + --PredictCTLearnModel.stack_telescope_images True \\ + --PredictCTLearnModel.batch_size 2 \\ + --overwrite""" +) +run_command_line( + """ctlearn-predict-stereo-model --verbose \\ + --input_url "$CTLEARN_TUTORIAL_CONVERTED_DIR/proton_with_images_01.dl2.h5" \\ + --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/predictions/proton_with_images_01.pytorch.ctlearn.stereo.dl2.h5" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/dl1dh_example_config.json" \\ + --energy_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-stereo-energy/ctlearn_model.pth" \\ + --DLImageReader.mode stereo --DLImageReader.min_telescopes 2 \\ + --TableQualityQuery.quality_criteria "[]" \\ + --PredictCTLearnModel.stack_telescope_images True \\ + --PredictCTLearnModel.batch_size 2 \\ + --overwrite""" +) + +###################################################################### +# Part D: CNN-based model inference using waveform data +# ----------------------------------------------------- +# +# We perform inference with the previously trained mono energy model using +# waveform data. The configuration must be consistent with the training +# setup. An important configuration change is required to read waveform data: +# the ``--PredictCTLearnModel.dl1dh_reader_type`` option must be set to the +# appropriate DL1 data reader component for waveform reading +# (**DLWaveformReader**) rather than the default image reader. +# +# For this demonstration, we use the same data file as used during training, +# since suitable test data are currently not available. This is done only to +# demonstrate that the software workflow is functional. In a real analysis, +# using training data for testing is not valid practice. +# +# The following commands run the inference with both the Keras and PyTorch +# models. + +WAVEFORM_FILE = DATA_DIR / f"gamma_prod5{MAX_EVENTS_SUFFIX}.r1.dl1.h5" +if not WAVEFORM_FILE.is_file(): + raise FileNotFoundError( + f"Cached waveform data is missing: {WAVEFORM_FILE}. " + "Run examples/tutorials/explore_public_data.py first." + ) + +###################################################################### +# 1. Keras waveform model prediction +# ---------------------------------- + +run_command_line( + """ctlearn-predict-mono-model --verbose \\ + --input_url "$CTLEARN_TUTORIAL_DATA_DIR/gamma_prod5${CTLEARN_TUTORIAL_MAX_EVENTS_SUFFIX}.r1.dl1.h5" \\ + --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/predictions/gamma_prod5.keras.waveform.dl2.h5" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/dl1dh_example_config.json" \\ + --energy_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-waveform-energy/ctlearn_model.keras" \\ + --PredictCTLearnModel.dl1dh_reader_type DLWaveformReader \\ + --PredictCTLearnModel.batch_size 2 \\ + --TableQualityQuery.quality_criteria "[]" \\ + --overwrite""" +) + +###################################################################### +# 2. PyTorch waveform model prediction +# ------------------------------------ + +run_command_line( + """ctlearn-predict-mono-model --verbose \\ + --input_url "$CTLEARN_TUTORIAL_DATA_DIR/gamma_prod5${CTLEARN_TUTORIAL_MAX_EVENTS_SUFFIX}.r1.dl1.h5" \\ + --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/predictions/gamma_prod5.pytorch.waveform.dl2.h5" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/dl1dh_example_config.json" \\ + --energy_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-waveform-energy/ctlearn_model.pth" \\ + --PredictCTLearnModel.dl1dh_reader_type DLWaveformReader \\ + --PredictCTLearnModel.batch_size 2 \\ + --TableQualityQuery.quality_criteria "[]" \\ + --overwrite""" +) + +###################################################################### +# Part E: CNN-based model inference using LST-1 lstchain data +# =========================================================== +# +# The following three cells demonstrate the prediction tool for LST-1 DL1 +# data in the lstchain format. Since LST-1 data are private to the LST-1 +# collaboration and cannot be distributed, the first cell creates a mock +# dataset in the required format. The second cell displays the tool help and +# its available options. The final cell performs inference on the mock data +# using the models trained in the previous notebook. The tool predicts +# gammaness, energy, and arrival direction and writes the results to a ctapipe +# DL2 output file, together with the relevant LST-1 subarray, trigger, +# pointing, and DL1b parameter information. +# +# **Note**: This prediction tool is specifically designed for the lstchain +# DL1 format and should not be used with other input data formats. +# +# The inference commands below use the Keras and PyTorch models. + +n_events = 25 +rng = np.random.default_rng(1234) +subarray = get_lst1_subarray_description() +tel_id = 1 +n_pixels = subarray.tel[tel_id].camera.geometry.n_pixels +event_ids = np.arange(1, n_events + 1, dtype=np.int64) +mock_lst1_file = PREDICTION_DIR / "mock_data_lst1.dl1.h5" + +image_table = Table() +image_table["obs_id"] = np.ones(n_events, dtype=np.int64) +image_table["event_id"] = event_ids +image_table["tel_id"] = np.full(n_events, tel_id, dtype=np.int16) +image_table.add_column( + Column( + rng.uniform(80, 150, size=(n_events, n_pixels)).astype(np.float32), + name="image", + dtype=np.float32, + shape=(n_pixels,), + ) +) +image_table.add_column( + Column( + rng.integers(0, 2, size=(n_events, n_pixels), dtype=bool), + name="image_mask", + dtype=bool, + shape=(n_pixels,), + ) +) +image_table.add_column( + Column( + rng.normal(5.0, 0.5, size=(n_events, n_pixels)).astype(np.float32), + name="peak_time", + dtype=np.float32, + shape=(n_pixels,), + ) +) + +parameter_table = Table() +parameter_table["obs_id"] = np.ones(n_events, dtype=np.int64) +parameter_table["event_id"] = event_ids +parameter_table["tel_id"] = np.full(n_events, tel_id, dtype=np.int16) +parameter_table["intensity"] = rng.uniform(90, 140, size=n_events) +parameter_table["x"] = rng.normal(0.0, 0.05, size=n_events) +parameter_table["y"] = rng.normal(0.0, 0.05, size=n_events) +parameter_table["phi"] = rng.uniform(-np.pi, np.pi, size=n_events) +parameter_table["psi"] = rng.uniform(-np.pi, np.pi, size=n_events) +parameter_table["length"] = rng.uniform(0.05, 0.15, size=n_events) +parameter_table["length_uncertainty"] = rng.uniform(0.001, 0.003, size=n_events) +parameter_table["width"] = rng.uniform(0.02, 0.08, size=n_events) +parameter_table["width_uncertainty"] = rng.uniform(0.001, 0.003, size=n_events) +parameter_table["skewness"] = rng.normal(0.0, 0.2, size=n_events) +parameter_table["kurtosis"] = rng.normal(0.0, 0.2, size=n_events) +parameter_table["time_gradient"] = rng.normal(0.0, 0.01, size=n_events) +parameter_table["intercept"] = rng.normal(0.0, 0.01, size=n_events) +parameter_table["n_pixels"] = np.full(n_events, n_pixels, dtype=np.int16) +parameter_table["n_islands"] = np.zeros(n_events, dtype=np.int16) +parameter_table["event_type"] = np.full(n_events, 32, dtype=np.int16) +parameter_table["az_tel"] = np.full(n_events, 1.0) +parameter_table["alt_tel"] = np.full(n_events, 1.2) +parameter_table["dragon_time"] = np.linspace(1_700_000_000, 1_700_000_300, n_events) + +subarray.to_hdf(mock_lst1_file, overwrite=True) +write_table( + image_table, + mock_lst1_file, + "/dl1/event/telescope/image/LST_LSTCam", + overwrite=True, +) +write_table( + parameter_table, + mock_lst1_file, + "/dl1/event/telescope/parameters/LST_LSTCam", + overwrite=True, +) + +run_command_line("ctlearn-predict-LST1 -h") + +###################################################################### +# 1. Keras model prediction using LST-1 lstchain mock data +# -------------------------------------------------------- + +run_command_line( + """ctlearn-predict-LST1 --verbose \\ + --input_url "$CTLEARN_TUTORIAL_OUTPUT_DIR/predictions/mock_data_lst1.dl1.h5" \\ + --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/predictions/mock_data_lst1.keras.ctlearn.dl2.h5" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/dl1dh_example_config.json" \\ + --type_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-classification/ctlearn_model.keras" \\ + --energy_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-energy/ctlearn_model.keras" \\ + --cameradirection_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-cameradirection/ctlearn_model.keras" \\ + --LST1PredictionTool.batch_size 5 \\ + --LST1PredictionTool.channels cleaned_image \\ + --LST1PredictionTool.channels cleaned_relative_peak_time \\ + --LST1PredictionTool.image_mapper_type BilinearMapper \\ + --TableQualityQuery.quality_criteria "[]" \\ + --overwrite""" +) + +###################################################################### +# 2. PyTorch model prediction using LST-1 lstchain mock data +# ---------------------------------------------------------- + +run_command_line( + """ctlearn-predict-LST1 --verbose \\ + --input_url "$CTLEARN_TUTORIAL_OUTPUT_DIR/predictions/mock_data_lst1.dl1.h5" \\ + --output "$CTLEARN_TUTORIAL_OUTPUT_DIR/predictions/mock_data_lst1.pytorch.ctlearn.dl2.h5" \\ + --config "$CTLEARN_TUTORIAL_CONFIG_DIR/dl1dh_example_config.json" \\ + --type_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-classification/ctlearn_model.pth" \\ + --energy_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-energy/ctlearn_model.pth" \\ + --cameradirection_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-cameradirection/ctlearn_model.pth" \\ + --LST1PredictionTool.batch_size 5 \\ + --LST1PredictionTool.channels cleaned_image \\ + --LST1PredictionTool.channels cleaned_relative_peak_time \\ + --LST1PredictionTool.image_mapper_type BilinearMapper \\ + --TableQualityQuery.quality_criteria "[]" \\ + --overwrite""" +) diff --git a/examples/tutorials/train_ctlearn_model.py b/examples/tutorials/train_ctlearn_model.py index 00f9212c..c4f62410 100644 --- a/examples/tutorials/train_ctlearn_model.py +++ b/examples/tutorials/train_ctlearn_model.py @@ -1,6 +1,6 @@ """ -Train CTLearn models -==================== +Tutorial 2: Train CTLearn models +================================ Train models for CTAO image and waveform data with CTLearn. The image examples use only the gamma-ray and proton ``00`` files; the ``01`` files @@ -178,6 +178,7 @@ def find_config_dir(): def run_command_line(command): + print(f"Running command: $ {command.strip()}") result = subprocess.run( command, shell=True, @@ -200,7 +201,7 @@ def run_command_line(command): ###################################################################### # 1. Primary particle energy regression -# -------------------------------------- +# ------------------------------------- # # The model reconstructs the energy of the primary particle as a continuous # value. Internally, CTLearn performs the regression on the energy in TeV and diff --git a/pyproject.toml b/pyproject.toml index 32abf344..7909e4d7 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -86,6 +86,8 @@ tests = [ docs = [ "ctlearn[all]", + "ctaplot", + "scikit-learn", "sphinx", "sphinx-gallery >= 0.16.0", "sphinx-changelog", From 1ee623e260d09d656d01b66697ce3e48147c9692 Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Tue, 10 Nov 2026 11:48:36 +0100 Subject: [PATCH 35/53] polish train and predict tutorials --- examples/tutorials/predict_ctlearn_model.py | 33 ++++++++++++++------- examples/tutorials/train_ctlearn_model.py | 7 +++++ 2 files changed, 30 insertions(+), 10 deletions(-) diff --git a/examples/tutorials/predict_ctlearn_model.py b/examples/tutorials/predict_ctlearn_model.py index 4c52df64..87917940 100644 --- a/examples/tutorials/predict_ctlearn_model.py +++ b/examples/tutorials/predict_ctlearn_model.py @@ -2,18 +2,31 @@ Tutorial 3: Perform inference with CTlearn models ================================================= -For this notebook, one would need to download the HDF5 data files from the -CTAO opendata folder (https://cloud.iaa.es/index.php/s/77d6MK4rGfanSKx) and -the trained models of ``train_ctlearn_model.py``. +Predict the CTAO image and waveform data using the CTLearn models +from the second tutorial ``train_ctlearn_model.py``. The predictions +are stored in DL2 files following the CTAO reference data model. +The tutorial also shows how to visualize the classifier performance, +energy resolution, and angular resolution of the predicted events. +The tutorial is intenionally kept simple and uses only a small fraction +of the available statistics to keep the prediction time manageable. +The resulting performance metrics are not representative of a production-level +analysis nor should they be compared directly with published results. The main +goal is to illustrate the analysis workflow and to become familiar with the +command-line tools and the DL2 data format. This tutorial can be modified from +the users to use larger datasets and more statistics to obtain meaningful results. + +Each section explains a prediction task followed immediately by its literal +command-line example. Running this script executes every example in order. """ ###################################################################### # Check paths, environments, CTAO test data, and trained models # ------------------------------------------------------------- # -# The executable tutorial uses the shared downloaded data and the Keras and -# PyTorch models produced by ``train_ctlearn_model.py``. In a notebook, prefix -# the displayed command-line examples with ``!``. +# The executable tutorial uses the shared downloaded and processed data +# from ``explore_public_data.py`` and the Keras and PyTorch models produced +# by ``train_ctlearn_model.py``. In a notebook, prefix the displayed +# command-line examples with ``!``. import os import subprocess @@ -26,7 +39,6 @@ from astropy.table import Column, Table from ctapipe import __version__ as ctapipe_version from ctapipe.io import TableLoader, write_table -from matplotlib.colors import LogNorm from sklearn.metrics import auc, roc_curve from ctlearn.tools.utils import get_lst1_subarray_description @@ -186,6 +198,7 @@ def run_command_line(command): --type_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-classification/ctlearn_model.keras" \\ --energy_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-energy/ctlearn_model.keras" \\ --cameradirection_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-cameradirection/ctlearn_model.keras" \\ + --PredictCTLearnModel.batch_size 16 \\ --overwrite""" ) run_command_line( @@ -196,6 +209,7 @@ def run_command_line(command): --type_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-classification/ctlearn_model.keras" \\ --energy_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-energy/ctlearn_model.keras" \\ --cameradirection_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/keras-cameradirection/ctlearn_model.keras" \\ + --PredictCTLearnModel.batch_size 16 \\ --overwrite""" ) @@ -215,6 +229,7 @@ def run_command_line(command): --type_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-classification/ctlearn_model.pth" \\ --energy_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-energy/ctlearn_model.pth" \\ --cameradirection_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-cameradirection/ctlearn_model.pth" \\ + --PredictCTLearnModel.batch_size 16 \\ --overwrite""" ) run_command_line( @@ -225,6 +240,7 @@ def run_command_line(command): --type_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-classification/ctlearn_model.pth" \\ --energy_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-energy/ctlearn_model.pth" \\ --cameradirection_model "$CTLEARN_TUTORIAL_OUTPUT_DIR/pytorch-cameradirection/ctlearn_model.pth" \\ + --PredictCTLearnModel.batch_size 16 \\ --overwrite""" ) @@ -471,7 +487,6 @@ def read_valid_telescope_events(filename): true_energy_edges, reco_energy_edges, np.ma.masked_where(hist_energy == 0, hist_energy).T, - norm=LogNorm(vmin=1, vmax=hist_energy.max()), cmap="viridis", shading="auto", ) @@ -502,7 +517,6 @@ def read_valid_telescope_events(filename): true_altitude_edges, reco_altitude_edges, np.ma.masked_where(hist_altitude == 0, hist_altitude).T, - norm=LogNorm(vmin=1, vmax=hist_altitude.max()), cmap="viridis", shading="auto", ) @@ -529,7 +543,6 @@ def read_valid_telescope_events(filename): true_azimuth_edges, reco_azimuth_edges, np.ma.masked_where(hist_azimuth == 0, hist_azimuth).T, - norm=LogNorm(vmin=1, vmax=hist_azimuth.max()), cmap="viridis", shading="auto", ) diff --git a/examples/tutorials/train_ctlearn_model.py b/examples/tutorials/train_ctlearn_model.py index c4f62410..f6c459e0 100644 --- a/examples/tutorials/train_ctlearn_model.py +++ b/examples/tutorials/train_ctlearn_model.py @@ -5,6 +5,13 @@ Train models for CTAO image and waveform data with CTLearn. The image examples use only the gamma-ray and proton ``00`` files; the ``01`` files remain untouched for future evaluation tutorials. +The tutorial is intenionally kept simple and uses only a small fraction +of the available statistics to keep the training time manageable. +The resulting performance metrics are not representative of a production-level +analysis nor should they be compared directly with published results. The main +goal is to illustrate the analysis workflow and to become familiar with the +command-line tools and the DL2 data format. This tutorial can be modified from +the users to use larger datasets and more statistics to obtain meaningful results. Each section explains a training task followed immediately by its literal command-line example. Running this script executes every example in order. From 324e2370377449d35b7906f76328f69f3b95c281 Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Tue, 10 Nov 2026 12:40:15 +0100 Subject: [PATCH 36/53] add tutorial number to part sections --- examples/tutorials/explore_public_data.py | 6 +++--- examples/tutorials/predict_ctlearn_model.py | 10 +++++----- examples/tutorials/train_ctlearn_model.py | 14 +++++++------- 3 files changed, 15 insertions(+), 15 deletions(-) diff --git a/examples/tutorials/explore_public_data.py b/examples/tutorials/explore_public_data.py index 2e5b4561..07e3c202 100644 --- a/examples/tutorials/explore_public_data.py +++ b/examples/tutorials/explore_public_data.py @@ -99,7 +99,7 @@ print(f"Using existing processed file: {gamma_dl1_path}") ###################################################################### -# Part A: Read calibrated waveforms +# Part A1: Read calibrated waveforms # ================================= # # DL1DataHandler can read calibrated waveforms and map each camera into a @@ -184,7 +184,7 @@ def update( plt.show() ###################################################################### -# Part B: Read monoscopic images +# Part B1: Read monoscopic images # ============================== # # The image reader returns integrated charge and relative peak-time images. @@ -283,7 +283,7 @@ def update( print(f"Using existing ctapipe output: {output_path}") ###################################################################### -# Part C: Read stereo images +# Part C1: Read stereo images # ========================== # # Finally, combine gamma and proton events in stereo mode and plot the diff --git a/examples/tutorials/predict_ctlearn_model.py b/examples/tutorials/predict_ctlearn_model.py index 87917940..083034f6 100644 --- a/examples/tutorials/predict_ctlearn_model.py +++ b/examples/tutorials/predict_ctlearn_model.py @@ -163,7 +163,7 @@ def run_command_line(command): run_command_line("ctlearn-predict-stereo-model -h") ###################################################################### -# Part A: Monoscopic CNN-based model inference +# Part A3: Monoscopic CNN-based model inference # ============================================ # # We perform inference using the three previously trained CTLearn models from @@ -245,7 +245,7 @@ def run_command_line(command): ) ###################################################################### -# Part B: Exploring the produced CTLearn DL2 data +# Part B3: Exploring the produced CTLearn DL2 data # =============================================== # # In the following cells, we will explore the DL2 predictions produced by the @@ -639,7 +639,7 @@ def read_valid_telescope_events(filename): # of the data, and verifying that the predictions are stored correctly. ###################################################################### -# Part C: Stereoscopic CNN-based model inference +# Part C3: Stereoscopic CNN-based model inference # ============================================== # # We perform inference with the previously trained stereoscopic energy model. @@ -713,7 +713,7 @@ def read_valid_telescope_events(filename): ) ###################################################################### -# Part D: CNN-based model inference using waveform data +# Part D3: CNN-based model inference using waveform data # ----------------------------------------------------- # # We perform inference with the previously trained mono energy model using @@ -771,7 +771,7 @@ def read_valid_telescope_events(filename): ) ###################################################################### -# Part E: CNN-based model inference using LST-1 lstchain data +# Part E3: CNN-based model inference using LST-1 lstchain data # =========================================================== # # The following three cells demonstrate the prediction tool for LST-1 DL1 diff --git a/examples/tutorials/train_ctlearn_model.py b/examples/tutorials/train_ctlearn_model.py index f6c459e0..8d94d9e6 100644 --- a/examples/tutorials/train_ctlearn_model.py +++ b/examples/tutorials/train_ctlearn_model.py @@ -198,7 +198,7 @@ def run_command_line(command): ###################################################################### -# Part A: Monoscopic CNN-based model training +# Part A2: Monoscopic CNN-based model training # =========================================== # # We first train a basic monoscopic CNN-based model using the default CTLearn @@ -376,7 +376,7 @@ def run_command_line(command): ) ###################################################################### -# Part B: Customizing the CTLearn model architecture +# Part B2: Customizing the CTLearn model architecture # ================================================== # # CTLearn provides a flexible configuration system that allows users to @@ -481,7 +481,7 @@ def run_command_line(command): ) ###################################################################### -# Part C: Using a pre-trained model and transfer learning +# Part C2: Using a pre-trained model and transfer learning # ======================================================= # # The LoadedModel component allows a previously trained model following @@ -534,7 +534,7 @@ def run_command_line(command): ) ###################################################################### -# Part D: Stereoscopic CNN-based model training +# Part D2: Stereoscopic CNN-based model training # --------------------------------------------- # # CTLearn currently provides a basic approach for stereoscopic CNN-based @@ -596,7 +596,7 @@ def run_command_line(command): ) ###################################################################### -# Part E: CNN-based model training using waveform data +# Part E2: CNN-based model training using waveform data # ==================================================== # # The final example demonstrates training directly on waveform data. The @@ -656,7 +656,7 @@ def run_command_line(command): ) ###################################################################### -# Part F: Comparing training curves +# Part F2: Comparing training curves # ================================= # # Each training run writes its metrics to ``training_log.csv`` together @@ -785,7 +785,7 @@ def plot_metric(ax, run_name, metric, label, color, **kwargs): plt.show() ###################################################################### -# Part G: Monitoring training with TensorBoard +# Part G2: Monitoring training with TensorBoard # ============================================ # # CTLearn also writes TensorBoard event files, which are useful for monitoring From 127c42b16949c35328e4be99b4894efea3090dda Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Tue, 10 Nov 2026 12:58:12 +0100 Subject: [PATCH 37/53] further polishing docs --- examples/tutorials/GALLERY_HEADER.rst | 15 ++++++++-- examples/tutorials/explore_public_data.py | 16 +++++------ examples/tutorials/predict_ctlearn_model.py | 24 ++++++++-------- examples/tutorials/train_ctlearn_model.py | 32 ++++++++++----------- 4 files changed, 49 insertions(+), 38 deletions(-) diff --git a/examples/tutorials/GALLERY_HEADER.rst b/examples/tutorials/GALLERY_HEADER.rst index bde7b10b..bb3caca3 100644 --- a/examples/tutorials/GALLERY_HEADER.rst +++ b/examples/tutorials/GALLERY_HEADER.rst @@ -1,5 +1,16 @@ CTLearn tutorials ================= -Step-by-step examples for downloading public CTAO data and exploring -waveforms and images with CTLearn's data-reading tools. +Step-by-step examples for downloading and exploring public CTAO data, +training CTLearn models, and running inference on image and waveform data. + +The tutorials use small datasets to keep the examples manageable. Their +performance metrics are for demonstrating the workflow and are not +representative of a production-level analysis. **Tutorial 1** downloads and +converts the public simulation data and explores its waveforms and images. +**Tutorial 2** trains CTLearn models with Keras and PyTorch using image and +waveform data. **Tutorial 3** runs inference with those models, explores the +resulting DL2 data, and plots classification and reconstruction performance. + +Run the tutorials in order: the training tutorial uses data prepared by +Tutorial 1, and the prediction tutorial uses models created by Tutorial 2. diff --git a/examples/tutorials/explore_public_data.py b/examples/tutorials/explore_public_data.py index 07e3c202..eba53fd2 100644 --- a/examples/tutorials/explore_public_data.py +++ b/examples/tutorials/explore_public_data.py @@ -1,6 +1,6 @@ """ -Tutorial 1: Explore Public CTAO Data -==================================== +**Tutorial 1**: Explore Public CTAO Data +======================================== Download public CTAO simulation data, convert it with ctapipe, and explore waveforms and images using DL1DataHandler. @@ -99,8 +99,8 @@ print(f"Using existing processed file: {gamma_dl1_path}") ###################################################################### -# Part A1: Read calibrated waveforms -# ================================= +# *Part A1*: Read calibrated waveforms +# ==================================== # # DL1DataHandler can read calibrated waveforms and map each camera into a # regular image. Here we display an animation of the waveform samples for @@ -184,8 +184,8 @@ def update( plt.show() ###################################################################### -# Part B1: Read monoscopic images -# ============================== +# *Part B1*: Read monoscopic images +# ================================= # # The image reader returns integrated charge and relative peak-time images. # The mapper is selected for each camera type. @@ -283,8 +283,8 @@ def update( print(f"Using existing ctapipe output: {output_path}") ###################################################################### -# Part C1: Read stereo images -# ========================== +# *Part C1*: Read stereo images +# ============================= # # Finally, combine gamma and proton events in stereo mode and plot the # integrated charge and relative peak-time image from each telescope. diff --git a/examples/tutorials/predict_ctlearn_model.py b/examples/tutorials/predict_ctlearn_model.py index 083034f6..0780cac2 100644 --- a/examples/tutorials/predict_ctlearn_model.py +++ b/examples/tutorials/predict_ctlearn_model.py @@ -1,6 +1,6 @@ """ -Tutorial 3: Perform inference with CTlearn models -================================================= +**Tutorial 3**: Perform inference with CTlearn models +===================================================== Predict the CTAO image and waveform data using the CTLearn models from the second tutorial ``train_ctlearn_model.py``. The predictions @@ -163,8 +163,8 @@ def run_command_line(command): run_command_line("ctlearn-predict-stereo-model -h") ###################################################################### -# Part A3: Monoscopic CNN-based model inference -# ============================================ +# *Part A3*: Monoscopic CNN-based model inference +# =============================================== # # We perform inference using the three previously trained CTLearn models from # ``train_ctlearn_model.py``: the primary particle type (classification), @@ -245,8 +245,8 @@ def run_command_line(command): ) ###################################################################### -# Part B3: Exploring the produced CTLearn DL2 data -# =============================================== +# *Part B3*: Exploring the produced CTLearn DL2 data +# ================================================== # # In the following cells, we will explore the DL2 predictions produced by the # CTLearn models. Keep in mind that, for this hands-on tutorial, we trained @@ -639,8 +639,8 @@ def read_valid_telescope_events(filename): # of the data, and verifying that the predictions are stored correctly. ###################################################################### -# Part C3: Stereoscopic CNN-based model inference -# ============================================== +# *Part C3*: Stereoscopic CNN-based model inference +# ================================================= # # We perform inference with the previously trained stereoscopic energy model. # The telescope images are combined channel-wise and passed to the CNN, @@ -713,8 +713,8 @@ def read_valid_telescope_events(filename): ) ###################################################################### -# Part D3: CNN-based model inference using waveform data -# ----------------------------------------------------- +# *Part D3*: CNN-based model inference using waveform data +# ======================================================== # # We perform inference with the previously trained mono energy model using # waveform data. The configuration must be consistent with the training @@ -771,8 +771,8 @@ def read_valid_telescope_events(filename): ) ###################################################################### -# Part E3: CNN-based model inference using LST-1 lstchain data -# =========================================================== +# *Part E3*: CNN-based model inference using LST-1 lstchain data +# ============================================================== # # The following three cells demonstrate the prediction tool for LST-1 DL1 # data in the lstchain format. Since LST-1 data are private to the LST-1 diff --git a/examples/tutorials/train_ctlearn_model.py b/examples/tutorials/train_ctlearn_model.py index 8d94d9e6..4fcb5c96 100644 --- a/examples/tutorials/train_ctlearn_model.py +++ b/examples/tutorials/train_ctlearn_model.py @@ -1,6 +1,6 @@ """ -Tutorial 2: Train CTLearn models -================================ +**Tutorial 2**: Train CTLearn models +==================================== Train models for CTAO image and waveform data with CTLearn. The image examples use only the gamma-ray and proton ``00`` files; the ``01`` files @@ -198,8 +198,8 @@ def run_command_line(command): ###################################################################### -# Part A2: Monoscopic CNN-based model training -# =========================================== +# *Part A2*: Monoscopic CNN-based model training +# ============================================== # # We first train a basic monoscopic CNN-based model using the default CTLearn # model configuration. The model uses a **ThinResNet** backbone for feature @@ -376,8 +376,8 @@ def run_command_line(command): ) ###################################################################### -# Part B2: Customizing the CTLearn model architecture -# ================================================== +# *Part B2*: Customizing the CTLearn model architecture +# ===================================================== # # CTLearn provides a flexible configuration system that allows users to # customize the neural network architecture. @@ -481,8 +481,8 @@ def run_command_line(command): ) ###################################################################### -# Part C2: Using a pre-trained model and transfer learning -# ======================================================= +# *Part C2*: Using a pre-trained model and transfer learning +# ========================================================== # # The LoadedModel component allows a previously trained model following # the CTLearnModel structure to be loaded for either resuming training or @@ -534,8 +534,8 @@ def run_command_line(command): ) ###################################################################### -# Part D2: Stereoscopic CNN-based model training -# --------------------------------------------- +# *Part D2*: Stereoscopic CNN-based model training +# ================================================ # # CTLearn currently provides a basic approach for stereoscopic CNN-based # model training. The images from the different telescopes are concatenated @@ -596,8 +596,8 @@ def run_command_line(command): ) ###################################################################### -# Part E2: CNN-based model training using waveform data -# ==================================================== +# *Part E2*: CNN-based model training using waveform data +# ======================================================= # # The final example demonstrates training directly on waveform data. The # example dataset used in this tutorial is intentionally very small, so @@ -656,8 +656,8 @@ def run_command_line(command): ) ###################################################################### -# Part F2: Comparing training curves -# ================================= +# *Part F2*: Comparing training curves +# ==================================== # # Each training run writes its metrics to ``training_log.csv`` together # with the TensorBoard model checkpoints for training and validation, @@ -785,8 +785,8 @@ def plot_metric(ax, run_name, metric, label, color, **kwargs): plt.show() ###################################################################### -# Part G2: Monitoring training with TensorBoard -# ============================================ +# *Part G2*: Monitoring training with TensorBoard +# =============================================== # # CTLearn also writes TensorBoard event files, which are useful for monitoring # metrics live or exploring additional details after training. The tutorial From c792894e89bfa6693826bc5bee0fa47c2ff705b7 Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Tue, 10 Nov 2026 14:21:55 +0100 Subject: [PATCH 38/53] add three boxes for user/dev guide and api docs --- docs/source/{modules.rst => api.rst} | 4 +-- docs/source/contributing.rst | 5 +++ .../source/{installation.rst => devguide.rst} | 7 ++++ docs/source/index.rst | 28 ++++++++++++++-- docs/source/{tutorials.rst => userguide.rst} | 15 ++++----- examples/tutorials/explore_public_data.py | 16 +++++----- examples/tutorials/predict_ctlearn_model.py | 24 +++++++------- examples/tutorials/train_ctlearn_model.py | 32 +++++++++---------- 8 files changed, 81 insertions(+), 50 deletions(-) rename docs/source/{modules.rst => api.rst} (70%) create mode 100644 docs/source/contributing.rst rename docs/source/{installation.rst => devguide.rst} (97%) rename docs/source/{tutorials.rst => userguide.rst} (96%) diff --git a/docs/source/modules.rst b/docs/source/api.rst similarity index 70% rename from docs/source/modules.rst rename to docs/source/api.rst index 5f071185..f5aed739 100644 --- a/docs/source/modules.rst +++ b/docs/source/api.rst @@ -1,5 +1,5 @@ -ctlearn -======= +API Docs +======== .. toctree:: :maxdepth: 4 diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst new file mode 100644 index 00000000..30bb0428 --- /dev/null +++ b/docs/source/contributing.rst @@ -0,0 +1,5 @@ +Contributing +============ + +.. include:: ../../CONTRIBUTING.rst + :start-line: 3 diff --git a/docs/source/installation.rst b/docs/source/devguide.rst similarity index 97% rename from docs/source/installation.rst rename to docs/source/devguide.rst index 3adccc29..186f6db9 100644 --- a/docs/source/installation.rst +++ b/docs/source/devguide.rst @@ -65,6 +65,13 @@ provides the same project-managed environment used by CI. $ python -m pip install --upgrade pip $ python -m pip install -e ".[dev]" +Contributing +------------ + +.. toctree:: + :maxdepth: 1 + + contributing Installing on the IT Cluster ---------------------------- diff --git a/docs/source/index.rst b/docs/source/index.rst index fc9925b5..af3d6230 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -21,15 +21,37 @@ CTLearn: Deep Learning for IACT Event Reconstruction Use the version selector in the sidebar to switch between the current ``main`` documentation and published tagged releases. +.. grid:: 1 2 3 3 + :gutter: 3 + + .. grid-item-card:: User Guide + :link: userguide + :link-type: doc + + Explore the public CTAO data tutorials, train CTLearn models, and run + inference on image and waveform data. + + .. grid-item-card:: Developer Guide + :link: devguide + :link-type: doc + + Set up a development environment and contribute to CTLearn. + + .. grid-item-card:: API Docs + :link: api + :link-type: doc + + Browse the CTLearn Python package and its modules. + .. toctree:: :maxdepth: 2 :caption: Contents: - installation + devguide usage - tutorials + userguide supplementary - modules + api changelog Documentation diff --git a/docs/source/tutorials.rst b/docs/source/userguide.rst similarity index 96% rename from docs/source/tutorials.rst rename to docs/source/userguide.rst index 7420ad46..dcda31af 100644 --- a/docs/source/tutorials.rst +++ b/docs/source/userguide.rst @@ -1,9 +1,8 @@ -********* -Tutorials -********* +********** +User Guide +********** -Public CTAO data exploration ----------------------------- +**Public CTAO data exploration** This tutorial follows the executable Python-script style used by ctapipe's tutorials. It downloads a small SimTel sample for the monoscopic examples and @@ -29,8 +28,7 @@ CTLearn with its development dependencies and execute: The rendered tutorial, including its code, figures, and playable waveform animations, is generated by Sphinx-Gallery: -Training a CTLearn model ------------------------- +**Training a CTLearn model** The training tutorial documents monoscopic energy and direction regression, gamma/proton classification, custom ``SingleCNN`` and ``ResNet`` architectures, @@ -98,8 +96,7 @@ examples, run the script to execute the commands in sequence. Start TensorBoard for the resulting metrics with ``tensorboard --logdir ~/.cache/ctlearn/tutorial-training/``. -Predicting with CTLearn models ------------------------------- +**Predicting with CTLearn models** The prediction tutorial runs the Keras and PyTorch models produced by the training tutorial on the held-out ``01`` CTAO simulation files. Each command diff --git a/examples/tutorials/explore_public_data.py b/examples/tutorials/explore_public_data.py index eba53fd2..94c492ae 100644 --- a/examples/tutorials/explore_public_data.py +++ b/examples/tutorials/explore_public_data.py @@ -1,6 +1,6 @@ """ -**Tutorial 1**: Explore Public CTAO Data -======================================== +**Tutorial 1** Explore Public CTAO Data +======================================= Download public CTAO simulation data, convert it with ctapipe, and explore waveforms and images using DL1DataHandler. @@ -99,8 +99,8 @@ print(f"Using existing processed file: {gamma_dl1_path}") ###################################################################### -# *Part A1*: Read calibrated waveforms -# ==================================== +# *Part A1* Read calibrated waveforms +# =================================== # # DL1DataHandler can read calibrated waveforms and map each camera into a # regular image. Here we display an animation of the waveform samples for @@ -184,8 +184,8 @@ def update( plt.show() ###################################################################### -# *Part B1*: Read monoscopic images -# ================================= +# *Part B1* Read monoscopic images +# ================================ # # The image reader returns integrated charge and relative peak-time images. # The mapper is selected for each camera type. @@ -283,8 +283,8 @@ def update( print(f"Using existing ctapipe output: {output_path}") ###################################################################### -# *Part C1*: Read stereo images -# ============================= +# *Part C1* Read stereo images +# ============================ # # Finally, combine gamma and proton events in stereo mode and plot the # integrated charge and relative peak-time image from each telescope. diff --git a/examples/tutorials/predict_ctlearn_model.py b/examples/tutorials/predict_ctlearn_model.py index 0780cac2..805597c0 100644 --- a/examples/tutorials/predict_ctlearn_model.py +++ b/examples/tutorials/predict_ctlearn_model.py @@ -1,6 +1,6 @@ """ -**Tutorial 3**: Perform inference with CTlearn models -===================================================== +**Tutorial 3** Perform inference with CTlearn models +==================================================== Predict the CTAO image and waveform data using the CTLearn models from the second tutorial ``train_ctlearn_model.py``. The predictions @@ -163,8 +163,8 @@ def run_command_line(command): run_command_line("ctlearn-predict-stereo-model -h") ###################################################################### -# *Part A3*: Monoscopic CNN-based model inference -# =============================================== +# *Part A3* Monoscopic CNN-based model inference +# ============================================== # # We perform inference using the three previously trained CTLearn models from # ``train_ctlearn_model.py``: the primary particle type (classification), @@ -245,8 +245,8 @@ def run_command_line(command): ) ###################################################################### -# *Part B3*: Exploring the produced CTLearn DL2 data -# ================================================== +# *Part B3* Exploring the produced CTLearn DL2 data +# ================================================= # # In the following cells, we will explore the DL2 predictions produced by the # CTLearn models. Keep in mind that, for this hands-on tutorial, we trained @@ -639,8 +639,8 @@ def read_valid_telescope_events(filename): # of the data, and verifying that the predictions are stored correctly. ###################################################################### -# *Part C3*: Stereoscopic CNN-based model inference -# ================================================= +# *Part C3* Stereoscopic CNN-based model inference +# ================================================ # # We perform inference with the previously trained stereoscopic energy model. # The telescope images are combined channel-wise and passed to the CNN, @@ -713,8 +713,8 @@ def read_valid_telescope_events(filename): ) ###################################################################### -# *Part D3*: CNN-based model inference using waveform data -# ======================================================== +# *Part D3* CNN-based model inference using waveform data +# ======================================================= # # We perform inference with the previously trained mono energy model using # waveform data. The configuration must be consistent with the training @@ -771,8 +771,8 @@ def read_valid_telescope_events(filename): ) ###################################################################### -# *Part E3*: CNN-based model inference using LST-1 lstchain data -# ============================================================== +# *Part E3* CNN-based model inference using LST-1 lstchain data +# ============================================================= # # The following three cells demonstrate the prediction tool for LST-1 DL1 # data in the lstchain format. Since LST-1 data are private to the LST-1 diff --git a/examples/tutorials/train_ctlearn_model.py b/examples/tutorials/train_ctlearn_model.py index 4fcb5c96..e6168948 100644 --- a/examples/tutorials/train_ctlearn_model.py +++ b/examples/tutorials/train_ctlearn_model.py @@ -1,6 +1,6 @@ """ -**Tutorial 2**: Train CTLearn models -==================================== +**Tutorial 2** Train CTLearn models +=================================== Train models for CTAO image and waveform data with CTLearn. The image examples use only the gamma-ray and proton ``00`` files; the ``01`` files @@ -198,8 +198,8 @@ def run_command_line(command): ###################################################################### -# *Part A2*: Monoscopic CNN-based model training -# ============================================== +# *Part A2* Monoscopic CNN-based model training +# ============================================= # # We first train a basic monoscopic CNN-based model using the default CTLearn # model configuration. The model uses a **ThinResNet** backbone for feature @@ -376,8 +376,8 @@ def run_command_line(command): ) ###################################################################### -# *Part B2*: Customizing the CTLearn model architecture -# ===================================================== +# *Part B2* Customizing the CTLearn model architecture +# ==================================================== # # CTLearn provides a flexible configuration system that allows users to # customize the neural network architecture. @@ -481,8 +481,8 @@ def run_command_line(command): ) ###################################################################### -# *Part C2*: Using a pre-trained model and transfer learning -# ========================================================== +# *Part C2* Using a pre-trained model and transfer learning +# ========================================================= # # The LoadedModel component allows a previously trained model following # the CTLearnModel structure to be loaded for either resuming training or @@ -534,8 +534,8 @@ def run_command_line(command): ) ###################################################################### -# *Part D2*: Stereoscopic CNN-based model training -# ================================================ +# *Part D2* Stereoscopic CNN-based model training +# =============================================== # # CTLearn currently provides a basic approach for stereoscopic CNN-based # model training. The images from the different telescopes are concatenated @@ -596,8 +596,8 @@ def run_command_line(command): ) ###################################################################### -# *Part E2*: CNN-based model training using waveform data -# ======================================================= +# *Part E2* CNN-based model training using waveform data +# ====================================================== # # The final example demonstrates training directly on waveform data. The # example dataset used in this tutorial is intentionally very small, so @@ -656,8 +656,8 @@ def run_command_line(command): ) ###################################################################### -# *Part F2*: Comparing training curves -# ==================================== +# *Part F2* Comparing training curves +# =================================== # # Each training run writes its metrics to ``training_log.csv`` together # with the TensorBoard model checkpoints for training and validation, @@ -785,8 +785,8 @@ def plot_metric(ax, run_name, metric, label, color, **kwargs): plt.show() ###################################################################### -# *Part G2*: Monitoring training with TensorBoard -# =============================================== +# *Part G2* Monitoring training with TensorBoard +# ============================================== # # CTLearn also writes TensorBoard event files, which are useful for monitoring # metrics live or exploring additional details after training. The tutorial From d6385e3c4dfc191ba82f721d44851a9eedbd2b47 Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Wed, 11 Nov 2026 12:25:09 +0100 Subject: [PATCH 39/53] bump dl1dh version and polish docs --- docs/requirements.txt | 2 +- docs/source/devguide.rst | 18 +++--------------- examples/tutorials/GALLERY_HEADER.rst | 2 +- pyproject.toml | 2 +- 4 files changed, 6 insertions(+), 18 deletions(-) diff --git a/docs/requirements.txt b/docs/requirements.txt index d881992e..c04e8eaf 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -5,7 +5,7 @@ sphinx-design # Dependencies for autodoc and the executable Sphinx-Gallery tutorials. # The Sphinx autodoc configuration mocks the heavy ML frameworks. ctapipe>=0.29 -dl1_data_handler>=0.14.12 +dl1_data_handler>=0.14.13 matplotlib ctaplot scikit-learn diff --git a/docs/source/devguide.rst b/docs/source/devguide.rst index 186f6db9..32449b91 100644 --- a/docs/source/devguide.rst +++ b/docs/source/devguide.rst @@ -1,5 +1,5 @@ -Installation -============ +Getting Started +=============== User Installation ----------------- @@ -109,20 +109,8 @@ Core Dependencies * keras>=3.0 * astropy * ctapipe>=0.29.0 -* dl1_data_handler>=0.14.12 +* dl1_data_handler>=0.14.13 * numba * numpy * pandas * pyyaml - - -Uninstall CTLearn ------------------ - -To remove a conda environment in which CTLearn is installed: - -.. code-block:: bash - - conda remove --name ctlearn --all - -To remove a source checkout, delete its directory. diff --git a/examples/tutorials/GALLERY_HEADER.rst b/examples/tutorials/GALLERY_HEADER.rst index bb3caca3..f785d9f3 100644 --- a/examples/tutorials/GALLERY_HEADER.rst +++ b/examples/tutorials/GALLERY_HEADER.rst @@ -1,7 +1,7 @@ CTLearn tutorials ================= -Step-by-step examples for downloading and exploring public CTAO data, +Step-by-step examples for downloading and exploring public simulated CTAO data, training CTLearn models, and running inference on image and waveform data. The tutorials use small datasets to keep the examples manageable. Their diff --git a/pyproject.toml b/pyproject.toml index 7909e4d7..d412dbf1 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -30,7 +30,7 @@ requires-python = ">=3.12" dependencies = [ "astropy", "ctapipe>=0.29", - "dl1_data_handler>=0.14.12", + "dl1_data_handler>=0.14.13", "numba", "numpy", "pandas", From 26cafb54e809e0f7d90b7dfd67cb8877a76be6a8 Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Wed, 11 Nov 2026 12:31:40 +0100 Subject: [PATCH 40/53] added top bar for selecting different section --- docs/source/_static/top-nav.css | 33 ++++++++++++++++++++++++++++++ docs/source/_templates/layout.html | 11 ++++++++++ docs/source/conf.py | 1 + docs/source/index.rst | 10 --------- 4 files changed, 45 insertions(+), 10 deletions(-) create mode 100644 docs/source/_static/top-nav.css create mode 100644 docs/source/_templates/layout.html diff --git a/docs/source/_static/top-nav.css b/docs/source/_static/top-nav.css new file mode 100644 index 00000000..e195b4c5 --- /dev/null +++ b/docs/source/_static/top-nav.css @@ -0,0 +1,33 @@ +.ctlearn-top-nav { + display: flex; + flex-wrap: wrap; + gap: 0.25rem; + margin: 0 0 1.5rem; + border-bottom: 1px solid #d9d9d9; +} + +.ctlearn-top-nav a { + display: block; + padding: 0.65rem 1rem; + border-bottom: 3px solid transparent; + color: #404040; + font-weight: 600; + text-decoration: none; +} + +.ctlearn-top-nav a:hover, +.ctlearn-top-nav a:focus-visible { + color: #2980b9; + border-bottom-color: #2980b9; +} + +.ctlearn-top-nav a[aria-current="page"] { + color: #2980b9; + border-bottom-color: #2980b9; +} + +@media (max-width: 480px) { + .ctlearn-top-nav a { + padding: 0.55rem 0.65rem; + } +} diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html new file mode 100644 index 00000000..3973e2b6 --- /dev/null +++ b/docs/source/_templates/layout.html @@ -0,0 +1,11 @@ +{% extends "!layout.html" %} + +{% block document %} + +{{ super() }} +{% endblock %} diff --git a/docs/source/conf.py b/docs/source/conf.py index 35a3b23b..cd64a7ca 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -124,6 +124,7 @@ # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ["_static"] html_js_files = ["version-switcher.js"] +html_css_files = ["top-nav.css"] # Custom sidebar templates, must be a dictionary that maps document names # to template names. diff --git a/docs/source/index.rst b/docs/source/index.rst index af3d6230..50177cd0 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -43,16 +43,6 @@ Use the version selector in the sidebar to switch between the current Browse the CTLearn Python package and its modules. -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - devguide - usage - userguide - supplementary - api - changelog Documentation ================== From 63191c5fc98f46d20b5a399f18ae49b21029ee62 Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Wed, 11 Nov 2026 13:09:41 +0100 Subject: [PATCH 41/53] add back a hidden toctree --- docs/source/index.rst | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 50177cd0..be8497fc 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -21,6 +21,16 @@ CTLearn: Deep Learning for IACT Event Reconstruction Use the version selector in the sidebar to switch between the current ``main`` documentation and published tagged releases. +.. toctree:: + :maxdepth: 1 + :hidden: + devguide + usage + userguide + supplementary + api + changelog + .. grid:: 1 2 3 3 :gutter: 3 @@ -42,11 +52,3 @@ Use the version selector in the sidebar to switch between the current :link-type: doc Browse the CTLearn Python package and its modules. - - -Documentation -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` From 96d719c92ecd2a2d1ef1deef2dd48ccce3ae40da Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Wed, 11 Nov 2026 13:13:42 +0100 Subject: [PATCH 42/53] added github and pypi button --- docs/source/conf.py | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index cd64a7ca..8a53f4b4 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -117,7 +117,20 @@ # further. For a list of options available for each theme, see the # documentation. # -# html_theme_options = {} +html_theme_options = { + "icon_links": [ + { + "name": "GitHub", + "url": "https://github.com/ctlearn-project/ctlearn", + "icon": "fab fa-github", + }, + { + "name": "PyPI", + "url": "https://pypi.org/project/ctlearn/", + "icon": "fab fa-python", + }, + ] +} # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, From 00ef4ca0d23ae38badf6c687e2edfe200e301ee1 Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Wed, 11 Nov 2026 13:47:50 +0100 Subject: [PATCH 43/53] use pydata theme for docs --- .github/workflows/ci.yml | 29 ++++++++- docs/requirements.txt | 2 +- docs/source/_static/top-nav.css | 33 ---------- docs/source/_static/version-switcher.js | 86 ------------------------- docs/source/_templates/layout.html | 11 ---- docs/source/conf.py | 16 +++-- docs/source/devguide.rst | 7 +- docs/source/index.rst | 13 ++-- docs/source/userguide.rst | 1 + 9 files changed, 53 insertions(+), 145 deletions(-) delete mode 100644 docs/source/_static/top-nav.css delete mode 100644 docs/source/_static/version-switcher.js delete mode 100644 docs/source/_templates/layout.html diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3351e653..37979433 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -104,6 +104,7 @@ jobs: contents: read env: PIP_EXTRA_INDEX_URL: "https://download.pytorch.org/whl/cpu" + CTLEARN_DOCS_VERSION: ${{ github.ref_type == 'tag' && github.ref_name || 'main' }} steps: - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 with: @@ -125,7 +126,7 @@ jobs: python -m pip install --upgrade pip python -m pip install . python -m pip install -r docs/requirements.txt - python -m pip install sphinx sphinx-rtd-theme sphinx-changelog sphinx-design + python -m pip install sphinx pydata-sphinx-theme sphinx-changelog sphinx-design - name: Get ctapipe version for processed-data cache id: ctapipe-version @@ -240,13 +241,37 @@ jobs: versions = [] versions = [item for item in versions if item["version"] != version] - versions.append({"version": version, "path": version_path, "title": title}) + versions.append( + { + "version": version, + "name": title, + "url": ( + "https://ctlearn-project.github.io/ctlearn/" + f"{version_path}/" + ), + } + ) versions.sort( key=lambda item: (item["version"] != "main", item["version"]) ) versions[1:] = sorted( versions[1:], key=lambda item: item["version"], reverse=True ) + versions = [ + { + "version": item["version"], + "name": item.get("name", item.get("title", item["version"])), + "url": ( + item["url"] + if "url" in item + else ( + "https://ctlearn-project.github.io/ctlearn/" + f"{item['path']}/" + ) + ), + } + for item in versions + ] manifest_path.write_text(json.dumps(versions, indent=2) + "\n") PY diff --git a/docs/requirements.txt b/docs/requirements.txt index c04e8eaf..6afff7b2 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,5 +1,5 @@ sphinx -sphinx_rtd_theme +pydata-sphinx-theme sphinx-changelog sphinx-design # Dependencies for autodoc and the executable Sphinx-Gallery tutorials. diff --git a/docs/source/_static/top-nav.css b/docs/source/_static/top-nav.css deleted file mode 100644 index e195b4c5..00000000 --- a/docs/source/_static/top-nav.css +++ /dev/null @@ -1,33 +0,0 @@ -.ctlearn-top-nav { - display: flex; - flex-wrap: wrap; - gap: 0.25rem; - margin: 0 0 1.5rem; - border-bottom: 1px solid #d9d9d9; -} - -.ctlearn-top-nav a { - display: block; - padding: 0.65rem 1rem; - border-bottom: 3px solid transparent; - color: #404040; - font-weight: 600; - text-decoration: none; -} - -.ctlearn-top-nav a:hover, -.ctlearn-top-nav a:focus-visible { - color: #2980b9; - border-bottom-color: #2980b9; -} - -.ctlearn-top-nav a[aria-current="page"] { - color: #2980b9; - border-bottom-color: #2980b9; -} - -@media (max-width: 480px) { - .ctlearn-top-nav a { - padding: 0.55rem 0.65rem; - } -} diff --git a/docs/source/_static/version-switcher.js b/docs/source/_static/version-switcher.js deleted file mode 100644 index dfaef1e5..00000000 --- a/docs/source/_static/version-switcher.js +++ /dev/null @@ -1,86 +0,0 @@ -(() => { - const findManifest = async () => { - const pathParts = window.location.pathname.split("/").filter(Boolean); - for (let depth = 0; depth <= pathParts.length; depth += 1) { - const candidate = new URL( - `${"../".repeat(depth)}versions.json`, - window.location.href, - ); - try { - const response = await fetch(candidate); - if (!response.ok) { - continue; - } - const versions = await response.json(); - if ( - Array.isArray(versions) && - versions.some((version) => version.version === "main") - ) { - return { candidate, versions }; - } - } catch (error) { - console.warn("Could not load documentation versions.", error); - } - } - return null; - }; - - const addVersionSelector = async () => { - const search = document.querySelector(".wy-side-nav-search"); - if (!search) { - return; - } - - const manifest = await findManifest(); - if (!manifest) { - return; - } - - const sitePath = new URL(".", manifest.candidate).pathname; - const relativePath = window.location.pathname.slice(sitePath.length); - const pathParts = relativePath.split("/").filter(Boolean); - const currentVersion = manifest.versions.find( - (version) => version.path === pathParts[0], - ); - const pagePath = currentVersion ? pathParts.slice(1).join("/") : relativePath; - const selectedVersion = currentVersion?.version ?? "main"; - - const label = document.createElement("label"); - label.htmlFor = "documentation-version"; - label.textContent = "Documentation version"; - label.style.cssText = "display:block;margin:0.75em 0 0.25em;text-align:left"; - - const select = document.createElement("select"); - select.id = "documentation-version"; - select.setAttribute("aria-label", "Documentation version"); - select.style.cssText = "box-sizing:border-box;width:100%;padding:0.35em"; - - for (const version of manifest.versions) { - const option = document.createElement("option"); - option.value = version.path; - option.textContent = version.title; - option.selected = version.version === selectedVersion; - select.append(option); - } - - select.addEventListener("change", () => { - const destination = new URL(sitePath, window.location.origin); - const targetPath = [select.value, pagePath].filter(Boolean).join("/"); - destination.pathname += targetPath; - if (!pagePath || window.location.pathname.endsWith("/")) { - destination.pathname += "/"; - } - destination.search = window.location.search; - destination.hash = window.location.hash; - window.location.assign(destination); - }); - - search.append(label, select); - }; - - if (document.readyState === "loading") { - document.addEventListener("DOMContentLoaded", addVersionSelector); - } else { - addVersionSelector(); - } -})(); diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html deleted file mode 100644 index 3973e2b6..00000000 --- a/docs/source/_templates/layout.html +++ /dev/null @@ -1,11 +0,0 @@ -{% extends "!layout.html" %} - -{% block document %} - -{{ super() }} -{% endblock %} diff --git a/docs/source/conf.py b/docs/source/conf.py index 8a53f4b4..f2eab3bd 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -111,13 +111,23 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = "sphinx_rtd_theme" +html_theme = "pydata_sphinx_theme" + +version_match = os.getenv("CTLEARN_DOCS_VERSION", "main") +version_switcher_url = "https://ctlearn-project.github.io/ctlearn/versions.json" # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. # html_theme_options = { + "navbar_start": ["navbar-logo", "version-switcher"], + "navbar_center": ["navbar-nav"], + "navbar_end": ["navbar-icon-links"], + "switcher": { + "json_url": version_switcher_url, + "version_match": version_match, + }, "icon_links": [ { "name": "GitHub", @@ -129,15 +139,13 @@ "url": "https://pypi.org/project/ctlearn/", "icon": "fab fa-python", }, - ] + ], } # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ["_static"] -html_js_files = ["version-switcher.js"] -html_css_files = ["top-nav.css"] # Custom sidebar templates, must be a dictionary that maps document names # to template names. diff --git a/docs/source/devguide.rst b/docs/source/devguide.rst index 32449b91..939d8d77 100644 --- a/docs/source/devguide.rst +++ b/docs/source/devguide.rst @@ -1,4 +1,4 @@ -Getting Started +Developer Guide =============== User Installation @@ -114,3 +114,8 @@ Core Dependencies * numpy * pandas * pyyaml + +.. toctree:: + :hidden: + + supplementary diff --git a/docs/source/index.rst b/docs/source/index.rst index be8497fc..6038be6a 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -18,18 +18,17 @@ CTLearn: Deep Learning for IACT Event Reconstruction * Documentation: https://ctlearn-project.github.io/ctlearn/ * License: BSD-3 -Use the version selector in the sidebar to switch between the current +Use the version selector in the header to switch between the current ``main`` documentation and published tagged releases. .. toctree:: - :maxdepth: 1 - :hidden: - devguide - usage + :maxdepth: 1 + :hidden: + userguide - supplementary + devguide api - changelog + Changelog .. grid:: 1 2 3 3 :gutter: 3 diff --git a/docs/source/userguide.rst b/docs/source/userguide.rst index dcda31af..a8284053 100644 --- a/docs/source/userguide.rst +++ b/docs/source/userguide.rst @@ -134,3 +134,4 @@ in ``ViTables``: :maxdepth: 1 auto_tutorials/index + usage From 00a648be81720d5826efba8fae0c750ee44737e1 Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Wed, 11 Nov 2026 14:37:28 +0100 Subject: [PATCH 44/53] add logo and icon for docs --- docs/source/_static/ctlearn_favicon.ico | Bin 0 -> 2947 bytes docs/source/_static/ctlearn_logo.png | Bin 0 -> 51104 bytes docs/source/conf.py | 4 ++++ 3 files changed, 4 insertions(+) create mode 100644 docs/source/_static/ctlearn_favicon.ico create mode 100644 docs/source/_static/ctlearn_logo.png diff --git a/docs/source/_static/ctlearn_favicon.ico b/docs/source/_static/ctlearn_favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..8a134559212645b92eaf6abe3a9407a104caddf4 GIT binary patch literal 2947 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 Date: Wed, 11 Nov 2026 15:32:27 +0100 Subject: [PATCH 45/53] remove background from logo and polish some docs --- .../_static/ctlearn_logo_transparent.png | Bin 0 -> 66658 bytes docs/source/conf.py | 23 +++++++++++------- docs/source/index.rst | 12 +++------ images/CTLearnTextCTinBox_Transparent.png | Bin 0 -> 66658 bytes pyproject.toml | 12 ++++----- 5 files changed, 24 insertions(+), 23 deletions(-) create mode 100644 docs/source/_static/ctlearn_logo_transparent.png create mode 100644 images/CTLearnTextCTinBox_Transparent.png diff --git a/docs/source/_static/ctlearn_logo_transparent.png b/docs/source/_static/ctlearn_logo_transparent.png new file mode 100644 index 0000000000000000000000000000000000000000..6e71bbcaded33cd58c2e74bb07d29833df03c66f GIT binary patch literal 66658 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 literal 0 HcmV?d00001 diff --git a/docs/source/conf.py b/docs/source/conf.py index d057a5ae..b44d10b5 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -12,26 +12,29 @@ # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # +import datetime import os import sys +import tomllib +from pathlib import Path # Point Sphinx to the source directory where `ctlearn` lives sys.path.insert( 0, os.path.abspath(os.path.join(os.path.dirname(__file__), "../../src")) ) -# Import ctapipe.reco before autodoc mocks torch: it walks all scikit-learn -# submodules, and the scikit-learn torch compatibility layer fails on a mock. -import ctapipe.reco # noqa: F401 from sphinx_gallery.sorting import ExplicitOrder import ctlearn # -- Project information ----------------------------------------------------- - -project = "CTLearn" -copyright = "2022, CTLearn devs" -author = "CTLearn devs" +pyproject_path = Path(__file__).parent.parent / "pyproject.toml" +pyproject = tomllib.loads(pyproject_path.read_text()) +project = pyproject["project"]["name"] +author = pyproject["project"]["authors"][0]["name"] +copyright = "{}. Last updated {}".format( + author, datetime.datetime.now().strftime("%d %b %Y %H:%M") +) # The short X.Y version version = ctlearn.__version__ @@ -113,7 +116,7 @@ # html_favicon = r"_static/ctlearn_favicon.ico" -html_logo = r"_static/ctlearn_logo.png" +html_logo = r"_static/ctlearn_logo_transparent.png" html_theme = "pydata_sphinx_theme" @@ -127,11 +130,12 @@ html_theme_options = { "navbar_start": ["navbar-logo", "version-switcher"], "navbar_center": ["navbar-nav"], - "navbar_end": ["navbar-icon-links"], + "navbar_end": ["theme-switcher", "navbar-icon-links"], "switcher": { "json_url": version_switcher_url, "version_match": version_match, }, + "icon_links_label": "Quick Links", "icon_links": [ { "name": "GitHub", @@ -150,6 +154,7 @@ # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ["_static"] +html_context = {"default_mode": "dark"} # Custom sidebar templates, must be a dictionary that maps document names # to template names. diff --git a/docs/source/index.rst b/docs/source/index.rst index 6038be6a..a3fa54de 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -3,10 +3,13 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. +:html_theme.sidebar_secondary.remove: true +:html_theme.sidebar_primary.remove: true + CTLearn: Deep Learning for IACT Event Reconstruction ==================================================== -.. image:: ../../images/CTLearnTextCTinBox_WhiteBkgd.png +.. image:: _static/ctlearn_logo_transparent.png :align: center :width: 75% @@ -14,13 +17,6 @@ CTLearn: Deep Learning for IACT Event Reconstruction releases are available, users should expect changes to the code before a 1.0 release arrives. -* Code, feature requests, bug reports, pull requests: https://github.com/ctlearn-project/ctlearn -* Documentation: https://ctlearn-project.github.io/ctlearn/ -* License: BSD-3 - -Use the version selector in the header to switch between the current -``main`` documentation and published tagged releases. - .. toctree:: :maxdepth: 1 :hidden: diff --git a/images/CTLearnTextCTinBox_Transparent.png b/images/CTLearnTextCTinBox_Transparent.png new file mode 100644 index 0000000000000000000000000000000000000000..6e71bbcaded33cd58c2e74bb07d29833df03c66f GIT binary patch literal 66658 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 literal 0 HcmV?d00001 diff --git a/pyproject.toml b/pyproject.toml index d412dbf1..19f05eb2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -6,14 +6,14 @@ build-backend = "setuptools.build_meta" name = "ctlearn" description = "CTLearn is a package under active development to run deep learning models to analyze data from all major current and future arrays of imaging atmospheric Cherenkov telescopes (IACTs)." readme = "README.rst" -license = {text = "BSD-3-Clause"} authors = [ - {name = "Ari Brill"}, - {name = "Bryan Kim"}, - {name = "Tjark Miener"}, - {name = "Daniel Nieto", email = "d.nieto@ucm.es"} + {name = "CTLearn devs"}, ] - +maintainers = [ + {name = "Tjark Miener", email = "tmiener@iaa.csic.es"}, + {name = "Daniel Nieto", email = "d.nieto@ucm.es"}, +] +license = "BSD-3-Clause" classifiers = [ "License :: OSI Approved :: BSD License", "Intended Audience :: Science/Research", From 53ea1fc868801cab916cd7fd01e716984a5b9a2d Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Wed, 11 Nov 2026 15:37:58 +0100 Subject: [PATCH 46/53] fix bug with licence in pyproject --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 19f05eb2..ffdf8716 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -13,7 +13,7 @@ maintainers = [ {name = "Tjark Miener", email = "tmiener@iaa.csic.es"}, {name = "Daniel Nieto", email = "d.nieto@ucm.es"}, ] -license = "BSD-3-Clause" +license = {text = "BSD-3-Clause"} classifiers = [ "License :: OSI Approved :: BSD License", "Intended Audience :: Science/Research", From adff05a50dd39577aec958cbba66fdd964938078 Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Wed, 11 Nov 2026 15:51:51 +0100 Subject: [PATCH 47/53] fix path to pyproject in the conf of the docs --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index b44d10b5..b0aeb5fd 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -28,7 +28,7 @@ import ctlearn # -- Project information ----------------------------------------------------- -pyproject_path = Path(__file__).parent.parent / "pyproject.toml" +pyproject_path = Path(__file__).resolve().parents[2] / "pyproject.toml" pyproject = tomllib.loads(pyproject_path.read_text()) project = pyproject["project"]["name"] author = pyproject["project"]["authors"][0]["name"] From 092f886f9bd561f25837441060d762f6b9a81d54 Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Wed, 11 Nov 2026 17:06:05 +0100 Subject: [PATCH 48/53] make docs a little bit more beautiful --- docs/source/conf.py | 5 +++++ docs/source/index.rst | 14 +++----------- 2 files changed, 8 insertions(+), 11 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index b0aeb5fd..c2cc8f6c 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -148,6 +148,11 @@ "icon": "fab fa-python", }, ], + "announcement": """ +

This is not production-ready code yet. Although stable + releases are available, users should expect changes to the code + before a 1.0 release arrives.

+ """, } # Add any paths that contain custom static files (such as style sheets) here, diff --git a/docs/source/index.rst b/docs/source/index.rst index a3fa54de..001e3c83 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,21 +1,13 @@ -.. CTLearn documentation master file, created by - sphinx-quickstart on Mon Mar 28 13:43:00 2022. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +.. title:: CTLearn :html_theme.sidebar_secondary.remove: true :html_theme.sidebar_primary.remove: true -CTLearn: Deep Learning for IACT Event Reconstruction -==================================================== - .. image:: _static/ctlearn_logo_transparent.png + :alt: CTLearn Logo :align: center :width: 75% - -.. CAUTION:: This is not production-ready code yet. Although stable - releases are available, users should expect changes to the code - before a 1.0 release arrives. + :class: dark-light .. toctree:: :maxdepth: 1 From 40f8c8aca0df1bfc8adbf4ad77f09e4b0ea3379e Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Thu, 12 Nov 2026 16:44:13 +0100 Subject: [PATCH 49/53] fixs version switcher; also point to legacy read the docs for older verions of the code --- .github/workflows/ci.yml | 53 ------------------------------- docs/source/_static/switcher.json | 12 +++++++ docs/source/conf.py | 21 +++++++++++- docs/source/index.rst | 11 +++++-- 4 files changed, 40 insertions(+), 57 deletions(-) create mode 100644 docs/source/_static/switcher.json diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 37979433..0ff3b7fb 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -222,59 +222,6 @@ jobs: fi touch "$site_dir/.nojekyll" - python - "$site_dir/versions.json" "$VERSION" "$version_path" "$REF" <<'PY' - import json - import sys - from pathlib import Path - - manifest_path = Path(sys.argv[1]) - version, version_path, ref = sys.argv[2:] - if ref == "refs/heads/main": - version = "main" - title = "main (development)" - else: - title = version - - if manifest_path.exists(): - versions = json.loads(manifest_path.read_text()) - else: - versions = [] - - versions = [item for item in versions if item["version"] != version] - versions.append( - { - "version": version, - "name": title, - "url": ( - "https://ctlearn-project.github.io/ctlearn/" - f"{version_path}/" - ), - } - ) - versions.sort( - key=lambda item: (item["version"] != "main", item["version"]) - ) - versions[1:] = sorted( - versions[1:], key=lambda item: item["version"], reverse=True - ) - versions = [ - { - "version": item["version"], - "name": item.get("name", item.get("title", item["version"])), - "url": ( - item["url"] - if "url" in item - else ( - "https://ctlearn-project.github.io/ctlearn/" - f"{item['path']}/" - ) - ), - } - for item in versions - ] - manifest_path.write_text(json.dumps(versions, indent=2) + "\n") - PY - git -C "$site_dir" add -A if ! git -C "$site_dir" diff --cached --quiet; then git -C "$site_dir" -c user.name="github-actions[bot]" \ diff --git a/docs/source/_static/switcher.json b/docs/source/_static/switcher.json new file mode 100644 index 00000000..48298283 --- /dev/null +++ b/docs/source/_static/switcher.json @@ -0,0 +1,12 @@ +[ + { + "name": "dev", + "version": "main", + "url": "https://ctlearn-project.github.io/ctlearn/main/" + }, + { + "name": "legacy (Read the Docs)", + "version": "legacy", + "url": "https://ctlearn.readthedocs.io/en/stable/" + } +] diff --git a/docs/source/conf.py b/docs/source/conf.py index c2cc8f6c..6a68be1c 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -14,6 +14,7 @@ # import datetime import os +import subprocess import sys import tomllib from pathlib import Path @@ -42,6 +43,24 @@ release = version +def _release_date(): + """Date of the documented commit: the release day for tagged builds.""" + try: + return subprocess.run( + ["git", "log", "-1", "--format=%cs"], + cwd=Path(__file__).resolve().parent, + capture_output=True, + text=True, + check=True, + ).stdout.strip() + except (OSError, subprocess.CalledProcessError): + return "" + + +# Replaces |today|; falls back to the build date when git is unavailable. +today = _release_date() if os.getenv("CTLEARN_DOCS_VERSION", "main") != "main" else "" + + # -- General configuration --------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. @@ -121,7 +140,7 @@ html_theme = "pydata_sphinx_theme" version_match = os.getenv("CTLEARN_DOCS_VERSION", "main") -version_switcher_url = "https://ctlearn-project.github.io/ctlearn/versions.json" +version_switcher_url = "https://ctlearn-project.github.io/ctlearn/_static/switcher.json" # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the diff --git a/docs/source/index.rst b/docs/source/index.rst index 001e3c83..76e98eb9 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -3,12 +3,17 @@ :html_theme.sidebar_secondary.remove: true :html_theme.sidebar_primary.remove: true +**Version**: |version| **Date**: |today| + .. image:: _static/ctlearn_logo_transparent.png :alt: CTLearn Logo :align: center - :width: 75% + :width: 90% :class: dark-light +.. raw:: html +
+ .. toctree:: :maxdepth: 1 :hidden: @@ -16,7 +21,7 @@ userguide devguide api - Changelog + changelog .. grid:: 1 2 3 3 :gutter: 3 @@ -25,7 +30,7 @@ :link: userguide :link-type: doc - Explore the public CTAO data tutorials, train CTLearn models, and run + Explore the public simulated CTAO data tutorials, train CTLearn models, and run inference on image and waveform data. .. grid-item-card:: Developer Guide From 43616ddb689ae27233bdb086e6efe391000cc603 Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Thu, 12 Nov 2026 17:29:49 +0100 Subject: [PATCH 50/53] added skip-docs-tutorials label --- .github/workflows/ci.yml | 22 +++++++++++++++++----- CONTRIBUTING.rst | 16 ++++++++++++++++ docs/source/index.rst | 9 ++++----- 3 files changed, 37 insertions(+), 10 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 0ff3b7fb..a5f9ac3a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -29,6 +29,8 @@ jobs: cache-test-data: needs: lint runs-on: ubuntu-24.04 + env: + SKIP_DOCS_TUTORIALS: ${{ github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'skip-docs-tutorials') }} steps: - name: Cache ctapipe data id: cache-ctapipe @@ -38,6 +40,7 @@ jobs: key: ctapipe-data-${{ runner.os }}-v1 - name: Cache tutorial data + if: env.SKIP_DOCS_TUTORIALS != 'true' id: cache-tutorial-data uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 with: @@ -47,7 +50,7 @@ jobs: - name: Set up Python if: >- steps.cache-ctapipe.outputs.cache-hit != 'true' || - steps.cache-tutorial-data.outputs.cache-hit != 'true' + (env.SKIP_DOCS_TUTORIALS != 'true' && steps.cache-tutorial-data.outputs.cache-hit != 'true') uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5 with: python-version: '3.12' @@ -55,7 +58,7 @@ jobs: - name: Install ctapipe if: >- steps.cache-ctapipe.outputs.cache-hit != 'true' || - steps.cache-tutorial-data.outputs.cache-hit != 'true' + (env.SKIP_DOCS_TUTORIALS != 'true' && steps.cache-tutorial-data.outputs.cache-hit != 'true') run: pip install ctapipe - name: Download ctapipe test data @@ -64,7 +67,7 @@ jobs: python -c "from ctapipe.utils import get_dataset_path; get_dataset_path('gamma_test_large.simtel.gz'); get_dataset_path('proton_20deg_0deg_run4___cta-prod5-paranal_desert-2147m-Paranal-dark-100evts.simtel.zst')" - name: Download tutorial data - if: steps.cache-tutorial-data.outputs.cache-hit != 'true' + if: env.SKIP_DOCS_TUTORIALS != 'true' && steps.cache-tutorial-data.outputs.cache-hit != 'true' run: | python - <<'PY' from pathlib import Path @@ -105,6 +108,7 @@ jobs: env: PIP_EXTRA_INDEX_URL: "https://download.pytorch.org/whl/cpu" CTLEARN_DOCS_VERSION: ${{ github.ref_type == 'tag' && github.ref_name || 'main' }} + SKIP_DOCS_TUTORIALS: ${{ github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'skip-docs-tutorials') }} steps: - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 with: @@ -129,16 +133,19 @@ jobs: python -m pip install sphinx pydata-sphinx-theme sphinx-changelog sphinx-design - name: Get ctapipe version for processed-data cache + if: env.SKIP_DOCS_TUTORIALS != 'true' id: ctapipe-version run: echo "version=$(python -c 'import ctapipe; print(ctapipe.__version__)')" >> "$GITHUB_OUTPUT" - name: Restore tutorial input data + if: env.SKIP_DOCS_TUTORIALS != 'true' uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 with: path: ~/.cache/ctlearn/tutorial-data key: ctlearn-tutorial-data-${{ runner.os }}-v2 - name: Restore processed tutorial data + if: env.SKIP_DOCS_TUTORIALS != 'true' uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 with: path: | @@ -147,10 +154,15 @@ jobs: key: >- ctlearn-tutorial-processed-${{ runner.os }}-v2-max500-${{ steps.ctapipe-version.outputs.version }}-${{ hashFiles('examples/tutorials/explore_public_data.py', 'docs/requirements.txt', 'pyproject.toml') }} - - name: Build documentation and execute tutorials + - name: Build documentation env: CTLEARN_TUTORIAL_MAX_EVENTS: "500" - run: python -m sphinx -b html --keep-going docs/source docs/build/html + run: | + if [[ "$SKIP_DOCS_TUTORIALS" == "true" ]]; then + python -m sphinx -b html --keep-going -D sphinx_gallery_conf.plot_gallery=0 docs/source docs/build/html + else + python -m sphinx -b html --keep-going docs/source docs/build/html + fi - name: Upload rendered documentation for review if: >- diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index cb870e60..eccee370 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -35,6 +35,22 @@ all files, use: pre-commit run --all-files +Documentation builds +-------------------- + +For documentation-only pull requests, apply the ``documentation-only`` label +to skip the pip and Pixi test jobs and the dependent SonarCloud scan. The +documentation build still runs, as do the lint and data-cache jobs and any +other applicable workflow checks. Removing the label restores the skipped +pull request jobs. The label does not affect push builds, including pushes to +``main`` and tags, or the release workflow. + +To speed up a pull request's documentation build, apply the +``skip-docs-tutorials`` label. The documentation and tutorial pages are still +built, but the tutorials are not executed, so their outputs are omitted. +Removing the label restores tutorial execution. Push builds always execute the +tutorials, regardless of pull request labels. + Changelog entries ----------------- diff --git a/docs/source/index.rst b/docs/source/index.rst index 76e98eb9..b0bbb0b5 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -3,16 +3,15 @@ :html_theme.sidebar_secondary.remove: true :html_theme.sidebar_primary.remove: true -**Version**: |version| **Date**: |today| - .. image:: _static/ctlearn_logo_transparent.png :alt: CTLearn Logo :align: center - :width: 90% + :width: 80% :class: dark-light -.. raw:: html -
+ +**Version**: |version| **Date**: |today| + .. toctree:: :maxdepth: 1 From 7a6acefd4c8a829957ee9bacf90c906947dbe1ef Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Fri, 13 Nov 2026 15:36:23 +0100 Subject: [PATCH 51/53] polish docs --- .github/workflows/ci.yml | 1 - .gitignore | 2 + docs/source/_static/ctlearn_favicon.png | Bin 0 -> 2947 bytes docs/source/{ => api-reference}/ctlearn.rst | 0 .../{api.rst => api-reference/index.rst} | 0 docs/source/conf.py | 51 +++++- .../{ => developer-guide}/contributing.rst | 2 +- .../index.rst} | 62 +------ docs/source/index.rst | 16 +- docs/source/user-guide/index.rst | 63 +++++++ .../source/{ => user-guide}/supplementary.rst | 0 docs/source/user-guide/tutorials.rst | 155 ++++++++++++++++++ docs/source/{ => user-guide}/usage.rst | 0 docs/source/userguide.rst | 137 ---------------- examples/tutorials/GALLERY_HEADER.rst | 16 -- examples/tutorials/README.rst | 1 + examples/tutorials/predict_ctlearn_model.py | 18 +- examples/tutorials/train_ctlearn_model.py | 28 ++-- pyproject.toml | 1 + 19 files changed, 312 insertions(+), 241 deletions(-) create mode 100644 docs/source/_static/ctlearn_favicon.png rename docs/source/{ => api-reference}/ctlearn.rst (100%) rename docs/source/{api.rst => api-reference/index.rst} (100%) rename docs/source/{ => developer-guide}/contributing.rst (53%) rename docs/source/{devguide.rst => developer-guide/index.rst} (53%) create mode 100644 docs/source/user-guide/index.rst rename docs/source/{ => user-guide}/supplementary.rst (100%) create mode 100644 docs/source/user-guide/tutorials.rst rename docs/source/{ => user-guide}/usage.rst (100%) delete mode 100644 docs/source/userguide.rst delete mode 100644 examples/tutorials/GALLERY_HEADER.rst create mode 100644 examples/tutorials/README.rst diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a5f9ac3a..cfbc7a2b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -130,7 +130,6 @@ jobs: python -m pip install --upgrade pip python -m pip install . python -m pip install -r docs/requirements.txt - python -m pip install sphinx pydata-sphinx-theme sphinx-changelog sphinx-design - name: Get ctapipe version for processed-data cache if: env.SKIP_DOCS_TUTORIALS != 'true' diff --git a/.gitignore b/.gitignore index a1cef398..ad49beb6 100644 --- a/.gitignore +++ b/.gitignore @@ -12,6 +12,7 @@ output_dir2/ *.tar.gz *.pbtxt *.png +!docs/source/_static/ctlearn_favicon.png *.csv *~ *.log @@ -32,6 +33,7 @@ dist # Sphinx documentation docs/build/ docs/source/auto_tutorials/ +docs/source/user-guide/auto_tutorials/ docs/source/sg_execution_times.rst build/ # Default pytorch output diff --git a/docs/source/_static/ctlearn_favicon.png b/docs/source/_static/ctlearn_favicon.png new file mode 100644 index 0000000000000000000000000000000000000000..8a134559212645b92eaf6abe3a9407a104caddf4 GIT binary patch literal 2947 zcmV-}3w-p6P)Mf0r0mEzGz1EZGROj-uiG(XIJMYAi5SX&cgTXV3Ha@Rj4bpb=0l*@_pZS zpdgTq>&`hH3#b1dhGzIb0N7%HzX%{kFP^A}ShQ%7Oj|sHopGq6b4=aN-DnR-u%W&Q z554&jT91T^YKrqN%Jh2X0B8f)wi6kgEG!v*(sba^n#$WAL`)i;F)+sCX@<{>%O_Xk z`m-lubZ|%$!0rL~3IOfuH^J^+_(~Me7EXh9v zu;l>155QikE8WxnK4KA{SacVGa~<*Po} zwqV{fuk;GbG%qL%2Jo9Rs&UCF>6_3`fG-D*y19*xT08CsP{B!gfeW*}o?ie60c?wOA!_J&v9JtY=j}Okc-={hpF}if9356!mh#lI zLF3<>=3#TjkHR$*D^VHDmOc0vfG-Ddm|8myfa6nC{pG7(8}r=9JNgdW-7zL?cVzD# z#(}hvO28(EIV(? zh+KB#qzar}5)1=uB_Qqs&`2$RN5BZmDe9c%Yck&3wa?YE<+(#JK0m0*nS9T@H)S#f zOOV&(1@OypB?x#$1Yj=!LeAwMkpihWJapr7900KLS5vC5*|=wes~gX%9ElsIR-@t2 zx9SxMqHe*oMts%sd&`C!}cf#?@NYzcq@(lA*;iw}PXb(S zR(4S7WB^OIer)=v{6*D;!!ow)YqjQ8=+jKM8wY&p7@3oa-@dgaacW}DcNkV|Z?^I% zCTP!cWJu5AU>KR@#bsmiaP7NIMrFX~pI4rH^|?iX1!Pxl!YztxCm8xPKG>k7XCMBf8q7rOEF0~jBAJ>t#F zCzP9tnq!izMnGVu;ueSn*dJJ-?u7ydvtUUkI74e!%y@j~L1S)R6CSQ_Ic;BO_yxHi z0Ajxe;2#LE1i9z3n$hqG!K9)RmXU>-i-k>VQXWC|9oB?XmIe}Gt!E${GmLf3hmD0B zn{oeVEn}KH!Vdt^Mj&=8fE-W%fcd(@EPunS@}jbrckVT<=^UG;n`^EsVbVPUoW`w6 z&3EEJ9D>0HZNV^jWu`Qj;5JyRjO|^cuB8JT4<2EYgBkg=i?jb!nwfrcKY`^Ek3D$R zsbx!FZunZkLcuCP)57*~DlPcZtW!}F%%-{qeEj>|lbKD>_hV>(fu)rnpIRKeeM0__ zESg5hN~SfTcY-!%0o?GP9oXH>KB2OB@-=6%(|31wGpJs|%PVYj9kv`kpCybKo%ZIKvSyP|U2qUKqa07pvd(U@c& zHSS$p*eqj}r-*JKBWesJXwfMiI={RS1zA2BwoKTgPD@;^o|qNTNIA}XQdE~&Den_3 zbt2W%zlDeM*qko-`im-yXQm5*cP>7Y#&9x$<;Yz&+>fgtt>2H9P*>c!Wn)bJ z@5PPvlxuT!ih%j6 zL0?+^{}%>q3ecwt4x1!V#B4OU;6q!74!iuzgUP)kYGxZ3~Q?|zp`Pz_l&-UrVv*L=At8%`__. Pixi -provides the same project-managed environment used by CI. +We support two methods: *pip/venv* and `Pixi `__. .. tab-set:: @@ -73,31 +57,6 @@ Contributing contributing -Installing on the IT Cluster ----------------------------- - -For working on the IT cluster, create a conda environment with the required -build tools: - -.. code-block:: bash - - mamba create -n ctlearn-it-cluster -c conda-forge python==3.12 h5py scipy llvmlite gcc_linux-64 gxx_linux-64 openblas gfortran_linux-64 - conda activate ctlearn-it-cluster - export CC=$(which x86_64-conda-linux-gnu-gcc) - export CXX=$(which x86_64-conda-linux-gnu-g++) - export FC=$(which x86_64-conda-linux-gnu-gfortran) - pip install ctlearn - -Update ``LD_LIBRARY_PATH`` to include the necessary paths. For example, add the -following line to your ``.bashrc`` file: - -.. code-block:: bash - - export LD_LIBRARY_PATH=/path/to/your/conda/envs/ctlearn-it-cluster/lib:/path/to/cudnn/lib:$LD_LIBRARY_PATH - -Replace ``/path/to/your/conda/envs/ctlearn-it-cluster/lib`` with the path to -your conda environment and ``/path/to/cudnn/lib`` with the path to the system's -cuDNN libraries for CUDA 12. Core Dependencies @@ -114,8 +73,3 @@ Core Dependencies * numpy * pandas * pyyaml - -.. toctree:: - :hidden: - - supplementary diff --git a/docs/source/index.rst b/docs/source/index.rst index b0bbb0b5..d26614bd 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,8 +1,10 @@ -.. title:: CTLearn +.. title:: Home :html_theme.sidebar_secondary.remove: true :html_theme.sidebar_primary.remove: true +.. _ctlearn: + .. image:: _static/ctlearn_logo_transparent.png :alt: CTLearn Logo :align: center @@ -17,29 +19,29 @@ :maxdepth: 1 :hidden: - userguide - devguide - api + user-guide/index + developer-guide/index + api-reference/index changelog .. grid:: 1 2 3 3 :gutter: 3 .. grid-item-card:: User Guide - :link: userguide + :link: user-guide/index :link-type: doc Explore the public simulated CTAO data tutorials, train CTLearn models, and run inference on image and waveform data. .. grid-item-card:: Developer Guide - :link: devguide + :link: developer-guide/index :link-type: doc Set up a development environment and contribute to CTLearn. .. grid-item-card:: API Docs - :link: api + :link: api-reference/index :link-type: doc Browse the CTLearn Python package and its modules. diff --git a/docs/source/user-guide/index.rst b/docs/source/user-guide/index.rst new file mode 100644 index 00000000..9ef056b2 --- /dev/null +++ b/docs/source/user-guide/index.rst @@ -0,0 +1,63 @@ +.. _user-guide: + +********** +User Guide +********** + +.. currentmodule:: ctlearn + + +Getting Started for Users +------------------------- + +.. tab-set:: + + .. tab-item:: With Pixi + + Inside an existing Pixi project, add the released CTLearn package: + + .. code-block:: shell + + $ pixi add --pypi ctlearn + + .. tab-item:: With Pip + + .. code-block:: shell + + $ pip install ctlearn + + .. tab-item:: On IT-Cluster + + For working on the IT cluster, create a conda environment with the required + build tools: + + .. code-block:: shell + + $ mamba create -n ctlearn-it-cluster -c conda-forge python==3.12 h5py scipy llvmlite gcc_linux-64 gxx_linux-64 openblas gfortran_linux-64 + $ conda activate ctlearn-it-cluster + $ export CC=$(which x86_64-conda-linux-gnu-gcc) + $ export CXX=$(which x86_64-conda-linux-gnu-g++) + $ export FC=$(which x86_64-conda-linux-gnu-gfortran) + $ pip install ctlearn + + Update ``LD_LIBRARY_PATH`` to include the necessary paths. For example, add the + following line to your ``.bashrc`` file: + + .. code-block:: shell + + $ export LD_LIBRARY_PATH=/path/to/your/conda/envs/ctlearn-it-cluster/lib:/path/to/cudnn/lib:$LD_LIBRARY_PATH + + Replace ``/path/to/your/conda/envs/ctlearn-it-cluster/lib`` with the path to + your conda environment and ``/path/to/cudnn/lib`` with the path to the system's + cuDNN libraries for CUDA 12. + +.. toctree:: + :maxdepth: 1 + + auto_tutorials/index + +.. toctree:: + :hidden: + + usage + supplementary diff --git a/docs/source/supplementary.rst b/docs/source/user-guide/supplementary.rst similarity index 100% rename from docs/source/supplementary.rst rename to docs/source/user-guide/supplementary.rst diff --git a/docs/source/user-guide/tutorials.rst b/docs/source/user-guide/tutorials.rst new file mode 100644 index 00000000..7ca2f7ff --- /dev/null +++ b/docs/source/user-guide/tutorials.rst @@ -0,0 +1,155 @@ +CTLearn tutorials +================= + +Step-by-step examples for downloading and exploring public simulated CTAO data, +training CTLearn models, and running inference on image and waveform data. + +The tutorials use small datasets to keep the examples manageable. Their +performance metrics are for demonstrating the workflow and are not +representative of a production-level analysis. **Tutorial 1 (T1)** downloads and +converts the public simulation data and explores its waveforms and images. +**Tutorial 2 (T2)** trains CTLearn models with Keras and PyTorch using image and +waveform data. **Tutorial 3 (T3)** runs inference with those models, explores the +resulting DL2 data, and plots classification and reconstruction performance. + +.. tab-set:: + + .. tab-item:: **T1**: Data exploration + + This tutorial downloads a small SimTel sample for the monoscopic examples and + four CTAO simulation files from `Zenodo record 7298569 + `_ for the stereo example. The four Zenodo + files comprise gamma-ray and proton samples, each from two runs, ``00`` + and ``01``. The ``00`` run files are used for training in Tutorial 2, + while the ``01`` run files are held out for prediction in Tutorial 3. + Together, they require about 3.5 GB of disk space. By default, data are stored under + ``~/.cache/ctlearn/tutorial-data``; set ``CTLEARN_TUTORIAL_DATA_DIR`` to use a + different directory. Set ``CTLEARN_TUTORIAL_MAX_EVENTS`` to a positive integer + (for example, ``500``) to limit event processing per input file. Leave it unset to + process the full files, and use the same setting for all three tutorials. + The CI workflow preloads the source files, caches the converted products, and + sets the limit to 500 events per input file. + + .. tab-item:: **T2**: Training models + + The training tutorial documents monoscopic energy and direction regression, + gamma/proton classification, custom ``SingleCNN`` and ``ResNet`` architectures, + transfer learning with ``LoadedModel``, stereo image stacking, and waveform + training. It uses only the converted gamma-ray and proton ``00`` files for the + image examples and leaves the ``01`` files untouched for later evaluation in + Tutorial 3. The three example JSON configs are in ``docs/source/config`` in the + repository or ``config`` in the downloaded ZIP. The tutorial uses the descriptions + from the training notebook and executes every example sequentially during + the documentation build. This requires working TensorFlow and PyTorch + installations and can take substantial time and compute resources. + + Live training monitoring is available through TensorBoard. Start TensorBoard + in a separate terminal window and point it to the training output directory + and open a browser with the URL printed by TensorBoard (typically + ``http://localhost:6006``). + + .. code-block:: shell + + $ tensorboard --logdir $HOME/.cache/ctlearn/tutorial-training/ + + .. note:: + + Cluster users have to set up port forwarding to access TensorBoard in their browser. + For example, if you are using a cluster with a login node, you can set up port + forwarding like this: + + .. code-block:: shell + + $ ssh -L 6006:localhost:6006 user@cluster-login-node + + .. tab-item:: **T3**: Predicting models + + The prediction tutorial runs the Keras and PyTorch models produced by the + training tutorial on the held-out ``01`` CTAO simulation files. Each command + shows the model file path and configuration options explicitly. It plots + classification scores and ROC/AUC for both frameworks, plus regression + migration matrices and energy and angular resolution. The shared DL1 reader + configuration is shown in each command and controls telescope selection, + image channels, image mapping, and quality cuts. The tutorial also demonstrates + stereo prediction, waveform inference, and the LST-1 tool using a generated + mock DL1 file. The waveform example reuses training data only to demonstrate + the workflow; it is not an evaluation. + + The classifier and resolution figures are demonstrations on small samples + and should not be used for scientific conclusions or interpreted as production + instrument response functions. DL2 files are written to the same output directory + and can be inspected with ``ViTables``. The following command opens the DL2 files + in ``ViTables``: + + .. code-block:: shell + + $ pip install vitables + $ vitables $HOME/.cache/ctlearn/tutorial-training/predictions/*.dl2.h5 + + .. note:: + + Cluster users have to make sure to allow X11 forwarding to run ``ViTables``. + For example, if you are using a cluster with a login node, you can set up + X11 forwarding like this: + + .. code-block:: shell + + $ ssh -X user@cluster-login-node + +Download the Python or Jupyter ZIP for all examples using the links at the +bottom of this gallery, and extract it. Each individual tutorial page also +offers a ZIP containing that tutorial and its notebook. The ZIPs include a +``config/`` directory with the JSON configuration files; keep it alongside the +scripts or notebooks. Choose how to obtain and run the tutorials: + +.. tab-set:: + + .. tab-item:: Python ZIP + + Download the Python ZIP for all examples using the link at the bottom + of this gallery. + + .. code-block:: shell + + $ python -m pip install "ctlearn[docs]" + $ unzip auto_tutorials_python.zip -d ctlearn-tutorials + $ cd ctlearn-tutorials + $ export CTLEARN_TUTORIAL_DATA_DIR=$HOME/.cache/ctlearn/tutorial-data # optional: set a different cache location + $ export CTLEARN_TUTORIAL_MAX_EVENTS=500 # optional: limit events for fast execution of tutorials + $ python explore_public_data.py + $ python train_ctlearn_model.py + $ python predict_ctlearn_model.py + + .. tab-item:: Jupyter ZIP + + Download the Jupyter ZIP for all examples using the link at the bottom + of this gallery. Start Jupyter in the extracted directory, then open + and run the notebooks in order: ``explore_public_data.ipynb``, + ``train_ctlearn_model.ipynb``, and ``predict_ctlearn_model.ipynb``. + + .. code-block:: shell + + $ python -m pip install "ctlearn[docs]" notebook + $ unzip auto_tutorials_jupyter.zip -d ctlearn-tutorials + $ cd ctlearn-tutorials + $ export CTLEARN_TUTORIAL_DATA_DIR=$HOME/.cache/ctlearn/tutorial-data # optional: set a different cache location + $ export CTLEARN_TUTORIAL_MAX_EVENTS=500 # optional: limit events for fast execution of tutorials + $ jupyter notebook + + .. tab-item:: Git Clone + + Alternatively, clone the repository and install its documentation dependencies: + + .. code-block:: shell + + $ git clone https://github.com/ctlearn-project/ctlearn.git + $ cd ctlearn + $ python -m pip install -e ".[docs]" + $ export CTLEARN_TUTORIAL_DATA_DIR=$HOME/.cache/ctlearn/tutorial-data # optional: set a different cache location + $ export CTLEARN_TUTORIAL_MAX_EVENTS=500 # optional: limit events for fast execution of tutorials + $ python examples/tutorials/explore_public_data.py + $ python examples/tutorials/train_ctlearn_model.py + $ python examples/tutorials/predict_ctlearn_model.py + +Run the tutorials in order: the training tutorial uses data prepared by +Tutorial 1, and the prediction tutorial uses models created by Tutorial 2. diff --git a/docs/source/usage.rst b/docs/source/user-guide/usage.rst similarity index 100% rename from docs/source/usage.rst rename to docs/source/user-guide/usage.rst diff --git a/docs/source/userguide.rst b/docs/source/userguide.rst deleted file mode 100644 index a8284053..00000000 --- a/docs/source/userguide.rst +++ /dev/null @@ -1,137 +0,0 @@ -********** -User Guide -********** - -**Public CTAO data exploration** - -This tutorial follows the executable Python-script style used by ctapipe's -tutorials. It downloads a small SimTel sample for the monoscopic examples and -four CTAO simulation files from `Zenodo record 7298569 -`_ for the stereo example. The four Zenodo -files require about 3.5 GB of disk space. Downloaded and converted files are -reused on subsequent runs. By default, data are stored under -``~/.cache/ctlearn/tutorial-data``; set ``CTLEARN_TUTORIAL_DATA_DIR`` to use a -different directory. The CI workflow preloads the source files, caches the -converted products, and limits processing to 500 events per input file to keep -the documentation build bounded. Running the tutorial locally without that -environment variable processes the full files. The CI build executes the -tutorial and embeds its output; successful builds from pushes to ``main`` are -deployed to GitHub Pages. - -To run the complete tutorial locally from the CTLearn repository root, install -CTLearn with its development dependencies and execute: - -.. code-block:: console - - python examples/tutorials/explore_public_data.py - -The rendered tutorial, including its code, figures, and playable waveform -animations, is generated by Sphinx-Gallery: - -**Training a CTLearn model** - -The training tutorial documents monoscopic energy and direction regression, -gamma/proton classification, custom ``SingleCNN`` and ``ResNet`` architectures, -transfer learning with ``LoadedModel``, stereo image stacking, and waveform -training. It uses only the converted gamma-ray and proton ``00`` files for the -image examples and leaves the ``01`` files untouched for later evaluation. -The three example JSON configs are copied into -``docs/source/config``. The tutorial uses the descriptions -from the training notebook and executes every example sequentially during -the documentation build. This requires working TensorFlow and PyTorch -installations and can take substantial time and compute resources. -Run the data exploration tutorial first, then execute the training tutorial -from the repository root: - -.. code-block:: console - - python examples/tutorials/train_ctlearn_model.py - -The script presents each example as its own explanation followed by a literal -``ctlearn-train-keras-model`` command and then its PyTorch equivalent, -``ctlearn-train-pytorch-model``. The commands run in order; each -transfer-learning command uses the ``SingleCNN`` checkpoint from the same -framework's preceding architecture example. To use a different cache or output -location, set ``CTLEARN_TUTORIAL_DATA_DIR`` or -``CTLEARN_TUTORIAL_OUTPUT_DIR``. Training output defaults to -``~/.cache/ctlearn/tutorial-training``; use a new output directory for each -run because existing Keras and PyTorch model output directories are not -overwritten. - -To run classification directly in a terminal, set ``TRAIN_DIR`` to the -converted cache directory printed by the data exploration tutorial: - -.. code-block:: console - - TRAIN_DIR="$HOME/.cache/ctlearn/tutorial-data/ctapipe-" - ctlearn-train-keras-model \ - --signal "$TRAIN_DIR" \ - --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \ - --background "$TRAIN_DIR" \ - --pattern-background "proton_with_images_00.dl2.h5" \ - --output "$HOME/.cache/ctlearn/tutorial-training/keras-classification" \ - --config docs/source/config/dl1dh_example_config.json \ - --config docs/source/config/ctlearn_train_model_example_config.json \ - --reco type \ - --DLImageReader.focal_length_choice EQUIVALENT \ - --TrainCTLearnModel.n_epochs 5 \ - --TrainCTLearnModel.batch_size 32 - - # PyTorch equivalent: use the same arguments with the PyTorch command and output directory. - ctlearn-train-pytorch-model \ - --signal "$TRAIN_DIR" \ - --pattern-signal "gamma-diffuse_with_images_00.dl2.h5" \ - --background "$TRAIN_DIR" \ - --pattern-background "proton_with_images_00.dl2.h5" \ - --output "$HOME/.cache/ctlearn/tutorial-training/pytorch-classification" \ - --config docs/source/config/dl1dh_example_config.json \ - --config docs/source/config/ctlearn_train_model_example_config.json \ - --reco type \ - --DLImageReader.focal_length_choice EQUIVALENT \ - --TrainCTLearnModel.n_epochs 5 \ - --TrainCTLearnModel.batch_size 32 - -In a Jupyter notebook, prefix the same command with ``!``. For the other -examples, run the script to execute the commands in sequence. Start -TensorBoard for the resulting metrics with -``tensorboard --logdir ~/.cache/ctlearn/tutorial-training/``. - -**Predicting with CTLearn models** - -The prediction tutorial runs the Keras and PyTorch models produced by the -training tutorial on the held-out ``01`` CTAO simulation files. Each command -shows the model file path and configuration options explicitly. It plots -classification scores and ROC/AUC for both frameworks, plus regression -migration matrices and energy and angular resolution. The shared DL1 reader -configuration is shown in each command and controls telescope selection, -image channels, image mapping, and quality cuts. The tutorial also demonstrates -stereo prediction, waveform inference, and the LST-1 tool using a generated -mock DL1 file. The waveform example reuses training data only to demonstrate -the workflow; it is not an evaluation. - -Run the public data exploration tutorial and the training tutorial first, then -execute: - -.. code-block:: console - - python examples/tutorials/predict_ctlearn_model.py - -Prediction outputs are written to ``predictions`` under -``CTLEARN_TUTORIAL_OUTPUT_DIR`` (default: -``~/.cache/ctlearn/tutorial-training``). The classifier and resolution -figures are demonstrations on small samples and should not be used for -scientific conclusions or interpreted as production instrument response -functions. DL2 files are written to the same output directory and can be -inspected with ``ViTables``. The following command opens the DL2 files -in ``ViTables``: - -.. code-block:: console - - pip install vitables - vitables $HOME/.cache/ctlearn/tutorial-training/predictions/*.dl2.h5 - -.. toctree:: - :maxdepth: 1 - - auto_tutorials/index - usage diff --git a/examples/tutorials/GALLERY_HEADER.rst b/examples/tutorials/GALLERY_HEADER.rst deleted file mode 100644 index f785d9f3..00000000 --- a/examples/tutorials/GALLERY_HEADER.rst +++ /dev/null @@ -1,16 +0,0 @@ -CTLearn tutorials -================= - -Step-by-step examples for downloading and exploring public simulated CTAO data, -training CTLearn models, and running inference on image and waveform data. - -The tutorials use small datasets to keep the examples manageable. Their -performance metrics are for demonstrating the workflow and are not -representative of a production-level analysis. **Tutorial 1** downloads and -converts the public simulation data and explores its waveforms and images. -**Tutorial 2** trains CTLearn models with Keras and PyTorch using image and -waveform data. **Tutorial 3** runs inference with those models, explores the -resulting DL2 data, and plots classification and reconstruction performance. - -Run the tutorials in order: the training tutorial uses data prepared by -Tutorial 1, and the prediction tutorial uses models created by Tutorial 2. diff --git a/examples/tutorials/README.rst b/examples/tutorials/README.rst new file mode 100644 index 00000000..99760266 --- /dev/null +++ b/examples/tutorials/README.rst @@ -0,0 +1 @@ +.. include:: /user-guide/tutorials.rst diff --git a/examples/tutorials/predict_ctlearn_model.py b/examples/tutorials/predict_ctlearn_model.py index 805597c0..48ae78d8 100644 --- a/examples/tutorials/predict_ctlearn_model.py +++ b/examples/tutorials/predict_ctlearn_model.py @@ -86,18 +86,18 @@ def find_config_dir(): roots = [] script_path = globals().get("__file__") if script_path is not None: - roots.append(Path(script_path).resolve().parents[2]) + script_dir = Path(script_path).resolve().parent + roots.extend((script_dir, *script_dir.parents)) roots.extend((Path.cwd(), *Path.cwd().parents)) for root in roots: - config_dir = root / "docs" / "source" / "config" - if (config_dir / "dl1dh_example_config.json").is_file(): - return config_dir + for config_dir in (root / "config", root / "docs" / "source" / "config"): + if (config_dir / "dl1dh_example_config.json").is_file(): + return config_dir raise FileNotFoundError( - "Could not locate tutorial configs under docs/source/config. " - "Run this tutorial from the CTLearn repository or build it with " - "Sphinx-Gallery." + "Could not locate tutorial configs in config/ or docs/source/config/. " + "Extract the complete tutorial ZIP or run from the CTLearn repository." ) @@ -114,7 +114,7 @@ def find_config_dir(): missing = "\n".join(f" - {path}" for path in missing_files) raise FileNotFoundError( "Held-out tutorial data is missing. Run " - "examples/tutorials/explore_public_data.py first. Missing files:\n" + "explore_public_data.py first. Missing files:\n" f"{missing}" ) @@ -735,7 +735,7 @@ def read_valid_telescope_events(filename): if not WAVEFORM_FILE.is_file(): raise FileNotFoundError( f"Cached waveform data is missing: {WAVEFORM_FILE}. " - "Run examples/tutorials/explore_public_data.py first." + "Run explore_public_data.py first." ) ###################################################################### diff --git a/examples/tutorials/train_ctlearn_model.py b/examples/tutorials/train_ctlearn_model.py index e6168948..1809d39b 100644 --- a/examples/tutorials/train_ctlearn_model.py +++ b/examples/tutorials/train_ctlearn_model.py @@ -67,7 +67,7 @@ missing = "\n".join(f" - {path}" for path in missing_files) raise FileNotFoundError( "Cached stereo training data is missing. Run " - "examples/tutorials/explore_public_data.py first. Missing files:\n" + "explore_public_data.py first. Missing files:\n" f"{missing}" ) @@ -86,18 +86,18 @@ # followed immediately by the equivalent PyTorch command. In a notebook, # prefix either command with ``!``. # -# The three JSON configuration files shipped beside this tutorial are copies -# of the workshop examples: +# The three JSON configuration files are in ``docs/source/config`` in the +# repository and in ``config`` in the downloaded tutorial ZIPs: # -# - ``docs/source/config/dl1dh_example_config.json`` selects LST/LSTCam images, +# - ``dl1dh_example_config.json`` selects LST/LSTCam images, # the image and relative peak-time channels, bilinear mapping, and an # example 50,000 p.e. intensity cut. It also specifies NectarCam waveform # settings. -# - ``docs/source/config/ctlearn_train_model_example_config.json`` sets the +# - ``ctlearn_train_model_example_config.json`` sets the # reader, epoch and batch defaults, validation split, Adam optimizer and # learning rate, checkpointing, learning-rate reduction, random seed, and # early stopping. -# - ``docs/source/config/ctlearn_models_example_config.json`` defines the +# - ``ctlearn_models_example_config.json`` defines the # prediction heads, attention settings, custom ``SingleCNN`` and ``ResNet`` # architectures, and ``LoadedModel`` transfer-learning options. @@ -106,7 +106,8 @@ def find_config_dir(): roots = [] script_path = globals().get("__file__") if script_path is not None: - roots.append(Path(script_path).resolve().parents[2]) + script_dir = Path(script_path).resolve().parent + roots.extend((script_dir, *script_dir.parents)) roots.extend((Path.cwd(), *Path.cwd().parents)) config_names = ( @@ -115,14 +116,13 @@ def find_config_dir(): "ctlearn_models_example_config.json", ) for root in roots: - config_dir = root / "docs" / "source" / "config" - if all((config_dir / name).is_file() for name in config_names): - return config_dir + for config_dir in (root / "config", root / "docs" / "source" / "config"): + if all((config_dir / name).is_file() for name in config_names): + return config_dir raise FileNotFoundError( - "Could not locate tutorial configs under docs/source/config. " - "Run this tutorial from the CTLearn repository or build it with " - "Sphinx-Gallery." + "Could not locate tutorial configs in config/ or docs/source/config/. " + "Extract the complete tutorial ZIP or run from the CTLearn repository." ) @@ -621,7 +621,7 @@ def run_command_line(command): if not WAVEFORM_FILE.is_file(): raise FileNotFoundError( f"Cached waveform data is missing: {WAVEFORM_FILE}. " - "Run examples/tutorials/explore_public_data.py first." + "Run explore_public_data.py first." ) run_command_line( """ctlearn-train-keras-model --verbose \\ diff --git a/pyproject.toml b/pyproject.toml index ffdf8716..99ead1f3 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -93,6 +93,7 @@ docs = [ "sphinx-changelog", "sphinx-design", "sphinx-rtd-theme", + "pydata-sphinx-theme", ] dev = [ From 1752e8505a0d1e5ca83a5c6c948cb575f38f30ca Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Mon, 16 Nov 2026 11:41:11 +0100 Subject: [PATCH 52/53] polish docs --- CONTRIBUTING.rst | 25 ++- docs/source/developer-guide/contributing.rst | 5 - docs/source/developer-guide/index.rst | 26 +-- docs/source/index.rst | 3 +- docs/source/user-guide/index.rst | 173 ++++++++++++++++++- docs/source/user-guide/tutorials.rst | 2 + docs/source/user-guide/usage.rst | 90 ---------- 7 files changed, 207 insertions(+), 117 deletions(-) delete mode 100644 docs/source/developer-guide/contributing.rst delete mode 100644 docs/source/user-guide/usage.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index eccee370..06589bf3 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -3,9 +3,13 @@ Contributing to CTLearn ======================= CTLearn is open source and welcomes contributions from the community! +CTLearn follows the same code style and development guidelines as the ctapipe +community. We recommend reviewing the `ctapipe Developer Guide +`_ in +detail and following the guidelines below: Contributing guidelines ------------------------ +^^^^^^^^^^^^^^^^^^^^^^^ In CTLearn we follow the "fork-and-pull" Git workflow: @@ -16,8 +20,13 @@ In CTLearn we follow the "fork-and-pull" Git workflow: * Push your work back up to your fork on GitHub * Submit a Pull Request so the core developer team can review your changes +Some CI features are unavailable for pull requests from forks. Frequent +contributors and those preparing pull requests with significant changes +can contact the maintainers to request write access and contribute from a +branch in the main repository instead of a fork. + Code quality ------------- +^^^^^^^^^^^^ CTLearn uses pre-commit hooks for whitespace and file checks, spelling, and Ruff linting and formatting. Install the development dependencies and set up @@ -35,8 +44,12 @@ all files, use: pre-commit run --all-files +CI also runs ``SonarQube`` analysis through ``SonarCloud`` on pull requests from this +repository. It checks code quality, including potential bugs, security issues, +maintainability, and test coverage. + Documentation builds --------------------- +^^^^^^^^^^^^^^^^^^^^ For documentation-only pull requests, apply the ``documentation-only`` label to skip the pip and Pixi test jobs and the dependent SonarCloud scan. The @@ -52,7 +65,7 @@ Removing the label restores tutorial execution. Push builds always execute the tutorials, regardless of pull request labels. Changelog entries ------------------ +^^^^^^^^^^^^^^^^^ Every pull request should include a Towncrier fragment describing its user-facing changes. See ``docs/changes/README.md`` for the naming conventions and supported @@ -60,12 +73,12 @@ categories. If a change does not warrant a changelog entry, maintainers can appl the ``no-changelog-needed`` pull request label. Issues ------- +^^^^^^ Feel free to submit issues and enhancement requests through our `issues page on GitHub `_. Copyright and License ---------------------- +^^^^^^^^^^^^^^^^^^^^^ CTLearn is licensed under the `BSD 3-Clause License `_. diff --git a/docs/source/developer-guide/contributing.rst b/docs/source/developer-guide/contributing.rst deleted file mode 100644 index 1171612c..00000000 --- a/docs/source/developer-guide/contributing.rst +++ /dev/null @@ -1,5 +0,0 @@ -Contributing -============ - -.. include:: ../../../CONTRIBUTING.rst - :start-line: 3 diff --git a/docs/source/developer-guide/index.rst b/docs/source/developer-guide/index.rst index 1dce535e..55b771a4 100644 --- a/docs/source/developer-guide/index.rst +++ b/docs/source/developer-guide/index.rst @@ -9,6 +9,17 @@ Developer Guide Getting Started for Developers ------------------------------ +.. warning:: + + The following guide is used only if you want to *develop* the + CTLearn package, if you just want to write code that uses it + as a dependency, you can install CTLearn from PyPI. + See :ref:`user-guide`. + + +Installation for Developers +=========================== + As a developer, clone the repository and install CTLearn in development mode. We support two methods: *pip/venv* and `Pixi `__. @@ -49,18 +60,13 @@ We support two methods: *pip/venv* and `Pixi `__. $ python -m pip install --upgrade pip $ python -m pip install -e ".[dev]" -Contributing ------------- - -.. toctree:: - :maxdepth: 1 - - contributing - - +.. include:: ../../../CONTRIBUTING.rst Core Dependencies ------------------ +================= + +The following list shows CTLearn's most important dependencies and their minimum +versions where specified. We recommend installing the latest releases. * python>=3.12 * torch>=2.4.0 diff --git a/docs/source/index.rst b/docs/source/index.rst index d26614bd..ae4645ce 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -31,8 +31,7 @@ :link: user-guide/index :link-type: doc - Explore the public simulated CTAO data tutorials, train CTLearn models, and run - inference on image and waveform data. + Install the latest CTLearn version, learn the basics, and explore tutorials. .. grid-item-card:: Developer Guide :link: developer-guide/index diff --git a/docs/source/user-guide/index.rst b/docs/source/user-guide/index.rst index 9ef056b2..115de9e7 100644 --- a/docs/source/user-guide/index.rst +++ b/docs/source/user-guide/index.rst @@ -10,6 +10,15 @@ User Guide Getting Started for Users ------------------------- +.. warning:: + + The following guide is for *users*. If you want to contribute to + CTLearn as a developer, see :ref:`dev-guide`. + + +Installation for Users +====================== + .. tab-set:: .. tab-item:: With Pixi @@ -51,13 +60,169 @@ Getting Started for Users your conda environment and ``/path/to/cudnn/lib`` with the path to the system's cuDNN libraries for CUDA 12. -.. toctree:: - :maxdepth: 1 - auto_tutorials/index +Basic package usage +=================== + +The CTLearn package provides a set of command-line tools for training and predicting with deep learning models +using Keras or PyTorch. The tools are designed to work with data produced by the ``ctapipe`` package following +the CTAO data format. However, it also supports predicting on real observational data from the LST1 telescope +using the ``cta-lstchain`` package for the time being. Detail tutorials on how to use the CTLearn tools +are available in the :ref:`ctlearn-tutorials` section of this documentation. Additionally, a high-level companion +python package to the CTLearn package is available for easy usage of the CTLearn tools. +The package is called `CTLearnManager `_. + +Training tools +^^^^^^^^^^^^^^ + +To train a model, choose the Keras or PyTorch training tool. Use ``--help-all`` +to display its available options. The examples below train a ResNet model for +particle classification: + +.. tab-set:: + + .. tab-item:: Keras + + .. code-block:: shell + + $ ctlearn-train-keras-model --help-all + $ ctlearn-train-keras-model \ + --signal=/path/to/signal_dir \ + --pattern-signal="*gamma*.dl1.h5" \ + --background=/path/to/background_dir \ + --pattern-background="*proton*.dl1.h5" \ + --config=/path/to/reader_config.json \ + --output=/path/to/output_dir_keras \ + --reco=type \ + --TrainCTLearnModel.model_type=ResNet \ + --TrainCTLearnModel.n_epochs=10 \ + --TrainCTLearnModel.batch_size=64 + + .. tab-item:: PyTorch + + .. code-block:: shell + + $ ctlearn-train-pytorch-model --help-all + $ ctlearn-train-pytorch-model \ + --signal=/path/to/signal_dir \ + --pattern-signal="*gamma*.dl1.h5" \ + --background=/path/to/background_dir \ + --pattern-background="*proton*.dl1.h5" \ + --config=/path/to/reader_config.json \ + --output=/path/to/output_dir_pytorch \ + --reco=type \ + --TrainCTLearnModel.model_type=ResNet \ + --TrainCTLearnModel.n_epochs=10 \ + --TrainCTLearnModel.batch_size=64 + +View training progress in real time with TensorBoard: + +.. code-block:: shell + + $ tensorboard --logdir=/path/to/output_dir + +Prediction tools +^^^^^^^^^^^^^^^^ + +To predict with a trained Keras or PyTorch model, use the ``ctlearn-predict-mono-model`` or ``ctlearn-predict-stereo-model`` command. +The following command will display all available options for predicting with a CTLearn model: + +.. code-block:: shell + + $ ctlearn-predict-mono-model --help-all + $ ctlearn-predict-stereo-model --help-all + +**Example: Predicting with a trained mono classification model** + +Use the same reader configuration as for training: + +.. tab-set:: + + .. tab-item:: Keras + + .. code-block:: shell + + $ ctlearn-predict-mono-model \ + --input_url=/path/to/input.dl1.h5 \ + --output=/path/to/keras_prediction_output.dl2.h5 \ + --config=/path/to/reader_config.json \ + --type_model=/path/to/output_dir_keras/ctlearn_model.keras \ + --PredictCTLearnModel.batch_size=64 + + .. tab-item:: PyTorch + + .. code-block:: shell + + $ ctlearn-predict-mono-model \ + --input_url=/path/to/input.dl1.h5 \ + --output=/path/to/pytorch_prediction_output.dl2.h5 \ + --config=/path/to/reader_config.json \ + --type_model=/path/to/output_dir_pytorch/ctlearn_model.pth \ + --PredictCTLearnModel.batch_size=64 + +.. CAUTION:: This tool expects the input data to be produced + via the `ctapipe` package. The output file with the predictions + follows the `ctapipe` DL2 data format. + +View the predictions in a GUI with `ViTables `_: + +.. code-block:: shell + + $ pip install vitables + $ vitables /path/to/*_prediction_output.dl2.h5 + + + +LST-1 prediction tool +^^^^^^^^^^^^^^^^^^^^^ + +To predict on real observational data from the LST1 telescope, use the ``ctlearn-predict-LST1`` command. +The following command will display all available options for predicting with a CTLearn model: + +.. code-block:: shell + + $ ctlearn-predict-LST1 --help-all + +**Example: Predicting on LST1 observational data** + +Use the same image channels and mapping as for training: + +.. tab-set:: + + .. tab-item:: Keras + + .. code-block:: shell + + $ ctlearn-predict-LST1 \ + --input_url=/path/to/lst1_input.dl1.h5 \ + --output=/path/to/lst1_keras_prediction_output.dl2.h5 \ + --type_model=/path/to/type/ctlearn_model.keras \ + --energy_model=/path/to/energy/ctlearn_model.keras \ + --LST1PredictionTool.channels=cleaned_image \ + --LST1PredictionTool.channels=cleaned_relative_peak_time \ + --LST1PredictionTool.image_mapper_type=BilinearMapper + + .. tab-item:: PyTorch + + .. code-block:: shell + + $ ctlearn-predict-LST1 \ + --input_url=/path/to/lst1_input.dl1.h5 \ + --output=/path/to/lst1_pytorch_prediction_output.dl2.h5 \ + --type_model=/path/to/type/ctlearn_model.pth \ + --energy_model=/path/to/energy/ctlearn_model.pth \ + --LST1PredictionTool.channels=cleaned_image \ + --LST1PredictionTool.channels=cleaned_relative_peak_time \ + --LST1PredictionTool.image_mapper_type=BilinearMapper + +.. CAUTION:: This tool expects the input data to be produced + via the ``cta-lstchain`` package. The output file with the predictions + follows the ``ctapipe`` DL2 data format. + +For step-by-step examples from the different workflows, see the :doc:`CTLearn tutorials `. .. toctree:: :hidden: - usage + auto_tutorials/index supplementary diff --git a/docs/source/user-guide/tutorials.rst b/docs/source/user-guide/tutorials.rst index 7ca2f7ff..44f103b5 100644 --- a/docs/source/user-guide/tutorials.rst +++ b/docs/source/user-guide/tutorials.rst @@ -1,3 +1,5 @@ +.. _ctlearn-tutorials: + CTLearn tutorials ================= diff --git a/docs/source/user-guide/usage.rst b/docs/source/user-guide/usage.rst deleted file mode 100644 index 8c24255d..00000000 --- a/docs/source/user-guide/usage.rst +++ /dev/null @@ -1,90 +0,0 @@ -============= -Package usage -============= - -A high-level companion python package to the CTLearn package is available for easy usage of the CTLearn tools. The package is called `CTLearnManager `_. - -Low-level usage of CTLearn tools --------------------------------- - -This page provides a brief overview of how to use the CTLearn tools. - -Training tool -------------- - -To train a model, use the `ctlearn-train-keras-model` or `ctlearn-train-pytorch-model` command. The following command will display all available options for training a CTLearn model: - -.. code-block:: bash - - ctlearn-train-keras-model --help-all - ctlearn-train-pytorch-model --help-all - -**Example: Training a PyTorch ResNet model for particle classification** - -.. code-block:: bash - - ctlearn-train-pytorch-model \ - --signal=/path/to/signal_dir \ - --pattern-signal="*gamma*.dl1.h5" \ - --background=/path/to/background_dir \ - --pattern-background="*proton*.dl1.h5" \ - --output=/path/to/output_dir \ - --reco=type \ - --TrainCTLearnModel.model_type=ResNet \ - --TrainCTLearnModel.n_epochs=10 \ - --TrainCTLearnModel.batch_size=64 - -You can use the exact same arguments with `ctlearn-train-keras-model` to train using the Keras framework. - -View training progress in real time with TensorBoard: - -.. code-block:: bash - - tensorboard --logdir=/path/to/output_dir - -Prediction tools ----------------- - -To predict with a trained Keras or PyTorch model, use the `ctlearn-predict-mono-model` or `ctlearn-predict-stereo-model` command. The following command will display all available options for predicting with a CTLearn model: - -.. code-block:: bash - - ctlearn-predict-mono-model --help-all - ctlearn-predict-stereo-model --help-all - -**Example: Predicting with a trained stereo model** - -.. code-block:: bash - - ctlearn-predict-stereo-model \ - --input=/path/to/data_dir \ - --pattern="*.dl1.h5" \ - --output=/path/to/prediction_output_dir \ - --PredictCTLearnModel.load_model_from=/path/to/output_dir/ctlearn_model.pt \ - --PredictCTLearnModel.reco_tasks="['type']" \ - --PredictCTLearnModel.batch_size=64 - -.. CAUTION:: This tool expects the input data to be produced - via the `ctapipe` package. The output file with the predictions - follows the `ctapipe` DL2 data format. - -To predict on real observational data from the LST1 telescope, use the `ctlearn-predict-LST1` command. The following command will display all available options for predicting with a CTLearn model: - -.. code-block:: bash - - ctlearn-predict-LST1 --help-all - -**Example: Predicting on LST1 observational data** - -.. code-block:: bash - - ctlearn-predict-LST1 \ - --input=/path/to/lst1_data_dir \ - --pattern="Run*.h5" \ - --output=/path/to/lst1_prediction_output_dir \ - --PredictCTLearnModel.load_model_from=/path/to/output_dir/ctlearn_model.keras \ - --PredictCTLearnModel.reco_tasks="['type', 'energy']" - -.. CAUTION:: This tool expects the input data to be produced - via the `cta-lstchain` package. The output file with the predictions - follows the `ctapipe` DL2 data format. From e91fba761c2fae130563cd2b6b9b82f41c2505a1 Mon Sep 17 00:00:00 2001 From: Tjark Miener Date: Mon, 16 Nov 2026 15:10:50 +0100 Subject: [PATCH 53/53] fix typos --- docs/source/developer-guide/index.rst | 22 ++++++++++----------- examples/tutorials/predict_ctlearn_model.py | 2 +- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/source/developer-guide/index.rst b/docs/source/developer-guide/index.rst index 55b771a4..ff618e71 100644 --- a/docs/source/developer-guide/index.rst +++ b/docs/source/developer-guide/index.rst @@ -68,14 +68,14 @@ Core Dependencies The following list shows CTLearn's most important dependencies and their minimum versions where specified. We recommend installing the latest releases. -* python>=3.12 -* torch>=2.4.0 -* tensorflow>=2.18 -* keras>=3.0 -* astropy -* ctapipe>=0.29.0 -* dl1_data_handler>=0.14.13 -* numba -* numpy -* pandas -* pyyaml +* ``python``>=3.12 +* ``torch``>=2.4.0 +* ``tensorflow``>=2.18 +* ``keras``>=3.0 +* ``astropy`` +* ``ctapipe``>=0.29.0 +* ``dl1_data_handler``>=0.14.13 +* ``numba`` +* ``numpy`` +* ``pandas`` +* ``pyyaml`` diff --git a/examples/tutorials/predict_ctlearn_model.py b/examples/tutorials/predict_ctlearn_model.py index 48ae78d8..db24337b 100644 --- a/examples/tutorials/predict_ctlearn_model.py +++ b/examples/tutorials/predict_ctlearn_model.py @@ -7,7 +7,7 @@ are stored in DL2 files following the CTAO reference data model. The tutorial also shows how to visualize the classifier performance, energy resolution, and angular resolution of the predicted events. -The tutorial is intenionally kept simple and uses only a small fraction +The tutorial is intentionally kept simple and uses only a small fraction of the available statistics to keep the prediction time manageable. The resulting performance metrics are not representative of a production-level analysis nor should they be compared directly with published results. The main