diff --git a/ctapipe/calib/__init__.py b/ctapipe/calib/__init__.py index e721e039e5f..3cb1362da9f 100644 --- a/ctapipe/calib/__init__.py +++ b/ctapipe/calib/__init__.py @@ -1,7 +1,10 @@ # Licensed under a 3-clause BSD style license - see LICENSE.rst """ -Calibration +Module for calibration code """ from .camera import CameraCalibrator, GainSelector -__all__ = ["CameraCalibrator", "GainSelector"] +__all__ = [ + "CameraCalibrator", + "GainSelector", +] diff --git a/docs/ctapipe_logo.png b/docs/_static/ctapipe_logo.png similarity index 100% rename from docs/ctapipe_logo.png rename to docs/_static/ctapipe_logo.png diff --git a/docs/ctapipe_logo.webp b/docs/_static/ctapipe_logo.webp similarity index 100% rename from docs/ctapipe_logo.webp rename to docs/_static/ctapipe_logo.webp diff --git a/docs/ctapipe_logo_dark.webp b/docs/_static/ctapipe_logo_dark.webp similarity index 100% rename from docs/ctapipe_logo_dark.webp rename to docs/_static/ctapipe_logo_dark.webp diff --git a/docs/ctapipe_api/atmosphere/index.rst b/docs/api-reference/atmosphere/index.rst similarity index 100% rename from docs/ctapipe_api/atmosphere/index.rst rename to docs/api-reference/atmosphere/index.rst diff --git a/docs/ctapipe_api/calib/index_camera.rst b/docs/api-reference/calib/camera.rst similarity index 77% rename from docs/ctapipe_api/calib/index_camera.rst rename to docs/api-reference/calib/camera.rst index 0827c266218..2b0618e4cd1 100644 --- a/docs/ctapipe_api/calib/index_camera.rst +++ b/docs/api-reference/calib/camera.rst @@ -22,14 +22,13 @@ CameraCalibrator The primary class in this module is the `~ctapipe.calib.camera.calibrator.CameraCalibrator`. This class handles two data level transition stages for the event: -* R1 -> DL0 (:ref:`image_reducers`) -* DL0 -> DL1 (:ref:`image_charge_extractors`) +* R1 → DL0 (:ref:`image_reducers`) +* DL0 → DL1 (:ref:`image_charge_extractors`) The class takes a ctapipe event container, and fills the next data level containers with the calibrated information. -See the `CTA High-Level Data Model Definitions SYS-QA/160517 -`_ document (CTA internal) for information about the +See the `CTA Top-Level Data Model Definitions `_ document (CTA internal) for information about the different data levels. diff --git a/docs/ctapipe_api/calib/index.rst b/docs/api-reference/calib/index.rst similarity index 73% rename from docs/ctapipe_api/calib/index.rst rename to docs/api-reference/calib/index.rst index 398acfed120..949d8ef8a84 100644 --- a/docs/ctapipe_api/calib/index.rst +++ b/docs/api-reference/calib/index.rst @@ -13,24 +13,11 @@ Introduction This module include all the functions and classes needed for the Calibration of CTA data. -It consists in four main sub-modules: - -* :ref:`calib_camera` - -* Array Calibration - -* Atmosphere Calibration - -* Pointing Calibration +Currently, only code related to :ref:`calib_camera` is implemented here. For more information on where you should implement your code, please have a look to the README.rst files inside each directory. -Getting Started -=============== - -TODO: add examples. - Submodules ========== @@ -38,7 +25,7 @@ Submodules :maxdepth: 1 :glob: - index_* + camera diff --git a/docs/ctapipe_api/containers/index.rst b/docs/api-reference/containers/index.rst similarity index 100% rename from docs/ctapipe_api/containers/index.rst rename to docs/api-reference/containers/index.rst diff --git a/docs/ctapipe_api/coordinates/index.rst b/docs/api-reference/coordinates/index.rst similarity index 97% rename from docs/ctapipe_api/coordinates/index.rst rename to docs/api-reference/coordinates/index.rst index 094d833f125..1747b342fb5 100644 --- a/docs/ctapipe_api/coordinates/index.rst +++ b/docs/api-reference/coordinates/index.rst @@ -38,7 +38,7 @@ they can be transformed to and from any other `astropy.coordinates` frame, like The three different coordinate frames are shown here: -.. plot:: ctapipe_api/coordinates/plot_camera_frames.py +.. plot:: api-reference/coordinates/plot_camera_frames.py The `CameraFrame` is used internally in ``ctapipe`` and comes from ``sim_telarray``. diff --git a/docs/ctapipe_api/coordinates/plot_camera_frames.py b/docs/api-reference/coordinates/plot_camera_frames.py similarity index 100% rename from docs/ctapipe_api/coordinates/plot_camera_frames.py rename to docs/api-reference/coordinates/plot_camera_frames.py diff --git a/docs/ctapipe_api/core/corediagram.dot b/docs/api-reference/core/corediagram.dot similarity index 100% rename from docs/ctapipe_api/core/corediagram.dot rename to docs/api-reference/core/corediagram.dot diff --git a/docs/ctapipe_api/core/index.rst b/docs/api-reference/core/index.rst similarity index 100% rename from docs/ctapipe_api/core/index.rst rename to docs/api-reference/core/index.rst diff --git a/docs/ctapipe_api/core/tool-component.pdf b/docs/api-reference/core/tool-component.pdf similarity index 100% rename from docs/ctapipe_api/core/tool-component.pdf rename to docs/api-reference/core/tool-component.pdf diff --git a/docs/ctapipe_api/core/tool-component.png b/docs/api-reference/core/tool-component.png similarity index 100% rename from docs/ctapipe_api/core/tool-component.png rename to docs/api-reference/core/tool-component.png diff --git a/docs/ctapipe_api/core/traits.rst b/docs/api-reference/core/traits.rst similarity index 100% rename from docs/ctapipe_api/core/traits.rst rename to docs/api-reference/core/traits.rst diff --git a/docs/ctapipe_api/image/TwoPassWindowSum_1st_pass_example.png b/docs/api-reference/image/TwoPassWindowSum_1st_pass_example.png similarity index 100% rename from docs/ctapipe_api/image/TwoPassWindowSum_1st_pass_example.png rename to docs/api-reference/image/TwoPassWindowSum_1st_pass_example.png diff --git a/docs/ctapipe_api/image/cleaning.rst b/docs/api-reference/image/cleaning.rst similarity index 100% rename from docs/ctapipe_api/image/cleaning.rst rename to docs/api-reference/image/cleaning.rst diff --git a/docs/ctapipe_api/image/dilate.png b/docs/api-reference/image/dilate.png similarity index 100% rename from docs/ctapipe_api/image/dilate.png rename to docs/api-reference/image/dilate.png diff --git a/docs/ctapipe_api/image/extractor.rst b/docs/api-reference/image/extractor.rst similarity index 100% rename from docs/ctapipe_api/image/extractor.rst rename to docs/api-reference/image/extractor.rst diff --git a/docs/ctapipe_api/image/hillas.rst b/docs/api-reference/image/hillas.rst similarity index 100% rename from docs/ctapipe_api/image/hillas.rst rename to docs/api-reference/image/hillas.rst diff --git a/docs/ctapipe_api/image/index.rst b/docs/api-reference/image/index.rst similarity index 100% rename from docs/ctapipe_api/image/index.rst rename to docs/api-reference/image/index.rst diff --git a/docs/ctapipe_api/image/invalid_pixels.rst b/docs/api-reference/image/invalid_pixels.rst similarity index 100% rename from docs/ctapipe_api/image/invalid_pixels.rst rename to docs/api-reference/image/invalid_pixels.rst diff --git a/docs/ctapipe_api/image/modifications.rst b/docs/api-reference/image/modifications.rst similarity index 100% rename from docs/ctapipe_api/image/modifications.rst rename to docs/api-reference/image/modifications.rst diff --git a/docs/ctapipe_api/image/muon.rst b/docs/api-reference/image/muon.rst similarity index 100% rename from docs/ctapipe_api/image/muon.rst rename to docs/api-reference/image/muon.rst diff --git a/docs/ctapipe_api/image/pixel_likelihood.rst b/docs/api-reference/image/pixel_likelihood.rst similarity index 100% rename from docs/ctapipe_api/image/pixel_likelihood.rst rename to docs/api-reference/image/pixel_likelihood.rst diff --git a/docs/ctapipe_api/image/reducers.rst b/docs/api-reference/image/reducers.rst similarity index 100% rename from docs/ctapipe_api/image/reducers.rst rename to docs/api-reference/image/reducers.rst diff --git a/docs/ctapipe_api/image/toymodel.rst b/docs/api-reference/image/toymodel.rst similarity index 100% rename from docs/ctapipe_api/image/toymodel.rst rename to docs/api-reference/image/toymodel.rst diff --git a/docs/ctapipe_api/index.rst b/docs/api-reference/index.rst similarity index 100% rename from docs/ctapipe_api/index.rst rename to docs/api-reference/index.rst diff --git a/docs/ctapipe_api/instrument/camera.rst b/docs/api-reference/instrument/camera.rst similarity index 100% rename from docs/ctapipe_api/instrument/camera.rst rename to docs/api-reference/instrument/camera.rst diff --git a/docs/ctapipe_api/instrument/camera_geometry.rst b/docs/api-reference/instrument/camera_geometry.rst similarity index 98% rename from docs/ctapipe_api/instrument/camera_geometry.rst rename to docs/api-reference/instrument/camera_geometry.rst index ddf30ae6e8c..00a8bb5307b 100644 --- a/docs/ctapipe_api/instrument/camera_geometry.rst +++ b/docs/api-reference/instrument/camera_geometry.rst @@ -79,7 +79,7 @@ with `numpy` operations, since it is quite speed-efficient. Examples -------- -.. plot:: ctapipe_api/instrument/camerageometry_example.py +.. plot:: api-reference/instrument/camerageometry_example.py :include-source: diff --git a/docs/ctapipe_api/instrument/camera_readout.rst b/docs/api-reference/instrument/camera_readout.rst similarity index 100% rename from docs/ctapipe_api/instrument/camera_readout.rst rename to docs/api-reference/instrument/camera_readout.rst diff --git a/docs/ctapipe_api/instrument/camerageometry_example.py b/docs/api-reference/instrument/camerageometry_example.py similarity index 100% rename from docs/ctapipe_api/instrument/camerageometry_example.py rename to docs/api-reference/instrument/camerageometry_example.py diff --git a/docs/ctapipe_api/instrument/config.dot b/docs/api-reference/instrument/config.dot similarity index 100% rename from docs/ctapipe_api/instrument/config.dot rename to docs/api-reference/instrument/config.dot diff --git a/docs/ctapipe_api/instrument/index.rst b/docs/api-reference/instrument/index.rst similarity index 100% rename from docs/ctapipe_api/instrument/index.rst rename to docs/api-reference/instrument/index.rst diff --git a/docs/ctapipe_api/instrument/optics.rst b/docs/api-reference/instrument/optics.rst similarity index 100% rename from docs/ctapipe_api/instrument/optics.rst rename to docs/api-reference/instrument/optics.rst diff --git a/docs/ctapipe_api/instrument/subarray.rst b/docs/api-reference/instrument/subarray.rst similarity index 100% rename from docs/ctapipe_api/instrument/subarray.rst rename to docs/api-reference/instrument/subarray.rst diff --git a/docs/ctapipe_api/instrument/telescope.rst b/docs/api-reference/instrument/telescope.rst similarity index 100% rename from docs/ctapipe_api/instrument/telescope.rst rename to docs/api-reference/instrument/telescope.rst diff --git a/docs/ctapipe_api/io/index.rst b/docs/api-reference/io/index.rst similarity index 100% rename from docs/ctapipe_api/io/index.rst rename to docs/api-reference/io/index.rst diff --git a/docs/ctapipe_api/io/shower.png b/docs/api-reference/io/shower.png similarity index 100% rename from docs/ctapipe_api/io/shower.png rename to docs/api-reference/io/shower.png diff --git a/docs/ctapipe_api/reco/ImPACT.rst b/docs/api-reference/reco/ImPACT.rst similarity index 100% rename from docs/ctapipe_api/reco/ImPACT.rst rename to docs/api-reference/reco/ImPACT.rst diff --git a/docs/ctapipe_api/reco/images/ImageTemplates.png b/docs/api-reference/reco/images/ImageTemplates.png similarity index 100% rename from docs/ctapipe_api/reco/images/ImageTemplates.png rename to docs/api-reference/reco/images/ImageTemplates.png diff --git a/docs/ctapipe_api/reco/images/goodness.png b/docs/api-reference/reco/images/goodness.png similarity index 100% rename from docs/ctapipe_api/reco/images/goodness.png rename to docs/api-reference/reco/images/goodness.png diff --git a/docs/ctapipe_api/reco/images/likelihood.png b/docs/api-reference/reco/images/likelihood.png similarity index 100% rename from docs/ctapipe_api/reco/images/likelihood.png rename to docs/api-reference/reco/images/likelihood.png diff --git a/docs/ctapipe_api/reco/images/predictions.png b/docs/api-reference/reco/images/predictions.png similarity index 100% rename from docs/ctapipe_api/reco/images/predictions.png rename to docs/api-reference/reco/images/predictions.png diff --git a/docs/ctapipe_api/reco/index.rst b/docs/api-reference/reco/index.rst similarity index 100% rename from docs/ctapipe_api/reco/index.rst rename to docs/api-reference/reco/index.rst diff --git a/docs/ctapipe_api/reco/sklearn.rst b/docs/api-reference/reco/sklearn.rst similarity index 100% rename from docs/ctapipe_api/reco/sklearn.rst rename to docs/api-reference/reco/sklearn.rst diff --git a/docs/ctapipe_api/reco/stereo_combination.rst b/docs/api-reference/reco/stereo_combination.rst similarity index 100% rename from docs/ctapipe_api/reco/stereo_combination.rst rename to docs/api-reference/reco/stereo_combination.rst diff --git a/docs/ctapipe_api/tools/index.rst b/docs/api-reference/tools/index.rst similarity index 100% rename from docs/ctapipe_api/tools/index.rst rename to docs/api-reference/tools/index.rst diff --git a/docs/ctapipe_api/utils/index.rst b/docs/api-reference/utils/index.rst similarity index 100% rename from docs/ctapipe_api/utils/index.rst rename to docs/api-reference/utils/index.rst diff --git a/docs/ctapipe_api/visualization/index.rst b/docs/api-reference/visualization/index.rst similarity index 100% rename from docs/ctapipe_api/visualization/index.rst rename to docs/api-reference/visualization/index.rst diff --git a/docs/cameras.png b/docs/cameras.png deleted file mode 100644 index 94f2585d4a8..00000000000 Binary files a/docs/cameras.png and /dev/null differ diff --git a/docs/conf.py b/docs/conf.py index d4f43125505..013d575931e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -101,6 +101,19 @@ def setup(app): # These links are ignored in the checks, necessary due to broken intersphinx for # these nitpick_ignore = [ + # needed for building the docs with python 3.11 locally. + # we use the lowest supported version on readthedocs, so that is what we use the intersphinx + # link above + ("py:class", "enum.StrEnum"), + # these are coming from traitlets: + ("py:class", "t.Union"), + ("py:class", "t.Any"), + ("py:class", "t.Dict"), + ("py:class", "t.Optional"), + ("py:class", "t.Type"), + ("py:class", "t.List"), + ("py:class", "t.Tuple"), + ("py:class", "Config"), ("py:class", "traitlets.config.configurable.Configurable"), ("py:class", "traitlets.traitlets.HasTraits"), ("py:class", "traitlets.traitlets.HasDescriptors"), @@ -126,6 +139,7 @@ def setup(app): ("py:class", "astropy.table.table.Table"), ("py:class", "eventio.simtel.simtelfile.SimTelFile"), ("py:class", "ctapipe.compat.StrEnum"), + ("py:class", "ctapipe.compat.StrEnum"), ] @@ -196,19 +210,19 @@ def setup(app): json_url = "https://ctapipe.readthedocs.io/en/latest/_static/switcher.json" # Define the version we use for matching in the version switcher. -version_match = os.environ.get("READTHEDOCS_VERSION") +version_match = os.getenv("READTHEDOCS_VERSION") # If READTHEDOCS_VERSION doesn't exist, we're not on RTD # If it is an integer, we're in a PR build and the version isn't correct. if not version_match or version_match.isdigit(): # For local development, infer the version to match from the package. if "dev" in release or "rc" in release: version_match = "latest" - # We want to keep the relative reference if we are in dev mode - # but we want the whole url if we are effectively in a released version - json_url = "_static/switcher.json" else: version_match = release + # We want to keep the relative reference when on a pull request or locally + json_url = "_static/switcher.json" + # -- Options for HTML output ---------------------------------------------- @@ -222,8 +236,8 @@ def setup(app): # documentation. html_theme_options = { "logo": { - "image_light": "ctapipe_logo.webp", - "image_dark": "ctapipe_logo_dark.webp", + "image_light": "_static/ctapipe_logo.webp", + "image_dark": "_static/ctapipe_logo_dark.webp", "alt_text": "ctapipe", }, "github_url": "https://github.com/cta-observatory/ctapipe", diff --git a/docs/development/ceps/accepted/.keep b/docs/developer-guide/ceps/accepted/.keep similarity index 100% rename from docs/development/ceps/accepted/.keep rename to docs/developer-guide/ceps/accepted/.keep diff --git a/docs/development/ceps/accepted/cep-001.rst b/docs/developer-guide/ceps/accepted/cep-001.rst similarity index 100% rename from docs/development/ceps/accepted/cep-001.rst rename to docs/developer-guide/ceps/accepted/cep-001.rst diff --git a/docs/development/ceps/drafts/.keep b/docs/developer-guide/ceps/drafts/.keep similarity index 100% rename from docs/development/ceps/drafts/.keep rename to docs/developer-guide/ceps/drafts/.keep diff --git a/docs/development/ceps/index.rst b/docs/developer-guide/ceps/index.rst similarity index 67% rename from docs/development/ceps/index.rst rename to docs/developer-guide/ceps/index.rst index 502fc117764..c448e955f89 100644 --- a/docs/development/ceps/index.rst +++ b/docs/developer-guide/ceps/index.rst @@ -1,29 +1,29 @@ -**************************** -Ctapipe Enhancment Proposals -**************************** +***************************** +ctapipe Enhancement Proposals +***************************** -CEPs (Ctapipe Enhancment Proposals) are short documents proposing and describing +CEPs (ctapipe Enhancment Proposals) are short documents proposing and describing a major addition or change to ctapipe. See :ref:`cep-001` for further information. Below is a list of merged CEPs, i.e. the ones that are finalised, with status "accepted" or "rejected" or "withdrawn". The ones with "draft" status, i.e. that are under discussion, -can be found on Github as `pull requests with the "CEP" label`_ . +can be found on GitHub as `pull requests with the "CEP" label`_ . Accepted CEPs ============= .. toctree:: - :maxdepth: 1 + :maxdepth: 1 :glob: accepted/* Proposed CEPs ============= -.. +.. toctree:: - :maxdepth: 1 + :maxdepth: 1 :glob: proposed/* @@ -31,13 +31,12 @@ Proposed CEPs Rejected CEPs ============= -.. +.. toctree:: - :maxdepth: 1 + :maxdepth: 1 :glob: rejected/* .. _pull requests with the "cep" label: https://github.com/cta-observatory/ctapipe/issues?q=label%3ACEP - diff --git a/docs/development/ceps/rejected/.keep b/docs/developer-guide/ceps/rejected/.keep similarity index 100% rename from docs/development/ceps/rejected/.keep rename to docs/developer-guide/ceps/rejected/.keep diff --git a/docs/development/code-guidelines.rst b/docs/developer-guide/code-guidelines.rst similarity index 100% rename from docs/development/code-guidelines.rst rename to docs/developer-guide/code-guidelines.rst diff --git a/docs/developer-guide/getting-started.rst b/docs/developer-guide/getting-started.rst new file mode 100644 index 00000000000..146058d49ea --- /dev/null +++ b/docs/developer-guide/getting-started.rst @@ -0,0 +1,464 @@ + +.. _getting_started_dev: + +Getting Started For Developers +============================== + +We strongly recommend using the `mambaforge conda distribution `_. + +.. warning:: + + The following guide is used only if you want to *develop* the + ``ctapipe`` package, if you just want to write code that uses it + as a depdency, you can install ``ctapipe`` from PyPI or conda-forge. + See :ref:`getting_started_users` + + +Forking vs. Working in the Main Repository +------------------------------------------ +If you are a member of CTA (Consortium or Observatory), or +otherwise a regular contributor to ctapipe, the maintainers can give you +access to the main repository at ``cta-observatory/ctapipe``. +Working directly in the main repository has two main advantages +over using a personal fork: + +- No need for synchronisation between the fork and the main repository +- Easier collaboration on the same branch with other developers + +If you are an external contributor and don't plan to contribute regularly, +you need to go for the fork. + +The instructions below have versions for both approaches, select the tab that applies to your +setup. + + +Cloning the repository +---------------------- + +The examples below use ssh, assuming you setup an ssh key to access GitHub. +See `the GitHub documentation `_ if you haven't done so already. + +.. tab-set:: + + .. tab-item:: Working in the main repository + :sync: main + + Clone the repository: + + .. code-block:: console + + $ git clone git@github.com:cta-observatory/ctapipe.git + $ cd ctapipe + + + .. tab-item:: Working a fork + :sync: fork + + In order to checkout the software so that you can push changes to GitHub without + having write access to the main repository at ``cta-observatory/ctapipe``, you + `need to fork `_ it. + + After that, clone your fork of the repository and add the main reposiory as a second + remote called ``upstream``, so that you can keep your fork synchronized with the main repository. + + .. code-block:: console + + $ git clone https://github.com/[YOUR-GITHUB-USERNAME]/ctapipe.git + $ cd ctapipe + $ git remote add upstream https://github.com/cta-observatory/ctapipe.git + + + +Setting up the development environment +-------------------------------------- + +We provide a conda environment with all packages needed for development of ctapipe and a couple of additonal helpful pacakages (like ipython, jupyter and vitables): + +.. code-block:: console + + $ mamba env create -f environment.yml + + +Next, switch to this new virtual environment: + +.. code-block:: console + + $ mamba activate cta-dev + +You will need to run that last command any time you open a new +terminal to activate the conda environment. + + +Installing ctapipe in development mode +-------------------------------------- + +Now setup this cloned version for development. +The following command will use the editable installation feature of python packages. +From then on, all the ctapipe executables and the library itself will be +usable from anywhere, given you have activated the ``cta-dev`` conda environment. + +.. code-block:: console + + $ pip install -e . + +Using the editable installation means you won't have to rerun the installation for +simple code changes to take effect. +However, for things like adding new submodules or new entry points, rerunning the above +step might still be needed. + +ctapipe supports adding new ``EventSource`` and ``Reconstructor`` implementations +through plugins. In order for the respective tests to pass you have to install the +test plugin via + +.. code-block:: console + + $ pip install -e ./test_plugin + + +We are using the ``black`` and ``isort`` auto-formatters for automatic +adherence to the code style (see our :doc:`/developer-guide/style-guide`). +To enforce running these tools whenever you make a commit, setup the +`pre-commit hook `_: + +.. code-block:: console + + $ pre-commit install + +The pre-commit hook will then execute the tools with the same settings as when the a pull request is checked on github, +and if any problems are reported the commit will be rejected. +You then have to fix the reported issues before tying to commit again. +Note that a common problem is code not complying with the style guide, and that whenever this was the only problem found, +simply adding the changes resulting from the pre-commit hook to the commit will result in your changes being accepted. + +Run the tests to make sure everything is OK: + +.. code-block:: console + + $ pytest + +Build the HTML docs locally and open them in your web browser: + +.. code-block:: console + + $ make doc + +Run the example Python scripts: + +.. code-block:: console + + $ cd examples + $ python xxx_example.py + +Try running some command line tools: + +.. code-block:: console + + $ ctapipe-info --all + $ ctapipe-process -i dataset://gamma_prod5.simtel.zst -o test.h5 # try --help for more info + +To update to the latest development version (merging in remote changes +to your local working copy): + + +.. tab-set:: + + .. tab-item:: Working in the main repository + :sync: main + + .. code-block:: console + + $ git pull + + .. tab-item:: Working a fork + :sync: fork + + .. code-block:: console + + $ git fetch upstream + $ git merge upstream/main --ff-only + $ git push + + Note: you can also press the "Sync fork" button on the main page of your fork on the github + and then just use ``git pull``. + +Developing a new feature or code change +--------------------------------------- + +You should always create a new branch when developing some new code. +Make a new branch for each new feature, so that you can make pull-requests +for each one separately and not mix code from each. +It is much easier to review and merge small, well-defined contributions than +a collection of multiple, unrelated changes. + +Most importantly, you should *never* add commits to the ``main`` branch of your fork, +as the main branch will often be updated in the main ``cta-observatory`` repository +and having a diverging history in the main branch of a fork will create issues when trying +to keep forks in sync. + +Remember that ``git switch `` [#switch]_ switches between branches, +``git switch -c `` creates a new branch and switches to it, +and ``git branch`` on it's own will tell you which branches are available +and which one you are currently on. + + +Create a feature branch +^^^^^^^^^^^^^^^^^^^^^^^ + +First think of a name for your code change, here we'll use +*implement_feature_1* as an example. + + +To ensure you are starting your work from an up-to-date ``main`` branch, +we recommend starting a new branch like this: + + +.. tab-set:: + + .. tab-item:: Working in the main repository + :sync: main + + .. code-block:: console + + $ git fetch # get the latest changes + $ git switch -c origin/main # start a new branch from main + + .. tab-item:: Working a fork + :sync: fork + + .. code-block:: console + + $ git fetch upstream # get latest changes from main repository + $ git switch -c upstream/main # start new branch from upstream/main + + + +Edit the code +^^^^^^^^^^^^^ + +and make as many commits as you want (more than one is generally +better for large changes!). + +.. code-block:: sh + + $ git add some_changed_file.py another_file.py + $ git commit + [type descriptive message in window that pops up] + +and repeat. The commit message should follow the *Git conventions*: +use the imperative, the first line is a short description, followed by a blank line, +followed by details if needed (in a bullet list if applicable). You +may even refer to GitHub issue ids, and they will be automatically +linked to the commit in the issue tracker. An example commit message:: + + fix bug #245 + + - changed the order of if statements to avoid logical error + - added unit test to check for regression + +Of course, make sure you frequently test via ``make test`` (or ``pytest`` in a +sub-module), check the style, and make sure the docs render correctly +(both code and top-level) using ``make doc``. + +.. note:: + + A git commit should ideally contain one and only one feature change + (e.g it should not mix changes that are logically different). + Therefore it's best to group related changes with ``git + add ``. You may even commit only *parts* of a changed file + using and ``git add -p``. If you want to keep your git commit + history clean, learn to use commands like ``git commit --ammend`` + (append to previous commit without creating a new one, e.g. when + you find a typo or something small). + + A clean history and a chain of well-written commit messages will + make it easier on code reviews to see what you did. + +Push your changes +^^^^^^^^^^^^^^^^^ + +The first time you push a new branch, you need to specify to which remote the branch +should be pushed [#push]_. Normally this will be ``origin``: + +.. code-block:: console + + $ git push -u origin implement_feature_1 + +After that first setup, you can push new changes using a simple + +.. code-block:: console + + $ git push + + +You can do this at any time and more than once. It just moves the changes +from your local branch on your development machine to your fork on github. + + +Integrating changes from the ``main`` branch. +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In case of updates to the ``main`` branch during your development, +it might be necessary to update your branch to integrate those changes, +especially in case of conflicts. + +To get the latest changes, run: + +.. tab-set:: + + .. tab-item:: Working in the main repository + :sync: main + + .. code-block:: console + + $ git fetch + + .. tab-item:: Working a fork + :sync: fork + + .. code-block:: console + + $ git fetch upstream + +Then, update a local branch using: + +.. tab-set:: + + .. tab-item:: Working in the main repository + :sync: main + + .. code-block:: console + + $ git rebase origin/main + + or + + .. code-block:: console + + $ git merge origin/main + + .. tab-item:: Working a fork + :sync: fork + + .. code-block:: console + + $ git rebase upstream/main + + or + + .. code-block:: console + + $ git merge upstream/main + +For differences between rebasing and merging and when to use which, see `this tutorial `_. + + + +Create a *Pull Request* +^^^^^^^^^^^^^^^^^^^^^^^ + +When you're happy, you create PR on on your github fork page by clicking +"pull request". You can also do this via *GitHub Desktop* if you have +that installed, by pushing the pull-request button in the +upper-right-hand corner. + +Make sure to describe all the changes and give examples and use cases! + +See the :ref:`pullrequests` section for more info. + +Wait for a code review +^^^^^^^^^^^^^^^^^^^^^^ + +Keep in mind the following: + +* At least one reviewer must look at your code and accept your + request. They may ask for changes before accepting. +* All unit tests must pass. They are automatically run by Travis when + you submit or update your pull request and you can monitor the + results on the pull-request page. If there is a test that you added + that should *not* pass because the feature is not yet implemented, + you may `mark it as skipped temporarily + `_ until the + feature is complete. +* All documentation must build without errors. Again, this is checked + by Travis. It is your responsibility to run "make doc" and check + that you don't have any syntax errors in your docstrings. +* All code you have written should follow the style guide (e.g. no + warnings when you run the ``flake8`` syntax checker) + +If the reviewer asks for changes, all you need to do is make them, ``git +commit`` them and then run ``git push`` and the reviewer will see the changes. + +When the PR is accepted, the reviewer will merge your branch into the +*master* repo on cta-observatory's account. + +Delete your feature branch +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +since it is no longer needed (assuming it was accepted and merged in): + +.. code-block:: console + + $ git switch main # switch back to your master branch + +pull in the upstream changes, which should include your new features, and +remove the branch from the local and remote (github). + +.. tab-set:: + + .. tab-item:: Working in the main repository + :sync: main + + .. code-block:: console + + $ git pull + + .. tab-item:: Working a fork + :sync: fork + + .. code-block:: console + + $ git fetch upstream + $ git merge upstream/main --ff-only + +And then delete your branch: + +.. code-block:: console + + $ git branch --delete --remotes implement_feature_1 + + +Debugging Your Code +------------------- + +More often than not your tests will fail or your algorithm will +show strange behaviour. **Debugging** is one of the power tools each +developer should know. Since using ``print`` statements is **not** debugging and does +not give you access to runtime variables at the point where your code fails, we recommend +using ``pdb`` or ``ipdb`` for an IPython shell. +A nice introduction can be found `here `_. + +More Development help +--------------------- + +For coding details, read the :ref:`guidelines` section of this +documentation. + +To make git a bit easier (if you are on a Mac computer) you may want +to use the `github-desktop GUI `_, which +can do most of the fork/clone and remote git commands above +automatically. It provides a graphical view of your fork and the +upstream cta-observatory repository, so you can see easily what +version you are working on. It will handle the forking, syncing, and +even allow you to issue pull-requests. + +.. rubric:: Footnotes + +.. [#switch] ``git switch`` is a relatively new addition to git. If your version of git does not have it, update or use ``git checkout`` instead. The equivalent old command to ``git switch -c`` is ``git checkout -b``. + +.. [#push] As of git version 2.37, you can set these options so that ``git push`` will just work, + also for the first push: + + .. code-block:: console + + $ git config --global branch.autoSetupMerge simple + $ git config --global push.autoSetupRemote true diff --git a/docs/development/index.rst b/docs/developer-guide/index.rst similarity index 62% rename from docs/development/index.rst rename to docs/developer-guide/index.rst index e214e31ad00..dc1d1474c4f 100644 --- a/docs/development/index.rst +++ b/docs/developer-guide/index.rst @@ -1,14 +1,16 @@ -.. _guidelines: +.. _dev-guide: -Coding Guidelines -================= +Developer Guide +=============== .. toctree:: + :maxdepth: 2 + getting-started style-guide code-guidelines - support-libraries pullrequests + support-libraries maintainer-info ceps/index rootmigration diff --git a/docs/developer-guide/maintainer-info.rst b/docs/developer-guide/maintainer-info.rst new file mode 100644 index 00000000000..6922c8dcbe7 --- /dev/null +++ b/docs/developer-guide/maintainer-info.rst @@ -0,0 +1,57 @@ +Maintainer info +=============== + +This is a collection of some notes for maintainers. + +Python / numpy versions to support +---------------------------------- + +ctapipe follows `NEP 29 `_. + +This means ctapipe will require the following minimum python / numpy releases +vs. time: + +- After 2023-01-31 drop support for NumPy 1.20 (initially released on 2021-01-31) +- After 2023-04-14 drop support for Python 3.8 (initially released on 2019-10-14) +- After 2023-06-23 drop support for NumPy 1.21 (initially released on 2021-06-22) +- After 2024-01-01 drop support for NumPy 1.22 (initially released on 2021-12-31) +- After 2024-04-05 drop support for Python 3.9 (initially released on 2020-10-05) +- After 2024-06-22 drop support for NumPy 1.23 (initially released on 2022-06-22) +- After 2024-12-18 drop support for NumPy 1.24 (initially released on 2022-12-18) +- After 2025-04-04 drop support for Python 3.10 (initially released on 2021-10-04) +- After 2026-04-24 drop support for Python 3.11 (initially released on 2022-10-24) + + +However, for specific features, ctapipe could require more recent versions +of numpy. E.g. for the astropy quantity interoperability, we required 1.17 earlier than 2021. + + +How to update the online docs? +------------------------------ + +The docs are automatically built and deployed using readthedocs. + + +How to make a release? +---------------------- +1. Open a new pull request to prepare the release. + This should be the last pull request to be merged before making the actual release. + + Run ``towncrier`` in to render the changelog: + + .. code-block:: console + + $ git fetch + $ git switch -c prepare_ origin/main + $ towncrier build --version= + + Add the planned new version to the ``docs/_static/switcher.json`` file, so it will be + available from the version dropdown once the documentation is built. + +2. Create a new github release, a good starting point should already be made by the + release drafter plugin. + +3. The PyPI upload will be done automatically by Github Actions. + +4. conda packages are built by conda-forge, the recipe is maintained here: https://github.com/conda-forge/ctapipe-feedstock/ + A pull request to update the recipe should be opened automatically by a conda-forge bot when a new version is published to PyPi. This can take a couple of hours. diff --git a/docs/development/pullrequests.rst b/docs/developer-guide/pullrequests.rst similarity index 58% rename from docs/development/pullrequests.rst rename to docs/developer-guide/pullrequests.rst index df9301f84f4..4e54f9ff5eb 100644 --- a/docs/development/pullrequests.rst +++ b/docs/developer-guide/pullrequests.rst @@ -56,42 +56,25 @@ with the request and they will automatically appear (no new pull request needed). The following guidelines should be used to facilitate the review procedure: -* Perform a Scientific or Conceptual Review if the request introduces +* Perform a scientific or conceptual Review if the request introduces new features, algorithms, or design changes - - Look at the use case for the proposed change. +* Look at the use case for the proposed change. - + if the use case is missing, ask for one - + does it make sense? Is it connected to a goal, requirement, or specification? + - if the use case is missing, ask for one + - does it make sense? Is it connected to a goal, requirement, or specification? -* Perform a Code Review in 2 passes +* Perform a Code Review + - Check that all automatic checks succeeded, if not notify the author and give + guidance how to fix the identified issues. - Check that all functions and classes have API documentation in the - correct format (and check that there are no warnings generated - whenbuilding the docs) - - Check that there are at least basic unit tests for each function and class. - - Run all unit tests - - + If any unit tests included in the pull request fail, ask the - developer if that is normal (sometimes there are tests intended - to fail until a feature is available or implemented) - + If any other unit tests that previously suceeded now fail, - **stop** and ask the developer to find out what was broken by - their change - - - Read through the new code being contributed, and see that it - follows the style guidelines and that the API - - + no lines over 90 cols (prefer 80, but some can go a bit over) - + functions and variables are lower case, classes CamelCase, etc. - + variable names give clear meaning - + follows all other PEP8 conventions (run ``pylint`` or ``flake8`` to - check for example), if there are obvious style problems, ask for - them to be fixed. - - * Check for common coding mistakes - * Check that the API (function and class definitions) is clear and - easy to understand. If not, ask for it to be cleaned up - * Check that the code uses the existing features of the ctapipe framework - * Check that the code doesn't introduce new features that are - already present in another form in the framework + correct format. + - Check that there are at least basic unit tests for the added functionality / fixed bug. + - Check that the API (function and class definitions) is clear and + easy to understand. + - Check for common coding mistakes. + - Check for obvious performance issues. + - Check that the code uses the existing features of ctapipe. + - Check that the code doesn't introduce new features that are + already present in another form. diff --git a/docs/development/py-pipe-dependencies.pdf b/docs/developer-guide/py-pipe-dependencies.pdf similarity index 100% rename from docs/development/py-pipe-dependencies.pdf rename to docs/developer-guide/py-pipe-dependencies.pdf diff --git a/docs/development/py-pipe-dependencies.png b/docs/developer-guide/py-pipe-dependencies.png similarity index 100% rename from docs/development/py-pipe-dependencies.png rename to docs/developer-guide/py-pipe-dependencies.png diff --git a/docs/development/rootmigration.rst b/docs/developer-guide/rootmigration.rst similarity index 100% rename from docs/development/rootmigration.rst rename to docs/developer-guide/rootmigration.rst diff --git a/docs/development/style-guide.rst b/docs/developer-guide/style-guide.rst similarity index 96% rename from docs/development/style-guide.rst rename to docs/developer-guide/style-guide.rst index a8db3d5cabf..b442eafe6a4 100644 --- a/docs/development/style-guide.rst +++ b/docs/developer-guide/style-guide.rst @@ -8,7 +8,7 @@ Code follows the Python `PEP8 `_ style guide. This is enforced via the `black formatter `_ -and the pre-commit hook set up in :doc:`/getting_started/index`. +and the pre-commit hook set up in :ref:`getting_started_dev`. You can also use ``black \`` to reformat your code by hand or install editor plugins. diff --git a/docs/development/support-libraries.rst b/docs/developer-guide/support-libraries.rst similarity index 100% rename from docs/development/support-libraries.rst rename to docs/developer-guide/support-libraries.rst diff --git a/docs/development/maintainer-info.rst b/docs/development/maintainer-info.rst deleted file mode 100644 index c7b00f5ac1c..00000000000 --- a/docs/development/maintainer-info.rst +++ /dev/null @@ -1,75 +0,0 @@ -*************** -Maintainer info -*************** - -This is a collection of some notes for maintainers. - -Python / numpy versions to support ----------------------------------- - -ctapipe follows `NEP 29 `_. - -This means ctapipe will require the following minimum python / numpy releases -vs. time: - -After 2020-06-23 drop support for Python 3.6 (initially released on Dec 23, 2016) -After 2021-07-26 drop support for Numpy 1.17 (initially released on Jul 26, 2019) -After 2021-12-22 drop support for Numpy 1.18 (initially released on Dec 22, 2019) -After 2021-12-26 drop support for Python 3.7 (initially released on Jun 27, 2018) -After 2022-06-21 drop support for Numpy 1.19 (initially released on Jun 20, 2020) -After 2023-04-14 drop support for Python 3.8 (initially released on Oct 14, 2019) - -However, for specific features, ctapipe could require more recent versions -of numpy. E.g. for the astropy quantity interoperability, we required 1.17 earlier than 2021. - - -How to update the online docs? ------------------------------- - -The docs are automatically build by travis and uploaded to github pages. - -To do it manually, follow these instructions: - -First install `ghp-import `__ - -.. code-block:: bash - - pip install ghp-import - -Then build the docs: - -.. code-block:: bash - - python setup.py build_docs --clean-docs - -If there's no warnings, you can publish the docs with this command - -.. code-block:: bash - - ghp-import -n -p -m 'Update gh-pages docs' docs/_build/html - -which is equivalent to this make target so that you don't have to remember it: - -.. code-block:: bash - - make doc-publish - -Only ctapipe maintainers can do this, because you need write permission to the main repo. - -How to make a release? ----------------------- -1. Open a new PR to generate a meaningfull changelog. Run ``towncrier`` in order to - do this: - -.. code-block:: bash - - towncrier build --version= - - -2. Create a new github release, a good starting point should already be made by the - release drafter plugin. - -3. The PyPI upload will be done automatically by travis - -4. conda packages are built by conda-forge, the recipe is maintained here: https://github.com/conda-forge/ctapipe-feedstock/ - An pull request to update the recipe should be opened automatically by a conda-forge bot when a new version is published to PyPi. diff --git a/docs/event.png b/docs/event.png deleted file mode 100644 index 82bdbe1db24..00000000000 Binary files a/docs/event.png and /dev/null differ diff --git a/docs/getting_started/index.rst b/docs/getting_started/index.rst deleted file mode 100644 index 92e6ba6b614..00000000000 --- a/docs/getting_started/index.rst +++ /dev/null @@ -1,325 +0,0 @@ - -.. _getting_started: - -****************************** -Getting Started For Developers -****************************** - -We strongly recommend using the `mambaforge conda distribution `_. - -.. warning:: - - the following guide is used only if you want to *develop* the - ``ctapipe`` package, if you just want to write code that uses it - externally, you can install ``ctapipe`` as a conda package - with ``mamba install -c conda-forge ctapipe``. - - -You can use |python_requires| or above. - ------------------------- -Get the ctapipe software ------------------------- - -In order to checkout the software in such a way that you can read *and -commit* changes, you need to `Fork and Clone -`_ the main ctapipe -repository (cta-observatory/ctapipe). - -First, it's useful to make a directory where you have can check out -cta GIT repos (this is optinal - you can put it anywhere) - -.. code-block:: console - - $ mkdir ctasoft - $ cd ctasoft - -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -Step 1: Fork the Master CTA-Observatory ctapipe repository -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -Follow the instructions in the link above to make a *fork* of the -ctapipe repo in your own GitHub userspace. That fork will be then -called *yourusername*/ctapipe (it's as simple as clicking the fork button on `main ctapipe github page `_. - -You only need to make this fork once, when you first start developing, and -you can use it from then on. - -+++++++++++++++++++++++++++++++++++++++++ -Step 2: clone your forked version locally -+++++++++++++++++++++++++++++++++++++++++ - -Next, you need to clone (copy to your local machine) the newly forked -ctapipe repo (make sure you put in your own username there): - -.. code-block:: console - - $ git clone https://github.com/[YOUR-GITHUB-USERNAME]/ctapipe.git - $ cd ctapipe - - -You now need to tell Git that this repo where the master CTA version is: - -.. code-block:: console - - $ git remote add upstream https://github.com/cta-observatory/ctapipe.git - -If that worked, then you should see a *upstream* target in -addition to *origin* when typing ``git remote -v``. Later if you want -to pull in any changes from the master repo, you just need to type -``git pull upstream master``. - - -+++++++++++++++++++++++++++++++++++++++ -Step 4: Set up your package environment -+++++++++++++++++++++++++++++++++++++++ - -Change to the directory where you cloned ``ctapipe``, and type: - -.. code-block:: console - - $ conda env create -n cta-dev -f environment.yml - - -This will create a conda virtual environment called ``cta-dev`` with all -the ctapipe dependencies and a few useful packages for development and -interaction. Next, switch to this new virtual environment: - -.. code-block:: console - - $ source activate cta-dev - - -You will need to type that last command any time you open a new -terminal to actiavate the virtual environment (you can of course -install everything into the base Anaconda environment without creating -a virtual environment, but then you may have trouble if you want to -install other packages with different requirements on the -dependencies) - -+++++++++++++++++++++++++++++++++++++ -Step 5: Setup ctapipe for development -+++++++++++++++++++++++++++++++++++++ - -Now setup this cloned version for development. The following command -will make symlinks in your python library directory to your ctapipe -installation (it creates a ``.pth`` file, there is no need to set -PYTHONPATH, in fact it should be blank to avoid other problems). From -then on, all the ctapipe binaries and the library itself will be -usable from anywhere. - -.. code-block:: console - - $ pip install -e . - -ctapipe supports adding so-called event sources and reconstructors -through plugins. In order for the respective tests to pass you have -to install the test plugin via - -.. code-block:: console - - $ pip install -e ./test_plugin - -Run the tests to make sure everything is OK: - -.. code-block:: console - - $ pytest - -Build the HTML docs locally and open them in your web browser: - -.. code-block:: console - - $ make doc - -Run the example Python scripts: - -.. code-block:: console - - $ cd examples - $ python xxx_example.py - -try running some command line tools: - -.. code-block:: console - - $ ctapipe-info --all - $ ctapipe-camdemo --camera=NectarCam # try --help for more info - -To update to the latest development version (merging in remote changes -to your local working copy): - -.. code-block:: console - - $ git pull upstream master - ---------------------------------------- -Developing a new feature or code change ---------------------------------------- - -We adhere to the PEP8 coding style (see our :doc:`/development/style-guide`). -To enforce this, setup the -`pre-commit hook `_:: - - $ pre-commit install - -You should always create a branch when developing some new code (unless it is -a very small change). Generally make a new branch for each new feature, so -that you can make pull-requests for each one separately and not mix code -from each. Remember that ``git switch `` switches between branches, -``git switch -c `` creates a new branch, and ``git branch`` on it's own -will tell you which branches are available and which one you are currently on. - -First think of a name for your code change, here we'll use -*implement_feature_1* as an example. - -+++++++++++++++++++++++++++ -1. Create a feature branch: -+++++++++++++++++++++++++++ - -.. code-block:: sh - - $ git checkout -b implement_feature_1 - -++++++++++++++++ -2. Edit the code -++++++++++++++++ - -and make as many commits as you want (more than one is generally -better for large changes!). - -.. code-block:: sh - - $ git add some_changed_file.py another_file.py - $ git commit - [type descriptive message in window that pops up] - -and repeat. The commit message should follow the *GIT conventions*: -the first line is a short description, followed by a blank line, -followed by details if needed (in a bullet list if applicable). You -may even refer to GitHub issue ids, and they will be automatically -linked to the commit in the issue tracker. An example commit message:: - - fixed bug #245 - - - changed the order of if statements to avoid logical error - - added unit test to check for regression - -Of course, make sure you frequently test via ``make test`` (or ``pytest`` in a -sub-module), check the style, and make sure the docs render correctly -(both code and top-level) using ``make doc``. - -.. note:: - - A git commit should ideally contain one and only one feature change - (e.g it should not mix changes that are logically different - together). Therefore it's best to group related changes with ``git - add ``. You may even commit only *parts* of a changed file - using and ``git add -p``. If you want to keep your git commit - history clean, learn to use commands like ``git commit --ammend`` - (append to previous commit without creating a new one, e.g. when - you find a typo or something small). - - A clean history and a chain of well-written commit messages will - make it easier on code reviews to see what you did. - -++++++++++++++++++++++++++++++++++++++++++ -3. Push your branch to your fork on github -++++++++++++++++++++++++++++++++++++++++++ - -(sometimes refered to as -"publishing" since it becomes public, but only in your fork) by running - -.. code-block:: sh - - git push - -You can do this at any time and more than once. It just moves the changes -from your local branch on your development machine to your fork on github. - - -++++++++++++++++++++++++++ -4. Create a *Pull Request* -++++++++++++++++++++++++++ - -When you're happy, you create PR on on your github fork page by clicking -"pull request". You can also do this via *GitHub Desktop* if you have -that installed, by pushing the pull-request button in the -upper-right-hand corner. - -Make sure to describe all the changes and give examples and use cases! - -See the :ref:`pullrequests` section for more info. - -+++++++++++++++++++++++++ -5. Wait for a code review -+++++++++++++++++++++++++ - -Keep in mind the following: - -* At least one reviewer must look at your code and accept your - request. They may ask for changes before accepting. -* All unit tests must pass. They are automatically run by Travis when - you submit or update your pull request and you can monitor the - results on the pull-request page. If there is a test that you added - that should *not* pass because the feature is not yet implemented, - you may `mark it as skipped temporarily - `_ until the - feature is complete. -* All documentation must build without errors. Again, this is checked - by Travis. It is your responsibility to run "make doc" and check - that you don't have any syntax errors in your docstrings. -* All code you have written should follow the style guide (e.g. no - warnings when you run the ``flake8`` syntax checker) - -If the reviewer asks for changes, all you need to do is make them, ``git -commit`` them and then run ``git push`` and the reviewer will see the changes. - -When the PR is accepted, the reviewer will merge your branch into the -*master* repo on cta-observatory's account. - -+++++++++++++++++++++++++++++ -6. Delete your feature branch -+++++++++++++++++++++++++++++ - -since it is no longer needed (assuming it was accepted and merged in): - -.. code-block:: sh - - git checkout master # switch back to your master branch - -pull in the upstream changes, which should include your new features, and -remove the branch from the local and remote (github). - -.. code-block:: sh - - git pull upstream master - git branch --delete --remotes implement_feature_1 - -Note the last step can also be done on the GitHub website. - -------------------- -Debugging Your Code -------------------- - -More often than not your tests will fail or your algorithm will -show strange behaviour. **Debugging** is one of the power tools each -developer should know. Since using ``print`` statements is **not** debugging and does -not give you access to runtime variables at the point where your code fails, we recommend -using ``pdb`` or ``ipdb`` for an IPython shell. -A nice introdcution can be found `here `_. - ---------------------- -More Development help ---------------------- - -For coding details, read the :ref:`guidelines` section of this -documentation. - -To make git a bit easier (if you are on a Mac computer) you may want -to use the `github-desktop GUI `_, which -can do most of the fork/clone and remote git commands above -automatically. It provides a graphical view of your fork and the -upstream cta-observatory repository, so you can see easily what -version you are working on. It will handle the forking, syncing, and -even allow you to issue pull-requests. diff --git a/docs/getting_started_users/index.rst b/docs/getting_started_users/index.rst deleted file mode 100644 index 4dd9cf6cbe7..00000000000 --- a/docs/getting_started_users/index.rst +++ /dev/null @@ -1,44 +0,0 @@ - -.. _getting_started_users: - -************************* -Getting Started For Users -************************* - -.. warning:: - - The following guide is for *users*. As of now this will just cover - the basic installation procedure. This guide will be extended in - the future. - - ------------------------- -Get the ctapipe software ------------------------- - -+++++++++++++++++++++++++++++ -How to get the latest version -+++++++++++++++++++++++++++++ - -We recommend using the ``mamba`` package manager, which is a C++ reimplementation of ``conda``. -It can be found `here `_. -Once you created a new virtual environment, you can install ``ctapipe`` with the following command:: - - mamba install -c conda-forge ctapipe - -or with pip:: - - pip install ctapipe - - -+++++++++++++++++++++++++++++ -How to get a specific version -+++++++++++++++++++++++++++++ - -To install a specific version of ``ctapipe`` you can use the following command:: - - mamba install -c conda-forge ctapipe==0.17.0 - -or with pip:: - - pip install ctapipe==0.17.0 diff --git a/docs/index.rst b/docs/index.rst index 84dec76af64..dd18205f56c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,4 +1,4 @@ -.. include:: references.txt +.. include:: references.rst :html_theme.sidebar_secondary.remove: true :html_theme.sidebar_primary.remove: true @@ -13,30 +13,32 @@ Prototype CTA Pipeline Framework (``ctapipe``) | -.. image:: ctapipe_logo.webp +.. image:: _static/ctapipe_logo.webp :class: only-light :align: center :width: 90% :alt: The ctapipe logo. -.. image:: ctapipe_logo_dark.webp +.. image:: _static/ctapipe_logo_dark.webp :class: only-dark :align: center :width: 90% :alt: The ctapipe logo. -| -**Date**: |today| **Version**: |version| + +**Version**: |version| **Date**: |today| **Useful links**: `Source Repository `__ | `Issue Tracker `__ | `Discussions `__ -**License**: BSD-3 **Python**: |python_requires| +**License**: BSD-3 + +**Python**: |python_requires| + -| ``ctapipe`` is a framework for prototyping the low-level data processing algorithms for the Cherenkov Telescope Array. @@ -46,17 +48,11 @@ Prototype CTA Pipeline Framework (``ctapipe``) :maxdepth: 1 :hidden: - User Guide - Developer Guide - development/index - ctapipe_api/index - tutorials/index - examples/index - tools/index - FAQ - data_models/index - bibliography + user-guide/index + developer-guide/index + api-reference/index changelog + bibliography @@ -65,7 +61,7 @@ Prototype CTA Pipeline Framework (``ctapipe``) .. grid-item-card:: :octicon:`book;40px` - + User Guide ^^^^^^^^^^ @@ -74,7 +70,7 @@ Prototype CTA Pipeline Framework (``ctapipe``) +++ - .. button-ref:: getting_started_users/index + .. button-ref:: user-guide/index :expand: :color: primary :click-parent: @@ -85,7 +81,7 @@ Prototype CTA Pipeline Framework (``ctapipe``) .. grid-item-card:: :octicon:`person-add;40px` - + Developer Guide ^^^^^^^^^^^^^^^ @@ -95,90 +91,30 @@ Prototype CTA Pipeline Framework (``ctapipe``) +++ - .. button-ref:: getting_started/index + .. button-ref:: developer-guide/index :expand: :color: primary :click-parent: To the developer guide - - .. grid-item-card:: - - :octicon:`git-pull-request;40px` - - Coding Guidelines - ^^^^^^^^^^^^^^^^^ - - These guidelines explain the coding style and the workflow. The ctapipe - enhancement proposals (CEPs) can also be found here. - - +++ - - .. button-ref:: development/index - :expand: - :color: primary - :click-parent: - - To the development guidelines - .. grid-item-card:: - + :octicon:`code;40px` API Docs ^^^^^^^^ The API docs contain detailed descriptions of - of the various modules and functions included - in ctapipe. + of the various modules, classes and functions + included in ctapipe. +++ - .. button-ref:: ctapipe_api/index + .. button-ref:: api-reference/index :expand: :color: primary :click-parent: To API docs - - - .. grid-item-card:: - - :octicon:`mortar-board;40px` - - Tutorials - ^^^^^^^^^ - - A collection of tutorials aimed at new users - and developers to familiarize with ctapipe. - - +++ - - .. button-ref:: tutorials/index - :expand: - :color: primary - :click-parent: - - To the tutorials - - - .. grid-item-card:: - - :octicon:`light-bulb;40px` - - Examples - ^^^^^^^^ - - Some lower-level examples of features included in the ctapipe API. - - +++ - - .. button-ref:: examples/index - :expand: - :color: primary - :click-parent: - - To the examples - diff --git a/docs/references.txt b/docs/references.rst similarity index 100% rename from docs/references.txt rename to docs/references.rst diff --git a/docs/FAQ.rst b/docs/user-guide/FAQ.rst similarity index 100% rename from docs/FAQ.rst rename to docs/user-guide/FAQ.rst diff --git a/docs/data_models/dl1.rst b/docs/user-guide/data_models/dl1.rst similarity index 100% rename from docs/data_models/dl1.rst rename to docs/user-guide/data_models/dl1.rst diff --git a/docs/data_models/index.rst b/docs/user-guide/data_models/index.rst similarity index 100% rename from docs/data_models/index.rst rename to docs/user-guide/data_models/index.rst diff --git a/docs/examples/InstrumentDescription.ipynb b/docs/user-guide/examples/InstrumentDescription.ipynb similarity index 100% rename from docs/examples/InstrumentDescription.ipynb rename to docs/user-guide/examples/InstrumentDescription.ipynb diff --git a/docs/examples/Tools.ipynb b/docs/user-guide/examples/Tools.ipynb similarity index 100% rename from docs/examples/Tools.ipynb rename to docs/user-guide/examples/Tools.ipynb diff --git a/docs/examples/Tools.json b/docs/user-guide/examples/Tools.json similarity index 100% rename from docs/examples/Tools.json rename to docs/user-guide/examples/Tools.json diff --git a/docs/examples/array_display.ipynb b/docs/user-guide/examples/array_display.ipynb similarity index 100% rename from docs/examples/array_display.ipynb rename to docs/user-guide/examples/array_display.ipynb diff --git a/docs/examples/camera_display.ipynb b/docs/user-guide/examples/camera_display.ipynb similarity index 100% rename from docs/examples/camera_display.ipynb rename to docs/user-guide/examples/camera_display.ipynb diff --git a/docs/examples/containers.ipynb b/docs/user-guide/examples/containers.ipynb similarity index 100% rename from docs/examples/containers.ipynb rename to docs/user-guide/examples/containers.ipynb diff --git a/docs/examples/convert_images_to_2d.ipynb b/docs/user-guide/examples/convert_images_to_2d.ipynb similarity index 100% rename from docs/examples/convert_images_to_2d.ipynb rename to docs/user-guide/examples/convert_images_to_2d.ipynb diff --git a/docs/examples/dilate_image.ipynb b/docs/user-guide/examples/dilate_image.ipynb similarity index 100% rename from docs/examples/dilate_image.ipynb rename to docs/user-guide/examples/dilate_image.ipynb diff --git a/docs/examples/index.rst b/docs/user-guide/examples/index.rst similarity index 100% rename from docs/examples/index.rst rename to docs/user-guide/examples/index.rst diff --git a/docs/examples/nd_interpolation.ipynb b/docs/user-guide/examples/nd_interpolation.ipynb similarity index 100% rename from docs/examples/nd_interpolation.ipynb rename to docs/user-guide/examples/nd_interpolation.ipynb diff --git a/docs/examples/provenance.ipynb b/docs/user-guide/examples/provenance.ipynb similarity index 100% rename from docs/examples/provenance.ipynb rename to docs/user-guide/examples/provenance.ipynb diff --git a/docs/examples/table_writer_reader.ipynb b/docs/user-guide/examples/table_writer_reader.ipynb similarity index 100% rename from docs/examples/table_writer_reader.ipynb rename to docs/user-guide/examples/table_writer_reader.ipynb diff --git a/docs/user-guide/getting-started.rst b/docs/user-guide/getting-started.rst new file mode 100644 index 00000000000..ab1bb88a50f --- /dev/null +++ b/docs/user-guide/getting-started.rst @@ -0,0 +1,55 @@ + +.. _getting_started_users: + + +Getting Started For Users +========================= + +.. warning:: + + The following guide is for *users*. If you want to contribute to + ctapipe as a developer, see :ref:`getting_started_dev`. + + +Installation +------------ + +How to get the latest version +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +We recommend using the ``mamba`` package manager, which is a C++ reimplementation of ``conda``. +It can be found `here `_. + +To install ``ctapipe`` into an existing conda environment, use: + +.. code-block:: console + + $ mamba install -c conda-forge ctapipe + +You can also directly create a new environment like this (add more packages as you like): + +.. code-block:: console + + $ mamba create -n ctapipe -c conda-forge python ctapipe + +or with pip: + +.. code-block:: console + + $ pip install ctapipe + + +How to get a specific version +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To install a specific version of ``ctapipe`` you can use the following command: + +.. code-block:: console + + $ mamba install -c conda-forge ctapipe=0.17.0 + +or with pip: + +.. code-block:: console + + $ pip install ctapipe==0.17.0 diff --git a/docs/user-guide/index.rst b/docs/user-guide/index.rst new file mode 100644 index 00000000000..853408d8363 --- /dev/null +++ b/docs/user-guide/index.rst @@ -0,0 +1,14 @@ +.. _user-guide: + +User Guide +========== + +.. toctree:: + :maxdepth: 2 + + getting-started + tools + data_models/index + tutorials/index + examples/index + FAQ diff --git a/docs/tools/index.rst b/docs/user-guide/tools.rst similarity index 100% rename from docs/tools/index.rst rename to docs/user-guide/tools.rst diff --git a/docs/tutorials/calibrated_data_exploration.ipynb b/docs/user-guide/tutorials/calibrated_data_exploration.ipynb similarity index 100% rename from docs/tutorials/calibrated_data_exploration.ipynb rename to docs/user-guide/tutorials/calibrated_data_exploration.ipynb diff --git a/docs/tutorials/coordinates_example.ipynb b/docs/user-guide/tutorials/coordinates_example.ipynb similarity index 100% rename from docs/tutorials/coordinates_example.ipynb rename to docs/user-guide/tutorials/coordinates_example.ipynb diff --git a/docs/tutorials/ctapipe_handson.ipynb b/docs/user-guide/tutorials/ctapipe_handson.ipynb similarity index 92% rename from docs/tutorials/ctapipe_handson.ipynb rename to docs/user-guide/tutorials/ctapipe_handson.ipynb index 68115dfd9f5..f3c27873309 100644 --- a/docs/tutorials/ctapipe_handson.ipynb +++ b/docs/user-guide/tutorials/ctapipe_handson.ipynb @@ -26,6 +26,7 @@ "from ctapipe import utils\n", "from matplotlib import pyplot as plt\n", "import numpy as np\n", + "\n", "%matplotlib inline" ] }, @@ -146,8 +147,8 @@ "metadata": {}, "outputs": [], "source": [ - "plt.plot(r0tel.waveform[0,brightest_pixel], label=\"channel 0 (high-gain)\")\n", - "plt.plot(r0tel.waveform[1,brightest_pixel], label=\"channel 1 (low-gain)\")\n", + "plt.plot(r0tel.waveform[0, brightest_pixel], label=\"channel 0 (high-gain)\")\n", + "plt.plot(r0tel.waveform[1, brightest_pixel], label=\"channel 1 (low-gain)\")\n", "plt.legend()" ] }, @@ -159,6 +160,7 @@ "source": [ "from ipywidgets import interact\n", "\n", + "\n", "@interact\n", "def view_waveform(chan=0, pix_id=brightest_pixel):\n", " plt.plot(r0tel.waveform[chan, pix_id])" @@ -187,7 +189,7 @@ "metadata": {}, "outputs": [], "source": [ - "subarray = source.subarray " + "subarray = source.subarray" ] }, { @@ -325,7 +327,9 @@ "outputs": [], "source": [ "disp = CameraDisplay(tel.camera.geometry)\n", - "disp.image = r0tel.waveform[0,:,10] # display channel 0, sample 0 (try others like 10)" + "disp.image = r0tel.waveform[\n", + " 0, :, 10\n", + "] # display channel 0, sample 0 (try others like 10)" ] }, { @@ -367,7 +371,7 @@ "outputs": [], "source": [ "for event in EventSource(path, max_events=5):\n", - " calib(event) # fills in r1, dl0, and dl1\n", + " calib(event) # fills in r1, dl0, and dl1\n", " print(event.dl1.tel.keys())" ] }, @@ -395,7 +399,7 @@ "metadata": {}, "outputs": [], "source": [ - "dl1tel.image.shape # note this will be gain-selected in next version, so will be just 1D array of 1855" + "dl1tel.image.shape # note this will be gain-selected in next version, so will be just 1D array of 1855" ] }, { @@ -468,7 +472,7 @@ "outputs": [], "source": [ "cleaned = image.copy()\n", - "cleaned[~mask] = 0 " + "cleaned[~mask] = 0" ] }, { @@ -505,7 +509,7 @@ "disp.add_colorbar()\n", "plt.xlim(0.5, 1.0)\n", "plt.ylim(-1.0, 0.0)\n", - "disp.overlay_moments(params, color='white', lw=2)" + "disp.overlay_moments(params, color=\"white\", lw=2)" ] }, { @@ -557,8 +561,8 @@ "metadata": {}, "outputs": [], "source": [ - "data = utils.get_dataset_path(\"gamma_prod5.simtel.zst\") \n", - "source = EventSource(data) # remove the max_events limit to get more stats" + "data = utils.get_dataset_path(\"gamma_prod5.simtel.zst\")\n", + "source = EventSource(data) # remove the max_events limit to get more stats" ] }, { @@ -569,7 +573,7 @@ "source": [ "for event in source:\n", " calib(event)\n", - " \n", + "\n", " for tel_id, tel_data in event.dl1.tel.items():\n", " tel = source.subarray.tel[tel_id]\n", " mask = tailcuts_clean(tel.camera.geometry, tel_data.image)\n", @@ -583,7 +587,7 @@ "metadata": {}, "outputs": [], "source": [ - "from ctapipe.io import HDF5TableWriter\n" + "from ctapipe.io import HDF5TableWriter" ] }, { @@ -592,12 +596,12 @@ "metadata": {}, "outputs": [], "source": [ - "with HDF5TableWriter(filename='hillas.h5', group_name='dl1', overwrite=True) as writer:\n", - " \n", - " source = EventSource(data, allowed_tels=[1,2,3,4], max_events=10)\n", + "with HDF5TableWriter(filename=\"hillas.h5\", group_name=\"dl1\", overwrite=True) as writer:\n", + "\n", + " source = EventSource(data, allowed_tels=[1, 2, 3, 4], max_events=10)\n", " for event in source:\n", " calib(event)\n", - " \n", + "\n", " for tel_id, tel_data in event.dl1.tel.items():\n", " tel = source.subarray.tel[tel_id]\n", " mask = tailcuts_clean(tel.camera.geometry, tel_data.image)\n", @@ -629,7 +633,7 @@ "source": [ "import pandas as pd\n", "\n", - "hillas = pd.read_hdf(\"hillas.h5\", key='/dl1/hillas')\n", + "hillas = pd.read_hdf(\"hillas.h5\", key=\"/dl1/hillas\")\n", "hillas" ] }, @@ -639,7 +643,7 @@ "metadata": {}, "outputs": [], "source": [ - "_ = hillas.hist(figsize=(8,8))" + "_ = hillas.hist(figsize=(8, 8))" ] }, { diff --git a/docs/tutorials/ctapipe_overview.ipynb b/docs/user-guide/tutorials/ctapipe_overview.ipynb similarity index 100% rename from docs/tutorials/ctapipe_overview.ipynb rename to docs/user-guide/tutorials/ctapipe_overview.ipynb diff --git a/docs/tutorials/ground_frame.png b/docs/user-guide/tutorials/ground_frame.png similarity index 100% rename from docs/tutorials/ground_frame.png rename to docs/user-guide/tutorials/ground_frame.png diff --git a/docs/tutorials/index.rst b/docs/user-guide/tutorials/index.rst similarity index 100% rename from docs/tutorials/index.rst rename to docs/user-guide/tutorials/index.rst diff --git a/docs/tutorials/raw_data_exploration.ipynb b/docs/user-guide/tutorials/raw_data_exploration.ipynb similarity index 87% rename from docs/tutorials/raw_data_exploration.ipynb rename to docs/user-guide/tutorials/raw_data_exploration.ipynb index 4a5595c4b28..1f2a23c978b 100644 --- a/docs/tutorials/raw_data_exploration.ipynb +++ b/docs/user-guide/tutorials/raw_data_exploration.ipynb @@ -170,7 +170,7 @@ "metadata": {}, "outputs": [], "source": [ - "event.simulation.shower.energy.to('GeV')" + "event.simulation.shower.energy.to(\"GeV\")" ] }, { @@ -179,7 +179,7 @@ "metadata": {}, "outputs": [], "source": [ - "event.simulation.shower.energy.to('J')" + "event.simulation.shower.energy.to(\"J\")" ] }, { @@ -237,10 +237,10 @@ "source": [ "plt.pcolormesh(teldata.waveform[0])\n", "plt.colorbar()\n", - "plt.ylim(700,750)\n", + "plt.ylim(700, 750)\n", "plt.xlabel(\"sample number\")\n", "plt.ylabel(\"pixel_id\")\n", - "print(\"waveform[0] is an array of shape (N_pix,N_slice) =\",teldata.waveform[0].shape)" + "print(\"waveform[0] is an array of shape (N_pix,N_slice) =\", teldata.waveform[0].shape)" ] }, { @@ -258,8 +258,8 @@ "metadata": {}, "outputs": [], "source": [ - "trace = teldata.waveform[0][719] \n", - "plt.plot(trace, drawstyle='steps')" + "trace = teldata.waveform[0][719]\n", + "plt.plot(trace, drawstyle=\"steps\")" ] }, { @@ -277,8 +277,10 @@ "metadata": {}, "outputs": [], "source": [ - "for pix_id in range(718,723):\n", - " plt.plot(teldata.waveform[0][pix_id], label=\"pix {}\".format(pix_id), drawstyle='steps')\n", + "for pix_id in range(718, 723):\n", + " plt.plot(\n", + " teldata.waveform[0][pix_id], label=\"pix {}\".format(pix_id), drawstyle=\"steps\"\n", + " )\n", "plt.legend()" ] }, @@ -300,10 +302,10 @@ "metadata": {}, "outputs": [], "source": [ - "for pix_id in range(718,723):\n", - " plt.plot(teldata.waveform[0][pix_id],'+-')\n", - "plt.fill_betweenx([0,1600],19,24,color='red',alpha=0.3, label='Ped window')\n", - "plt.fill_betweenx([0,1600],5,9,color='green',alpha=0.3, label='Signal window')\n", + "for pix_id in range(718, 723):\n", + " plt.plot(teldata.waveform[0][pix_id], \"+-\")\n", + "plt.fill_betweenx([0, 1600], 19, 24, color=\"red\", alpha=0.3, label=\"Ped window\")\n", + "plt.fill_betweenx([0, 1600], 5, 9, color=\"green\", alpha=0.3, label=\"Signal window\")\n", "plt.legend()" ] }, @@ -323,7 +325,7 @@ "source": [ "data = teldata.waveform[0]\n", "peds = data[:, 19:24].mean(axis=1) # mean of samples 20 to 29 for all pixels\n", - "sums = data[:, 5:9].sum(axis=1)/(13-8) # simple sum integration" + "sums = data[:, 5:9].sum(axis=1) / (13 - 8) # simple sum integration" ] }, { @@ -332,7 +334,7 @@ "metadata": {}, "outputs": [], "source": [ - "phist = plt.hist(peds, bins=50, range=[0,150])\n", + "phist = plt.hist(peds, bins=50, range=[0, 150])\n", "plt.title(\"Pedestal Distribution of all pixels for a single event\")" ] }, @@ -368,8 +370,8 @@ "outputs": [], "source": [ "# we can also subtract the pedestals from the traces themselves, which would be needed to compare peaks properly\n", - "for ii in range(270,280):\n", - " plt.plot(data[ii] - peds[ii], drawstyle='steps', label=\"pix{}\".format(ii))\n", + "for ii in range(270, 280):\n", + " plt.plot(data[ii] - peds[ii], drawstyle=\"steps\", label=\"pix{}\".format(ii))\n", "plt.legend()" ] }, @@ -399,9 +401,9 @@ "metadata": {}, "outputs": [], "source": [ - "title=\"CT24, run {} event {} ped-sub\".format(event.index.obs_id,event.index.event_id)\n", - "disp = CameraDisplay(camgeom,title=title)\n", - "disp.image = sums - peds \n", + "title = \"CT24, run {} event {} ped-sub\".format(event.index.obs_id, event.index.event_id)\n", + "disp = CameraDisplay(camgeom, title=title)\n", + "disp.image = sums - peds\n", "disp.cmap = plt.cm.RdBu_r\n", "disp.add_colorbar()\n", "disp.set_limits_percent(95) # autoscale" @@ -429,8 +431,10 @@ "for tel in event.r0.tel.keys():\n", " plt.figure()\n", " camgeom = source.subarray.tel[tel].camera.geometry\n", - " title=\"CT{}, run {} event {}\".format(tel,event.index.obs_id,event.index.event_id)\n", - " disp = CameraDisplay(camgeom,title=title)\n", + " title = \"CT{}, run {} event {}\".format(\n", + " tel, event.index.obs_id, event.index.event_id\n", + " )\n", + " disp = CameraDisplay(camgeom, title=title)\n", " disp.image = event.r0.tel[tel].waveform[0].sum(axis=1)\n", " disp.cmap = plt.cm.RdBu_r\n", " disp.add_colorbar()\n", @@ -466,13 +470,17 @@ "pix_ids = np.arange(len(data))\n", "has_signal = sums > 300\n", "\n", - "widths = np.array([8,]) # peak widths to search for (let's fix it at 8 samples, about the width of the peak)\n", - "peaks = [signal.find_peaks_cwt(trace,widths) for trace in data[has_signal] ]\n", + "widths = np.array(\n", + " [\n", + " 8,\n", + " ]\n", + ") # peak widths to search for (let's fix it at 8 samples, about the width of the peak)\n", + "peaks = [signal.find_peaks_cwt(trace, widths) for trace in data[has_signal]]\n", "\n", - "for p,s in zip(pix_ids[has_signal],peaks):\n", - " print(\"pix{} has peaks at sample {}\".format(p,s))\n", - " plt.plot(data[p], drawstyle='steps-mid')\n", - " plt.scatter(np.array(s),data[p,s])" + "for p, s in zip(pix_ids[has_signal], peaks):\n", + " print(\"pix{} has peaks at sample {}\".format(p, s))\n", + " plt.plot(data[p], drawstyle=\"steps-mid\")\n", + " plt.scatter(np.array(s), data[p, s])" ] }, { diff --git a/docs/tutorials/theta_square.ipynb b/docs/user-guide/tutorials/theta_square.ipynb similarity index 92% rename from docs/tutorials/theta_square.ipynb rename to docs/user-guide/tutorials/theta_square.ipynb index 91191ae275a..6e2c7652f33 100644 --- a/docs/tutorials/theta_square.ipynb +++ b/docs/user-guide/tutorials/theta_square.ipynb @@ -75,7 +75,7 @@ "source": [ "source = EventSource(\n", " \"dataset://gamma_prod5.simtel.zst\",\n", - "# allowed_tels={1, 2, 3, 4},\n", + " # allowed_tels={1, 2, 3, 4},\n", ")\n", "\n", "subarray = source.subarray\n", @@ -105,12 +105,14 @@ " image_processor(event)\n", " shower_processor(event)\n", "\n", - " reco_result = event.dl2.stereo.geometry['HillasReconstructor']\n", + " reco_result = event.dl2.stereo.geometry[\"HillasReconstructor\"]\n", "\n", " # get angular offset between reconstructed shower direction and MC\n", " # generated shower direction\n", " true_shower = event.simulation.shower\n", - " off_angle = angular_separation(true_shower.az, true_shower.alt, reco_result.az, reco_result.alt)\n", + " off_angle = angular_separation(\n", + " true_shower.az, true_shower.alt, reco_result.az, reco_result.alt\n", + " )\n", "\n", " # Appending all estimated off angles\n", " off_angles.append(off_angle.to(u.deg).value)" @@ -140,7 +142,7 @@ "outputs": [], "source": [ "off_angles = np.array(off_angles)\n", - "thetasquare = off_angles[np.isfinite(off_angles)]**2" + "thetasquare = off_angles[np.isfinite(off_angles)] ** 2" ] }, { @@ -167,7 +169,7 @@ "outputs": [], "source": [ "plt.hist(thetasquare, bins=10, range=[0, 0.4])\n", - "plt.xlabel(r'$\\theta^2$ (deg)')\n", + "plt.xlabel(r\"$\\theta^2$ (deg)\")\n", "plt.ylabel(\"# of events\")\n", "plt.show()" ] diff --git a/docs/tutorials/tilted_ground_frame.png b/docs/user-guide/tutorials/tilted_ground_frame.png similarity index 100% rename from docs/tutorials/tilted_ground_frame.png rename to docs/user-guide/tutorials/tilted_ground_frame.png diff --git a/environment.yml b/environment.yml index 0836ac3a37b..e0951f7fec1 100644 --- a/environment.yml +++ b/environment.yml @@ -2,7 +2,6 @@ name: cta-dev channels: - conda-forge - - default dependencies: - python=3.11 - pip