Focal plane visualizer and detector file generator (#345)

* add plot_fp.py * ask duration_yr * CHANGELOG.md: Add entry for plot_fp.py implementation and its functionality * update README * add plot.fp.rst in docs * docs: Improve formatting and clarity in plot_fp.rst * Fix the formatting to make ruff happy --------- Co-authored-by: Yusuke Takase <[email protected]> Co-authored-by: Maurizio Tomasi <[email protected]>
litebird · Nov 20, 2024 · e7b14ea · e7b14ea
1 parent dd4c0bf
commit e7b14ea
Show file tree

Hide file tree

Showing 5 changed files with 416 additions and 0 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,6 +10,10 @@
 
 -   Make the code compatible with Python 3.12 [#332](https://github.com/litebird/litebird_sim/pull/332)
 
+-  plot_fp.py which visualizes focal plane and `DetectorInfo` is implemented. 
+Also it can generate a dector list file by clicking visualized detectors. 
+The function is executable by: `python -m litebird_sim.plot_fp` [#345](https://github.com/litebird/litebird_sim/pull/345)
+
 # Version 0.13.0
 
 -   **Breaking change**: new API for pointing computation [#319](https://github.com/litebird/litebird_sim/pull/319). Here is a in-depth list of all the breaking changes in this PR:

diff --git a/README.md b/README.md
@@ -112,6 +112,20 @@ command:
     make.bat html
     ```
 
+### Focal plane visualizer 
+
+We can visualize detectors in the focal plane by:
+```
+python -m litebird_sim.plot_fp
+```
+This software loads the IMo which is installed in the machine you are using. 
+As the conversation unfolds, an interactive Matplotlib window will appear. 
+Detectors corresponding to the specified channels are represented as blue dots. 
+Clicking on a dot reveals the `DetectorInfo` for that detector in real time, highlighted with a red star. 
+Additionally, if you agree during the conversation to generate a detector file,
+a list of starred detectors will be saved into a text file at the designated location after you closed the plot.
+
+![plot_fp_usage](https://private-user-images.githubusercontent.com/83496454/388083441-93876c66-8b61-40c0-b23f-79a6998e5e33.gif?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MzIxMDQ2MDcsIm5iZiI6MTczMjEwNDMwNywicGF0aCI6Ii84MzQ5NjQ1NC8zODgwODM0NDEtOTM4NzZjNjYtOGI2MS00MGMwLWIyM2YtNzlhNjk5OGU1ZTMzLmdpZj9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNDExMjAlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjQxMTIwVDEyMDUwN1omWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPTZlOTk2M2M3NDgyZjUyY2M4NjFiOGE3ZjliM2RhMWU1YWU2NjFkNmM1ZGQxYzAzM2Y3ZDVmOGI3ZTdhMTAwNjEmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0In0.MoAArSYcXhQgVYaer_O72XHIamO_Ex6B5ITuyVgB8_g)
 
 ## Roadmap
 

diff --git a/docs/source/part2.rst b/docs/source/part2.rst
@@ -7,6 +7,7 @@ Structure of the framework
    simulations.rst
    imo.rst
    detectors.rst
+   plot_fp.rst
    observations.rst
    data_layout.rst
    profiling.rst

diff --git a/docs/source/plot_fp.rst b/docs/source/plot_fp.rst
@@ -0,0 +1,44 @@
+.. _plot_fp:
+
+Focal plane visualization
+===========
+
+We can visualize detectors in the focal plane by:
+
+.. code-block:: text
+
+    python -m litebird_sim.plot_fp
+
+This software loads the IMo, which is installed on the machine you are using.
+As the conversation unfolds, an interactive Matplotlib window will appear.
+
+Detectors corresponding to the specified channels are represented as blue dots.
+Clicking on a dot reveals the `DetectorInfo` for that detector in real time, highlighted with a red star.
+
+Additionally, if you agree during the conversation to generate a detector file,
+a list of starred detectors will be saved into a text file at the designated location after you close the plot.
+
+The format of the detector file is as follows:
+
++------------+---------+---------+------------+------------+-----------------------+
+| Telescope  | Channel | IMO_NET | Number_det | Scaled_NET | Detector_name         |
++------------+---------+---------+------------+------------+-----------------------+
+| LFT        | L1-040  | 114.63  | 2/48       | 13.51      | `000_003_003_UB_040_T`|
++------------+---------+---------+------------+------------+-----------------------+
+| LFT        | L1-040  | 114.63  | 2/48       | 13.51      | `000_003_003_UB_040_B`|
++------------+---------+---------+------------+------------+-----------------------+
+
+The description of each column is as follows:
+
+- `Telescope`: The telescope name.
+- `Channel`: The channel name.
+- `IMO_NET`: The NET of the detector in IMo.
+- `Number_det`: :math:`N_{\text{selected}}/N_{\text{total}}` where :math:`N_{\text{selected}}` is the number of selected detectors by clicking and :math:`N_{\text{total}}` is the total number of detectors in the channel.
+- `Scaled_NET`: The scaled NET of the detectors is given by the following equation:
+
+    .. math::
+
+        \text{Scaled NET} = \text{NET}_{\text{IMO}} \sqrt{\frac{t_{\text{obs}}}{3} \frac{N_{\text{selected}}}{N_{\text{total}}}}
+
+  where :math:`t_{\text{obs}}` is the observation time in years that you can specify in the conversation. The factor of 3 is the nominal observation time in years.
+- `Detector_name`: The detector name.