Merge pull request #420 from kochebina/patch-2

Update user_guide_2_4_actors.md

docs/source/user_guide_2_4_actors.md

@@ -279,24 +279,55 @@ policy="keepAll"
 
 minSecDiff=1 #NOT YET IMPLEMENTED
 # apply coincidences sorter
-coincidences = coincidences_sorter(singles_tree, time_window, minSecDiff, policy, chunk_size=1000000)
+coincidences = coincidences_sorter(singles_tree, time_window, policy, minDistanceXY, maxDistanceZ, chunk_size=1000000)
 ```
-As parameters Coincidence Sorter expects as input:
+As parameters, Coincidence Sorter expects as input:
 
 * **Singles Tree**
 * Defined coincidence **time window**
-* **Minimum sector difference**  or minimal distance  between the detectors triggered the coincidence needed for removing geometrically impossible coincidences (Not yet implemented),
+* **minDistanceXY** (equivalent to Minimum sector difference in Gate 9.X) minimal distance in transaxial plane between the detectors triggered the coincidence needed for removing geometrically impossible coincidences,
+* **maxDistanceZ** maximal distance in axial plane between the detectors triggered the coincidence needed for data reduction for systems with a long axial size (ex.,total body systems)
 * **Policy** to process the multiple coincidences. When more than two singles are found in coincidence, several types of behavior could be implemented.
 * **Chunk size** important for very large root files to avoid loading everything in memory.
 
-GATE allows to model so far 2 different **policy** rules that can be used in such a case:
-| Policy         |      Description                             |Equivalent in Gate 9.X|
-|----------------|----------------------------------------------|----------------------|
-| keepAll        | Each good pairs are considered               |  takeAllGoods        |
-| removeMultiples| No multiple coincidences are accepted, no matter how many good pairs are present |  killAll |
+#### Policies
 
+When more than two singles are found in coincidence, several type of behavior could be implemented. GATE allows to model 5 different policies to treat multiple coincidences that can be used. Mutliple coincidences or "multicoincidence" are composed of at least three singles detected in the same **time window** that could form coincidence. The list of policies along with their explanation are given in Table below. The 5 policies, same as in [Gate9.X](https://opengate.readthedocs.io/en/latest/digitizer_and_detector_modeling.html#id43), were selected for the implementation as the most used. If an option that you need is missing, please, don't hesitate to report it in [Issues](https://github.com/OpenGATE/opengate/issues).
 
-A more detailed example can be found in [test 72](https://github.com/OpenGATE/opengate/blob/master/opengate/tests/src/test072_coinc_sorter_2keepAll.py).
+
+**Available multiple policies and associated meaning**. When a multiple coincidence involving n *singles* is processed, it is first decomposed into a list of n·(n−1) pairs which are analyzed individually.
+The naming convention:
+* "Good" means that a pair of singles are in coincidence and passes all filters **minDistanceXY** and **maxDistanceZ**
+* "take" means that 1 or more pairs of coincidences will be stored
+* "keep" means that a unique coincidence, composed of at least three singles will be kept in the data flow and is called "multicoincidence". *TO DO: In the latter case, the multicoincidence will not be written to the disk, but may participate to a possible deadtime or bandwidth occupancy. The user may clear the multicoincidence at any desired step of the acquisition, by using the multipleKiller pulse processor (described in #Multiple coincidence removal).*
+* "remove" prefix means that all events will be discarded and will not produce any coincidence
+
+| Policy name             | Description                                                                                            |
+|-------------------------|--------------------------------------------------------------------------------------------------------|
+| takeAllGoods            | Each good pairs are considered                                                                         |
+| takeWinnerOfGoods       | Only the good pair with the highest energy is considered                                               |
+| takeWinnerIfIsGood      | If the pair with the highest energy is good, take it, otherwise, kill the event                        |
+| keepIfOnlyOneGood       | If exactly one pair is good, keep the multicoincidence                                                 |
+| removeMultiples         | No multiple coincidences are accepted, no matter how many good pairs are present (*killAll in Gate9.X) |
+
+The following figure illustrates an example of different policies application. The stars represent the detected singles. The size of the star, as well as the number next to it, indicate the energy level of the single (ie. single no 1 has more energy than single no 2, which has itself more energy than the single no 3). The lines represent the possible **good** coincidences.
+
+![](figures/MultipleCases.jpg)
+
+In the table:
+* a **minus(-)** sign indicates that the event is killed (ie. no coincidence is formed)
+* **⋆** sign indicates that all the singles are kept into a unique multicoincidence *TODO:, which will not be written to disk, but which might participate to data loss via dead time or bandwidth occupancy*.
+* In the other cases, the list of pairs which are written to the disk is indicated
+
+| Policy name             | Case 1 | Case 2              | Case 3       | Case 4       |
+|-------------------------|--------|---------------------|--------------|--------------|
+| takeAllGoods            | (1,2)  | (1,2); (1,3); (2,3) | (1,2); (2,3) | (1,3); (2,3) |
+| takeWinnerOfGoods       | (1,2)  | (1,2)               | (1,2)        | (1,3)        |
+| takeWinnerIfIsGood      | (1,2)  | (1,2)               | (1,2)        | \-           |
+| keepIfOnlyOneGood       | \*     | \-                  | \-           | \-           |
+| removeMultiples         | \-     | \-                  | \-           | \-           |
+
+A more detailed example can be found in [test 072](https://github.com/OpenGATE/opengate/blob/master/opengate/tests/src/).
 
 ### MotionVolumeActor