Using ``csst_common`` ===================== In this chapter, we introduce the basic usages of some IMPORTANT functions / classes in ``csst_common``. Package source code and installation guide can be found in the link below. - https://csst-tb.bao.ac.cn/code/csst-l1/csst_common ``csst_common.data_manager.CsstMsDataManager`` ---------------------------------------------- A class that helps developers to access simulation files. .. code-block:: python from csst_common.data_manager import CsstMsDataManager # for full basic initialization dm_mbi = CsstMsDataManager( ver_sim="C5.2", # version of simulation, "C5.2" is the latest dir_l0="", # the L0/input directory dir_l1="", # the L1/output directory dir_pcref="", # position calibration reference (will be deprecated) path_aux="", # aux file paths (master bias, dark, flat) assert_all_detectors=False, # if True, assert all detectors are available datatype="mbi", # "mbi", "sls" or "all" ) dm_mbi.set_detectors(detectors=None) # use all available detectors .. code-block:: python # for a quick start () dm_mbi = CsstMsDataManager.quickstart( ver_sim="C5.2", datatype="mbi", dir_l1=".", exposure_id=100 # the 100th exposure ) dm_mbi.set_detectors(detectors=None) # use all available detectors .. note:: This ``quickstart`` method is ONLY available on ``dandelion`` and the Purple Mountain Lab node. In your local development environment, you have to use ``CsstMsDataManager(...)`` to initialize it. .. code-block:: python # access L0 directory dm_mbi.dir_l0 # access L1 directory dm_mbi.dir_l1 # access dir_pcref dm_mbi.dir_pcref # access path_aux dm_mbi.path_aux # access ver_sim dm_mbi.ver_sim # access target detectors dm_mbi.target_detectors # access available detectors dm_mbi.available_detectors # define an L1 file (detector-specified) dm_mbi.l1_detector(detector=6) # define an L1 file (non-detector-specified) dm_mbi.l1_file("flipped_image.fits") .. code-block:: python # to get bias dm_mbi.get_bias() # to get dark dm_mbi.get_dark() # to get flat dm_mbi.get_flat() Access code to data products ---------------------------- ``Multi-Band Imaging`` ^^^^^^^^^^^^^^^^^^^^^^ ========================== ===== ========================================================== ================== Data source Level File name / access code Notes ========================== ===== ========================================================== ================== raw 0 ``dm.l0_detector(detector=detector)`` sci image raw 0 ``dm.l0_crs(detector=detector)`` cosmic ray image raw 0 ``dm.l0_cat(detector=detector)`` input catalog raw 0 ``dm.l0_log(detector=detector)`` log file ``csst_ms_mbi_instrument`` -- ``dm.l1_detector(detector=detector, post="img.fits")`` corrected image ``csst_ms_mbi_instrument`` -- ``dm.l1_detector(detector=detector, post="flg.fits")`` flag image ``csst_ms_mbi_instrument`` -- ``dm.l1_detector(detector=detector, post="wht.fits")`` weight image ``csst_ms_mbi_instrument`` -- ``dm.l1_detector(detector=detector, post="img.head")`` L0 fits header ``DFS`` -- ``dm.l1_file(name="gaia_dfs.fits")`` reference catalog ``csst_ms_mbi_distortion`` -- ``dm.l1_detector(detector=detector, post="wcs.head")`` fits head with WCS ``csst_ms_mbi_position`` -- ``dm.l1_detector(detector=detector, post="img.acat")`` photometry catalog ``csst_ms_mbi_position`` -- ``dm.l1_detector(detector=detector, post="img.rcat")`` reference catalog ``csst_ms_mbi_flux`` 1 ``dm.l1_detector(detector=detector, post="img_L1.fits")`` sci image (L1) ``csst_ms_mbi_flux`` 1 ``dm.l1_detector(detector=detector, post="flg_L1.fits")`` flag image (L1) ``csst_ms_mbi_flux`` 1 ``dm.l1_detector(detector=detector, post="wht_L1.fits")`` weight image (L1) ========================== ===== ========================================================== ================== ``Slit-Less Spectra`` ^^^^^^^^^^^^^^^^^^^^^ ========================== ===== ========================================================== ================== Data source Level File name / access code Notes ========================== ===== ========================================================== ================== raw 0 ``dm.l0_detector(detector=detector)`` sci image raw 0 ``dm.l0_crs(detector=detector)`` cosmic ray image raw 0 ``dm.l0_cat(detector=detector)`` input catalog raw 0 ``dm.l0_log(detector=detector)`` log file ``csst_ms_sls_instrument`` 1 ``dm.l1_detector(detector=detector, post="flt.fits")`` corrected image ``csst_ms_sls_position`` -- ``dm.l1_detector(detector=detector, post="L1_1.fits")`` image with wcs ========================== ===== ========================================================== ================== ``csst_common.file_recorder.FileRecorder`` ------------------------------------------ Get an empty ``FileRecorder``. This is initially a ``list``-like object. Use ``FileRecorder.add_record()`` to add file records. .. code-block:: :linenos: >>> from csst_common.file_recorder import FileRecorder >>> fr = FileRecorder() >>> for i in range(3): >>> fr.add_record(filepath="test{:03d}.txt".format(i), >>> db=True, >>> comment="Test file {:d}".format(i)) >>> fr.pprint_all() filepath db comment existence ----------- ---- ----------- --------- test000.txt True Test file 0 False test001.txt True Test file 1 False test002.txt True Test file 2 False ``FileRecorder`` inherits from ``list``. Therefore, if you are collecting records from subprocesses, here is the way to combine records: .. code-block:: python :linenos: >>> from csst_common.file_recorder import FileRecorder >>> fr1 = FileRecorder() >>> fr1.add_record(filepath="test1.txt", db=False, comment="test file 1") >>> fr2 = FileRecorder() >>> fr2.add_record(filepath="test2.txt", db=False, comment="test file 2") >>> fr_all = FileRecorder([*fr1, *fr2]) >>> fr_all.pprint_all() filepath db comment existence --------- ----- ----------- --------- test1.txt False test file 1 False test2.txt False test file 2 False >>> fr_all.extend(fr1) >>> fr_all.pprint_all() filepath db comment existence --------- ----- ----------- --------- test1.txt False test file 1 False test2.txt False test file 2 False test1.txt False test file 1 False ``csst_common.logger.get_logger()`` ----------------------------------- Get the default configured ``logging.Logger``. .. code-block:: python :linenos: from csst_common.logger import get_logger logger = get_logger() .. warning:: Developers should NOT use ``print`` function extensively in code. Generally ``print`` can be replaced with ``logger.debug("msg")``. For important information, use ``logger.info("msg")``. For warnings, use ``logger.warning("msg")``. For errors, use ``logger.error("msg")``. Conf https://docs.python.org/3/library/logging.html for more information about the usage of ``logging.Logger``. ``csst_common.status.CsstStatus`` --------------------------------- Developers should use ``csst_common.status.CsstStatus`` to return the status of their interfaces. .. code-block:: python :linenos: from csst_common.status import CsstStatus # presently 3 kinds of status are available, they are CsstStatus.PERFECT CsstStatus.WARNING CsstStatus.ERROR An example interface -------------------- We recommend our developers to use the code structure used in the example interfaces, e.g., ``process_single_image`` and ``process_multiple_images``. The example code is shown below. Source code ^^^^^^^^^^^ .. literalinclude:: csst_common/example_interface.py :caption: ``example_interface.py`` :emphasize-lines: 7-11,36-41,85,87-88,91-92,95-96,99-101,111-116,148,155-165,167-173,178-179,182-183,186-187,190-191 :linenos: :language: python Rendered ``docstring`` ^^^^^^^^^^^^^^^^^^^^^^ .. automodule:: example_interface :members: ``csst_common.params`` ---------------------- to be updated Module Identifier ----------------- to be updated