Skip to content

refactor: merge adjacent docstring blocks so tutorial sections render as one cell #104

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Jammy2211 merged 1 commit into from
Nov 4, 2026
Merged

refactor: merge adjacent docstring blocks so tutorial sections render as one cell #104

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 4 additions & 14 deletions notebooks/chapter_1_introduction/tutorial_0_visualization.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -273,13 +273,8 @@
"`subplot_shape_to_figsize_factor` controls subplot sizes. The per-call options above are enough for this lesson.\n",
"\n",
"**\ud83e\udd16 Ask AI:** Why can logarithmic colour scaling make faint structure easier to see without increasing its\n",
"signal-to-noise ratio?"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"signal-to-noise ratio?\n",
"\n",
"__Visuals__\n",
"\n",
"A mask selects which pixels to use. Here an annular mask keeps a ring between 0.3 and 3.0 arcseconds from\n",
Expand Down Expand Up @@ -312,13 +307,8 @@
"metadata": {},
"source": [
"Compare the masked plot with the original image: the central light is excluded from this view, not removed\n",
"from the original dataset. We keep the masked version in `masked_dataset` so `dataset` remains available."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"from the original dataset. We keep the masked version in `masked_dataset` so `dataset` remains available.\n",
"\n",
"__Wrap Up__\n",
"\n",
"You have plotted an image, compared dataset panels and changed the display without changing the pixel values.\n",
Expand Down
185 changes: 60 additions & 125 deletions notebooks/chapter_3_pixelizations/tutorial_3_fit_problems.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,51 +22,8 @@
"- Why the mesh becomes a limitation\n",
"- Why one regularization coefficient becomes a compromise\n",
"- Why maximizing the evidence does not remove the compromise\n",
"- Wrap Up"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"__Google Colab Setup__\n",
"\n",
"Set up Google Colab as in [the introductory notebook](https://github.com/PyAutoLabs/HowToGalaxy/blob/main/notebooks/chapter_1_introduction/tutorial_1_grids_and_galaxies.ipynb).\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"cellView": "form",
"jupyter": {
"source_hidden": true
}
},
"outputs": [],
"source": [
"# @title Set up Google Colab { display-mode: \"form\" }\n",
"try:\n",
" import google.colab\n",
"except ImportError:\n",
" from autogalaxy import setup_colab as _setup_colab\n",
"else:\n",
" import importlib\n",
" import subprocess\n",
" import sys\n",
"\n",
" subprocess.check_call(\n",
" [sys.executable, \"-m\", \"pip\", \"install\", \"autonerves\", \"--no-deps\"]\n",
" )\n",
" _setup_colab = importlib.import_module(\"autonerves.setup_colab\")\n",
"- Wrap Up\n",
"\n",
"_setup_colab.setup(\"howtogalaxy\")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"__When the best coefficient is not enough__\n",
"\n",
"We have learned how to reconstruct a galaxy and choose its regularization coefficient using Bayesian evidence.\n",
Expand Down Expand Up @@ -98,18 +55,51 @@
"- Separating the limitations of mesh resolution and constant regularization.\n",
"- Motivating adaptation to the galaxy\u2019s brightness distribution.\n",
"\n",
"---"
"---\n",
"\n",
"__Three progressively compact galaxies__\n",
"\n",
"We use three S\u00e9rsic profiles with the same centre and elliptical shape.\n",
"\n",
"For the first, we choose a relatively large effective radius and a S\u00e9rsic index of `1.0`. For the next two, we decrease the effective radius and increase the S\u00e9rsic index. Their light becomes more concentrated, with a steeper brightness gradient near the centre."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"__Three progressively compact galaxies__\n",
"__Google Colab Setup__\n",
"\n",
"We use three S\u00e9rsic profiles with the same centre and elliptical shape.\n",
"Set up Google Colab as in [the introductory notebook](https://github.com/PyAutoLabs/HowToGalaxy/blob/main/notebooks/chapter_1_introduction/tutorial_1_grids_and_galaxies.ipynb).\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"cellView": "form",
"jupyter": {
"source_hidden": true
}
},
"outputs": [],
"source": [
"# @title Set up Google Colab { display-mode: \"form\" }\n",
"try:\n",
" import google.colab\n",
"except ImportError:\n",
" from autogalaxy import setup_colab as _setup_colab\n",
"else:\n",
" import importlib\n",
" import subprocess\n",
" import sys\n",
"\n",
"For the first, we choose a relatively large effective radius and a S\u00e9rsic index of `1.0`. For the next two, we decrease the effective radius and increase the S\u00e9rsic index. Their light becomes more concentrated, with a steeper brightness gradient near the centre."
" subprocess.check_call(\n",
" [sys.executable, \"-m\", \"pip\", \"install\", \"autonerves\", \"--no-deps\"]\n",
" )\n",
" _setup_colab = importlib.import_module(\"autonerves.setup_colab\")\n",
"\n",
"_setup_colab.setup(\"howtogalaxy\")"
]
},
{
Expand Down Expand Up @@ -175,13 +165,8 @@
"source": [
"There is no lensing transformation. All three images use the same sky coordinates, while the spatial resolution needed to describe their light changes.\n",
"\n",
"---"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"---\n",
"\n",
"__Simulating the images__\n",
"\n",
"We now simulate the three galaxy images using the same image grid and telescope blurring.\n",
Expand Down Expand Up @@ -299,13 +284,8 @@
"\n",
"Next, we will reconstruct them using the same rectangular mesh and constant regularization scheme. For each dataset, we will scan the coefficient and inspect its evidence-preferred reconstruction.\n",
"\n",
"We will compare alternative reconstructions **within each dataset**. We will not rank the three different simulated galaxies against one another using their absolute evidence values."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We will compare alternative reconstructions **within each dataset**. We will not rank the three different simulated galaxies against one another using their absolute evidence values.\n",
"\n",
"__Reconstructing the galaxies__\n",
"\n",
"We will reconstruct all three galaxies using a `25 \u00d7 25` rectangular mesh and `Constant` regularization.\n",
Expand Down Expand Up @@ -354,13 +334,8 @@
"\n",
"For now, the only reconstruction setting we vary is the regularization coefficient.\n",
"\n",
"---"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"---\n",
"\n",
"__Finding the preferred regularization__\n",
"\n",
"As in tutorial 2, we evaluate a range of coefficients and compare their log evidences. We do this separately for each dataset: a coefficient suitable for the extended galaxy need not be suitable for either compact galaxy.\n",
Expand Down Expand Up @@ -454,13 +429,8 @@
"\n",
"We can now inspect the reconstructions knowing that we have selected their smoothing strengths systematically.\n",
"\n",
"---"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"---\n",
"\n",
"__Starting with the extended galaxy__\n",
"\n",
"Let\u2019s begin with the extended galaxy.\n",
Expand Down Expand Up @@ -531,13 +501,8 @@
"source": [
"A value around one is a useful reference for noise-level residuals, but it does not tell us whether those residuals form a spatial pattern. Keep the residual map alongside this number.\n",
"\n",
"This extended-galaxy fit provides our baseline. Next, we will make the galaxy more compact without giving the mesh any additional resolution, and examine where the reconstruction begins to struggle."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"This extended-galaxy fit provides our baseline. Next, we will make the galaxy more compact without giving the mesh any additional resolution, and examine where the reconstruction begins to struggle.\n",
"\n",
"__Making the galaxy more compact__\n",
"\n",
"Now inspect the compact galaxy.\n",
Expand Down Expand Up @@ -606,13 +571,8 @@
"\n",
"The question is therefore no longer simply \u201cHave we chosen the wrong coefficient?\u201d We need to ask whether our mesh and regularization scheme can represent this galaxy adequately.\n",
"\n",
"---"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"---\n",
"\n",
"__A very compact galaxy__\n",
"\n",
"Our final galaxy has an effective radius of just `0.1` arcsec and a S\u00e9rsic index of `4.0`. Its light rises steeply towards the centre, placing a greater demand on the reconstruction.\n",
Expand Down Expand Up @@ -689,13 +649,8 @@
"\n",
"These galaxies also have different brightness distributions and signal-to-noise ratios. We should not interpret the comparison as a measurement of galaxy-size effects alone. Its purpose is to expose the practical difficulty of reconstructing increasingly concentrated light with an unchanged mesh and one smoothing coefficient.\n",
"\n",
"---"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"---\n",
"\n",
"__Why the mesh becomes a limitation__\n",
"\n",
"Let\u2019s examine the first problem: where our galaxy pixels are placed.\n",
Expand Down Expand Up @@ -748,13 +703,8 @@
"\n",
"This motivates adapting the mesh to the **galaxy\u2019s brightness distribution**, which we will explore in the next tutorial.\n",
"\n",
"First, there is a second limitation to understand. Even with enough mesh points, should we apply the same regularization coefficient to the bright centre and faint outskirts?"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"First, there is a second limitation to understand. Even with enough mesh points, should we apply the same regularization coefficient to the bright centre and faint outskirts?\n",
"\n",
"__Why one regularization coefficient becomes a compromise__\n",
"\n",
"Suppose we had enough mesh points to resolve the galaxy\u2019s bright centre. Would that solve the problem?\n",
Expand Down Expand Up @@ -838,13 +788,8 @@
"\n",
"These changes need not be equally visible in every dataset. The important point is that changing one coefficient changes the smoothing preference everywhere, even though different galaxy regions may benefit from different strengths.\n",
"\n",
"---"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"---\n",
"\n",
"__Why maximizing the evidence does not remove the compromise__\n",
"\n",
"Why does the Bayesian evidence not simply select a coefficient that fixes both regions?\n",
Expand Down Expand Up @@ -894,13 +839,8 @@
"\n",
"The evidence still decides whether that additional flexibility is useful. We compare the constant and adaptive schemes on the same dataset, allowing their parameters to vary appropriately. Adaptation is a way to improve the available reconstructions, rather than a guarantee that every fit will improve.\n",
"\n",
"---"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"---\n",
"\n",
"__Wrap Up__\n",
"\n",
"We began with three galaxies whose light became progressively more concentrated, while keeping the image sampling, PSF and noise realization fixed.\n",
Expand All @@ -922,13 +862,8 @@
"\n",
"At each stage, we will return to the questions raised here: does the mesh resolve the galaxy\u2019s bright structure, and does regularization preserve that structure while controlling fluctuations elsewhere?\n",
"\n",
"Tutorial 5 then returns to search chaining and combines an MGE with a pixelization. That alternative can let analytic profiles describe the smooth central light while a mesh supplies additional spatial freedom."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Tutorial 5 then returns to search chaining and combines an MGE with a pixelization. That alternative can let analytic profiles describe the smooth central light while a mesh supplies additional spatial freedom.\n",
"\n",
"**\ud83e\udd16 Ask AI:** How would you distinguish insufficient galaxy-mesh resolution from over-smoothing when compact-galaxy residuals remain at the evidence-preferred coefficient?"
]
}
Expand Down
Loading
Loading