Custom workflows
================
.. note::
We're constantly adding examples to this page, so please check back soon for more.
Or, if you have a request or a workflow you'd like to share, please either open an
issue or suggest an edit to this page by clicking the GitHub link at the top.
Default figure generation
-------------------------
.. raw:: html
By default, the workflow defined in the ``Snakefile`` looks like this:
.. code-block:: python
# User config
configfile: "showyourwork.yml"
# Import the showyourwork module
module showyourwork:
snakefile:
"showyourwork/workflow/Snakefile"
config:
config
# Use all default rules
use rule * from showyourwork
The default behavior in this workflow is to infer figure dependencies based on
the figure labels in the tex file.
The following block in ``ms.tex``
.. code-block:: latex
\begin{figure}
\begin{centering}
\includegraphics{figures/mandelbrot.pdf}
\caption{The Mandelbrot set.}
% This label tells showyourwork that the script `figures/mandelbrot.py'
% generates the PDF file included above
\label{fig:mandelbrot}
\end{centering}
\end{figure}
tells ``showyourwork`` to execute a script called ``mandelbrot.py`` in the ``src/figures``
directory to generated ``figures/mandelbrot.pdf``.
To change, supplement, or override this behavior, read on!
Multi-panel figures
-------------------
.. raw:: html
It is possible to include multiple figures within a ``figure`` environment, provided
they are all generated by the same script:
.. code-block:: latex
\begin{figure}[ht!]
\begin{centering}
\includegraphics[width=0.4\linewidth]{figures/koch1.pdf}
\includegraphics[width=0.4\linewidth]{figures/koch2.pdf}
\caption{
Two Koch snowflakes.
}
% This label tells showyourwork that the script `figures/koch.py'
% generates the two PDF files included above
\label{fig:koch}
\end{centering}
\end{figure}
If you would like to include figures generated from different scripts in the
same ``figure`` environment, you'll have to provide a custom rule (see below).
Static figures
--------------
.. raw:: html
It is also possible to commit the figure PDF/PNG/SVG/etc directly and tell ``showyourwork`` not to
try to produce it programmatically. Simply place the figure in the ``src/static`` directory:
.. code-block:: latex
\begin{figure}[ht!]
\begin{centering}
\includegraphics[width=0.4\linewidth]{static/broccoli.pdf}
\caption{
A photo of some broccoli.
}
% The fact that the figure is in the static directory tells
% showyourwork not to look for a script that generates this figure
\label{fig:broccoli}
\end{centering}
\end{figure}
Custom dependencies: datasets
-----------------------------
.. raw:: html
Download a dataset and make it a dependency of a particular figure:
.. code-block:: python
# Custom rule to download a dataset
rule my_dataset:
output:
report("src/figures/my_dataset.dat", category="Dataset")
shell:
"curl https://zenodo.org/record/5187276/files/fibonacci.dat --output {output[0]}"
Specify this dependency in the configuration file ``showyourwork.yml``:
.. code-block:: yaml
# Tell showyourwork that `src/figures/my_figure.py`
# requires the file `src/figures/my_dataset.dat` to run
figure_dependencies:
my_figure.py:
- my_dataset.dat
Custom dependencies: scripts
----------------------------
.. raw:: html
Sometimes we would like to tell ``showyourwork`` about script dependencies, such as
when our figure script imports something from a locally-hosted script or package.
We can do this in the same way as above by specifying a dependency in the configuration
file ``showyourwork.yml``:
.. code-block:: yaml
# Tell showyourwork that `src/figures/my_figure.py`
# depends on `src/figures/utils/helper_script.py`
figure_dependencies:
my_figure.py:
- utils/helper_script.py
Custom figure scripts
---------------------
.. raw:: html
Specify a custom script for a figure. Useful when ``showyourwork`` can't
automatically determine the figure script, such as when a figure is
included outside of a ``figure`` environment:
.. code-block:: python
# Subclass the `figure` rule to specify that the figure
# `src/figures/custom_figure.pdf` is generated from the script
# `src/figures/custom_script.py`
use rule figure from showyourwork as custom_figure with:
input:
"src/figures/custom_script.py",
"environment.yml"
output:
report("src/figures/custom_figure.pdf", category="Figure")
Override the internal ``figure`` rule completely:
.. code-block:: python
rule custom_figure:
input:
"src/figures/custom_script.py",
"environment.yml",
output:
report("src/figures/custom_figure.pdf", category="Figure")
conda:
"environment.yml"
shell:
"cd src/figures && python custom_script.py"