Creating a Datapage
===================

While we have seen how to fetch and plot :ref:`lightcurves <Plotting a Light Curve>` and :ref:`images <Plotting an Image>` in previous tutorials, storing and analysing these separately can quickly become a tiresome process. This is where another feature of ATK comes in: :ref:`Datapages <Datapages>`. The :func:`datapage() <AstroToolkit.Datapages.datapage>` tool allows for any bokeh plots (including those generated by ATK) to be neatly stacked together in a customisable grid.

We haven't yet encountered all of the data structures that will be utilised in this tutorial, but it should still be fairly easy to follow since they all function in the same way.

We start by fetching all the data that we want in our datapage. We will start with an image:

.. code-block:: python
    
    from AstroToolkit.Datapages import buttons, datatable, datapage
    from AstroToolkit.Tools import query

    source=587316166180416640
    
    image = query(
        kind="image",
        survey="panstarrs",
        source=source,
        overlays=["gaia", "galex"],
        check_exists="datapage_image",
    ).plot()

We can then fetch a :class:`Hertzsprung-Russell Diagram <AstroToolkit.Data.hrdquery.HrdStruct>` (HRD), a :class:`spectrum <AstroToolkit.Data.spectrumquery.SpectrumStruct>` and a :class:`spectral energy distribution <AstroToolkit.Data.sedquery.SedStruct>` (SED):

.. code-block:: python

    hrd = query(kind="hrd", sources=source, check_exists="datapage_hrd").plot()

    spectrum = query(
        kind="spectrum", survey="sdss", source=source, check_exists="datapage_spectrum"
    ).plot()

    sed = query(kind="sed", source=source, check_exists="datapage_sed").plot(
        spectrum_overlay=spectrum
    )

Here, we have passed the spectrum to our SED's :func:`plot() <AstroToolkit.Data.dataquery.SedStruct.plot>` method - another example of the differing capabilities of each :ref:`data structure <Data Structures>`.

We can now fetch a light curve and use it to generate a power spectrum:

.. code-block:: python

    lightcurves = query(
        kind="lightcurve", survey="ztf", source=source, check_exists="datapage_lightcurve"
    ).plot(colours=["green", "red", "blue"])

    powspec = query(
        kind="lightcurve", survey="ztf", source=source, check_exists="datapage_lightcurve"
    ).plot(kind="powspec")

Note that no additional (and in this case repeated) query is performed here when fetching a power spectrum - the data already exists. Finally, we can fetch some additional panels which are specifically designed for use in datapages. We start with Vizier and SIMBAD :func:`buttons <AstroToolkit.Datapages.buttons>`, which open the source in `Vizier <https://vizier.cds.unistra.fr/>`_/`SIMBAD <https://simbad.u-strasbg.fr/simbad/>`_ in the web browser when clicked:

.. code-block:: python

    buttons = buttons(source=source)

We can also create a :func:`datatable <AstroToolkit.Datapages.datatable>`, which generates and populates a table with survey data:

.. code-block:: python

    metadata = datatable(
        source=source,
        entries=[
            {
                "kind": "atk_defaults",
                "surveys": [
                    "gaia",
                    "galex",
                    "panstarrs",
                    "skymapper",
                    "sdss",
                    "wise",
                    "twomass",
                ],
            }
        ],
    )

Here, we have used the package's default entries for its :ref:`supported data surveys <Data Surveys>` for simplicity, but datatables can also be populated with data from any `Vizier <https://vizier.cds.unistra.fr/>`_ catalogue or with any other external data. See :func:`datatable() <AstroToolkit.Datapages.datatable>` for a full description.

We then use the :func:`datapage() <AstroToolkit.Datapages.datapage>` tool to generate our datapage from the above elements:

.. code-block:: python

    datapage = datapage(
        dimensions={"width": 6, "height": 6},
        panels=[
            {"name": "image", "figure": image, "width": 2, "height": 2},
            {"name": "hrd", "figure": hrd, "width": 2, "height": 2},
            {"name": "sed", "figure": sed, "width": 3, "height": 2},
            {"name": "buttons", "figure": buttons, "width": 2, "height": 2},
            {"name": "lightcurves", "figure": lightcurves, "width": 4, "height": 2},
            {"name": "powspec", "figure": powspec, "width": 3, "height": 2},
            {"name": "spectrum", "figure": spectrum, "width": 5, "height": 2},
            {"name": "metadata_table", "figure": metadata, "width": 7, "height": 2},
        ],
        layout=[
            ["image", "sed", "buttons"],
            ["hrd", "spectrum"],
            ["lightcurves", "powspec"],
            ["metadata_table"],
        ],
    )

We start by specifying the total dimensions of the grid we wish to use (in this case 6x6). We then pass a list of data structures, giving them a label and specifying their individual dimensions within the grid. Here, we have used only elements provided by ATK, but any Bokeh figure may be used. Finally, we specify the layout of our grid row-by-row (columns are also supported, see :func:`datapage <AstroToolkit.Datapages.datapage>` for a full description).

The :func:`datapage() <AstroToolkit.Datapages.datapage>` tool returns a :class:`Datapage <AstroToolkit.Misc.grid.Datapage>`, which acts similarly to the other :ref:`data structures <Data Structures>` that we have seen so far. We can hence show the resulting datapage as we would with any other :ref:`data structure <Data Structures>` (although in this case providing a file name is required!):

.. code-block:: python

    datapage.showplot(f"{source}_datapage")

The resulting datapage is shown below - try out the interactive elements!

.. raw:: html
    
    <div align="center"><embed src="../_static/587316166180416640_datapage.html" width=100% height=1625</embed></div>

|

Note: The code used in this tutorial can be executed using:

.. code-block:: python

    from AstroToolkit.Examples import datapage_creation