Guide to Jupyter Book markdown

34. Guide to Jupyter Book markdown#

Here we give examples of how to do things in JB markdown.

34.1. *Marking a section in a different color#

Begin the highlighted section with <div class="highlight-section"> and end it with </div>. Add an asterisk before a title to indicate a section that can be skipped (use \* if you want the asterisk close to the title).

At present this puts the highlighted section in a box, which means additional margins on the left and right (including any title).

34.2. Frontmatter for markdown files#

At the top of any md file include:

---
jupytext:
  formats: md:myst
  text_representation:
    extension: .md
    format_name: myst
kernelspec:
  display_name: Python 3
  language: python
  name: python3
---

34.3. Labeling and referencing a section#

Down below we labeled the Macros section with

(sec:Macros)=
## Macros

Now we can reference that section as Macros using {ref}`sec:Macros` .

34.4. Admonitions#

Here we give examples of various admonitions that are pre-defined. You can either use three backticks ``` or colons ::: to delimit the admonitions (we use colons here to make it easy to use backticks for the code). If you have nested admonitions, add another backtick or colon to delimit outer layes (see the checkpoint questions example).

Note the :class: references that invoke particular styles (e.g., colors) and dropdowns.

Notes#

Note

Trivia: “Student” was the pen name of the Head Brewer at Guiness — a pioneer of small-sample experimental design (hence not necessarily Gaussian). His real name was William Sealy Gossett.

comes from

:::{note}
Trivia: "Student" was the pen name of the Head Brewer at Guiness --- a pioneer of small-sample experimental design (hence not necessarily Gaussian). His real name was William Sealy Gossett. 
:::

Warnings#

Warning

Although we alluded to the analogy between inserting a complete set of states and marginalization above this analogy breaks down in general. It’s ok to use this as a mnemonic though.

comes from

:::{warning}
Although we alluded to the analogy between inserting a complete set
of states and marginalization above this analogy breaks down in
general. It's ok to use this as a mnemonic though.
:::

Checkpoint questions#

Checkpoint question

What is the probability to find particle 1 at \(x_1\) while particle 2 is anywhere?

Answer

\(\int_{-\infty}^{+\infty} |\psi(x_1, x_2)|^2\, dx_2\ \ \) or, more generally, integrated over the domain of \(x_2\).

comes from

::::{admonition} Checkpoint question
:class: my-checkpoint
What is the probability to find particle 1 at $x_1$ while particle 2 is *anywhere*?
:::{admonition} Answer 
:class: dropdown, my-answer 
$\int_{-\infty}^{+\infty} |\psi(x_1, x_2)|^2\, dx_2\ \ $ or, more generally, integrated over the domain of $x_2$.
:::
::::

and to give a hint:

Checkpoint question

Construct your own example of \(\prob(x|y) \neq \prob(y|x)\)

Possible answers

The probability that there is a cloud in the sky given that it is raining is not the same as the probability that it’s raining given that there is a cloud in the sky.

comes from

::::{admonition} Checkpoint question
:class: my-checkpoint
Construct your own example of $\prob(x|y) \neq \prob(y|x)$
:::{admonition} Possible answers 
:class: dropdown, my-hint 
The probability that there is a cloud in the sky given that it is
raining is not the same as the probability that it's raining given
that there is a cloud in the sky. 
:::
::::

You can combine these examples to have a hint and an answer (just stack the internal admonitions).

Exercises and solutions#

Exercise 34.1

Derive Eq. (4.21) using the rules of probability calculus and inference.

and

come from

:::{exercise}
:label: exercise:ppd_definition_b
Derive Eq. {eq}`eq_ppd` using the rules of probability calculus and inference.
:::

and

::::{solution} exercise:ppd_definition_b
:label: solution:ppd_definition_b
:class: dropdown

*Hint:* see part of the solution to {ref}`exercise:coin_ppd`.

::::

Note the use of :label: exercise:ppd_definition_b that is referenced by the solution and also the reference to exercise:coin_ppd.

The tip class#

Parameter Estimation:

Premise: We have chosen a model (say \(M_1\))

\(\Rightarrow\) What can we say about its parameters \(\boldsymbol{\theta}_1\)?

from

:::{Admonition} Parameter Estimation:
  :class: tip
  Premise: We have chosen a model (say $M_1$)
  
  $\Rightarrow$ What can we say about its parameters $\boldsymbol{\theta}_1$?
:::

Remarks#

Remark 34.1 (Checklist for statistically sound Bayesian inference)

  1. Interact with the experts (i.e., statisticians, applied mathematicians).

  2. Incorporate all sources of experimental and theoretical errors.

  3. Formulate statistical models for uncertainties.

  4. Use as informative priors as is reasonable; test sensitivity to priors.

  5. Account for correlations in inputs (type x) and observables (type y).

  6. Propagate uncertainties through the calculation.

  7. Use model checking to validate our models.

comes from

:::{prf:remark} Checklist for statistically sound Bayesian inference
:label: remark:BayesianWorkflow:buqeye-checklist_b

1. Interact with the experts (i.e., statisticians, applied mathematicians).
2. Incorporate all sources of experimental and theoretical errors.
3. Formulate statistical models for uncertainties.
4. Use as informative priors as is reasonable; test sensitivity to priors.
5. Account for correlations in inputs (type x) and observables (type y).
6. Propagate uncertainties through the calculation.
7. Use model checking to validate our models.
:::

34.5. Hidden code cell#

Hide code cell content

 
# Common imports
import numpy as np
import matplotlib.pyplot as plt
import scipy.integrate as integrate

# Given information
H0=70
sigH=10
v0=10**5
sigv=5000

# grid for evaluating and plotting p(d|...)
dgrid = np.linspace(500,2500,100)

# Case 1
def pdf_1(d):
    return np.exp(-(v0-H0*d)**2/(2*sigv**2))
# Case 2
def pdf_2(H,d):
    return np.exp(-(H-H0)**2 / (2*sigH**2)) * np.exp(-(v0-H*d)**2 / (2*sigv**2))
# ... with numerical integration over H
pdf_2_grid = np.zeros_like(dgrid)
for i_d,di in enumerate(dgrid):
   I = integrate.quad(pdf_2, 0, 140, args=(di))
   pdf_2_grid[i_d] = I[0] / 20
# Case 3
def pdf_3(H,d):
    return np.exp(-(v0-H*d)**2 / (2*sigv**2))
# ... with numerical integration
pdf_3_grid = np.zeros_like(dgrid)
deltaH = np.sqrt(12*sigH**2/4)
for i_d,di in enumerate(dgrid):
   I = integrate.quad(pdf_3, H0-2*sigH, H0+2*sigH, args=(di))
   pdf_3_grid[i_d] = I[0] / 30
# Case 4 (see example 9.3)
d0 = v0/H0
sigd = d0*np.sqrt(sigH**2/H0**2 + sigv**2/v0**2)
def pdf_4(d):
    return np.exp(-(d-d0)**2 / (2*sigd**2)) / 2
    
fig,ax = plt.subplots(1,1)
ax.plot(dgrid,pdf_1(dgrid),label='Case 1')
ax.plot(dgrid,pdf_2_grid,label='Case 2')
ax.plot(dgrid,pdf_3_grid,label='Case 3')
ax.plot(dgrid,pdf_4(dgrid),label='Case 4')

ax.set_xlabel(r'$d$ [Mpc]')
ax.set_ylabel(r'$p(d|\mathcal{D},I)$')
ax.legend(loc='best');
../../_images/baa470161897e45b5583789f4be8b13859d79aec0bf41d1416eaa42c028b14ab.png

comes from

```{code-cell} python3
:tags: [hide-cell]

