Jupyter Book¶
Introducción¶
Jupyter Book es un proyecto de código abierto para crear libros y documentos mediante Jupyter Notebooks y/o Markdown.
Algunas características importantes del uso de Jupyter Book:
- contenido con calidad de publicación que incluya figuras, símbolos matemáticos, citas y referencias cruzadas!
- escribir contenido como Jupyter Notebooks, markdown o reStructuredText
- Agregue interactividad a su libro, por ejemplo, alternar la visibilidad de las celdas, conectarse con un servicio en línea como Binder e incluir resultados interactivos (por ejemplo, figuras y widgets).
- generar una variedad de resultados, incluidos sitios web (HTML, CSS, JS), markdown y PDF.
- una interfaz de línea de comandos para crear libros rápidamente, por ejemplo,
jupyter-book build mybook
En esta sesión, se muestra un ejemplo de cómo crear un Jupyter Book desde cero y algunas de las características clave que ofrece Jupyter Book.
Nota: Puede encontrar los códigos de este ejemplo en el siguiente repositorio. Por otro lado, puede revisar el siguente link para ver la compilación con GitLab CI/CD.
Crear una estructura de libro¶
Jupyter Book viene con una herramienta que le permite crear y construir libros rápidamente. Para crear el esqueleto del libro, escriba lo siguiente en la línea de comando:
jupyter-book create jupiter
Nota: Aquí llamamos al libro
jupiter, pero puedes elegir llamar a tu libro como quieras.
Ahora tendrás un nuevo directorio llamado jupiter (o como quieras llamar a tu libro), con el siguiente contenido:
jupiter
├── _config.yml
├── _toc.yml
├── content.md
├── intro.md
├── markdown.md
├── notebooks.ipynb
├── references.bib
└── requirements.txt
en donde:
_config.yml: archivo que contiene las configuraciones del proyecto._toc.yml: archivo que ordena los capítulos del libro.content.md: archivo genérico.md.intro.md: archivo genérico.md.markdown.md: archivo genérico.md.notebooks.ipynb: archivo genérico.ipynb.references.bib: archivo para añadir las referencias.requirements.txt: archivo que contiene las dependencias python) del proyecto.
Re-estructuración del directorio¶
Jupyter Book admite varios tipos de archivos:
- Markdown (.md)
- notebooks (.ipynb)
- etc.
Como Markdown y Jupyter Notebooks probablemente serán los tipos de archivo más comunes que usará, se mostrará un ejemplo de ello.
Lo primero será eliminar los archivos de inicio en el directorio:
- content.md
- intro.md
- markdown.md
- notebooks.ipynb
Así que ejecutamos por línea de comando:
rm content.md intro.md markdown.md notebooks.ipynb
Por otro lado, nuestro proyecto estaré conformado por tres archivos:
- index.md
- Introduction.md
- great_red_spot.ipynb
Luego, debemos indicar cómo serán mostrados estos documentos en el archivo _toc.yml. La estructura será la siguiente:
format: jb-book
root: index
chapters:
- file: Introduction
- file: great_red_spot
En este caso, root: index corresponde al primer archivo que se visualiza en el jupyter-book. Dentro del archivo index.md escribiremos:
# Home
jupyter book example
## Contenidos
```{tableofcontents}
```
Agregar un archivo Markdown¶
Se comienza por agregar un archivo de markdown. Con algún editor a elección (por ejemplo, jupyter notebook o jupyterlab) se crea un nuevo archivo markdown llamado Introduction.md.
Se usa este archivo como demostración de algunos de los principales tipos de contenido que puede agregar en Jupyter-Book.
Texto¶
Se agrega un texto de Markdown simple a nuestro archivo. Si no está familiarizado con la sintaxis de markdown, consulte Markdown Cheat Sheet. Puede copiar y pegar el siguiente contenido directamente en su archivo Introduction.md.
# Jupiter Book
This book contains information about the planet **Jupiter** - the fifth planet from the sun and the largest planet in the solar system!
Figuras¶
Puedes incluir figuras en tu Jupyter Book usando la siguiente sintaxis:
```{figure} my_image.png
---
height: 150px
name: my-image
---
Here is my image's caption!
```
Si bien la imagen puede estar contenida y referenciada desde el directorio raíz, también se puede incluir imágenes a través de URL. Incluyamos una imagen del planeta Júpiter en nuestro archivo Introduction.md usando lo siguiente:
```{figure} https://solarsystem.nasa.gov/system/resources/detail_files/2486_stsci-h-p1936a_1800.jpg
---
height: 300px
name: jupiter-figure
---
The beautiful planet Jupiter!
```
La razón por la que le damos un "nombre" a nuestra imagen es para que podamos hacer referencia a ella fácilmente con la sintaxis:
{numref}`jupiter-figure`
Se agregará una oración que incluya esta referencia. El archivo completo ahora debería verse así:
# Jupiter Book
This book contains information about the planet Jupiter - the fifth planet from the sun and the largest planet in the solar system! {numref}`jupiter-figure` below shows an image of Jupiter captured by the Hubble Space Telescope on June 27, 2019.
```{figure} https://solarsystem.nasa.gov/system/resources/detail_files/2486_stsci-h-p1936a_1800.jpg
---
height: 300px
name: jupiter-figure
---
The beautiful planet Jupiter! Source: [NASA](https://solarsystem.nasa.gov/resources/2486/hubbles-new-portrait-of-jupiter/?category=planets_jupiter).
```
En este punto, probablemente se debería crear nuetro libro para asegurarnos de que tenga el aspecto esperado. Para hacer eso, primero necesitamos modificar nuestro archivo _toc.yml. Este archivo contiene la tabla de contenido de nuestro libro. Abra ese archivo ahora y elimine todo lo que hay allí. Luego, simplemente agregue lo siguiente:
- file: introduction
Ahora podemos construir nuestro libro desde la línea de comandos asegurándonos de que estamos en el directorio raíz de nuestro libro y luego usando:
jupyter-book build .
Una vez finalizada la compilación, tendrá un nuevo subdirectorio llamado_build/html/ en la raíz de su libro, navegue hasta esa ubicación y abra _build/html/index.html. Debería verse algo como esto:
Equaciones matemáticas¶
Jupyter Book usa MathJax para componer matemáticas, lo que le permite agregar matemáticas de estilo LaTeX a su libro. Puede agregar matemáticas en línea, bloques matemáticos y ecuaciones numeradas a su libro Jupyter. Sigamos adelante y creemos un nuevo encabezado en nuestro archivo Introduction.md que incluye algunas matemáticas.
Las matemáticas en línea se pueden definir usando $ de la siguiente manera:
Jupiter has a mass of: $m_{j} \approx 1.9 \times 10^{27} kg$
Jupiter has a mass of: $m_{j} \approx 1.9 \times 10^{27} kg$
Los bloques matemáticos se pueden definir usando la notación $$:
$$m_{j} \approx 1.9 \times 10^{27} kg$$
$$m_{j} \approx 1.9 \times 10^{27} kg$$
Nota: Si lo prefiere, los bloques matemáticos también se pueden definir con
\begin{equation}en lugar de$$.
Las ecuaciones numeradas se pueden definir así (este es el estilo que te recomiendo que uses con más frecuencia):
```{math}
:label: my_label
m_{j} \approx 1.9 \times 10^{27} kg
```
Agreguemos más contenido a nuestro libro. Copie y agregue el siguiente texto a su archivo Introduction.md:
## The Mass of Jupiter
We can estimate the mass of Jupiter from the period and size of an object orbiting it. For example, we can use Jupiter's moon Callisto to estimate it's mass.
Callisto's period: $p_{c}=16.7 days$
Callisto's orbit radius: $r_{c}=1,900,000 km$
Now, using [Kepler's Law](https://solarsystem.nasa.gov/resources/310/orbits-and-keplers-laws/) we can work out the mass of Jupiter.
```{math}
:label: eq1
m_{j} \approx \frac{r_{c}}{p_{c}} \times 7.9 \times 10^{10}
```
```{math}
:label: eq2
m_{j} \approx 1.9 \times 10^{27} kg
```
A continuación, puede reconstruir su libro (jupyter-book build .) y abrir _build/html/index.html para asegurarse de que todo se esté procesando como se esperaba.
Controlando el diseño de la página¶
Hay varias formas diferentes de controlar el diseño de las páginas de su Jupyter Book. El cambio de diseño que utilizo con más frecuencia es agregar contenido a un margen en la página. Puede agregar un margen usando la siguiente directiva:
```{margin} An optional title
Some margin content.
```
Agreguemos algo de contenido marginal al libro:
```{margin} Did you know?
Jupiter is 11.0x larger than Earth!
```
Advertencias¶
Hay todo tipo de advertencias diferentes que puede usar en Jupyter Book que se enumeran aquí en la documentación de Jupyter Book. Las advertencias se crean con la sintaxis:
```{note}
I am a useful note!
```
No dude en agregar la siguiente advertencia a Introduction.md:
```{hint}
NASA provides a lot more information about the physical characteristics of Jupiter [here](https://solarsystem.nasa.gov/planets/jupiter/by-the-numbers/).
```
Citas y bibliografía¶
El último contenido corresponde a referencias y una bibliografía. Puede agregar citas de cualquier trabajo almacenado en el archivo Bibtex Reference.bib que se encuentra en el directorio raíz de su libro.
Para incluir una cita en su libro, agregue una entrada bibtex a references.bib, por ejemplo:
@article{mayor1995jupiter,
title={A Jupiter-mass companion to a solar-type star},
author={Mayor, Michel and Queloz, Didier},
journal={Nature},
volume={378},
number={6555},
pages={355--359},
year={1995},
publisher={Nature Publishing Group}
}
@article{guillot1999interiors,
title={Interiors of giant planets inside and outside the solar system},
author={Guillot, Tristan},
journal={Science},
volume={286},
number={5437},
pages={72--77},
year={1999},
publisher={American Association for the Advancement of Science}
}
Nota: Consulte la documentación de BibTex para obtener información sobre el estilo de referencia de BibTex. Google Scholar facilita la exportación de un formato de cita bibtex.
A continuación, puede hacer referencia al trabajo en su libro utilizando la siguiente directiva:
{cite}`mayor1995jupiter`
O para múltiples citas:
{cite}`mayor1995jupiter,guillot1999interiors`
Luego puede crear una bibliografía a partir de reference.bib usando:
```{bibliography} references.bib
```
Por ejemplo, intente agregar esto a su archivo Introduction.md:
There might even be more planets out there with a similar mass to Jupiter {cite}`mayor1995jupiter,guillot1999interiors`!
## Bibliography
```{bibliography} references.bib
```
Su archivo final Introduction.md debería verse así:
# Jupiter Book
This book contains information about the planet Jupiter - the fifth planet from the sun and the largest planet in the solar system! {numref}`jupiter-figure` below shows an image of Jupiter captured by the Hubble Space Telescope on June 27, 2019.
```{figure} https://solarsystem.nasa.gov/system/resources/detail_files/2486_stsci-h-p1936a_1800.jpg
---
height: 300px
name: jupiter-figure
---
The beautiful planet Jupiter! Source: [NASA](https://solarsystem.nasa.gov/resources/2486/hubbles-new-portrait-of-jupiter/?category=planets_jupiter).
```
## The Mass of Jupiter
We can estimate the mass of Jupiter from the period and size of an object orbiting it. For example, we can use Jupiter's moon Callisto to estimate it's mass.
Callisto's period: $p_{c}=16.7 days$
Callisto's orbit radius: $r_{c}=1,900,000 km$
Now, using [Kepler's Law](https://solarsystem.nasa.gov/resources/310/orbits-and-keplers-laws/) we can work out the mass of Jupiter.
```{math}
:label: eq1
m_{j} \approx \frac{r_{c}}{p_{c}} \times 7.9 \times 10^{10}
```
```{math}
:label: eq2
m_{j} \approx 1.9 \times 10^{27} kg
```
```{margin} Did you know?
Jupiter is 11.0x larger than Earth!
```
```{hint}
NASA provides a lot more information about the physical characteristics of Jupiter [here](https://solarsystem.nasa.gov/planets/jupiter/by-the-numbers/).
```
There might even be more planets out there with a similar mass to Jupiter {cite}`mayor1995jupiter,guillot1999interiors`!
## Bibliography
```{bibliography} references.bib
```
Y debería renderizarse así:
Agregar un archivo de contenido de Jupyter Notebook¶
Todos los flujos de trabajo de formato y estilo que vimos en markdown también se aplican a un Jupyter Notebook; simplemente agréguelos a una celda de markdown y listo.
Comencemos con lo siguiente:
- Cree un nuevo notebook llamado
great_red_spot.ipynb; - Agregue este archivo a su
_toc.yml; - Agregue una celda de markdown con el siguiente contenido:
# The Great Red Spot
Jupiter’s iconic Great Red Spot (GRS) is actually an enormous storm that is bigger than Earth that has raged for hundreds of years! {numref}`great-red-spot` below shows an image of Jupiter captured by the Hubble Space Telescope on June 27, 2019.
```{figure} https://solarsystem.nasa.gov/system/resources/detail_files/626_PIA21775.jpg
---
height: 300px
name: great-red-spot
---
Jupiter's Great Red Spot! Source: [NASA](https://solarsystem.nasa.gov/resources/626/jupiters-great-red-spot-in-true-color/?category=planets_jupiter).
```
Jupiter's GRS has been observed to be shrinking for about the last century and a half! [Here](https://github.com/UBC-DSCI/jupyterdays/tree/master/jupyterdays/sessions/beuzen/data) is some data of the length of the GRS spanning the last ~150 years which we can use to investigate this phenomenon.
¡Ahora intente construir su libro (jupyter-book build .) para asegurarse de que todo se vea bien! Usando la barra de contenido del lado izquierdo, navegue a la nueva página “The Great Red Spot”, que debería verse así:
¡Ok genial! Ahora importemos los datos a los que hicimos referencia para que podamos crear algunos gráficos.
Cree una nueva celda de código debajo de la celda de rebaja actual y agregue el siguiente código para leer en nuestro conjunto de datos de GRS como un marco de datos de Pandas.
import pandas as pd
pd.options.plotting.backend = "plotly"
url = "https://raw.githubusercontent.com/UBC-DSCI/jupyterdays/master/jupyterdays/sessions/beuzen/data/GRS_data.csv"
df = pd.read_csv(url)
df['Year'] = df['Year'].astype(int)
df.head()
Nota: Estamos imprimiendo la salida en la pantalla con el uso de
df.head()y esto se mostrará en nuestro Jupyter Book renderizado.
Si reconstruye su libro (jupyter-book build .) en este punto, verá algo como lo siguiente:
Ahora, podemos usar estos datos para crear algunos gráficos.
Las tramas en su Jupyter Book pueden ser estáticas (por ejemplo, matplotlib, seaborn) o interactivas (por ejemplo, altair, plotly, bokeh).
Para este tutorial, crearemos algunos gráficos de ejemplo usando Plotly (a través del backend de Pandas).
Primero creemos un diagrama de dispersión simple de nuestros datos. Cree una nueva celda de código en su cuaderno y agregue el siguiente código:
import plotly.io as pio
pio.renderers.default = "notebook"
fig = df.plot.scatter(x="Year", y="GRS Length", color="Recorder",
range_x=[1870, 2030], range_y=[10, 40],
width=650, height=400)
fig.update_layout(title={'text': "Great Red Spot Size", 'x':0.5, 'y':0.92})
fig.update_traces(marker=dict(size=7))
Ya que estamos en eso, creemos también una trama animada. Cree otra celda de código nueva y agregue el siguiente código:
fig = df.plot.scatter(x="Year", y="GRS Length",
animation_frame="Year",
range_x=[1870, 2030], range_y=[10, 40],
width=600, height=520)
fig.update_layout(title={'text': "Great Red Spot Size Animation", 'x':0.5, 'y':0.94})
fig.layout.updatemenus[0].buttons[0].args[1]["frame"]["duration"] = 200
fig.update_traces(marker=dict(size=10))
Nota: Plotly tiene diferentes renderizadores disponibles para generar gráficos. Es posible que deba experimentar con renderizadores para obtener el resultado que desea en su Jupyter Book. He descubierto que
pio.renderers.default = "notebook"funciona con la versión actual de Jupyter Book.
¡Ahora, reconstruyamos nuestro libro y echemos un vistazo!
Es posible que desee ocultar parte del código en su libro, ¡no hay problema! Eso también se hace fácilmente con Jupyter Book.
El que nos interesa aquí es ocultar la entrada de código. Podemos hacerlo fácilmente agregando la etiqueta hide-input a la celda que deseamos ocultar. Hay varias formas de agregar etiquetas a la celda en Jupyter Notebooks. En Jupyter Lab, haga clic en el icono de engranaje en la barra lateral izquierda y luego agregue la etiqueta deseada como se muestra a continuación:
Continúe y agregue las etiquetas hide-input a ambas celdas de trazado en su archivo great_red_spot.ipynb. Cuando reconstruyas el libro, verás que la entrada del código está oculta (pero se puede alternar con el ícono +):
Nota: También puede almacenar el contenido de la libreta como valores, gráficos o marcos de datos en variables que se pueden utilizar en toda su libreta mediante la herramienta
glue.