diff --git a/docs/api/plot.rst b/docs/api/plot.rst index 33219479..3fe971ef 100644 --- a/docs/api/plot.rst +++ b/docs/api/plot.rst @@ -83,7 +83,7 @@ visuals to figures. Matplot Lib Wrappers [aplt] --------------------------- -Wrappers for every ``matplotlib`` function used by a ``Plotter``, allowing for detailed customizaiton of +Wrappers for every ``matplotlib`` function used by a ``Plotter``, allowing for detailed customization of every figure and subplot. .. currentmodule:: autogalaxy.plot diff --git a/docs/overview/overview_2_new_user_guide.rst b/docs/overview/overview_2_new_user_guide.rst index 91614f82..8904e200 100644 --- a/docs/overview/overview_2_new_user_guide.rst +++ b/docs/overview/overview_2_new_user_guide.rst @@ -3,28 +3,241 @@ New User Guide ============== -1) Read the `autolens_workspace/start_here.ipynb` notebook if yo have not already. +**PyAutoGalaxy** is an extensive piece of software with functionality for doing many different analysis tasks, fitting +different data types and it is used for a variety of different science cases. This means the documentation is quite +extensive, and it may be difficult to find the example script you need. -2) Decide if you should take the HowToLens lectures. +This page provides a sequential guide for news users on how to begin learning **PyAutoGalaxy**, and can act as a useful +resource for existing users who are looking for how to do a specific task. -3) Config files and make sure default visualization settings are correct. +Before starting this guide, you should ensure you have installed **PyAutoGalaxy** and downloaded the ``autogalaxy_workspace`` +by following the `installation guide `_. -4) Determine if you are `imaging` / `interferometer` / `point_source` / `group`. +Contents +-------- -5) Quickly look at the API reference guides and unit convention guides, so you know to refer to them if you get stuck (`autolens_workspace/api`). +One line summaries of each step in the new user guide is given below, to give you a sense of what you are going to learn: -6) Learn how to simulate data (`autolens_workspace/start_here/simulators/start_here.ipynb`). +**1) Workspace:** Read the ``start_here.ipynb`` workspace example for a quick run through of the core API. +**2) HowToGalaxy?**: Whether you should begin with lectures aimed at inexperienced scientists (e.g. under graduate students). -7) Learn how to model data (`autolens_workspace/start_here/modeling/start_here.ipynb`). -8) Learn how to prepare data and model it (`autolens_workspace/start_here/data_preparation/start_here.ipynb`). +1) Workspace +------------ -9) Learn more about results (`autolens_workspace/start_here/results/start_here.ipynb`). +You should now have the ``autogalaxy_workspace`` on your computer and see many of the folder and files we'll begin +navigating. -10) Learn how to plot data (`autolens_workspace/start_here/plotting/start_here.ipynb`). +First of all, if you have not already, you should read the `autogalaxy_workspace/start_here.ipynb` notebook, +which provides a run through of the core API for galaxy morphology calculations and modeling. -11) Decide if you need to use any number of features in the `autolens_workspace/features` package. +GitHub Links: -12) Advanced stuff. +https://github.com/Jammy2211/autogalaxy_workspace/tree/release -13) Do science and cite correctly! \ No newline at end of file +2) HowToGalaxy? +------------- + +For experienced scientists, the **PyAutoGalaxy** examples will be simple to follow. Concepts surrounding galaxy morphology may +already be familiar and the statistical techniques used for fitting and modeling already understood. + +For those less familiar with these concepts (e.g. undergraduate students, new PhD students or interested members of the +public), things may have been less clear and a slower more detailed explanation of each concept would be beneficial. + +The **HowToGalaxy** Jupyter Notebook lectures provide exactly this. They are a 3+ chapter guide which thoroughly +take you through the core concepts of galaxy morphology, teach you the principles of the statistical techniques +used in modeling and ultimately will allow you to undertake scientific research like a professional astronomer. + +To complete thoroughly, they'll probably take 2-4 days, so you may want try moving ahead to the examples but can +go back to these lectures if you find them hard to follow. + +If this sounds like it suits you, checkout the ``autogalaxy_workspace/notebooks/HowToGalaxy`` package now. + +GitHub Links: + +https://github.com/Jammy2211/autogalaxy_workspace/tree/release/notebooks/HowToGalaxy + +3) Configs +---------- + +The ``autogalaxy_workspace/config`` folder contains numerous .YAML configuration files which customization many +default settings of **PyAutoGalaxy**. + +Documentation for all config settings are provided within each config file. + +New users should not worry about the majority of configs for now. However, the ``config/visualize`` folder contains +config files which customization ``matplotlib`` visualization, and editing these now will ensure figures and +images display optimally in your Jupyter Notebooks. + +All default ``matplotlib`` options are customized via the `mat_wrap.yaml`, `mat_wrap_1d.yaml` and `mat_wrap_2d.yaml` files +in `autogalaxy_workspace/config/visualize/mat_wrap`. For example, if figures display with labels that are too big +or small, you can adjust their default labelsizes by changing the following options: + + - mat_wrap.yaml -> Figure -> figure: -> figsize + - mat_wrap.yaml -> YLabel -> figure: -> fontsize + - mat_wrap.yaml -> XLabel -> figure: -> fontsize + - mat_wrap.yaml -> TickParams -> figure: -> labelsize + - mat_wrap.yaml -> YTicks -> figure: -> labelsize + - mat_wrap.yaml -> XTicks -> figure: -> labelsize + +The default colormap can be changed from the default to your favour ``matplotlib`` colormap, but adjusting: + + - mat_wrap.yaml -> Cmap -> figure -> cmap + +All settings have a ``figure`` and ``subplot`` option, so that single image ``figures`` and a subplot of multiple +figures can be customized independently. + +GitHub Links: + +https://github.com/Jammy2211/autogalaxy_workspace/tree/release/config +https://github.com/Jammy2211/autogalaxy_workspace/tree/release/config/visualize + +4) Dataset Type +--------------- + +**PyAutoGalaxy** supports multiple different data types, and you as a user likely only require to learn how to use +the software to analyse one type of dataset. + +Therefore, you now need to assess which dataset type is relevant to you: + +- **Imaging**: CCD imaging data (e.g. from the Hubble Space Telescope or James Webb Space Telescope), in which case +you will go to the ``imaging`` packages in the workspace. + +- **Interferometry**: Interferometer data from a submm or radio interferometer (e.g. ALMA or JVLA), in which case +you will go to the ``interferometer`` packages in the workspace. + +5) API and Units Guides +----------------------- + +The ``autogalaxy_workspace/guides`` package has many useful guides, including concise API reference guides (``guides/api``) +and unit conversion guides (``guides/units``). + +Quickly navigate to this part of the workspace and skim read the guides quickly. You do not need to understand them in detail now +so don't spend long reading them. + +The purpose of looking at them now is you know they exist and can refer to them if you get stuck using **PyAutoGalaxy**. + +GitHub Links: + +https://github.com/Jammy2211/autogalaxy_workspace/tree/release/notebooks/guides +https://github.com/Jammy2211/autogalaxy_workspace/tree/release/notebooks/guides/api +https://github.com/Jammy2211/autogalaxy_workspace/tree/release/notebooks/guides/units + +6) Simulations +-------------- + +Learning how to simulate your type of data is the best way to understanding how to analyse it. + +Therefore, in the ``autogalaxy_workspace/simulators`` folder, find the ``start_here.ipynb`` of your dataset. + +For example, if your dataset type is CCD imaging data, you'll read the notebook ``autogalaxy_workspace/simulators/imaging/start_here.ipynb``. + +Your **PyAutoGalaxy** use case might only require you to be able to simulate galaxies, for example if you are +training a neural network. In this case, you can stop the guide and use the tools in the ``simulators`` package +to start doing your science! + +GitHub Links: + +https://github.com/Jammy2211/autogalaxy_workspace/tree/release/notebooks/simulators + +7) Modeling +----------- + +Having simulated a dataset, you are now ready to learn how to model it. + +Therefore, in the ``autogalaxy_workspace/modeling`` folder, find the ``start_here.ipynb`` of your dataset. + +For example, if your dataset type is CCD imaging data, you'll read the notebook ``autogalaxy_workspace/modeling/imaging/start_here.ipynb``. + +Your **PyAutoGalaxy** use case might only require you to be able to model simulated galaxies, for example if you are +investigating what models can be used to learn about galaxy structure. In this case, you can skip the data preparation +step below and go straight to learning about results. + +GitHub Links: + +https://github.com/Jammy2211/autogalaxy_workspace/tree/release/notebooks/modeling + +8) Data Preparation +------------------- + +If you have real observations of galaxies you want to model, you need to prepare the data so that it +is appropriate for **PyAutoGalaxy**. + +This includes reducing the data so the galaxy is in the centre of the image, making sure all units +are defined correctly and reducing extra data products like the Point Spread Function for CCD imaging data. + +Therefore, in the ``autogalaxy_workspace/data_preparation`` folder, find the ``start_here.ipynb`` of your dataset. + +For example, if your dataset type is CCD imaging data, you'll read the notebook ``autogalaxy_workspace/data_preparation/imaging/start_here.ipynb``. + +GitHub Links: + +https://github.com/Jammy2211/autogalaxy_workspace/tree/release/notebooks/data_preparation + +9) Results +---------- + +Modeling infers many results, including parameter estimates, posteriors and a Bayesian evidence of the model. +Furthermore, you may wish to inspect the results, the quality of the fit and produce visuals to determine +if you think its a good fit. + +Therefore, now read the ``autogalaxy_workspace/*/results/start_here.ipynb`` notebook. + +GitHub Links: + +https://github.com/Jammy2211/autogalaxy_workspace/tree/release/notebooks/results + +10) Plotting +------------ + +**PyAutoGalaxy** has an in depth visualizaiton library that allows for high levels of customization via ``matplotlib``. + +Plotting has its own dedicated API, which you should become familiar with via the example ``autogalaxy_workspace/*/plot/start_here.ipynb``. + +GitHub Links: + +https://github.com/Jammy2211/autogalaxy_workspace/blob/main/notebooks/plot/start_here.ipynb + +11) Features +------------ + +You now have a comprehensive understanding of the **PyAutoGalaxy** API and how to use it to simulate, model and +plot your data. + +**PyAutoGalaxy** has many more features, which may or may not be useful for your science case. + +Example notebooks for every feature are provided in the ``autogalaxy_workspace/*/features`` package and a high-level +summary of each feature is provided on the next page of this readthedocs. + +What features you need depend on many factors: (i) your science case; (ii) the quality of your data; (iii) how +much time you are willing to invest in learning **PyAutoGalaxy**. We recommend you read the literature in conjunction +with assessing what features are available, and then make an informed decision on what is appropriate for you. + +GitHub Links: + +https://github.com/Jammy2211/autogalaxy_workspace/tree/release/notebooks/features + +12) Advanced +------------ + +The ``autogalaxy_workspace/*/advanced`` folder has numerous advanced examples which only a user experienced with +**PyAutoGalaxy** should use. + +These include examples of how to fit multiple datasets simultaneously (e.g. multi-wavelength CCD imaging datasets), +automated pipelines for modeling large galaxy samples (called the Source, Light and Mass (SLaM) pipelines in the +literature) and a step-by-step guide of the **PyAutoGalaxy** likelihood function. + +New users should ignore this folder for now, but note that you may find it has important functionality for +your science research in a couple of months time once you are experienced with **PyAutoGalaxy**! + +GitHub Links: + +https://github.com/Jammy2211/autogalaxy_workspace/tree/release/notebooks/advanced + +Wrap Up +------- + +After completing this guide, you should be able to use **PyAutoGalaxy** for your science research. + +The biggest decisions you'll need to make are what features and functionality your specific science case requires, +which the next readthedocs page gives an overview of to help you decide. \ No newline at end of file