# Common imports
import numpy as np
import matplotlib.pyplot as plt
import scipy.integrate as integrate

# Given information
H0=70
sigH=10
v0=10**5
sigv=5000

# grid for evaluating and plotting p(d|...)
dgrid = np.linspace(500,2500,100)

# Case 1
def pdf_1(d):
    return np.exp(-(v0-H0*d)**2/(2*sigv**2))
# Case 2
def pdf_2(H,d):
    return np.exp(-(H-H0)**2 / (2*sigH**2)) * np.exp(-(v0-H*d)**2 / (2*sigv**2))
# ... with numerical integration over H
pdf_2_grid = np.zeros_like(dgrid)
for i_d,di in enumerate(dgrid):
   I = integrate.quad(pdf_2, 0, 140, args=(di))
   pdf_2_grid[i_d] = I[0] / 20
# Case 3
def pdf_3(H,d):
    return np.exp(-(v0-H*d)**2 / (2*sigv**2))
# ... with numerical integration
pdf_3_grid = np.zeros_like(dgrid)
deltaH = np.sqrt(12*sigH**2/4)
for i_d,di in enumerate(dgrid):
   I = integrate.quad(pdf_3, H0-2*sigH, H0+2*sigH, args=(di))
   pdf_3_grid[i_d] = I[0] / 30
