Merge branch 'feature_documentation' of...

fig/mbh_mstar.pdf: src/scripts/plots/plot_mbh_mstar.py

	python3 $< $@

fig/mbh_mstar_test_z5-5.5.pdf: src/scripts/plots/plot_mbh_mstar.py

	python3 $< $@ --redshifts 0.0 4.0 5.0 5.1 5.2 5.3 5.4 5.45 --zfmt "%.2f" --vmax=6.0

overleaf/fig/mbh_mstar_20260225.pdf: src/scripts/plots/plot_mbh_mstar.py

	python3 $< $@

fig/mbh_mstar_with_zou2024.pdf: src/scripts/plots/plot_mbh_mstar.py

	python3 $< $@ --plot_zou2024

- Visit         -- Information about LSST visits

- ForcedSource  -- Forced photometry on coadded image detections

- Object        -- Coadded image detections

- Truth         -- The AGILE truth catalog

- Truth         -- The AGILE truth catalog (see below)

The schema of each table follows closely that of DP0.2: (see here

https://dp0-2.lsst.io/data-products-dp0-2/index.html and here

https://dp0-2.lsst.io/data-products-dp0-2/index.html#id3).

The truth catalog follows the schema as presented in the appendix of Viitanen

et al., 2026 as illustrated in the table below.

Catalogs: truth catalog FITS file (14G)

+++++++++++++++++++++++++++++++++++++++

We provide the truth catalog as part of the master.db, as well as a standalone

FITS file in the DR1 repository. The truth catalog follows the schema as

presented in the appendix of Viitanen et al., 2026 as illustrated in the table

below.

.. image:: img/truth-columns.png

`deepCoadded` images in the LSST bands. The `calexp` images are provided for

each CCD, band, and visit separately. The  `deepCoadded` images follow the DC2

skymap tesselation scheme of `tracts` and `patches`.

Known issues

------------

AGN structure function at infinity

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

DR1 contains an error in the input structure function at infinity, i.e.

:math:`\mathrm{SF}_\infty`. This means that  In the DR1 released truth catalog,

:math:`\mathrm{SF}_\infty` is incorrectly divided by :math:`\sqrt{1+z}`, where

:math:`z` is the redshift associated with each source. The error is propagated

to the simulated images and the photometric catalogs.

To recover the correct values both in the truth catalog and in the photometric

catalogs, multiply by :math:`\sqrt{1+z}`:

.. math::

   \mathrm{SF}_{\infty,corrected} = \mathrm{SF}_\infty \times \sqrt{1+z}

        """

        return_tau_sf_inf = kwargs.get("return_tau_sf_inf", False)

        if not return_tau_sf_inf:

            # Short-circuit for non-AGN

            is_agn = self["is_agn"][i]

            if not is_agn:

                return np.load(filename)

        mjd = util.get_mjd_vec()

        kwargs.update(

            {

                "mjd0": 0.0,

                "seed": self._get_seed("get_lightcurve") + i,

            }

        )

        logger.info(f"Estimating AGN lightcurve {i} {band}")

        logger.info(f"Estimating AGN lightcurve {i=} {band=} {kwargs=}")

        lc = lightcurve.get_lightcurve_agn(*args, **kwargs)

        if return_tau_sf_inf:

            tau, sf_inf = lc

            return tau, sf_inf

        logger.info(f"Writing AGN lightcurve {filename}")

        util.create_directory(filename)

        if lc is None:

            return None

        return np.interp(mjd - mjd0, util.get_mjd_vec(), lc)

    def get_tau(self, band="lsst-r"):

        """Return the Damped Random Walk characteristic timescale tau."""

        ret = self.get_lightcurve(0, band, return_tau_sf_inf=True)

        return ret[0]

    def get_sf_inf(self, band="lsst-r", divide_sf_inf_by_z1=False):

        """Return the Damped Random Walk parameter structure function at infinity."""

        ret = self.get_lightcurve(0, band, return_tau_sf_inf=True, divide_sf_inf_by_z1=divide_sf_inf_by_z1)

        return ret[1]

        Binary star catalog.

    sql_query: str

        Input SQL query if a database file is read.

    columns: str

        Input columns if a FITS file is read.

    cache: bool

        Use an existing catalog whenever available. Otherwise, always overwrite

        the one in disk.

        catalog_star=None,

        catalog_binary=None,

        sql_query=None,

        columns=None,

        cache=True,

    ):

        """

        # NOTE: short-circuit for an existing truth catalog

        if cache and os.path.exists(filename := self.get_filename()):

            logger.info(f"Found catalog FITS file {filename}")

            self.catalog_combined = util.read_fits(filename)

            self.catalog_combined = util.read_fits(filename, columns=columns)

            return

        # NOTE: short-circuit for an existing database truth catalog

        use_occupation_fraction: bool

            weight LF by occupation fraction

        Returns

        -------

        x, dx, y, dy:

            Bin centers (x), Bin width (dx), Counts (y), Delta counts (dy). Error

            on the counts is assumed to be Poissonian i.e. sqrt(Ncounts).

        """

        # select in redshift

        z = self["Z"]

            area_deg2=self.get_area(),

            nmin=nmin,

        )

    def write_database(

        self, name_table: str, filename_database: str, debug=False, blocksize=4096, *args, **kwargs

    ):

        """

        Write the combined catalog into a sqlite3 database table.

        Parameters

        ----------

        name_table: str

            name of the database table

        filename_database: str

            filename of the sqlite3 database

        """

        import sqlite3

        from astropy.table import Table

        if os.path.exists(filename_database):

            raise FileExistsError(f"Filename {filename_database} exists. Will not overwrite.")

        with sqlite3.connect(filename_database) as con:

            for fst in range(0, len(self.catalog_combined), blocksize):

                lst = fst + blocksize

                logger.info(f"ingesting {filename_database} {name_table} {fst} {lst} ...")

                df = Table(self.catalog_combined[fst:lst]).to_pandas()

                df = df.reset_index(drop=True)

                df.to_sql(

                    f"{name_table}",

                    con,

                    index=False,

                    if_exists="append",

                    chunksize=1024,

                    method="multi",

                )

        return df

    meanmag=None,

    lambda_rest=None,

    divide_sf_inf_by_z1=False,

    return_tau_sf_inf=False,

):

    """Return an AGN light-curve in flux units."""

    # Initialize the time vector

        meanmag=meanmag,

        divide_sf_inf_by_z1=divide_sf_inf_by_z1,

    )

    if return_tau_sf_inf:

        return tau, sf_inf

    # Convert from magnitudes to fluxes

    yy = util.mag_to_flux(yy)