diff --git a/docs/api-reference/atmosphere/index.rst b/docs/api-reference/atmosphere/index.rst index 78ca82592d0..c4815d075be 100644 --- a/docs/api-reference/atmosphere/index.rst +++ b/docs/api-reference/atmosphere/index.rst @@ -1,8 +1,8 @@ .. _atmosphere: -================================================== +***************************************** Atmosphere Models (`~ctapipe.atmosphere`) -================================================== +***************************************** .. currentmodule:: ctapipe.atmosphere @@ -10,6 +10,7 @@ Models of the atmosphere useful for transforming between *column densities* (atmosphere depths :math:`X`, in units of mass per area) and *heights* (in distance above sea-level units). + Reference/API ============= diff --git a/docs/api-reference/calib/camera.rst b/docs/api-reference/calib/camera.rst index 2b0618e4cd1..e0892367e5f 100644 --- a/docs/api-reference/calib/camera.rst +++ b/docs/api-reference/calib/camera.rst @@ -1,23 +1,21 @@ .. _calib_camera: -################## +****************** Camera Calibration -################## +****************** .. currentmodule:: ctapipe.calib.camera -************ Introduction -************ +============ This module contains all the methods and classes that are used to calibrate the CTA Cameras (MC, prototypes and final camera calibration algorithms). -**************** 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: @@ -32,9 +30,8 @@ See the `CTA Top-Level Data Model Definitions 'GCT') Reference/API -------------- +============= .. automodapi:: ctapipe.instrument.optics :no-inheritance-diagram: diff --git a/docs/api-reference/instrument/subarray.rst b/docs/api-reference/instrument/subarray.rst index e17fa4b5d42..5745f5d09ba 100644 --- a/docs/api-reference/instrument/subarray.rst +++ b/docs/api-reference/instrument/subarray.rst @@ -2,8 +2,9 @@ .. currentmodule:: ctapipe.instrument +******************** Subarray Description -==================== +******************** The `SubarrayDescription` class holds info about the list of telescopes in an array or subarray and the position on the ground of each. Internally these @@ -16,8 +17,9 @@ You can also convert them to `astropy.table.Table` objects using `SubarrayDescription.to_table()`, which can then be saved to disk or manipulated. + Reference/API -------------- +============= .. automodapi:: ctapipe.instrument.subarray :no-inheritance-diagram: diff --git a/docs/api-reference/instrument/telescope.rst b/docs/api-reference/instrument/telescope.rst index e30b9364ead..60515eed1c1 100644 --- a/docs/api-reference/instrument/telescope.rst +++ b/docs/api-reference/instrument/telescope.rst @@ -2,8 +2,9 @@ .. currentmodule:: ctapipe.instrument +********************* Telescope Description -===================== +********************* The `TelescopeDescription` class holds info about a complete telescope, namely it's `OpticsDescription` and `CameraDescription` (though other aspects @@ -11,7 +12,7 @@ may be added) Reference/API -------------- +============= .. automodapi:: ctapipe.instrument.telescope :no-inheritance-diagram: diff --git a/docs/api-reference/io/index.rst b/docs/api-reference/io/index.rst index adbc43492b4..60238913676 100644 --- a/docs/api-reference/io/index.rst +++ b/docs/api-reference/io/index.rst @@ -1,11 +1,12 @@ .. _io: -==================== - Input/Output (`io`) -==================== +******************* +Input/Output (`io`) +******************* .. currentmodule:: ctapipe.io + Introduction ============ @@ -127,6 +128,7 @@ using the `~ctapipe.io.HDF5TableReader`, or more generically using the array values in a column cannot be read into a ``pandas.DataFrame``, since it only supports scalar values). + Writing Output Files ==================== @@ -144,8 +146,10 @@ information. It can be used in an event loop like: calibrate(event) write_data(event) + Reading Output Tables ===================== + In addition to using an `EventSource` to read R0-DL1 data files, one can also access full *tables* for files that are in HDF5 format (e.g. DL1 and higher files). @@ -200,10 +204,10 @@ In this case, use: For more examples, see `~ctapipe.io.TableLoader`. + Reading Single HDF5 Tables -------------------------- - The `read_table` function will load any table in an HDF5 table into an ``astropy.table.QTable`` in memory, while maintaining units, column descriptions, and other ctapipe metadata. Astropy Tables can also be converted to Pandas tables via their ``to_pandas()`` method, @@ -217,7 +221,6 @@ as long as the table does not contain any vector columns. mctable.write("output.fits") - Standard Metadata Headers ========================= diff --git a/docs/api-reference/reco/ImPACT.rst b/docs/api-reference/reco/ImPACT.rst index aa6a45e1305..185a65f80de 100644 --- a/docs/api-reference/reco/ImPACT.rst +++ b/docs/api-reference/reco/ImPACT.rst @@ -1,12 +1,14 @@ .. _ImPACT: -Analysis with ImPACT -================================== +******************** +Analysis With ImPACT +******************** .. currentmodule:: ctapipe.reco.impact -What is ImPACT? ---------------------- + +What Is ImPACT? +=============== ImPACT stands for **Image Pixel-wise fit for Atmospheric Cherenkov Telescopes**, it is an event reconstruction algorithm originally created for the H.E.S.S. experiment. This @@ -15,7 +17,7 @@ and nergy, thereby extracting the maximum possible performance of the instrument Image Templates -++++++++++++++++++++++ +--------------- The first step of the analysis is to generate a library of image templates for all possible shower energies, impact distances and depth of maximum. There templates are @@ -31,8 +33,9 @@ details as to how this is performed check the paper (link). The above figure shows 4 examples of the image templates, created in the nominal system (X-Y axis in degrees), with the Z-axis showing the expected number of photo-electrons. + Image Prediction -++++++++++++++++++++++ +---------------- Once the template library has been generated it can then be used to create a predicted gamma-ray image by interpolating between the template available in the library. @@ -45,7 +48,7 @@ class. Calculating Image Likelihood -++++++++++++++++++++++++++++ +---------------------------- Once a prediction of the image expectation can be made it should be compared to the data to assess the likelihood that the model represents the data. Several likelihood @@ -68,8 +71,9 @@ more) additional rows of pixels added around the image edge, and summed over all telescopes passing selection cuts to find an event likelihood for a given set of shower parameters. + Maximum Likelihood Fitting -++++++++++++++++++++++++++ +-------------------------- This event likelihood must then be minimised in a 6-dimensional fit over direction, impact point, Xmax and primary energy. In order to simplify the reconstruction of Xmax @@ -84,13 +88,15 @@ package (a wrapper around the MINUIT minimiser), providing a fast and reliable m The algorithm finds a function minimum in the majority of cases, typically taking around 500 function calls to reach the minimum. + Performance -++++++++++++++++++++++ +----------- Coming soon...? -Running an ImPACT analysis --------------------------- + +Running an ImPACT Analysis +========================== Simple pseudocode example of using ImPACT is shown below. Full example will be added to examples directory soon. @@ -130,8 +136,9 @@ Once the event properties have been passed the event reconstruction can be perfo simply calling the `~ctapipe.reco.ImPACTReconstructor.predict` function and providing a seed shower direction and energy. -Choosing you minimiser -++++++++++++++++++++++ + +Choosing Your Minimiser +----------------------- When initialising the ImPACT reconstructor (see `~ctapipe.reco.ImPACTReconstructor`), one can choose the minimiser to be used in the @@ -142,5 +149,3 @@ purposes. Any of the minimiser names listed for `~scipy.optimize.minimize` or `~scipy.optimize.least_squares` can be used. For example "bfgs" or "lm" can be used to select the scipy BFGS or Levenberg-Marquart minimisers respectively. - - diff --git a/docs/api-reference/reco/index.rst b/docs/api-reference/reco/index.rst index c96f83ba4df..248328d5510 100644 --- a/docs/api-reference/reco/index.rst +++ b/docs/api-reference/reco/index.rst @@ -1,11 +1,12 @@ .. _reco: -================================ +******************************** Reconstruction (`~ctapipe.reco`) -================================ +******************************** .. currentmodule:: ctapipe.reco + Introduction ============ @@ -16,10 +17,12 @@ or mono (single telescope) information. All shower reconstruction algorithms should be subclasses of `~ctapipe.reco.Reconstructor` which defines some common functionality. + Currently Implemented Algorithms ================================ -Moment-Based Stereo Reconstruction + +Moment-based Stereo Reconstruction ---------------------------------- Moment-base reconstruction uses the moments of each shower image (the @@ -28,7 +31,8 @@ combines them geometrically to estimate the true shower direction. The implementation is in the `~ctapipe.reco.HillasReconstructor` class. -Machine-Learning-Based Reconstruction + +Machine Learning-based Reconstruction ------------------------------------- This module also provides `~ctapipe.reco.Reconstructor` implementations using @@ -37,7 +41,8 @@ machine learning algorithms. At the moment, these are based on algorithms from ``scikit-learn`` and make use of DL1b and DL2 information. -Template-Based Stereo Reconstruction + +Template-based Stereo Reconstruction ------------------------------------ Moment-base reconstruction uses the a fit of the full camera images to an expected diff --git a/docs/api-reference/reco/sklearn.rst b/docs/api-reference/reco/sklearn.rst index 2548f92362a..7680c306ffe 100644 --- a/docs/api-reference/reco/sklearn.rst +++ b/docs/api-reference/reco/sklearn.rst @@ -1,11 +1,12 @@ .. _reco_sklearn: -============================================================== -Reconstructors based on Scikit-Learn (`~ctapipe.reco.sklearn`) -============================================================== +************************************************************** +Reconstructors Based On Scikit-Learn (`~ctapipe.reco.sklearn`) +************************************************************** .. currentmodule:: ctapipe.reco.sklearn + Introduction ============ diff --git a/docs/api-reference/reco/stereo_combination.rst b/docs/api-reference/reco/stereo_combination.rst index 04294cb6e50..2e822c5d7bf 100644 --- a/docs/api-reference/reco/stereo_combination.rst +++ b/docs/api-reference/reco/stereo_combination.rst @@ -1,11 +1,12 @@ .. _reco_stereo_combination: -================== +****************** Stereo Combination -================== +****************** .. currentmodule:: ctapipe.reco.sklearn + Introduction ============ diff --git a/docs/api-reference/tools/index.rst b/docs/api-reference/tools/index.rst index e9e9823e253..25efbb905e8 100644 --- a/docs/api-reference/tools/index.rst +++ b/docs/api-reference/tools/index.rst @@ -1,11 +1,12 @@ .. _tools: -===================================== -Command line tools (`~ctapipe.tools`) -===================================== +************************************* +Command-line Tools (`~ctapipe.tools`) +************************************* .. currentmodule:: ctapipe.tools + Introduction ============ @@ -47,7 +48,7 @@ Common Tool Functionality shown, but if you specify DEBUG you will get everything. -Developing a new Tool +Developing a New Tool ===================== To create a new command-line Tool, follow the following procedure: @@ -77,7 +78,6 @@ To create a new command-line Tool, follow the following procedure: re-install the ctapipe package in non-developer mode. - Reference/API ============= diff --git a/docs/api-reference/utils/index.rst b/docs/api-reference/utils/index.rst index 3e0f90c3462..d3646582e6d 100644 --- a/docs/api-reference/utils/index.rst +++ b/docs/api-reference/utils/index.rst @@ -1,11 +1,12 @@ .. _utils: -============================ +**************************** Utilities (`~ctapipe.utils`) -============================ +**************************** .. currentmodule:: ctapipe.utils + Introduction ============ @@ -24,7 +25,7 @@ It currently provides: * json conversion -Access to Service Data files +Access To Service Data Files ============================ The `get_dataset_path()` function provides a common way to load CTA "SVC" diff --git a/docs/api-reference/visualization/index.rst b/docs/api-reference/visualization/index.rst index 8585163b643..c5c5ced1573 100644 --- a/docs/api-reference/visualization/index.rst +++ b/docs/api-reference/visualization/index.rst @@ -1,11 +1,12 @@ .. _visualization: -======================================== +**************************************** Visualization (`~ctapipe.visualization`) -======================================== +**************************************** .. currentmodule:: ctapipe.visualization + Introduction ============ @@ -17,7 +18,7 @@ to render displays, but in the future more rendering methods may be supported. The main classes are: * `CameraDisplay` -* `ArrayDisplay` +* `ArrayDisplay` Reference/API @@ -25,8 +26,3 @@ Reference/API .. automodapi:: ctapipe.visualization :no-inheritance-diagram: - - - - - diff --git a/docs/bibliography.rst b/docs/bibliography.rst index 3ae82af0d7e..f77f2667aeb 100644 --- a/docs/bibliography.rst +++ b/docs/bibliography.rst @@ -1,5 +1,6 @@ +********** References -========== +********** .. [chaudhuri93] B. B. Chaudhuri und P. Kundu. "Optimum circular fit to weighted data in multi-dimensional space". Pattern diff --git a/docs/changelog.rst b/docs/changelog.rst index 54cb53989b7..2120f0791ea 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -1,6 +1,5 @@ - -========== +********** Change Log -========== +********** .. include:: ../CHANGES.rst diff --git a/docs/changes/2474.maintenance.rst b/docs/changes/2474.maintenance.rst new file mode 100644 index 00000000000..38839a05c30 --- /dev/null +++ b/docs/changes/2474.maintenance.rst @@ -0,0 +1,2 @@ +Fix headings in docs. Change occurrences of ``API Reference`` to ``Reference/API`` for consistency. +Change capitalization of some headings for consistency. diff --git a/docs/developer-guide/ceps/accepted/cep-001.rst b/docs/developer-guide/ceps/accepted/cep-001.rst index 4fec1a4f434..cc4e59dc277 100644 --- a/docs/developer-guide/ceps/accepted/cep-001.rst +++ b/docs/developer-guide/ceps/accepted/cep-001.rst @@ -1,9 +1,9 @@ .. _cep-001: -********************************** -CEP 1 - Purpose and guidelines -********************************** +****************************** +CEP 1 - Purpose and Guidelines +****************************** * Status: accepted * Discussion: `PR #2256`_ @@ -12,6 +12,7 @@ CEP 1 - Purpose and guidelines * Author: Tomas Bylund * Created: 2023-02-10 + Abstract ======== @@ -35,7 +36,7 @@ Because the CEPs are maintained as text files in a versioned repository history is the historical record of the feature proposal -What is a CEP? +What Is a CEP? ============== ctapipe Enhancment Proposals are short documents proposing a major @@ -69,6 +70,7 @@ Instead bring the topic up in discussions first with other ctapipe developers, o the mailing list, to get some initial feedback. This will let you figure out if writing a CEP will be helpful or not to realise your proposal. + Writing a CEP ============= @@ -111,8 +113,10 @@ Process CEPs do not require an reference implementation, but in cases where chan to governance or decision-making is being proposed it is highly encouraged to give examples of the process in use by other organisations. -The CEP format + +The CEP Format -------------- + When starting to write a CEP, we suggest you copy & paste & update the header at the top of this file, i.e. the title, bullet list with "Author" etc, up to and including the ``Abstract`` section. @@ -145,8 +149,10 @@ to just put a new one, and in that case what the plan concerning the old code is `PEP 481`_ is an example of a "process" PEP, proposing to move CPython development to git and Github. + Submitting a CEP ================ + Once a complete draft for a CEP is written, it can be submitted for comunity discussion by opening a pull request adding a RST file to the ``docs/development/ceps`` folder in the main ctapipe repository. @@ -158,7 +164,8 @@ the author, but the role can be filled by any interested party. Most discussion ctapipe will happen by talking to each other directly (calls or face-to-face), or online on slack or Github. -CEP review + +CEP Review ========== CEP review happens on the pull request on Github. @@ -185,7 +192,8 @@ with the goal to reach consensus or compromise, and then make the final decision Usually a short "Decision rationale" section will be added at the end of the document after discussion by the reviewers. -CEP status + +CEP Status ========== CEPs can have a status of: @@ -206,7 +214,8 @@ one of "withdrawn", "accepted" or "rejected". The reviewers should add a section decision on this CEP. Then in any case, the CEP should be merged, even if it's status is "withdrawn" or "rejected". -Final remarks + +Final Remarks ============= This CEP leaves some points open. @@ -236,8 +245,10 @@ Specifically the following points remain flexible: that ctapipe the core developers will be friendly people that can collaborate and find a solution or at least compromise that works for everyone. + Acknowledgments =============== + The above proposal text borrows heavily from the Gammapy change proposal document, having started as a straight copy of it. It also copies and adapts substantial parts of the change proposal document for Astropy, as well as incorporates some diff --git a/docs/developer-guide/ceps/index.rst b/docs/developer-guide/ceps/index.rst index dc92c93ad54..352e578a7f1 100644 --- a/docs/developer-guide/ceps/index.rst +++ b/docs/developer-guide/ceps/index.rst @@ -20,6 +20,7 @@ Accepted CEPs accepted/* + Proposed CEPs ============= @@ -29,6 +30,7 @@ Proposed CEPs proposed/* + Rejected CEPs ============= diff --git a/docs/developer-guide/ceps/proposed/cep-002.rst b/docs/developer-guide/ceps/proposed/cep-002.rst index 02121dbc9ad..f48c18dec9f 100644 --- a/docs/developer-guide/ceps/proposed/cep-002.rst +++ b/docs/developer-guide/ceps/proposed/cep-002.rst @@ -1,6 +1,5 @@ .. _cep-002: - *********************** CEP 2 - Event Structure *********************** @@ -12,6 +11,7 @@ CEP 2 - Event Structure * Author: Maximilian Linhoff * Created: 2023-04-04 + Abstract ======== @@ -29,7 +29,8 @@ This has the following advantages: This maps nicely to readers filling a ``TelescopeEventContainer`` which are then joined together with array level information into an ``ArrayEventContainer``. -Proposed new structure + +Proposed New Structure ====================== This CEP proposes to change the current layout of ``ArrayEventContainer`` from having multiple @@ -68,7 +69,7 @@ Which each data level container having specific fields and/or subcontainers incl information (interpolated / chosen for that specific event). -Advantages of the new structure +Advantages of the New Structure =============================== The new proposed scheme makes it easier to parallelize over array events and move loops @@ -89,12 +90,12 @@ In the current scheme (simplified from ctapipe-process) it looks like this: # calibrate r1 to dl0 # for tel_id, dl0 in array_event.dl0.tel.items(): # calibrate dl0 to dl1 - + image_processor(array_event) # image processor also has an internal loop over the telescope events # for tel_id, dl1 in array_event.dl1.tel.items(): # image cleaning and parametrization - + shower_processor(array_event) This looks simple, but there are hidden loops over the telescopes in both the ``CameraCalibrator`` @@ -183,8 +184,7 @@ will become: which is more idiomatic python and does not require repeated lookup via tel_id. - -Previous discussions +Previous Discussions ==================== Previous discussion of this issue has occurred over multiple issues, @@ -193,9 +193,7 @@ but also in `#1301 `_, and `722 `_. - - -Advantages of the old structure +Advantages of the Old Structure =============================== By having the data level first in the hierarchy, it is easier to drop certain data levels for diff --git a/docs/developer-guide/ceps/proposed/cep-003-remove-image-parameters-in-camera-frame.rst b/docs/developer-guide/ceps/proposed/cep-003-remove-image-parameters-in-camera-frame.rst index 463df4ac2a5..a9bdc2bbdff 100644 --- a/docs/developer-guide/ceps/proposed/cep-003-remove-image-parameters-in-camera-frame.rst +++ b/docs/developer-guide/ceps/proposed/cep-003-remove-image-parameters-in-camera-frame.rst @@ -1,8 +1,7 @@ .. _cep-003: - ************************************************************ -CEP 3 - Dropping support for image parameters in CameraFrame +CEP 3 - Dropping Support for Image Parameters in CameraFrame ************************************************************ * Status: draft @@ -12,6 +11,7 @@ CEP 3 - Dropping support for image parameters in CameraFrame * Author: Maximilian Linhoff * Created: 2023-09-22 + Abstract ======== @@ -29,7 +29,8 @@ The overhead of supporting both ``TelescopeFrame`` and ``CameraFrame`` represent of the image parameters is quite significant, as it e.g. requires dealing with both possible definitions in all Hillas-style dl2 reconstructors. -Advantages of computation in TelescopeFrame + +Advantages of Computation in TelescopeFrame =========================================== Computing the image parameters in ``TelescopeFrame`` – angular units on the sky – @@ -44,8 +45,9 @@ has the following advantages: special handling of the curved cameras of dual mirror telescopes. -Previous discussions +Previous Discussions ==================== + * Issue discussing the removal of the camera frame image parameters: `#2061 `_ * Original issue for introducing the computation of image parameters in telescope frame: `#1090 `_ * Pull Request implementing image parameters in telescope frame, also setting it as the default: `#1591 `_ diff --git a/docs/developer-guide/code-guidelines.rst b/docs/developer-guide/code-guidelines.rst index bf8a9d6ae2f..c5126aee807 100644 --- a/docs/developer-guide/code-guidelines.rst +++ b/docs/developer-guide/code-guidelines.rst @@ -1,5 +1,6 @@ +*************** Code Guidelines -=============== +*************** Coding should follow the CTA coding guidelines from the **CTA Code Standards** document. @@ -9,15 +10,17 @@ also the style-guide for code style). This guide is subject to change as we further develop the framework, so it should be checked regularly. -References for good coding practices ------------------------------------- + +References for Good Coding Practices +==================================== * `Good Python Style `_ * `Best Practices in Scientific Computing (Presentation) `_ * `Best Practices for Scientific Computing (Paper) `_ + Checking for Logistic Errors ----------------------------- +============================ Several static analysis packages exist to help look for common coding errors, and these should be used frequently. @@ -34,8 +37,9 @@ errors, and these should be used frequently. If you use *PyCharm* as an IDE, there is also a GUI function to find and review all common code errors and style issues. + Unit-tests ----------- +========== A *unit test* is a piece of code that tests a single functionality of a library (e.g. a function, method, or class). @@ -69,7 +73,7 @@ Follow these basic guidelines: Data Structures ---------------- +=============== Python is very flexible with data structures: data can be in classes, dictionaries, lists, tuples, and numpy ``NDArrays``. Furthermore, the @@ -91,8 +95,8 @@ basic guidelines: disk (they are not necessary for simple function return values) -Logging and debugging ---------------------- +Logging and Debugging +===================== * do not use the ``print()`` function to output text. Instead use the common logging failities of ``ctapipe``. Log messages should be @@ -148,8 +152,8 @@ Some logging guidelines: ``logger.debug("some message: %d", val)`` -Function or method Input/Output -------------------------------- +Function or Method Input/Output +=============================== Functions and methods should *not modify input parameters*. Therefore any data you pass in should be independent of what is output (do not @@ -158,8 +162,9 @@ reason for this is to allow for parallelization and flow-based chaining of algorithms, which is impossible if one algorithm modifies the input to another. + Unit Quantities ---------------- +=============== When approprate (e.g. in high-level algorithms APIs), use ``astropy.units`` for any quantity where the unit may be ambiguous or @@ -202,7 +207,7 @@ parameters are defined), and assume it. Writing Algorithms ------------------- +================== Note that if you write an algorithm, it may be used in many ways: in a command-line tool used in a batch-based system, in a server that diff --git a/docs/developer-guide/getting-started.rst b/docs/developer-guide/getting-started.rst index 146058d49ea..a6c912f5751 100644 --- a/docs/developer-guide/getting-started.rst +++ b/docs/developer-guide/getting-started.rst @@ -1,8 +1,9 @@ .. _getting_started_dev: -Getting Started For Developers -============================== +****************************** +Getting Started for Developers +****************************** We strongly recommend using the `mambaforge conda distribution `_. @@ -15,7 +16,8 @@ We strongly recommend using the `mambaforge conda distribution `_ if you haven't done so already. @@ -68,9 +70,8 @@ See `the GitHub documentation upstream/main # start new branch from upstream/main - -Edit the code -^^^^^^^^^^^^^ +Edit the Code +------------- and make as many commits as you want (more than one is generally better for large changes!). @@ -273,8 +274,9 @@ sub-module), check the style, and make sure the docs render correctly 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 -^^^^^^^^^^^^^^^^^ + +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``: @@ -294,8 +296,8 @@ 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. -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +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, @@ -352,9 +354,8 @@ Then, update a local branch using: 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 @@ -365,8 +366,9 @@ 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 -^^^^^^^^^^^^^^^^^^^^^^ + +Wait for a Code Review +---------------------- Keep in mind the following: @@ -391,8 +393,9 @@ 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 -^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Delete Your Feature Branch +-------------------------- since it is no longer needed (assuming it was accepted and merged in): @@ -428,7 +431,7 @@ And then delete your branch: 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 @@ -437,8 +440,9 @@ not give you access to runtime variables at the point where your code fails, we using ``pdb`` or ``ipdb`` for an IPython shell. A nice introduction can be found `here `_. -More Development help ---------------------- + +More Development Help +===================== For coding details, read the :ref:`guidelines` section of this documentation. diff --git a/docs/developer-guide/index.rst b/docs/developer-guide/index.rst index dc1d1474c4f..52b1d5afc2c 100644 --- a/docs/developer-guide/index.rst +++ b/docs/developer-guide/index.rst @@ -1,7 +1,8 @@ .. _dev-guide: +*************** Developer Guide -=============== +*************** .. toctree:: :maxdepth: 2 diff --git a/docs/developer-guide/maintainer-info.rst b/docs/developer-guide/maintainer-info.rst index 6922c8dcbe7..b024884cc5c 100644 --- a/docs/developer-guide/maintainer-info.rst +++ b/docs/developer-guide/maintainer-info.rst @@ -1,10 +1,12 @@ -Maintainer info -=============== +*************** +Maintainer Info +*************** This is a collection of some notes for maintainers. -Python / numpy versions to support ----------------------------------- + +Python / NumPy Versions To Support +================================== ctapipe follows `NEP 29 `_. @@ -26,14 +28,15 @@ 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? ------------------------------- +How To Update the Online Docs? +============================== The docs are automatically built and deployed using readthedocs. -How to make a release? ----------------------- +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. diff --git a/docs/developer-guide/pullrequests.rst b/docs/developer-guide/pullrequests.rst index 4e54f9ff5eb..782a7dd4d45 100644 --- a/docs/developer-guide/pullrequests.rst +++ b/docs/developer-guide/pullrequests.rst @@ -1,10 +1,12 @@ .. _pullrequests: +********************************** Making and Accepting Pull Requests -================================== +********************************** + Making a Pull Request ---------------------- +===================== In the pull request description (editable on GitHub), you should include the following information (some may be omitted if it is e.g. a @@ -32,8 +34,8 @@ Note that you can include syntax-highlighted code examples by using 3 back-tics: ``` -Keep in mind ------------- +Keep in Mind +============ * make sure you remember to update the **documentation** as well as the code! (see the ``docs/`` directory), and make sure it builds with no errors @@ -47,7 +49,7 @@ Keep in mind Accepting a Pull Request ------------------------- +======================== ``ctapipe`` maintainers must do a *code review* before accepting any pull request. During the review the reviewer can ask for changes to be diff --git a/docs/developer-guide/rootmigration.rst b/docs/developer-guide/rootmigration.rst index 167850a325e..e05234858c1 100644 --- a/docs/developer-guide/rootmigration.rst +++ b/docs/developer-guide/rootmigration.rst @@ -1,5 +1,5 @@ ************** -For ROOT users +For ROOT Users ************** Many previous VHE gamma-ray developers are familiar with the CERN ROOT @@ -14,7 +14,7 @@ python stack, the following table can be helpful: +---------------------------------+------------------------------------------------------------+ -| **ROOT functionality** | **Recommended Python Equivalent** | +| **ROOT Functionality** | **Recommended Python Equivalent** | +=================================+============================================================+ | interactive interpreter | ipython, jupyter notebook | +---------------------------------+------------------------------------------------------------+ diff --git a/docs/developer-guide/style-guide.rst b/docs/developer-guide/style-guide.rst index b442eafe6a4..6560934b2a8 100644 --- a/docs/developer-guide/style-guide.rst +++ b/docs/developer-guide/style-guide.rst @@ -1,8 +1,10 @@ +*********** Style Guide -================== +*********** + Coding Style ------------- +============ Code follows the Python `PEP8 `_ style guide. @@ -15,7 +17,7 @@ editor plugins. API Documentation Style ------------------------ +======================= All functions, classes, and modules should contain appropriate API documentation in their *docstrings*. The *docstrings* should be @@ -30,9 +32,8 @@ citing a reference in that file:: this algorithm is an implementaton of [author2003]_ - Interactive Development Environment ------------------------------------ +=================================== It is recommended that a fully python-aware *interactive development environment* (IDE) is used to develop code, rather than a basic text @@ -46,7 +47,4 @@ problems. The recommended IDEs are: The IDEs provide a lot of support for avoiding common style and coding mistakes, and automatic re-formatting (e.g. ``M-x py-autopep8-buffer`` -in emacs) - - - +in emacs). diff --git a/docs/developer-guide/support-libraries.rst b/docs/developer-guide/support-libraries.rst index ade030f267a..6c9b61a7868 100644 --- a/docs/developer-guide/support-libraries.rst +++ b/docs/developer-guide/support-libraries.rst @@ -43,6 +43,7 @@ Specific functionality: these functions are all based on ``numpy.ndarray`` data structures, which provide c-like speeds. + Multivariate Analysis and Machine Learning ========================================== @@ -93,7 +94,8 @@ We support the following systems to process and manipulate tabular data (e.g. * ``pytables``: for direct manipulation of tables in HDF5 files (faster than other systems for large on-disk files) -low-level FITS Table Access + +Low-level FITS Table Access --------------------------- FITS Tables can be read via ``astropy.table``, or ``astropy.io.fits``, @@ -104,7 +106,8 @@ in a FITS table, the ``fitsio`` module should be used instead. It is a simple wrapper for libCFITSIO, and supports efficient row-wise table access. -low-level HDF5 Table Access + +Low-level HDF5 Table Access --------------------------- For HDF5 input/output we use ``pytables`` directly and ``h5py`` through @@ -117,6 +120,7 @@ Model Fitting We support only ``scipy.optimize``, ``iminuit``, and ``scikit-learn`` fitting systems. + Graphics and Plotting ===================== @@ -125,6 +129,7 @@ We support the following: * ``matplotlib`` (recommended for most cases) * ``bokeh`` (for web-guis) + Parallelization and Speed-ups ============================= @@ -132,7 +137,8 @@ Since execution speed is important in some algorithms (particularly those called per-event), the speed of python can be a hindrance to performance. The following methods to improve speed are allowed in ``ctapipe``: -Use NumPy operations + +Use NumPy Operations -------------------- One of the easiest way to speed up code is to attempt to avoid *for-loops* @@ -141,6 +147,7 @@ well as libraries that use them internally (like ``scipy`` and ``astropy``). Thi requires no special support, but can sometimes be conceptually difficult to achieve. If it is not possible, use one of the following supported methods. + Use Numba --------- @@ -151,7 +158,8 @@ and no compilation step, however as a somewhat "black-box" it does not always improve your code without some help. See the ``numba`` documentation for more info. -Use C/C++ code and wrap it + +Use C/C++ Code and Wrap It -------------------------- Currently, ctapipe does not have any AoT compiled components. diff --git a/docs/index.rst b/docs/index.rst index dd18205f56c..9709e6f7079 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,9 +5,9 @@ .. _ctapipe: -============================================== +############################################## Prototype CTA Pipeline Framework (``ctapipe``) -============================================== +############################################## .. currentmodule:: ctapipe @@ -117,4 +117,4 @@ Prototype CTA Pipeline Framework (``ctapipe``) :color: primary :click-parent: - To API docs + To the API docs diff --git a/docs/user-guide/FAQ.rst b/docs/user-guide/FAQ.rst index aee8141f31b..86f8c2c42fc 100644 --- a/docs/user-guide/FAQ.rst +++ b/docs/user-guide/FAQ.rst @@ -1,8 +1,7 @@ -========================== +************************** Frequently Asked Questions -========================== +************************** ----------------- -Technical Issues ----------------- +Technical Issues +================ diff --git a/docs/user-guide/data_models/dl1.rst b/docs/user-guide/data_models/dl1.rst index f792d495074..0e555449545 100644 --- a/docs/user-guide/data_models/dl1.rst +++ b/docs/user-guide/data_models/dl1.rst @@ -2,9 +2,9 @@ .. currentmodule:: ctapipe.io.containers -================== -CTAPipe Data Model -================== +****************** +ctapipe Data Model +****************** The DL1 files are HDF5 format files, with the following data set hierarchy. The tables should be written with `pytables `_ (not ``h5py``), @@ -17,9 +17,8 @@ generated by ctapipe (e.g. the ``ctapipe-process`` tool which uses the :py:class:`~ctapipe.io.DataWriter` component to generate output data). --------------- DL1 Data Model --------------- +============== This describes data that change per-event. The following datasets will be written to the group ``/dl1/event/`` in the output file: @@ -46,9 +45,9 @@ The following datasets will be written to the group ``/dl1/event/`` in the outp - tables of telescope images (one per telescope) - :py:class:`~ctapipe.containers.TelEventIndexContainer` +, :py:class:`~ctapipe.containers.DL1CameraContainer` --------------- + DL2 Data Model --------------- +============== This describes data that change per-event. The following datasets will be written to the group ``/dl2/event/stereo//`` and or @@ -72,10 +71,11 @@ output file, where ```` is the identifier of the algorithm (e.g. * - /classification - shower classification parameters - :py:class:`~ctapipe.containers.EventIndexContainer`, :py:class:`~ctapipe.containers.ParticleClassificationContainer` - ---------------------- + + Simulation Data Model ---------------------- +===================== + * - ``/simulation/event/subarray/shower`` - true shower parameters from Monte-Carlo simulation - :py:class:`~ctapipe.containers.EventIndexContainer` +, :py:class:`~ctapipe.containers.SimulatedShowerContainer` @@ -89,9 +89,9 @@ Simulation Data Model - simulated shower distribution histograms - :py:class:`~ctapipe.containers.SimulatedShowerDistribution` ------------------------- + Configuration Data Model ------------------------- +======================== The output file should also contain serializations of the instrument, observation (if applicable), simulation (if applicable) configuration information, written to the @@ -125,9 +125,9 @@ applicable), simulation (if applicable) configuration information, written to th - Monte-Carlo simulation run information - :py:class:`~ctapipe.containers.SimulationConfigContainer` ---------------- + Core Provenance ---------------- +=============== The root group of the file shall contain all of the "CTA Core Provenance Metadata" headers as user attributes, with the hierarchy flattened and separated by spaces diff --git a/docs/user-guide/data_models/index.rst b/docs/user-guide/data_models/index.rst index c28bd7475bf..e239c47333b 100644 --- a/docs/user-guide/data_models/index.rst +++ b/docs/user-guide/data_models/index.rst @@ -1,7 +1,8 @@ .. _datamodels: +*********** Data Models -=========== +*********** .. toctree:: diff --git a/docs/user-guide/getting-started.rst b/docs/user-guide/getting-started.rst index ab1bb88a50f..f228d9213b8 100644 --- a/docs/user-guide/getting-started.rst +++ b/docs/user-guide/getting-started.rst @@ -2,8 +2,9 @@ .. _getting_started_users: -Getting Started For Users -========================= +************************* +Getting Started for Users +************************* .. warning:: @@ -12,10 +13,11 @@ Getting Started For Users Installation ------------- +============ -How to get the latest version -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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 `_. @@ -39,8 +41,8 @@ or with pip: $ pip install ctapipe -How to get a specific version -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +How To Get a Specific Version +----------------------------- To install a specific version of ``ctapipe`` you can use the following command: diff --git a/docs/user-guide/index.rst b/docs/user-guide/index.rst index c74bf247684..2d2411f11e6 100644 --- a/docs/user-guide/index.rst +++ b/docs/user-guide/index.rst @@ -1,7 +1,8 @@ .. _user-guide: +********** User Guide -========== +********** .. toctree:: :maxdepth: 2 diff --git a/docs/user-guide/tools.rst b/docs/user-guide/tools.rst index 15280e2a097..13e80ec7c8f 100644 --- a/docs/user-guide/tools.rst +++ b/docs/user-guide/tools.rst @@ -1,7 +1,8 @@ .. _command_line_tools: -Command-Line Tools -================== +****************** +Command-line Tools +****************** You can get a list of all available command-line tools by typing @@ -10,14 +11,15 @@ You can get a list of all available command-line tools by typing ctapipe-info --tools -Data Processing Tools: ----------------------- +Data Processing Tools +===================== * ``ctapipe-process``: input R0, R1, or DL0 data and output DL1/DL2 data in HDF5 format * ``ctapipe-merge``: merge DL1-DL2 data files into a single file * ``ctapipe-reconstruct-muons``: detect and parameterize muons (deprecated, to be merged with process tool) -Other Tools: ------------- + +Other Tools +=========== * ``ctapipe-dump-instrument``: writes instrumental info from any supported event input file, and writes them out as FITS files for external use.