Add doc for PTW module

.github/workflows/code_check.yml

@@ -26,7 +26,7 @@ jobs:
       - name: Set up python
         uses: actions/setup-python@v4
         with:
-          python-version: 3.10
+          python-version: "3.10"
       #----------------------------------------------
       #  -----  install & configure poetry  -----
       #----------------------------------------------

.github/workflows/deploy_doc.yml

@@ -30,7 +30,7 @@ jobs:
       - name: Set up python
         uses: actions/setup-python@v4
         with:
-          python-version: 3.10
+          python-version: "3.10"
       - name: Install Poetry
         uses: snok/install-poetry@v1
         with:

.github/workflows/documentation.yml

@@ -25,7 +25,7 @@ jobs:
       - name: Set up python
         uses: actions/setup-python@v4
         with:
-          python-version: 3.10
+          python-version: "3.10"
       #----------------------------------------------
       #  -----  install & configure poetry  -----
       #----------------------------------------------

docs/authors.rst

@@ -17,8 +17,19 @@ Alphabetical list of past and present authors:
 Citation
 ########
 
-Authors of papers including reference to or results obtained with Georges are encouraged to cite as follow:
+Authors of papers including reference to or results obtained with Georges are encouraged to cite as follow::
 
+   @Misc{Georges,
+   author       = {C. Hernalsteens and R. Tesse and E. Gnacadja and N. Pauly and E. Ramoisiaux and M. Vanwelde},
+   howpublished = {\url{https://ulb-metronu.github.io/georges/}},
+   title        = {Georges},
+   year         = {2023},
+   url          = {https://ulb-metronu.github.io/georges/}
+   }
+
+.. note::
+
+   A paper is currently in preparation for Software-X.
 
 List of publications
 ####################

docs/changelog.rst

@@ -7,6 +7,7 @@ Changelog
 
 * 2023-1
 
+    * Add documentation of the PTW module
     * Add documentation for the optimisation of a beamline
     * Minor fix in observers
     * Add a plotting method for the SymmetryObserver

docs/contributing.rst

@@ -46,9 +46,9 @@ The documentation files are located in the docs repository and can be generated
 go to the docs repository and use the `make` command::
 
     cd docs
-    make html / latexpdf
+    make html
 
-The results are in the folder `build/html` (`build/latex`).
+The results are in the folder `build/html`.
 
 Pre-commit file
 ###############

docs/installation.rst

@@ -2,8 +2,8 @@
 Installation
 ************
 
-You can install :code:`georges` from PyPI with pip::
-
+..
+ You can install :code:`georges` from PyPI with pip::
     pip install georges
 
 For development purposes you can copy the source code on your computer. georges is hosted on Github and can be downloaded using the following::
@@ -163,10 +163,16 @@ Run Docker
 
 You can run a container with::
 
-    docker run -it --rm --name georges -p 8899:8899 georges
+    docker run -it --rm --name georges -p 8899:8899 ${IMAGE_ID}
 
 then connect to http://127.0.0.1:8899 to access the Jupyter Lab interface
 and type::
 
     import georges
 
+.. note ::
+
+    You can tag the image using the following command::
+
+        docker image tag ${IMAGE_ID} georges
+        docker run -it --rm --name georges -p 8899:8899 georges

docs/modules/manzoni/manzoni_example.rst

@@ -1,7 +1,7 @@
 Basic example
 #############
 
-In this example, we define beamline with `Quadrupoles`, `SBEND` and `Collimators`. We use different observers to analyse the beam and its properties.
+In this example, we define beamline with `Quadrupoles`, `SBEND` and `Collimators` and we use different observers to analyse the beam and its properties.
 
 Let's first import the necessary packages
 

docs/modules/ptw.rst

@@ -4,7 +4,19 @@
 PTW
 ***
 
-Describe PTW
+The PTW module includes several classes that allow for direct assessment of various clinical parameters in charged particle therapy. These parameters include distal fall-off, range, transverse and in-depth flatness, and lateral penumbra. The following classes are implemented:
+
+* **BraggPeakAnalysis**: This class processes a normalized 1D depth dose profile, or a pristine Bragg peak, to extract key information such as the maximum dose position, the distal range at a given percentage of the maximum, and the distal fall-off (DFO). The user must provide both the dose data and the corresponding positions in depth.
+
+* **SpreadOutBraggPeakAnalysis**: This class takes a set of Bragg peaks, or a Bragg peak library, as input and computes the relative weights required to obtain a uniform depth dose profile, known as the SOBP. Additionally, this class processes the resulting SOBP and provides the flatness, DFO, and distal range at a given percentage of the maximum to the user.
+
+* **LateralProfileAnalysis**: This class takes a normalized 1D transverse dose profile as input and computes various parameters such as the field size, the uniform region (defined as 80% of the field size), the transverse flatness of the uniform region, and the lateral penumbra at the left and right of this region. The user must provide both the dose data and the corresponding transverse positions.
+
+The module also includes two classes that help optimize spot spacing in pencil beam scanning treatment:
+
+* **RegularSpotScanning**: This class provides a method to calculate the required spot spacing for a regular grid irradiation scheme in order to obtain a two-dimensional uniform dose deposition profile for a given spot width (1 sigma) and a targeted circular field. The user inputs the half value of the field size, the desired number of spots along each axis of the field, and the standard deviation (1 sigma) of the beam. The required spot spacing to achieve a 2D dose uniformity of at least 98% is directly outputted.
+
+* **ContourSpotScanning**: This class works similarly to RegularSpotScanning but uses a circular, contour-based irradiation scheme with a central spot placed at the center of the field. The user can choose whether to impose the irradiation radius. The output of the calculation includes the relative weight of the contour spots compared to the central spot and the angle spacing between these spots.
 
 Example
 #######

georges/fermi/propagation.py

@@ -32,10 +32,10 @@ def propagate(sequence: Sequence, energy: _ureg.Quantity, beam: Optional[Mapping
     """
 
     Args:
-        sequence:
-        energy:
-        beam:
-        model:
+        sequence: Sequence to track in
+        energy: Beam energy
+        beam: A_i beam parameters
+        model: Model to use. Default is DifferentialMoliere
 
     Returns:
 

georges/ptw/ptw.py

@@ -50,6 +50,12 @@ def __init__(self, m: str = "") -> None:  # pragma: no cover
 
 
 class BraggPeakAnalysis:
+    """
+    This class processes a normalized 1D depth dose profile, or a pristine Bragg peak, to extract key information such
+    as the maximum dose position, the distal range at a given percentage of the maximum, and the distal fall-off (DFO).
+    The user must provide both the dose data and the corresponding positions in depth.
+    """
+
     def __init__(self, bp: pd.DataFrame, method: str, low_dose=1, high_dose=70):
         self.data = bp
         self.low_bound = low_dose
@@ -202,6 +208,12 @@ def compute_dfo_80_20(self) -> float:
 
 
 class SpreadOutBraggPeakAnalysis:
+    """
+    This class takes a set of Bragg peaks, or a Bragg peak library, as input and computes the relative weights required
+    to obtain a uniform depth dose profile, known as the SOBP. Additionally, this class processes the resulting SOBP
+    and provides the flatness, DFO, and distal range at a given percentage of the maximum to the user.
+    """
+
     def __init__(
         self,
         dose_data: Optional[pd.DataFrame] = None,
@@ -463,6 +475,13 @@ def get_ur_max_dose(self):
 
 
 class LateralProfileAnalysis:
+    """
+    This class takes a normalized 1D transverse dose profile as input and computes various parameters such as the field
+    size, the uniform region (defined as 80% of the field size), the transverse flatness of the uniform region, and the
+    lateral penumbra at the left and right of this region. The user must provide both the dose data and the
+    corresponding transverse positions.
+    """
+
     def __init__(self, dose_profile: _np.array, positions: _np.array):
         self.dose_profile = dose_profile
         self.positions = positions
@@ -649,6 +668,14 @@ class GammaAnalysis:
 
 
 class RegularSpotScanning:
+    """
+    This class provides a method to calculate the required spot spacing for a regular grid irradiation scheme in order
+    to obtain a two-dimensional uniform dose deposition profile for a given spot width (1 sigma) and a targeted
+    circular field. The user inputs the half value of the field size, the desired number of spots along each axis of
+    the field, and the standard deviation (1 sigma) of the beam. The required spot spacing to achieve a 2D dose
+    uniformity of at least 98% is directly outputted.
+    """
+
     def __init__(self, sigma, fieldsize, n_spots_per_axis):
         self.sigma = sigma
         self.fieldsize = fieldsize
@@ -718,6 +745,13 @@ def compute_2d_profile_flatness(x):
 
 
 class ContourSpotScanning:
+    """
+    This class works similarly to RegularSpotScanning but uses a circular, contour-based irradiation scheme with a
+    central spot placed at the center of the field. The user can choose whether to impose the irradiation radius. The
+    output of the calculation includes the relative weight of the contour spots compared to the central spot and the
+    angle spacing between these spots.
+    """
+
     def __init__(self, sigma, fieldsize, desired_angle, shoot_on_aperture: bool = True, angle_imposed: bool = False):
         self.sigma = sigma
         self.fieldsize = fieldsize