add an example notebook

            "-d", # Flag for cached environment and doctrees

            "./docs/_build/doctrees", # Directory

            "-D", # Flag to override settings in conf.py

            "exclude_patterns=notebooks/*,_build", # Exclude notebooks and build dir from pre-commit

            #"exclude_patterns=notebooks/*,_build", # Exclude notebooks and build dir from pre-commit

            "exclude_patterns=_build", # Exclude notebooks and build dir from pre-commit

          ]

    # Run unit tests, verify that they pass. Note that coverage is run against

    # the ./src directory here because that is what will be committed. In the

Dev Guide - Getting Started

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

Before installing any dependencies or writing code, it's a great idea to create a

virtual environment. LINCC-Frameworks engineers primarily use `conda` to manage virtual

environments. If you have conda installed locally, you can run the following to

create and activate a new environment.

Before installing any dependencies or writing code, it's a great idea to create

a virtual environment. LINCC-Frameworks engineers primarily use `conda` to

manage virtual environments. If you have conda installed locally, you can run

the following to create and activate a new environment.

.. code-block:: console

   >> conda create env -n <env_name> python=3.11

   >> conda create env -n <env_name> python=3.12

   >> conda activate <env_name>

========================================================================================

.. toctree::

    Introducing Jupyter Notebooks <notebooks/intro_notebook>

    Example truth catalog generation <notebooks/create_truth_catalog>

%% Cell type:markdown id:70b92b7a-6039-4468-bf49-87dc87c2d965 tags:

# Create an example AGILE truth catalog

This notebooks demonstrates the basic usage of the truth catalog library, and generates an extermely small truth catalog for testing purposes.

%% Cell type:markdown id:3cbfa609-8950-474a-97f0-9fcefb71c103 tags:

# Initialize

%% Cell type:code id:9759604f-8be1-4a5d-b63a-88da53fab067 tags:

``` python

import os

if not os.path.exists("src/lsst_inaf_agile"):

    os.chdir("../../")

    os.getcwd()

```

%% Cell type:code id:a01c8b5b-8e8e-409d-94c2-185806a70646 tags:

``` python

import logging

import numpy as np

from lsst_inaf_agile.catalog_agn import CatalogAGN

from lsst_inaf_agile.catalog_combined import CatalogCombined

from lsst_inaf_agile.catalog_galaxy import CatalogGalaxy

from lsst_inaf_agile.catalog_star import CatalogStar

from lsst_inaf_agile.egg import Egg

from lsst_inaf_agile.image_simulator import ImageSimulator

from lsst_inaf_agile.merloni2014 import Merloni2014

```

%% Cell type:code id:67317893-e15d-43c6-9f8f-94e37b27e3af tags:

``` python

# Setup the dirname

dirname = "data/tests/test_notebook"

```

%% Cell type:markdown id:897ccf7a-3bdc-4ae6-943d-20a7eb2b6c9e tags:

# Create the galaxy catalog

%% Cell type:code id:37224123-c322-4cc8-beab-fe8d56d3455b tags:

``` python

# Create the egg catalog

# The following list of keyword arguments may be expanded on.

# Look into 'egg-gencat help'for all the available EGG arguments.

egg_kwargs = Egg.get_example_egg_kwargs(dirname + "/egg.fits")

egg_kwargs

```

%% Cell type:code id:e004eed5-a555-4307-80c2-ebe8460d4ae0 tags:

``` python

egg = Egg(egg_kwargs)

egg.run()

```

%% Cell type:code id:62685aff-dd9b-4054-92b6-5bf4f3e6cb6c tags:

``` python

catalog_egg = Egg.read(egg_kwargs["out"])

```

%% Cell type:code id:cb439284-3a83-45d6-8727-ee749892eb03 tags:

``` python

# Create the galaxy catalog

catalog_galaxy = CatalogGalaxy(dirname, catalog_egg)

```

%% Cell type:markdown id:f0634979-f64c-40af-ac05-b8ab7095e39d tags:

# Create the AGN catalog

%% Cell type:code id:4f39b065-f97b-4aa7-9f59-8ed05794b724 tags:

``` python

# Create the AGN catalog

kwargs_catalog_agn = dict(

    dirname=dirname,

    catalog_galaxy=catalog_galaxy,

    type_plambda="zou+2024",

    save_sed=1,

    seed=20251005,

    merloni2014=Merloni2014(1, 0, 0.05, 0.95),

)

catalog_agn = CatalogAGN(**kwargs_catalog_agn)

```

%% Cell type:code id:b7a84c27-01ac-4d8b-a2c9-0db599980547 tags:

``` python

# Create the star catalogs

catalog_star = CatalogStar(dirname, catalog_galaxy, is_binary=False)

catalog_binary = CatalogStar(dirname, catalog_galaxy, is_binary=True)

```

%% Cell type:code id:8901a2f1-86a1-4d43-a32e-6158f8f017a8 tags:

``` python

# Get the combined truth catalog

catalog_combined = CatalogCombined(dirname, catalog_galaxy, catalog_agn, catalog_star, catalog_binary)

```

%% Cell type:code id:73045582-05f0-4fb3-8202-e77862cfed06 tags:

``` python

# Example plot: (host) galaxy stellar mass versus redshift

plt.figure(dpi=200)

plt.plot(catalog_combined["Z"], catalog_combined["M"], ".")

plt.xlabel(r"$z$")

plt.ylabel(r"$\log (M\,/\,M_\mathrm{star})$");

```

%% Cell type:code id:eb4c0774-7cc7-45e2-b84d-8a21826add84 tags:

``` python

# Example plot: distribution of the observed g-band flux.

plt.figure(dpi=200)

plt.hist(catalog_combined["lsst-g_total"], bins=np.logspace(-3, 3, 61))

plt.loglog()

plt.xlabel(r"lsst-g_total [uJy]")

plt.ylabel("frequency");

```

%% Cell type:code id:e05a1872-b6b2-4f8f-a45b-4999a7a5b5db tags:

``` python

```

%% Cell type:markdown id:textblock1 tags:

# Introducing Jupyter Notebooks in Sphinx

This notebook showcases very basic functionality of rendering your jupyter notebooks as tutorials inside your sphinx documentation.

As part of the LINCC Frameworks python project template, your notebooks will be executed AND rendered at document build time.

You can read more about Sphinx, ReadTheDocs, and building notebooks in [LINCC's documentation](https://lincc-ppt.readthedocs.io/en/latest/practices/sphinx.html)

%% Cell type:code id:codeblock1 tags:

``` python

def sierpinsky(order):

    """Define a method that will create a Sierpinsky triangle of given order,

    and will print it out."""

    triangles = ["*"]

    for i in range(order):

        spaces = " " * (2**i)

        triangles = [spaces + triangle + spaces for triangle in triangles] + [

            triangle + " " + triangle for triangle in triangles

        ]

    print(f"Printing order {order} triangle")

    print("\n".join(triangles))

```

%% Cell type:markdown id:textblock2 tags:

Then, call our method a few times. This will happen on the fly during notebook rendering.

%% Cell type:code id:codeblock2 tags:

``` python

for order in range(3):

    sierpinsky(order)

```

%% Cell type:code id:codeblock3 tags:

``` python

sierpinsky(4)

```