Merge pull request #27 from synthesizer-project/qdev

Docs improvements

Author: tHarvey303

README.md

@@ -7,23 +7,21 @@
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![Contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/synthesizer-project/synference/blob/main/docs/CONTRIBUTING.md)
 [![License: GPLv3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
-
-<!--[![Documentation Status](https://github.com/synthesizer-project/synference/actions/workflows/static.yml/badge.svg)](https://synthesizer-project.github.io/synference/)-->
+[![Documentation Status](https://github.com/synthesizer-project/synference/actions/workflows/docs.yml/badge.svg)](https://synthesizer-project.github.io/synference/)
 
 ### Overview
 
-Synference is a Python package designed to fit to perform simulation-based inference (SBI, also known as likelihood free inference) SED fitting. It integrates with [Synthesizer](https://synthesizer-project.github.io) for flexible and fast generation of mock spectra and photometry,
-and uses the [LtU-ILI](https://ltu-ili.readthedocs.io/) package for fast, amortised posterior inference.
+Synference is a Python package designed to fit to perform simulation-based inference (SBI, also known as likelihood free inference) SED fitting. It integrates with [Synthesizer](https://synthesizer-project.github.io) for flexible and fast generation of mock spectra and photometry, and uses the [LtU-ILI](https://ltu-ili.readthedocs.io/) package for fast, amortised posterior inference.
 
 ### Key Features
 
 - **Flexible Mock Generation**: Generate mock spectra and photometry using Synthesizer, allowing for full flexibility in almost every aspect of SED generation, including a wide range of post-processed stellar population synthesis grids.
-- **Flexible Training**: Mock photometry creation is seperated from the training of the inference model, allowing for flexible training strategies and the use of different inference models, as well as quickly switching between different feature sets - e.g. different filtersets, different noise models, etc.
+- **Flexible Training**: Mock photometry creation is separated from the training of the inference model, allowing for flexible training strategies and the use of different inference models, as well as quickly switching between different feature sets - e.g. different filtersets, different noise models, etc.
 - **Fast Inference**: Leverage LtU-ILI for fast, amortised posterior inference, enabling efficient fitting of complex models to data.
 
 ### Requirements
 
-synference requires Python 3.10 or higher. It has the following dependencies:
+Synference requires Python 3.10 or higher. It has the following dependencies:
 
 - [synthesizer](https://synthesizer-project.github.io) for mock generation
 - [ltu-ili](https://ltu-ili.readthedocs.io/) for inference
@@ -39,11 +37,11 @@ synference requires Python 3.10 or higher. It has the following dependencies:
 - [tqdm](https://tqdm.github.io/) for progress bars
 - [jax](https://jax.readthedocs.io/) for GPU acceleration (optional, for some inference models)
 
-These dependencies will be automatically installed when you install synference using pip.
+These dependencies will be automatically installed when you install Synference using pip.
 
 ### Installation
 
-The easiest way to currently install synference is to clone the repository and install it in editable mode:
+The easiest way to currently install Synference is to clone the repository and install it in editable mode:
 
 ```bash
 git clone https://www.github.com/synthesizer-project/synference.git
@@ -53,7 +51,7 @@ pip install -e .
 
 ### Getting Started
 
-To get started with synference, you can check out the [examples](examples/) directory for usage examples and tutorials. The examples cover various aspects of using synference, including:
+To get started with Synference, you can check out the [examples](examples/) directory for usage examples and tutorials. The examples cover various aspects of using Synference, including:
 
 - Generating mock spectra and photometry with Synthesizer
 - Training inference models with LtU-ILI
@@ -64,7 +62,7 @@ To get started with synference, you can check out the [examples](examples/) dire
 
 The most basic usage, for creating a simple mock catalogue and training a model on it looks like this:
 
-Firstly we setup the Synthesizer based model. More details on how to set up the Synthesizer model can be found in the [Synthesizer documentation](https://synthesizer-project.github.io/). Here we use a BPASS SPS grid, a lognormal star formation history, a single stellar metallicity and a simple emission model including Cloudy nebular emission but no dust reprocessing. The photometric filters used are common JWST/NIRCam wideband filters, but any filters supported by [SVO](https://svo2.cab.inta-csic.es/theory/fps/index.php) or loaded manually can be used. The model parameters are drawn from a Latin hypercube sampling of the parameter space, but this can be done in any way indepedent of synference. All we are providing to the grid generation is a set of *10,000* galaxies with a range of stellar masses, redshifts, metallicities, and star formation histories, and these can be created in any way you like.
+Firstly we setup the Synthesizer based model. More details on how to set up the Synthesizer model can be found in the [Synthesizer documentation](https://synthesizer-project.github.io/). Here we use a BPASS SPS grid, a lognormal star formation history, a single stellar metallicity and a simple emission model including Cloudy nebular emission but no dust reprocessing. The photometric filters used are common JWST/NIRCam wideband filters, but any filters supported by [SVO](https://svo2.cab.inta-csic.es/theory/fps/index.php) or loaded manually can be used. The model parameters are drawn from a Latin hypercube sampling of the parameter space, but this can be done in any way independent of Synference. All we are providing to the grid generation is a set of *10,000* galaxies with a range of stellar masses, redshifts, metallicities, and star formation histories, and these can be created in any way you like.
 
 ```python
 from synthesizer.grid import Grid
@@ -156,17 +154,15 @@ empirical_model_fitter.recover_SED(observed_data_vector)
 
 ```
 
-This is just a basic example to get you started. synference is highly flexible and can be adapted to a wide range of use cases in simulation-based inference for SED fitting.
+This is just a basic example to get you started. Synference is highly flexible and can be adapted to a wide range of use cases in simulation-based inference for SED fitting.
 
 ### Documentation
 
-Work in progress.
+Documentation for Synference is available at [synthesizer-project.github.io/synference](https://synthesizer-project.github.io/synference/). The documentation includes installation instructions, tutorials, API references, and examples to help you get started with using Synference for your own projects.
 
 ### Contributing
 
-We welcome contributions to synference! If you have suggestions, bug reports, or would like to contribute code, please open an issue or submit a pull request on GitHub. Please see our [Code of Conduct](CODE_OF_CONDUCT.md) for more details on how to contribute and interact with the community.
+We welcome contributions to Synference! If you have suggestions, bug reports, or would like to contribute code, please open an issue or submit a pull request on GitHub. Please see our [Code of Conduct](CODE_OF_CONDUCT.md) for more details on how to contribute and interact with the community.
 
 ### License
-This project is licensed under the GNU General Public License v3.0 (GPLv3). See the [LICENSE](LICENSE) file for details. This means you can use, modify, and distribute the code freely, but any derivative works must also be open source and distributed under the same license. We warn users that this software is offered "as is", without any warranty or guarantee of fitness for a particular purpose. synference is under active development, and therefore may change in the future.
-
-
+This project is licensed under the GNU General Public License v3.0 (GPLv3). See the [LICENSE](LICENSE) file for details. This means you can use, modify, and distribute the code freely, but any derivative works must also be open source and distributed under the same license. We warn users that this software is offered "as is", without any warranty or guarantee of fitness for a particular purpose. Synference is under active development, and therefore may change in the future.

docs/CONTRIBUTING.md

@@ -94,7 +94,7 @@ This will build a local copy of the documentation representative of the currentl
 
 ## Contributing to the Documentation
 
-The synference documentation is written in a combination of reStructuredText, Jupyter notebooks and Python scripts.
+The Synference documentation is written in a combination of reStructuredText, Jupyter notebooks and Python scripts.
 Adding content should be relatively simple if you follow the instructions below.
 
 ### Adding notebooks

docs/source/conf.py

@@ -80,7 +80,7 @@
     "sidebar_hide_name": True,
 }
 
-html_title = "synference"
+html_title = "Synference"
 
 ignore_pattern = ["basic_model.py"]
 

docs/source/index.rst

@@ -6,7 +6,7 @@ Synference is an open-source python package for SED fitting of photometric and s
 This documentation provides a broad overview of the various components in Synference and how they interact.
 The `Getting Started guide <getting_started/getting_started>`_ contains download and installation instructions, as well as an overview of the code.
 
-For detailed examples of what synference can do, take a look at the `Examples <auto_examples/index>`_ page.
+For detailed examples of what Synference can do, take a look at the `Examples <auto_examples/index>`_ page.
 A full description of the code base is provided in the `API <API>`_.
 
 Contents
@@ -29,7 +29,7 @@ Contents
 Citation & Acknowledgement
 --------------------------
 
-Please cite **all** of the following papers if you use synference in your research. Harvey et al. 2025 (in prep.) introduces the synference code, `Lovell et al. 2025 <https://ui.adsabs.harvard.edu/abs/2025arXiv250803888L/abstract>`_ & `Roper et al. 2025 <https://ui.adsabs.harvard.edu/abs/2025arXiv250615811R/abstract>`_ introduce the synthesizer code, and `Ho et al. 2024 <https://ui.adsabs.harvard.edu/abs/2024OJAp....7E..54H/abstract>`_ introduces the LtU-ILI framework.
+Please cite **all** of the following papers if you use Synference in your research. Harvey et al. 2025 (in prep.) introduces the Synference code, `Lovell et al. 2025 <https://ui.adsabs.harvard.edu/abs/2025arXiv250803888L/abstract>`_ & `Roper et al. 2025 <https://ui.adsabs.harvard.edu/abs/2025arXiv250615811R/abstract>`_ introduce the Synthesizer code, and `Ho et al. 2024 <https://ui.adsabs.harvard.edu/abs/2024OJAp....7E..54H/abstract>`_ introduces the LtU-ILI framework.
 
 .. code-block:: bibtex
 
@@ -97,4 +97,4 @@ Primary Contributors
 License
 -------
 
-synference is free software made available under the GNU General Public License v3.0. For details see the `LICENSE <https://github.com/synthesizer-project/synference/blob/main/LICENSE.md>`_.
+Synference is free software made available under the GNU General Public License v3.0. For details see the `LICENSE <https://github.com/synthesizer-project/synference/blob/main/LICENSE.md>`_.

docs/source/library_gen/library_generation.rst

@@ -3,9 +3,9 @@ Library Generation
 
 The principle of simulation-based inference relies on a 'simulator', which takes in a set of parameters and produces a synthetic observation. In traditional SED fitting, this is often a forward model that generates a synthetic SED from a set of physical parameters, and typically computed on-the-fly during inference. Whilst SBI models can be trained using such a simulator (called 'online' or 'active' learning), this is computationally wasteful if you intend to train multiple SBI models with the same simulator configuration.
 
-synference therefore provides tools to generate a 'library' of pre-computed simulations, which can then be used to train multiple SBI models. This is particularly useful for computationally expensive simulators, where generating a large library of simulations can take hours or days, but training an SBI model on that library takes only minutes to hours.
+Synference therefore provides tools to generate a 'library' of pre-computed simulations, which can then be used to train multiple SBI models. This is particularly useful for computationally expensive simulators, where generating a large library of simulations can take hours or days, but training an SBI model on that library takes only minutes to hours.
 
-Normal use of synference uses the 'Synthesizer' package to generate synthetic observables from a set of input parameters. The Synthesizer package provides a high-level interface to a variety of underlying astrophysical simulation codes, and can generate a wide range of synthetic observables including photometric fluxes, spectra, and images. The full Synthesizer documentation can be found `here <https://synthesizer-project.github.io/synthesizer/>`_, but we provide a brief crash course below.
+Normal use of Synference uses the 'Synthesizer' package to generate synthetic observables from a set of input parameters. The Synthesizer package provides a high-level interface to a variety of underlying astrophysical simulation codes, and can generate a wide range of synthetic observables including photometric fluxes, spectra, and images. The full Synthesizer documentation can be found `here <https://synthesizer-project.github.io/synthesizer/>`_, but we provide a brief crash course below.
 
 .. toctree::
    :maxdepth: 2

docs/source/noise_modelling/creating_noise_model.rst

@@ -1,7 +1,7 @@
 Uncertainty Modelling
 *********************
 
-Here we detail the various ways to create noise models in Synference.
+Here we detail the various ways to create noise models in Synference. Noise models are used to characterise the observational uncertainties on synthetic observables, and are an important component of simulation-based inference when applying it to real data.
 
 .. toctree::
    :maxdepth: 2

docs/source/posterior_inference/intro.rst

@@ -1,6 +1,10 @@
 Posterior Inference
 *******************
 
+In this section, we provide an overview of the various methods for performing posterior inference in Synference. Posterior inference is a crucial step in the simulation-based inference workflow, once an SBI model has been trained. It involves using the trained model to infer the posterior distribution of model parameters given observed data.
+
+We can also use the trained SBI model alongside our simulator to recover the predicted observables for our posterior samples, allowing us to assess the quality of our inference, and assess how well our model is able to reproduce the observed data.
+
 .. toctree::
    :maxdepth: 2
 

docs/source/sbi/introduction_to_sbi.rst

@@ -1,6 +1,8 @@
 Introduction to SBI
 *********************
 
+In this section, we provide an introduction to the background and theory of Simulation-Based Inference (SBI) methods, which form the core of the Synference package. We discuss the advantages of SBI over traditional inference methods, and outline the general workflow for performing SBI.
+
 .. toctree::
    :maxdepth: 2
 

docs/source/sbi_train/intro_sbi.rst

@@ -1,6 +1,8 @@
 Training SBI Models
 *******************
 
+In this section, we provide an overview of the various methods for training Simulation-Based Inference (SBI) models in Synference. Training an SBI model is a crucial step in the simulation-based inference workflow, as it allows us to learn the relationship between model parameters and synthetic observables from a library of pre-computed simulations or via online learning.
+
 .. toctree::
    :maxdepth: 2