Popularity
2.7
Growing
Activity
9.0
Declining
4
1
0

Monthly Downloads: 132
Programming language: Haskell
License: GNU General Public License v2.0 only
Tags: Documentation     Pandoc
Latest version: v0.2.1.0

## pandoc-plot alternatives and similar packages

Based on the "pandoc" category

• ### pandoc-pyplot

A Pandoc filter to include figures generated from Python code blocks
• ### pandoc-emphasize-code

A Pandoc filter for emphasizing code in fenced blocks
• ### pandoc-markdown-ghci-filter

Pandoc-filter to evaluate code section in markdown and auto-embed output.

Do you think we are missing an alternative of pandoc-plot or a related project?

## A Pandoc filter to generate figures from code blocks in documents

pandoc-plot turns code blocks present in your documents (Markdown, LaTeX, etc.) into embedded figures, using your plotting toolkit of choice, including Matplotlib, ggplot2, MATLAB, Mathematica, and more.

## Usage

This program is a Pandoc filter. It operates on the Pandoc abstract syntax tree, and can therefore be used in the middle of conversion from input format to output format.

The filter recognizes code blocks with classes that match plotting toolkits. For example, using the matplotlib toolkit:

# My document

This is a paragraph.

{.matplotlib}
import matplotlib.pyplot as plt

plt.figure()
plt.plot([0,1,2,3,4], [1,2,3,4,5])
plt.title('This is an example figure')


Putting the above in input.md, we can then generate the plot and embed it in an HTML page:

bash
pandoc --filter pandoc-plot input.md --output output.html


Note that pandoc-plot only works with pandoc >= 2.8 because of some breaking changes in pandoc's API.

## Supported toolkits

pandoc-plot currently supports the following plotting toolkits (installed separately):

• matplotlib: plots using the matplotlib Python library;
• plotly_python : plots using the plotly Python library;
• matlabplot: plots using MATLAB;
• mathplot : plots using Mathematica;
• octaveplot: plots using GNU Octave;
• ggplot2: plots using ggplot2;
• gnuplot: plots using gnuplot;

To know which toolkits are useable on your machine (and which ones are not available), you can check with the --toolkits/-t flag:

pandoc-plot --toolkits


Wish your plotting toolkit of choice was available? Please raise an issue!

## Features

### Captions

You can also specify a caption for your image. This is done using the optional caption parameter.

Markdown:

{.matlabplot caption="This is a simple figure with a **Markdown** caption"}
x  = 0: .1 : 2*pi;
y1 = cos(x);
y2 = sin(x);

figure
plot(x, y1, 'b', x, y2, 'r-.', 'LineWidth', 2)


__LaTex__:

latex
\begin{minted}[caption=This is a simple figure with a \LaTeX caption]{matlabplot}
x  = 0: .1 : 2*pi;
y1 = cos(x);
y2 = sin(x);

figure
plot(x, y1, 'b', x, y2, 'r-.', 'LineWidth', 2)
\end{minted}


Caption formatting should match the document formatting.

In case of an output format that supports links (e.g. HTML), the embedded image generated by pandoc-plot can show a link to the source code which was used to generate the file. Therefore, other people can see what code was used to create your figures.

You can turn this off via the source=true key:

Markdown:

{.mathplot source=true}
...


__LaTex__:

latex
\begin{minted}[source=true]{mathplot}
...
\end{minted}


or via a configuration file.

### Preamble scripts

If you find yourself always repeating some steps, inclusion of scripts is possible using the preamble parameter. For example, if you want all Matplotlib plots to have the ggplot style, you can write a very short preamble style.py like so:

import matplotlib.pyplot as plt
plt.style.use('ggplot')


and include it in your document as follows:

{.matplotlib preamble=style.py}
plt.figure()
plt.plot([0,1,2,3,4], [1,2,3,4,5])
plt.title('This is an example figure')


Which is equivalent to writing the following markdown:

~~~markdown
{.matplotlib}
import matplotlib.pyplot as plt
plt.style.use('ggplot')

plt.figure()
plt.plot([0,1,2,3,4], [1,2,3,4,5])
plt.title('This is an example figure')


The equivalent LaTeX usage is as follows:

latex
\begin{minted}[include=style.py]{matplotlib}

\end{minted}


This preamble parameter is perfect for longer documents with many plots. Simply define the style you want in a separate script! You can also import packages this way, or define functions you often use.