# Case 4 (see example 9.3)
d0 = v0/H0
sigd = d0*np.sqrt(sigH**2/H0**2 + sigv**2/v0**2)
def pdf_4(d):
    return np.exp(-(d-d0)**2 / (2*sigd**2)) / 2
    
fig,ax = plt.subplots(1,1)
ax.plot(dgrid,pdf_1(dgrid),label='Case 1')
ax.plot(dgrid,pdf_2_grid,label='Case 2')
ax.plot(dgrid,pdf_3_grid,label='Case 3')
ax.plot(dgrid,pdf_4(dgrid),label='Case 4')

ax.set_xlabel(r'$d$ [Mpc]')
ax.set_ylabel(r'$p(d|\mathcal{D},I)$')
ax.legend(loc='best');
```

34.6. External URL references#

The general form is

[name in text](url)

For example, to point to Dick Furnstahl’s home page, use

[Dick Furnstahl](https://physics.osu.edu/people/furnstahl.1)

to get Dick Furnstahl.

34.7. Bibliography references#

BibTeX entries are stored in references.bib. Use the tags defined there for citations.

For example,

{cite}`gelman2013bayesian` Andrew Gelman et al., *"Bayesian Data Analysis, Third Edition"*, Chapman & Hall/CRC Texts in Statistical Science (2013).

will produce

[GCS+13] Andrew Gelman et al., “Bayesian Data Analysis, Third Edition”, Chapman & Hall/CRC Texts in Statistical Science (2013).

The link will take you to the bibliography. In normal usage you would just put the {cite} part, e.g., “Look in up in BDA3 [GCS+13].”

34.8. Equation references#

Here is a simple equation

(34.1)#\[ E = mc^2 \]

which was written as

$$
   E = mc^2
$$ (eq:JB_tests:Einstein_equation)

To cite this equation we use `{eq}eq:JB_tests:Einstein_equation` which gives (34.1).

What about an aligned equation? It seems we can only (easily) have one equation reference, and to get that we can surround \begin{align} and \end{align} with $$:

$$\begin{align}
   A &= B + C \\
   D &= E + F
\end{align}$$ (eq:JB_tests:align_test)

produces

(34.2)#\[\begin{split}\begin{align} A &= B + C \\ D &= E + F \end{align}\end{split}\]

Now we can refer to the equation: (34.2).

34.9. Macros#

LaTeX macros are defined in the _config.yml file in two formats, for use with html and pdf output. They can be entered by hand, but a better way to is to use the process_new_macros_for_config_file.py script (just type python process_new_macros_for_config_file.py at the command line), which reads in the macros.sty file as well as _config.yml and outputs a new _config.yml file. For safety this is done in the LaTeX_macros directory.

In macros.sty, the macros are defined as usual with newcommand or renewcommand statements. For example:

\newcommand{\prob}{\mathbb{P}}
\newcommand{\Lra}{\Longrightarrow}
\newcommand{\yth}{y_{\text{th}}}
\newcommand{\yexp}{y_{\text{exp}}}
\newcommand{\p}[1]{p \left( #1 \right)}

Note that you can have arguments as usual (e.g., the \p example). Even if the macro is text-only, it is only evaluated in LaTeX mode (e.g., like $\macro$).

Testing various definitions: $\prob$, $\yth \Lra \yexp$, $\p{A|B}$ become \(\prob\), \(\yth \Lra \yexp\), \(\p{A|B}\).

34.10. Inserting figures and references to them#

../../_images/2048px-Bayesian_research_cycle-mod.png

Fig. 34.1 Shortened caption here.#

from

:::{figure} ./figs/2048px-Bayesian_research_cycle-mod.png
:height: 600px
:name: fig-BayesianWorkflow-research-cycle_b

Shortened caption here.

:::

The convention is to have the figure files in a subdirectory called figs (that is, a subdirectory of the directory that has the markdown file). We can refer to this figure as Fig. 34.1 using {numref}`fig-BayesianWorkflow-research-cycle_b` and we get the appropriate hyperlink.

Contents