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

test status Repository Article PDF

By default, the workflow defined in the Snakefile looks like this:

# 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

\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

test status Repository Article PDF

It is possible to include multiple figures within a figure environment, provided they are all generated by the same script:

\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

test status Repository Article PDF

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:

\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

test status Repository Article PDF

Download a dataset and make it a dependency of a particular figure:

# 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:

# 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

test status Repository Article PDF

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:

# 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

test status Repository Article PDF

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:

# 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:

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"