### No wasted work

pandoc-plot minimizes work, only generating figures if it absolutely must, i.e. if the content has changed. Therefore, you can confidently run the filter on very large documents containing dozens of figures --- like a book or a thesis --- and only the figures which have changed will be re-generated.

### Compatibility with pandoc-crossref

pandoc-crossref is a pandoc filter that makes it effortless to cross-reference objects in Markdown documents.

You can use pandoc-crossref in conjunction with pandoc-plot for the ultimate figure-making pipeline. You can combine both in a figure like so:

{#fig:myexample .plotly_python caption="This is a caption"}
# Insert figure script here


As you can see in @fig:myexample, ...


If the above source is located in file myfile.md, you can render the figure and references by applying pandoc-plot **first**, and then pandoc-crossref. For example:

bash
pandoc --filter pandoc-plot --filter pandoc-crossref -i myfile.md -o myfile.html


## Configuration

To avoid repetition, pandoc-plot can be configured using simple YAML files. pandoc-plot will look for a .pandoc-plot.yml file in the current working directory. Here are all the possible parameters:

# The following parameters affect all toolkits
directory: plots/
source: false
dpi: 80
format: PNG
python_interpreter: python

# The possible parameters for the Matplotlib toolkit
matplotlib:
preamble: matplotlib.py
tight_bbox: false
transparent: false
executable: python

# The possible parameters for the MATLAB toolkit
matlabplot:
preamble: matlab.m
executable: matlab

# The possible parameters for the Plotly/Python toolkit
plotly_python:
preamble: plotly-python.py
executable: python

# The possible parameters for the Mathematica toolkit
mathplot:
preamble: mathematica.m
executable: math

# The possible parameters for the GNU Octave toolkit
octaveplot:
preamble: octave.m
executable: octave

# The possible parameters for the ggplot2 toolkit
ggplot2:
preamble: ggplot2.r
executable: Rscript

# The possible parameters for the gnuplot toolkit
gnuplot:
preamble: gnuplot.gp
executable: gnuplot



A file like the above sets the default values; you can still override them in documents directly.

Using pandoc-plot --write-example-config will write the default configuration to a file which you can then customize.

### Executables

The executable parameter for all toolkits can be either the executable name (if it is present on the PATH), or the full path to the executable.

Examples:

matplotlib:
executable: python3

matlabplot:
executable: "C:\Program Files\Matlab\R2019b\bin\matlab.exe"


### Toolkit-specific options

#### Matplotlib

• tight_bbox is a boolean that determines whether to use bbox_inches="tight" or not when saving Matplotlib figures. For example, tight_bbox: true. See here for details.
• transparent is a boolean that determines whether to make Matplotlib figure background transparent or not. This is useful, for example, for displaying a plot on top of a colored background on a web page. High-resolution figures are not affected. For example, transparent: true.

## Usage as a Haskell library

To include the functionality of pandoc-plot in a Haskell package, you can use the makePlot function (for single blocks) or plotTransform function (for entire documents). Take a look at the documentation on Hackage.

### Usage with Hakyll

In case you want to use the filter with your own Hakyll setup, you can use a transform function that works on entire documents:

import Text.Pandoc.Filter.Plot (plotTransform)

import Data.Default (def) -- From data-default package, for default configuration
import Hakyll

-- Unsafe compiler is required because of the interaction
-- in IO (i.e. running an external script).
makePlotPandocCompiler :: Compiler (Item String)
makePlotPandocCompiler =
pandocCompilerWithTransformM
defaultHakyllReaderOptions
defaultHakyllWriterOptions
(unsafeCompiler . plotTransform def fmt)
where
config = def              -- Default configuration
fmt    = Just "markdown"  -- Document format, including extensions


## Installation

### Binaries and Installers (Windows)

Windows binaries and installers are available on the GitHub release page.

### From Hackage/Stackage

pandoc-plot is available on Hackage and Stackage. Using the cabal-install tool:

cabal update
cabal install pandoc-plot


or

stack update
stack install pandoc-plot


### From source

Building from source can be done using stack or cabal:

git clone https://github.com/LaurentRDC/pandoc-plot
cd pandoc-plot
stack install # Alternatively, cabal install


## Warning

Do not run this filter on unknown documents. There is nothing in pandoc-plot` that can stop a script from performing evil actions.

*Note that all licence references and agreements mentioned in the pandoc-plot README section above are relevant to that project's source code only.