c8_changes.rst

C8主巡天流水线接口
=========================

Change list
    - 仓库名修改：
        - ``csst_ms*`` 修改为 ``csst_msc_*``, 注意修改文件夹路径和 ``setup.py`` 中的名称
    - 接口文件修改：
        ``top_level_interface.py`` 文件改名为 ``api.py`` , 这个文件中用于导入每个 python package 与流水线的接口函数
    - 接口名称修改：
        每个开发模块需要把接口函数命名为 ``base_`` 开头的函数，例如 ``base_phot``
    - ``DataManager`` ``FileRecorder`` 不再使用, 底层接口都尽可能使用文件路径作为参数
    - 使用 ``csst_common.status.CsstResult`` 作为返回类型, 包含三个部分：
        - 运行状态 ``status`` 必须是 ``CsstStatus`` 的三种类型之一
        - 输出文件列表 ``file_list``, 是一个 ``list``, 需要包含所有输出文件，包括临时文件
        - 额外输出 （一般不需要，除非有其他额外输出）
    - 程序中禁止使用当前文件夹 ``.`` 或 ``./``，所有路径应使用绝对路径
    - 尽可能避免创建临时文件夹等操作

    - 单元测试
        - 覆盖率合格线可以设置稍低
        - 由于代码接口定义更新，原则上单元测试应该会更加容易，
        - 单元测试服务器： csstunittest@10.3.10.10 外网 -p 2000 159.226.170.52
        - 单元测试需要一个大表来统计所有模块的每个案例(文件、类、函数名)和其简单解释(~10个字)
        - Jenkins上需要有一个随时更新的单元测试统计结果 包括覆盖率，测试案例列表等

    - 接口定义修改：
        ``csst_msc_mbi_distortion`` 样例代码如下

        .. code-block:: python

            import os

            import numpy as np
            import numpy.typing as npt
            from astropy import table
            from astropy.io import fits
            from csst_common.status import CsstStatus, CsstResult


            def read_data(file_path: str = "/path/to/data") -> np.ndarray:
                return fits.getdata(file_path)


            def _do_step_one(data: npt.NDArray) -> npt.NDArray:
                reduced_data = np.fliplr(data)
                return reduced_data


            def _do_step_two(data: npt.NDArray) -> npt.NDArray:
                reduced_data = np.flipud(data)
                return reduced_data


            def _do_step_three(data: npt.NDArray, rc: str = "/path/to/catalog") -> npt.NDArray:
                trc = table.Table.read(rc)
                return data + np.mean(trc["ra"]) + np.mean(trc["dec"])


            def base_msc_l1_mbi_image_distortion(
                input_file: str,
                output_file: str,
                rc: str = "/path/to/gaia_dr3.fits",
                **kwargs
            ) -> CsstResult:
                """your docstring here"""
                # read data
                data = read_data(input_file)
                # do your algorithm
                data = _do_step_one(data)
                data = _do_step_two(data)
                data = _do_step_three(data, rc=rc)
                # write results
                hl = fits.HDUList(fits.PrimaryHDU(data=data))
                hl.writeto(output_file, overwrite=True)
                assert os.path.exists(output_file)
                # construct CsstResult
                result = CsstResult(
                    status=CsstStatus.PERFECT,
                    file_list=[
                        output_file,
                        "/path/to/result1.fits",
                        "/path/to/result2.fits",
                    ],
                )
                return result



导入模块
---------

.. code-block:: python

    # import modules
    import numpy as np
    import matplotlib.pyplot as plt
    from astropy.io import fits
    from astropy import table

    # import modules
    from scipy import signal
    from astropy import units as u
    from astropy import constants as const

    # import classes / functions
    from astropy.coordinates import SkyCoord
    from scipy.interpolate import least_squares

    # DO NOT use 'import *'


.. 主巡天模块-接口列表
.. ----------------------

.. .. code-block:: python

..     # csst-l1/mbi/csst_msc_mbi_instrument
..     def base_instcorr(input_file, img_file, wht_file, flg_file) -> CsstResult
..     # csst-l1/mbi/csst_msc_mbi_distortion
..     def base_distortion(input_file, img_file, wht_file, flg_file): -> CsstResult
..     # csst-l1/mbi/csst_msc_mbi_position
..     def base_position_single(input_file, img_file, wht_file, flg_file): -> CsstResult
..     def base_position_multiple(input_file, img_file, wht_file, flg_file): -> CsstResult
..     # csst-l1/mbi/csst_msc_mbi_flux
..     def base_flux(input_file, img_file, wht_file, flg_file): -> CsstResult
..     # csst-l1/mbi/csst_msc_mbi_photometry
..     def base_phot(input_file, img_file, wht_file, flg_file): -> CsstResult
..     # csst-l1/sls/csst_msc_sls_instrument
..     def base_instcorr(input_file, output_file): -> CsstResult
..     # csst-l1/sls/csst_msc_sls_position
..     def base_position(input_file, output_file): -> CsstResult
..     # csst-l1/sls/csst_msc_sls_mosaic
..     def base_mosaic(input_files, output_file): -> CsstResult
..     # csst-l1/sls/csst_msc_sls_directimage
..     def base_dimg(input_file, output_file): -> CsstResult
..     # csst-l1/sls/csst_msc_sls_sky
..     def base_skybkg(input_file, output_file): -> CsstResult
..     # csst-l1/sls/csst_msc_sls_objextraction
..     def base_objext(input_file, output_file): -> CsstResult
..     # csst-l1/sls/csst_msc_sls_axe
..     def base_axe(input_file, output_file, dir_slsconf): -> CsstResult
..     # csst-l1/sls/csst_msc_sls_cde
..     def base_cde(input_file, output_file, dir_slsconf): -> CsstResult
..     # csst-l1/qc/csst_msc_qc0
..     def base_qc0(input_file, output_file): -> CsstResult
..     # csst-l1/qc/csst_msc_sls_qc1
..     def base_qc1(input_file, output_file): -> CsstResult