diff --git a/CITATIONS.md b/CITATIONS.md new file mode 100644 index 0000000..6040f3e --- /dev/null +++ b/CITATIONS.md @@ -0,0 +1,14 @@ +# Citations & References + +The bibtex entries for **PyAutoFit** and its affiliated software packages can be found +[here](https://github.com/rhayes777/PyAutoFit/blob/main/files/citations.bib), with example text for citing **PyAutoFit** +in [.tex format here](https://github.com/rhayes777/PyAutoFit/blob/main/files/citations.tex) and +[.md format here](https://github.com/rhayes777/PyAutoFit/blob/main/files/citations.md). As shown in the examples, we +would greatly appreciate it if you mention **PyAutoFit** by name and include a link to our GitHub page! + +**PyAutoFit** is published in the [Journal of Open Source Software](https://joss.theoj.org/papers/10.21105/joss.03127) and its +entry in the above .bib file is under the citation key `pyautofit`. + +You should also specify the non-linear search(es) you use in your analysis (e.g. Dynesty, Emcee, Nautilus, etc.) in +the main body of text, and delete as appropriate any packages your analysis did not use. The citations.bib file includes +the citation key for all of these projects. diff --git a/CITATIONS.rst b/CITATIONS.rst deleted file mode 100644 index 6557ec8..0000000 --- a/CITATIONS.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. _references: - -Citations & References -====================== - -The bibtex entries for **PyAutoFit** and its affiliated software packages can be found -`here `_, with example text for citing **PyAutoFit** -in `.tex format here `_ and -`.md format here `_. As shown in the examples, we -would greatly appreciate it if you mention **PyAutoFit** by name and include a link to our GitHub page! - -**PyAutoFit** is published in the `Journal of Open Source Software `_ and its -entry in the above .bib file is under the citation key ``pyautofit``. - -You should also specify the non-linear search(es) you use in your analysis (e.g. Dynesty, Emcee, Nautilus, etc.) in -the main body of text, and delete as appropriate any packages your analysis did not use. The citations.bib file includes -the citation key for all of these projects. diff --git a/README.md b/README.md new file mode 100644 index 0000000..6e55d6a --- /dev/null +++ b/README.md @@ -0,0 +1,94 @@ +# HowToFit + +[Installation Guide](https://pyautofit.readthedocs.io/en/latest/installation/overview.html) | +[PyAutoFit readthedocs](https://pyautofit.readthedocs.io/en/latest/index.html) | +[autofit_workspace](https://github.com/PyAutoLabs/autofit_workspace) + + + +Welcome to **HowToFit** — the tutorial lecture series for [PyAutoFit](https://github.com/PyAutoLabs/PyAutoFit), +an open-source probabilistic programming library for Bayesian model fitting. + +**HowToFit** teaches new users how to compose, fit, and interpret probabilistic models with **PyAutoFit**. +It assumes minimal prior knowledge of statistics and takes you from first principles — what a model is, +what a non-linear search does, how a likelihood function is built — through to graphical and hierarchical +models for fitting large datasets simultaneously. + +For experienced scientists who already know the fundamentals of Bayesian modeling, the +[autofit_workspace](https://github.com/PyAutoLabs/autofit_workspace) examples will be more appropriate — +they are concise, API-focused, and assume the concepts taught in **HowToFit** as background. + +## Chapters + +- `chapter_1_introduction` — Models, likelihoods, non-linear searches, why modeling is hard, and how to + interpret the results of a fit. +- `chapter_2_scientific_workflow` — Reserved for future material on building a full scientific + model-fitting workflow. Currently a stub; the corresponding overview lives in + `autofit_workspace/scripts/overview/overview_2_science_workflow.py`. +- `chapter_3_graphical_models` — Fitting many datasets simultaneously with graphical models, + hierarchical models, and Expectation Propagation. + +Each chapter is organised into numbered tutorial files: `chapter__/tutorial__.py` +(Python script) or the matching `.ipynb` in `notebooks/`. Tutorials build on each other within a +chapter and assume you have completed the earlier ones. + +## Getting Started + +You can run the tutorials on your own machine by following the +[PyAutoFit installation guide](https://pyautofit.readthedocs.io/en/latest/installation/overview.html), +then cloning this repository: + +```bash +git clone https://github.com/PyAutoLabs/HowToFit.git +cd HowToFit +``` + +Alternatively, every tutorial can be opened directly in Google Colab via the links in each chapter's +`README.md`. + +The tutorials are distributed as both Jupyter notebooks (`notebooks/`) and Python scripts (`scripts/`). +We recommend the notebooks for reading — figures render inline, and you can step through small code blocks +interactively. Use the Python scripts for actual **PyAutoFit** use. + +## Before Chapter 1 + +Before starting chapter 1, open `start_here.py` for a one-page overview of the series, then begin +`scripts/chapter_1_introduction/tutorial_1_models.py`. + +## Repository Structure + +- `scripts/` — Runnable Python tutorial scripts, one subfolder per chapter. +- `notebooks/` — Jupyter notebook versions of the scripts (auto-generated; see below). +- `config/` — **PyAutoFit** configuration YAML files used by the tutorials. +- `dataset/` — Tutorial 1D datasets are generated at runtime by `scripts/simulators/simulators.py` — + no data files are committed. +- `output/` — Model-fit results (generated at runtime, not committed). + +## Notebooks vs Scripts + +Notebooks in `notebooks/` are generated from the Python files in `scripts/`. **Always edit the \`\`.py\`\` +scripts, never the notebooks directly.** The `# %%` markers in each script alternate between code and +markdown cells, which [PyAutoBuild](https://github.com/PyAutoLabs/PyAutoBuild) uses to produce the +`.ipynb` files. + +## Relationship to autofit_workspace + +[autofit_workspace](https://github.com/PyAutoLabs/autofit_workspace) is the main user-facing workspace +for **PyAutoFit** — concise examples, cookbooks, and search templates aimed at users who already understand +probabilistic modeling. **HowToFit** is the teaching companion. Tutorials in chapters 1 and 3 reference +`autofit_workspace` scripts as the next place to go after the relevant concept has been introduced. + +## Citations + +If you use **HowToFit** or **PyAutoFit** in your research, please cite the references listed in +`CITATIONS.rst`. + +## Community & Support + +Support for **PyAutoFit** is available via our Slack workspace. Slack is invitation-only; send an email +if you'd like an invite. + +For installation issues, bug reports, or feature requests, raise an issue on the +[PyAutoFit GitHub issues page](https://github.com/PyAutoLabs/PyAutoFit/issues) (for library issues) +or the [HowToFit GitHub issues page](https://github.com/PyAutoLabs/HowToFit/issues) (for tutorial +content issues). diff --git a/README.rst b/README.rst deleted file mode 100644 index c4e1dbc..0000000 --- a/README.rst +++ /dev/null @@ -1,104 +0,0 @@ -HowToFit -======== - -`Installation Guide `_ | -`PyAutoFit readthedocs `_ | -`autofit_workspace `_ - -.. image:: https://github.com/Jammy2211/PyAutoLogo/blob/main/gifs/pyautofit.gif?raw=true - :width: 900 - -Welcome to **HowToFit** — the tutorial lecture series for `PyAutoFit `_, -an open-source probabilistic programming library for Bayesian model fitting. - -**HowToFit** teaches new users how to compose, fit, and interpret probabilistic models with **PyAutoFit**. -It assumes minimal prior knowledge of statistics and takes you from first principles — what a model is, -what a non-linear search does, how a likelihood function is built — through to graphical and hierarchical -models for fitting large datasets simultaneously. - -For experienced scientists who already know the fundamentals of Bayesian modeling, the -`autofit_workspace `_ examples will be more appropriate — -they are concise, API-focused, and assume the concepts taught in **HowToFit** as background. - -Chapters --------- - -- ``chapter_1_introduction`` — Models, likelihoods, non-linear searches, why modeling is hard, and how to - interpret the results of a fit. -- ``chapter_2_scientific_workflow`` — Reserved for future material on building a full scientific - model-fitting workflow. Currently a stub; the corresponding overview lives in - ``autofit_workspace/scripts/overview/overview_2_science_workflow.py``. -- ``chapter_3_graphical_models`` — Fitting many datasets simultaneously with graphical models, - hierarchical models, and Expectation Propagation. - -Each chapter is organised into numbered tutorial files: ``chapter__/tutorial__.py`` -(Python script) or the matching ``.ipynb`` in ``notebooks/``. Tutorials build on each other within a -chapter and assume you have completed the earlier ones. - -Getting Started ---------------- - -You can run the tutorials on your own machine by following the -`PyAutoFit installation guide `_, -then cloning this repository: - -.. code-block:: bash - - git clone https://github.com/PyAutoLabs/HowToFit.git - cd HowToFit - -Alternatively, every tutorial can be opened directly in Google Colab via the links in each chapter's -``README.rst``. - -The tutorials are distributed as both Jupyter notebooks (``notebooks/``) and Python scripts (``scripts/``). -We recommend the notebooks for reading — figures render inline, and you can step through small code blocks -interactively. Use the Python scripts for actual **PyAutoFit** use. - -Before Chapter 1 ----------------- - -Before starting chapter 1, open ``start_here.py`` for a one-page overview of the series, then begin -``scripts/chapter_1_introduction/tutorial_1_models.py``. - -Repository Structure --------------------- - -- ``scripts/`` — Runnable Python tutorial scripts, one subfolder per chapter. -- ``notebooks/`` — Jupyter notebook versions of the scripts (auto-generated; see below). -- ``config/`` — **PyAutoFit** configuration YAML files used by the tutorials. -- ``dataset/`` — Tutorial 1D datasets are generated at runtime by ``scripts/simulators/simulators.py`` — - no data files are committed. -- ``output/`` — Model-fit results (generated at runtime, not committed). - -Notebooks vs Scripts --------------------- - -Notebooks in ``notebooks/`` are generated from the Python files in ``scripts/``. **Always edit the ``.py`` -scripts, never the notebooks directly.** The ``# %%`` markers in each script alternate between code and -markdown cells, which `PyAutoBuild `_ uses to produce the -``.ipynb`` files. - -Relationship to autofit_workspace ---------------------------------- - -`autofit_workspace `_ is the main user-facing workspace -for **PyAutoFit** — concise examples, cookbooks, and search templates aimed at users who already understand -probabilistic modeling. **HowToFit** is the teaching companion. Tutorials in chapters 1 and 3 reference -``autofit_workspace`` scripts as the next place to go after the relevant concept has been introduced. - -Citations ---------- - -If you use **HowToFit** or **PyAutoFit** in your research, please cite the references listed in -``CITATIONS.rst``. - -Community & Support -------------------- - -Support for **PyAutoFit** is available via our Slack workspace. Slack is invitation-only; send an email -if you'd like an invite. - -For installation issues, bug reports, or feature requests, raise an issue on the -`PyAutoFit GitHub issues page `_ (for library issues) -or the `HowToFit GitHub issues page `_ (for tutorial -content issues). diff --git a/config/README.md b/config/README.md new file mode 100644 index 0000000..115a631 --- /dev/null +++ b/config/README.md @@ -0,0 +1,13 @@ +The `config` folder contains configuration files which customize default **PyAutoLens**. + +# Folders + +- `priors`: Configs defining default priors assumed on every model component and set of parameters. + +# Files + +- `general.yaml`: Customizes general **PyAutoLens** settings. +- `non-linear.yaml`: Configs for default non-linear search (e.g. MCMC, nested sampling) settings. +- `logging.yaml`: Customizes the logging behaviour of **PyAutoLens**. +- `visualize.yaml`: Configs defining what images are output by a lens model fit. +- `notation.yaml`: Configs defining labels and formatting of model parameters when used for visualization. diff --git a/config/README.rst b/config/README.rst deleted file mode 100644 index 7c08fcf..0000000 --- a/config/README.rst +++ /dev/null @@ -1,15 +0,0 @@ -The ``config`` folder contains configuration files which customize default **PyAutoLens**. - -Folders -------- - -- ``priors``: Configs defining default priors assumed on every model component and set of parameters. - -Files ------ - -- ``general.yaml``: Customizes general **PyAutoLens** settings. -- ``non-linear.yaml``: Configs for default non-linear search (e.g. MCMC, nested sampling) settings. -- ``logging.yaml``: Customizes the logging behaviour of **PyAutoLens**. -- ``visualize.yaml``: Configs defining what images are output by a lens model fit. -- ``notation.yaml``: Configs defining labels and formatting of model parameters when used for visualization. diff --git a/config/non_linear/README.md b/config/non_linear/README.md new file mode 100644 index 0000000..f69c3b3 --- /dev/null +++ b/config/non_linear/README.md @@ -0,0 +1,8 @@ +The `non_linear` folder contains configuration files which customize the default behaviour of non-linear searches in +**PyAutoLens**. + +# Files + +- `mcmc.yaml`: Settings default behaviour of MCMC non-linear searches (e.g. Emcee). +- `nest.yaml`: Settings default behaviour of nested sampler non-linear searches (e.g. Dynesty). +- `mle.yaml`: Settings default behaviour of maximum likelihood estimator (mle) searches (e.g. LBFGS). diff --git a/config/non_linear/README.rst b/config/non_linear/README.rst deleted file mode 100644 index 6226f9f..0000000 --- a/config/non_linear/README.rst +++ /dev/null @@ -1,9 +0,0 @@ -The ``non_linear`` folder contains configuration files which customize the default behaviour of non-linear searches in -**PyAutoLens**. - -Files ------ - -- ``mcmc.yaml``: Settings default behaviour of MCMC non-linear searches (e.g. Emcee). -- ``nest.yaml``: Settings default behaviour of nested sampler non-linear searches (e.g. Dynesty). -- ``mle.yaml``: Settings default behaviour of maximum likelihood estimator (mle) searches (e.g. LBFGS). \ No newline at end of file diff --git a/config/priors/README.md b/config/priors/README.md new file mode 100644 index 0000000..73ed122 --- /dev/null +++ b/config/priors/README.md @@ -0,0 +1,42 @@ +The prior config files contain the default priors and related variables for every light profile and mass profile +when it is used as a model. + +They appear as follows: + +```bash +Gaussian: + centre: + type: Uniform + lower_limit: 0.0 + upper_limit: 100.0 + width_modifier: + type: Absolute + value: 20.0 + limits: + lower: -inf + upper: inf +``` + +The sections of this example config set the following: + +> type {Uniform, Gaussian, LogUniform} +> +> : The default prior given to this parameter when used by the non-linear search. In the example above, a +> UniformPrior is used with lower_limit of 0.0 and upper_limit of 4.0. A GaussianPrior could be used by +> putting "Gaussian" in the "type" box, with "mean" and "sigma" used to set the default values. Any prior can be +> set in an analogous fashion (see the example configs). +> +> width_modifier +> +> : When the results of a search are passed to a subsequent search to set up the priors of its non-linear search, +> this entry describes how the Prior is passed. For a full description of prior passing, checkout the examples +> in 'autolens_workspace/examples/complex/linking'. +> +> limits +> +> : When the results of a search are passed to a subsequent search, they are passed using a GaussianPrior. The +> limits set the physical lower and upper limits of this GaussianPrior, such that parameter samples +> can not go beyond these limits. + +The files `template_module.yaml` and `TemplateObject.yaml` give templates one can use to set up prior default +configs for your own model components. diff --git a/config/priors/README.rst b/config/priors/README.rst deleted file mode 100644 index 9900012..0000000 --- a/config/priors/README.rst +++ /dev/null @@ -1,37 +0,0 @@ -The prior config files contain the default priors and related variables for every light profile and mass profile -when it is used as a model. - -They appear as follows: - -.. code-block:: bash - - Gaussian: - centre: - type: Uniform - lower_limit: 0.0 - upper_limit: 100.0 - width_modifier: - type: Absolute - value: 20.0 - limits: - lower: -inf - upper: inf - -The sections of this example config set the following: - - type {Uniform, Gaussian, LogUniform} - The default prior given to this parameter when used by the non-linear search. In the example above, a - UniformPrior is used with lower_limit of 0.0 and upper_limit of 4.0. A GaussianPrior could be used by - putting "Gaussian" in the "type" box, with "mean" and "sigma" used to set the default values. Any prior can be - set in an analogous fashion (see the example configs). - width_modifier - When the results of a search are passed to a subsequent search to set up the priors of its non-linear search, - this entry describes how the Prior is passed. For a full description of prior passing, checkout the examples - in 'autolens_workspace/examples/complex/linking'. - limits - When the results of a search are passed to a subsequent search, they are passed using a GaussianPrior. The - limits set the physical lower and upper limits of this GaussianPrior, such that parameter samples - can not go beyond these limits. - -The files ``template_module.yaml`` and ``TemplateObject.yaml`` give templates one can use to set up prior default -configs for your own model components. \ No newline at end of file diff --git a/config/visualize/README.md b/config/visualize/README.md new file mode 100644 index 0000000..f5c6146 --- /dev/null +++ b/config/visualize/README.md @@ -0,0 +1,6 @@ +The `config` folder contains configuration files which customize default **PyAutoLens**. + +# Files + +- `general.yaml`: Customizes general visualization settings (e.g. the matplotlib backend). +- `plots_search.yaml`: Customize which non-linear search figures are output during a model-fit. diff --git a/config/visualize/README.rst b/config/visualize/README.rst deleted file mode 100644 index 200fa3c..0000000 --- a/config/visualize/README.rst +++ /dev/null @@ -1,7 +0,0 @@ -The ``config`` folder contains configuration files which customize default **PyAutoLens**. - -Files ------ - -- ``general.yaml``: Customizes general visualization settings (e.g. the matplotlib backend). -- ``plots_search.yaml``: Customize which non-linear search figures are output during a model-fit. \ No newline at end of file diff --git a/notebooks/README.md b/notebooks/README.md new file mode 100644 index 0000000..30b0d45 --- /dev/null +++ b/notebooks/README.md @@ -0,0 +1,69 @@ +The `scripts` folder contains **HowToFit** lectures, which teach a new user how to compose and fit models in **PyAutoFit**. + +# Folders + +- `chapter_1_introduction`: Introduction lectures describing how to compose and fit models in **PyAutoFit**. +- `chapter_2_scientific_workflow`: Reserved stub for future material on building a full scientific model-fitting workflow. The equivalent overview currently lives in `autofit_workspace/scripts/overview/overview_2_science_workflow.py`. +- `chapter_3_graphical_models`: How to compose and fit graphical models which fit many datasets simultaneously, including hierarchical models and Expectation Propagation. +- `simulators`: Simulator scripts that generate the tutorial 1D datasets at runtime. + +# Jupyter Notebooks + +The tutorials are supplied as *Jupyter notebooks*, which come with a `.ipynb` suffix. For those new to +Python, *Jupyter notebooks* are a different way to write, view and use Python code. Compared to traditional +Python scripts, they allow: + +- Small blocks of code to be viewed and run at a time +- Images and visualization from a code block to be displayed directly underneath it. +- Text script to appear between the blocks of code. + +This makes them an ideal way for us to present the **HowToFit** lecture series. The notebooks live under +`notebooks/` and are auto-generated from the Python scripts in `scripts/` — **edit the Python scripts, +not the notebooks.** + +For actual **PyAutoFit** use we recommend the Python scripts. Chapter 3 onwards assumes that transition. + +# Code Style and Formatting + +You may notice the style and formatting of our Python code looks different to what you are used to. For +example, it is common for brackets to be placed on their own line at the end of function calls, and the +inputs of a function or class may be listed over many separate lines. + +This is intentional, because we believe it makes the cleanest, most readable code possible. The codebase +is auto-formatted with `black` — see . + +# How to Approach HowToFit + +**HowToFit** currently consists of three chapters (chapter 2 is a stub). Chapter 1 will take a couple of +hours to work through. The concepts in chapter 3 are challenging, and familiarity with **PyAutoFit** and +model fitting is desirable before tackling them. + +We recommend that you complete chapter 1 and then apply what you've learnt to a model-fitting problem you +are interested in, building on the scripts found in the +[autofit_workspace](https://github.com/PyAutoLabs/autofit_workspace) repository. Once you're confident +with your use of **PyAutoFit**, return for chapter 3. + +# Overview of Chapter 1 (Beginner) + +**Model Fitting with PyAutoFit** + +In chapter 1, we'll learn about model composition and fitting with **PyAutoFit**. By the end, you'll be +able to: + +1. Compose a model in **PyAutoFit**. +2. Define a `log_likelihood_function()` via an `Analysis` class to fit that model to data. +3. Understand the concept of a non-linear search and non-linear parameter space. +4. Fit a model to data using a non-linear search. +5. Compose and fit more complex models using **PyAutoFit**'s model composition API. +6. Analyse the results of a model-fit, including parameter estimates and errors. + +# Overview of Chapter 3 (Advanced) + +**Fitting Graphical Models to Large Datasets** + +Chapter 3 covers how to compose and fit graphical models to extremely large datasets. You'll learn: + +1. Why fitting a model to many datasets one-by-one is suboptimal. +2. How to fit a graphical model to all datasets simultaneously and why this improves the model results. +3. How to scale graphical model fits up to extremely large datasets via Expectation Propagation. +4. How to fit a hierarchical model using the graphical modeling framework and Expectation Propagation. diff --git a/notebooks/README.rst b/notebooks/README.rst deleted file mode 100644 index 536ac6b..0000000 --- a/notebooks/README.rst +++ /dev/null @@ -1,75 +0,0 @@ -The ``scripts`` folder contains **HowToFit** lectures, which teach a new user how to compose and fit models in **PyAutoFit**. - -Folders -------- - -- ``chapter_1_introduction``: Introduction lectures describing how to compose and fit models in **PyAutoFit**. -- ``chapter_2_scientific_workflow``: Reserved stub for future material on building a full scientific model-fitting workflow. The equivalent overview currently lives in ``autofit_workspace/scripts/overview/overview_2_science_workflow.py``. -- ``chapter_3_graphical_models``: How to compose and fit graphical models which fit many datasets simultaneously, including hierarchical models and Expectation Propagation. -- ``simulators``: Simulator scripts that generate the tutorial 1D datasets at runtime. - -Jupyter Notebooks ------------------ - -The tutorials are supplied as *Jupyter notebooks*, which come with a ``.ipynb`` suffix. For those new to -Python, *Jupyter notebooks* are a different way to write, view and use Python code. Compared to traditional -Python scripts, they allow: - -- Small blocks of code to be viewed and run at a time -- Images and visualization from a code block to be displayed directly underneath it. -- Text script to appear between the blocks of code. - -This makes them an ideal way for us to present the **HowToFit** lecture series. The notebooks live under -``notebooks/`` and are auto-generated from the Python scripts in ``scripts/`` — **edit the Python scripts, -not the notebooks.** - -For actual **PyAutoFit** use we recommend the Python scripts. Chapter 3 onwards assumes that transition. - -Code Style and Formatting -------------------------- - -You may notice the style and formatting of our Python code looks different to what you are used to. For -example, it is common for brackets to be placed on their own line at the end of function calls, and the -inputs of a function or class may be listed over many separate lines. - -This is intentional, because we believe it makes the cleanest, most readable code possible. The codebase -is auto-formatted with ``black`` — see https://github.com/python/black. - -How to Approach HowToFit ------------------------- - -**HowToFit** currently consists of three chapters (chapter 2 is a stub). Chapter 1 will take a couple of -hours to work through. The concepts in chapter 3 are challenging, and familiarity with **PyAutoFit** and -model fitting is desirable before tackling them. - -We recommend that you complete chapter 1 and then apply what you've learnt to a model-fitting problem you -are interested in, building on the scripts found in the -`autofit_workspace `_ repository. Once you're confident -with your use of **PyAutoFit**, return for chapter 3. - -Overview of Chapter 1 (Beginner) --------------------------------- - -**Model Fitting with PyAutoFit** - -In chapter 1, we'll learn about model composition and fitting with **PyAutoFit**. By the end, you'll be -able to: - -1) Compose a model in **PyAutoFit**. -2) Define a ``log_likelihood_function()`` via an ``Analysis`` class to fit that model to data. -3) Understand the concept of a non-linear search and non-linear parameter space. -4) Fit a model to data using a non-linear search. -5) Compose and fit more complex models using **PyAutoFit**'s model composition API. -6) Analyse the results of a model-fit, including parameter estimates and errors. - -Overview of Chapter 3 (Advanced) --------------------------------- - -**Fitting Graphical Models to Large Datasets** - -Chapter 3 covers how to compose and fit graphical models to extremely large datasets. You'll learn: - -1) Why fitting a model to many datasets one-by-one is suboptimal. -2) How to fit a graphical model to all datasets simultaneously and why this improves the model results. -3) How to scale graphical model fits up to extremely large datasets via Expectation Propagation. -4) How to fit a hierarchical model using the graphical modeling framework and Expectation Propagation. diff --git a/notebooks/chapter_1_introduction/README.md b/notebooks/chapter_1_introduction/README.md new file mode 100644 index 0000000..e660685 --- /dev/null +++ b/notebooks/chapter_1_introduction/README.md @@ -0,0 +1,18 @@ +In chapter 1, we introduce you to the **PyAutoFit** and describe how to set up your own model, fit it to data via +a non-linear search and inspect and interpret the results. + +**Colab** links to every tutorial are included. + +# Files + +The chapter contains the following tutorials: + +- [Tutorial 1: Models](https://colab.research.google.com/github/PyAutoLabs/HowToFit/blob/2026.5.1.4/notebooks/chapter_1_introduction/tutorial_1_models.ipynb) — What probabilistic models are and how to compose them using PyAutoFit. + +- [Tutorial 2: Fitting Data](https://colab.research.google.com/github/PyAutoLabs/HowToFit/blob/2026.5.1.4/notebooks/chapter_1_introduction/tutorial_2_fitting_data.ipynb) — Fitting a model with an input set of parameters to data and quantifying the goodness of fit. + +- [Tutorial 3: Non Linear Search](https://colab.research.google.com/github/PyAutoLabs/HowToFit/blob/2026.5.1.4/notebooks/chapter_1_introduction/tutorial_3_non_linear_search.ipynb) — Searching non-linear parameter spaces to find the best-fit model. + +- [Tutorial 4: Complex Models](https://colab.research.google.com/github/PyAutoLabs/HowToFit/blob/2026.5.1.4/notebooks/chapter_1_introduction/tutorial_4_complex_models.ipynb) — Composing and fitting more complex models in a scalable and extensible way. + +- [Tutorial 5: Results and Samples](https://colab.research.google.com/github/PyAutoLabs/HowToFit/blob/2026.5.1.4/notebooks/chapter_1_introduction/tutorial_5_results_and_samples.ipynb) — Interpreting model-fit results and using the samples for scientific analysis. diff --git a/notebooks/chapter_1_introduction/README.rst b/notebooks/chapter_1_introduction/README.rst deleted file mode 100644 index c885cec..0000000 --- a/notebooks/chapter_1_introduction/README.rst +++ /dev/null @@ -1,24 +0,0 @@ -In chapter 1, we introduce you to the **PyAutoFit** and describe how to set up your own model, fit it to data via -a non-linear search and inspect and interpret the results. - -**Colab** links to every tutorial are included. - -Files ------ - -The chapter contains the following tutorials: - -`Tutorial 1: Models `_ -- What probabilistic models are and how to compose them using PyAutoFit. - -`Tutorial 2: Fitting Data `_ -- Fitting a model with an input set of parameters to data and quantifying the goodness of fit. - -`Tutorial 3: Non Linear Search `_ -- Searching non-linear parameter spaces to find the best-fit model. - -`Tutorial 4: Complex Models `_ -- Composing and fitting more complex models in a scalable and extensible way. - -`Tutorial 5: Results and Samples `_ -- Interpreting model-fit results and using the samples for scientific analysis. diff --git a/scripts/chapter_2_scientific_workflow/README.rst b/notebooks/chapter_2_scientific_workflow/README.md similarity index 78% rename from scripts/chapter_2_scientific_workflow/README.rst rename to notebooks/chapter_2_scientific_workflow/README.md index 90b6c7d..4d6ea83 100644 --- a/scripts/chapter_2_scientific_workflow/README.rst +++ b/notebooks/chapter_2_scientific_workflow/README.md @@ -1,10 +1,10 @@ -This folder will contain chapter 2 of the **HowToFit** lectures, which will explain -how to build a scientific workflow. However, the chapter is not written yet. - -The functionality required to develop a scientific workflow is fully supported in autofit and described in the -following overview example: - -``autofit_workspace/*/overview/overview_2_science_workflow.py`` - -If you are a confident model-fitting practitioner, you should be able to follow this example to perform the tasks -required to build a scientific workflow. \ No newline at end of file +This folder will contain chapter 2 of the **HowToFit** lectures, which will explain +how to build a scientific workflow. However, the chapter is not written yet. + +The functionality required to develop a scientific workflow is fully supported in autofit and described in the +following overview example: + +`autofit_workspace/*/overview/overview_2_science_workflow.py` + +If you are a confident model-fitting practitioner, you should be able to follow this example to perform the tasks +required to build a scientific workflow. diff --git a/notebooks/chapter_3_graphical_models/README.md b/notebooks/chapter_3_graphical_models/README.md new file mode 100644 index 0000000..0904bd7 --- /dev/null +++ b/notebooks/chapter_3_graphical_models/README.md @@ -0,0 +1,19 @@ +In this chapter, we take you through how to compose and fit graphical models in **PyAutoFit**. Graphical models +simultaneously fit many datasets with a model that has 'local' parameters specific to each individual dataset +and 'global' parameters that fit for global trends across the whole dataset. + +**Colab** links to every tutorial are included. + +# Files + +The chapter contains the following tutorials: + +- [Tutorial 1: Individual Models](https://colab.research.google.com/github/PyAutoLabs/HowToFit/blob/2026.5.1.4/notebooks/chapter_3_graphical_models/tutorial_1_individual_models.ipynb) — Inferring global parameters from a dataset by fitting the model to each individual dataset one-by-one. + +- [Tutorial 2: Graphical Model](https://colab.research.google.com/github/PyAutoLabs/HowToFit/blob/2026.5.1.4/notebooks/chapter_3_graphical_models/tutorial_2_graphical_model.ipynb) — Fitting the dataset with a graphical model that fits all datasets simultaneously to infer the global parameters. + +- [Tutorial 3: Graphical Benefits](https://colab.research.google.com/github/PyAutoLabs/HowToFit/blob/2026.5.1.4/notebooks/chapter_3_graphical_models/tutorial_3_graphical_benefits.ipynb) — Illustrating the benefits of graphical modeling over fitting individual datasets one-by-one. + +- [Tutorial 4: Hierarchical Models](https://colab.research.google.com/github/PyAutoLabs/HowToFit/blob/2026.5.1.4/notebooks/chapter_3_graphical_models/tutorial_4_hierarchical_models.ipynb) — Fitting hierarchical models using the graphical modeling framework. + +- [Tutorial 5: Expectation Propagation](https://colab.research.google.com/github/PyAutoLabs/HowToFit/blob/2026.5.1.4/notebooks/chapter_3_graphical_models/tutorial_5_expectation_propagation.ipynb) — Scaling graphical models up to fit extremely large datasets using Expectation Propagation (EP). diff --git a/notebooks/chapter_3_graphical_models/README.rst b/notebooks/chapter_3_graphical_models/README.rst deleted file mode 100644 index b6c181a..0000000 --- a/notebooks/chapter_3_graphical_models/README.rst +++ /dev/null @@ -1,25 +0,0 @@ -In this chapter, we take you through how to compose and fit graphical models in **PyAutoFit**. Graphical models -simultaneously fit many datasets with a model that has 'local' parameters specific to each individual dataset -and 'global' parameters that fit for global trends across the whole dataset. - -**Colab** links to every tutorial are included. - -Files ------ - -The chapter contains the following tutorials: - -`Tutorial 1: Individual Models `_ -- Inferring global parameters from a dataset by fitting the model to each individual dataset one-by-one. - -`Tutorial 2: Graphical Model `_ -- Fitting the dataset with a graphical model that fits all datasets simultaneously to infer the global parameters. - -`Tutorial 3: Graphical Benefits `_ -- Illustrating the benefits of graphical modeling over fitting individual datasets one-by-one. - -`Tutorial 4: Hierarchical Models `_ -- Fitting hierarchical models using the graphical modeling framework. - -`Tutorial 5: Expectation Propagation `_ -- Scaling graphical models up to fit extremely large datasets using Expectation Propagation (EP). \ No newline at end of file diff --git a/scripts/README.md b/scripts/README.md new file mode 100644 index 0000000..30b0d45 --- /dev/null +++ b/scripts/README.md @@ -0,0 +1,69 @@ +The `scripts` folder contains **HowToFit** lectures, which teach a new user how to compose and fit models in **PyAutoFit**. + +# Folders + +- `chapter_1_introduction`: Introduction lectures describing how to compose and fit models in **PyAutoFit**. +- `chapter_2_scientific_workflow`: Reserved stub for future material on building a full scientific model-fitting workflow. The equivalent overview currently lives in `autofit_workspace/scripts/overview/overview_2_science_workflow.py`. +- `chapter_3_graphical_models`: How to compose and fit graphical models which fit many datasets simultaneously, including hierarchical models and Expectation Propagation. +- `simulators`: Simulator scripts that generate the tutorial 1D datasets at runtime. + +# Jupyter Notebooks + +The tutorials are supplied as *Jupyter notebooks*, which come with a `.ipynb` suffix. For those new to +Python, *Jupyter notebooks* are a different way to write, view and use Python code. Compared to traditional +Python scripts, they allow: + +- Small blocks of code to be viewed and run at a time +- Images and visualization from a code block to be displayed directly underneath it. +- Text script to appear between the blocks of code. + +This makes them an ideal way for us to present the **HowToFit** lecture series. The notebooks live under +`notebooks/` and are auto-generated from the Python scripts in `scripts/` — **edit the Python scripts, +not the notebooks.** + +For actual **PyAutoFit** use we recommend the Python scripts. Chapter 3 onwards assumes that transition. + +# Code Style and Formatting + +You may notice the style and formatting of our Python code looks different to what you are used to. For +example, it is common for brackets to be placed on their own line at the end of function calls, and the +inputs of a function or class may be listed over many separate lines. + +This is intentional, because we believe it makes the cleanest, most readable code possible. The codebase +is auto-formatted with `black` — see . + +# How to Approach HowToFit + +**HowToFit** currently consists of three chapters (chapter 2 is a stub). Chapter 1 will take a couple of +hours to work through. The concepts in chapter 3 are challenging, and familiarity with **PyAutoFit** and +model fitting is desirable before tackling them. + +We recommend that you complete chapter 1 and then apply what you've learnt to a model-fitting problem you +are interested in, building on the scripts found in the +[autofit_workspace](https://github.com/PyAutoLabs/autofit_workspace) repository. Once you're confident +with your use of **PyAutoFit**, return for chapter 3. + +# Overview of Chapter 1 (Beginner) + +**Model Fitting with PyAutoFit** + +In chapter 1, we'll learn about model composition and fitting with **PyAutoFit**. By the end, you'll be +able to: + +1. Compose a model in **PyAutoFit**. +2. Define a `log_likelihood_function()` via an `Analysis` class to fit that model to data. +3. Understand the concept of a non-linear search and non-linear parameter space. +4. Fit a model to data using a non-linear search. +5. Compose and fit more complex models using **PyAutoFit**'s model composition API. +6. Analyse the results of a model-fit, including parameter estimates and errors. + +# Overview of Chapter 3 (Advanced) + +**Fitting Graphical Models to Large Datasets** + +Chapter 3 covers how to compose and fit graphical models to extremely large datasets. You'll learn: + +1. Why fitting a model to many datasets one-by-one is suboptimal. +2. How to fit a graphical model to all datasets simultaneously and why this improves the model results. +3. How to scale graphical model fits up to extremely large datasets via Expectation Propagation. +4. How to fit a hierarchical model using the graphical modeling framework and Expectation Propagation. diff --git a/scripts/README.rst b/scripts/README.rst deleted file mode 100644 index 536ac6b..0000000 --- a/scripts/README.rst +++ /dev/null @@ -1,75 +0,0 @@ -The ``scripts`` folder contains **HowToFit** lectures, which teach a new user how to compose and fit models in **PyAutoFit**. - -Folders -------- - -- ``chapter_1_introduction``: Introduction lectures describing how to compose and fit models in **PyAutoFit**. -- ``chapter_2_scientific_workflow``: Reserved stub for future material on building a full scientific model-fitting workflow. The equivalent overview currently lives in ``autofit_workspace/scripts/overview/overview_2_science_workflow.py``. -- ``chapter_3_graphical_models``: How to compose and fit graphical models which fit many datasets simultaneously, including hierarchical models and Expectation Propagation. -- ``simulators``: Simulator scripts that generate the tutorial 1D datasets at runtime. - -Jupyter Notebooks ------------------ - -The tutorials are supplied as *Jupyter notebooks*, which come with a ``.ipynb`` suffix. For those new to -Python, *Jupyter notebooks* are a different way to write, view and use Python code. Compared to traditional -Python scripts, they allow: - -- Small blocks of code to be viewed and run at a time -- Images and visualization from a code block to be displayed directly underneath it. -- Text script to appear between the blocks of code. - -This makes them an ideal way for us to present the **HowToFit** lecture series. The notebooks live under -``notebooks/`` and are auto-generated from the Python scripts in ``scripts/`` — **edit the Python scripts, -not the notebooks.** - -For actual **PyAutoFit** use we recommend the Python scripts. Chapter 3 onwards assumes that transition. - -Code Style and Formatting -------------------------- - -You may notice the style and formatting of our Python code looks different to what you are used to. For -example, it is common for brackets to be placed on their own line at the end of function calls, and the -inputs of a function or class may be listed over many separate lines. - -This is intentional, because we believe it makes the cleanest, most readable code possible. The codebase -is auto-formatted with ``black`` — see https://github.com/python/black. - -How to Approach HowToFit ------------------------- - -**HowToFit** currently consists of three chapters (chapter 2 is a stub). Chapter 1 will take a couple of -hours to work through. The concepts in chapter 3 are challenging, and familiarity with **PyAutoFit** and -model fitting is desirable before tackling them. - -We recommend that you complete chapter 1 and then apply what you've learnt to a model-fitting problem you -are interested in, building on the scripts found in the -`autofit_workspace `_ repository. Once you're confident -with your use of **PyAutoFit**, return for chapter 3. - -Overview of Chapter 1 (Beginner) --------------------------------- - -**Model Fitting with PyAutoFit** - -In chapter 1, we'll learn about model composition and fitting with **PyAutoFit**. By the end, you'll be -able to: - -1) Compose a model in **PyAutoFit**. -2) Define a ``log_likelihood_function()`` via an ``Analysis`` class to fit that model to data. -3) Understand the concept of a non-linear search and non-linear parameter space. -4) Fit a model to data using a non-linear search. -5) Compose and fit more complex models using **PyAutoFit**'s model composition API. -6) Analyse the results of a model-fit, including parameter estimates and errors. - -Overview of Chapter 3 (Advanced) --------------------------------- - -**Fitting Graphical Models to Large Datasets** - -Chapter 3 covers how to compose and fit graphical models to extremely large datasets. You'll learn: - -1) Why fitting a model to many datasets one-by-one is suboptimal. -2) How to fit a graphical model to all datasets simultaneously and why this improves the model results. -3) How to scale graphical model fits up to extremely large datasets via Expectation Propagation. -4) How to fit a hierarchical model using the graphical modeling framework and Expectation Propagation. diff --git a/scripts/chapter_1_introduction/README.md b/scripts/chapter_1_introduction/README.md new file mode 100644 index 0000000..e660685 --- /dev/null +++ b/scripts/chapter_1_introduction/README.md @@ -0,0 +1,18 @@ +In chapter 1, we introduce you to the **PyAutoFit** and describe how to set up your own model, fit it to data via +a non-linear search and inspect and interpret the results. + +**Colab** links to every tutorial are included. + +# Files + +The chapter contains the following tutorials: + +- [Tutorial 1: Models](https://colab.research.google.com/github/PyAutoLabs/HowToFit/blob/2026.5.1.4/notebooks/chapter_1_introduction/tutorial_1_models.ipynb) — What probabilistic models are and how to compose them using PyAutoFit. + +- [Tutorial 2: Fitting Data](https://colab.research.google.com/github/PyAutoLabs/HowToFit/blob/2026.5.1.4/notebooks/chapter_1_introduction/tutorial_2_fitting_data.ipynb) — Fitting a model with an input set of parameters to data and quantifying the goodness of fit. + +- [Tutorial 3: Non Linear Search](https://colab.research.google.com/github/PyAutoLabs/HowToFit/blob/2026.5.1.4/notebooks/chapter_1_introduction/tutorial_3_non_linear_search.ipynb) — Searching non-linear parameter spaces to find the best-fit model. + +- [Tutorial 4: Complex Models](https://colab.research.google.com/github/PyAutoLabs/HowToFit/blob/2026.5.1.4/notebooks/chapter_1_introduction/tutorial_4_complex_models.ipynb) — Composing and fitting more complex models in a scalable and extensible way. + +- [Tutorial 5: Results and Samples](https://colab.research.google.com/github/PyAutoLabs/HowToFit/blob/2026.5.1.4/notebooks/chapter_1_introduction/tutorial_5_results_and_samples.ipynb) — Interpreting model-fit results and using the samples for scientific analysis. diff --git a/scripts/chapter_1_introduction/README.rst b/scripts/chapter_1_introduction/README.rst deleted file mode 100644 index c885cec..0000000 --- a/scripts/chapter_1_introduction/README.rst +++ /dev/null @@ -1,24 +0,0 @@ -In chapter 1, we introduce you to the **PyAutoFit** and describe how to set up your own model, fit it to data via -a non-linear search and inspect and interpret the results. - -**Colab** links to every tutorial are included. - -Files ------ - -The chapter contains the following tutorials: - -`Tutorial 1: Models `_ -- What probabilistic models are and how to compose them using PyAutoFit. - -`Tutorial 2: Fitting Data `_ -- Fitting a model with an input set of parameters to data and quantifying the goodness of fit. - -`Tutorial 3: Non Linear Search `_ -- Searching non-linear parameter spaces to find the best-fit model. - -`Tutorial 4: Complex Models `_ -- Composing and fitting more complex models in a scalable and extensible way. - -`Tutorial 5: Results and Samples `_ -- Interpreting model-fit results and using the samples for scientific analysis. diff --git a/notebooks/chapter_2_scientific_workflow/README.rst b/scripts/chapter_2_scientific_workflow/README.md similarity index 78% rename from notebooks/chapter_2_scientific_workflow/README.rst rename to scripts/chapter_2_scientific_workflow/README.md index 90b6c7d..4d6ea83 100644 --- a/notebooks/chapter_2_scientific_workflow/README.rst +++ b/scripts/chapter_2_scientific_workflow/README.md @@ -1,10 +1,10 @@ -This folder will contain chapter 2 of the **HowToFit** lectures, which will explain -how to build a scientific workflow. However, the chapter is not written yet. - -The functionality required to develop a scientific workflow is fully supported in autofit and described in the -following overview example: - -``autofit_workspace/*/overview/overview_2_science_workflow.py`` - -If you are a confident model-fitting practitioner, you should be able to follow this example to perform the tasks -required to build a scientific workflow. \ No newline at end of file +This folder will contain chapter 2 of the **HowToFit** lectures, which will explain +how to build a scientific workflow. However, the chapter is not written yet. + +The functionality required to develop a scientific workflow is fully supported in autofit and described in the +following overview example: + +`autofit_workspace/*/overview/overview_2_science_workflow.py` + +If you are a confident model-fitting practitioner, you should be able to follow this example to perform the tasks +required to build a scientific workflow. diff --git a/scripts/chapter_3_graphical_models/README.md b/scripts/chapter_3_graphical_models/README.md new file mode 100644 index 0000000..0904bd7 --- /dev/null +++ b/scripts/chapter_3_graphical_models/README.md @@ -0,0 +1,19 @@ +In this chapter, we take you through how to compose and fit graphical models in **PyAutoFit**. Graphical models +simultaneously fit many datasets with a model that has 'local' parameters specific to each individual dataset +and 'global' parameters that fit for global trends across the whole dataset. + +**Colab** links to every tutorial are included. + +# Files + +The chapter contains the following tutorials: + +- [Tutorial 1: Individual Models](https://colab.research.google.com/github/PyAutoLabs/HowToFit/blob/2026.5.1.4/notebooks/chapter_3_graphical_models/tutorial_1_individual_models.ipynb) — Inferring global parameters from a dataset by fitting the model to each individual dataset one-by-one. + +- [Tutorial 2: Graphical Model](https://colab.research.google.com/github/PyAutoLabs/HowToFit/blob/2026.5.1.4/notebooks/chapter_3_graphical_models/tutorial_2_graphical_model.ipynb) — Fitting the dataset with a graphical model that fits all datasets simultaneously to infer the global parameters. + +- [Tutorial 3: Graphical Benefits](https://colab.research.google.com/github/PyAutoLabs/HowToFit/blob/2026.5.1.4/notebooks/chapter_3_graphical_models/tutorial_3_graphical_benefits.ipynb) — Illustrating the benefits of graphical modeling over fitting individual datasets one-by-one. + +- [Tutorial 4: Hierarchical Models](https://colab.research.google.com/github/PyAutoLabs/HowToFit/blob/2026.5.1.4/notebooks/chapter_3_graphical_models/tutorial_4_hierarchical_models.ipynb) — Fitting hierarchical models using the graphical modeling framework. + +- [Tutorial 5: Expectation Propagation](https://colab.research.google.com/github/PyAutoLabs/HowToFit/blob/2026.5.1.4/notebooks/chapter_3_graphical_models/tutorial_5_expectation_propagation.ipynb) — Scaling graphical models up to fit extremely large datasets using Expectation Propagation (EP). diff --git a/scripts/chapter_3_graphical_models/README.rst b/scripts/chapter_3_graphical_models/README.rst deleted file mode 100644 index b6c181a..0000000 --- a/scripts/chapter_3_graphical_models/README.rst +++ /dev/null @@ -1,25 +0,0 @@ -In this chapter, we take you through how to compose and fit graphical models in **PyAutoFit**. Graphical models -simultaneously fit many datasets with a model that has 'local' parameters specific to each individual dataset -and 'global' parameters that fit for global trends across the whole dataset. - -**Colab** links to every tutorial are included. - -Files ------ - -The chapter contains the following tutorials: - -`Tutorial 1: Individual Models `_ -- Inferring global parameters from a dataset by fitting the model to each individual dataset one-by-one. - -`Tutorial 2: Graphical Model `_ -- Fitting the dataset with a graphical model that fits all datasets simultaneously to infer the global parameters. - -`Tutorial 3: Graphical Benefits `_ -- Illustrating the benefits of graphical modeling over fitting individual datasets one-by-one. - -`Tutorial 4: Hierarchical Models `_ -- Fitting hierarchical models using the graphical modeling framework. - -`Tutorial 5: Expectation Propagation `_ -- Scaling graphical models up to fit extremely large datasets using Expectation Propagation (EP). \ No newline at end of file