Pelican plugins » Plots and graphs

These plug­in al­low you to ren­der plots and graphs di­rect­ly from da­ta spec­i­fied in­line in the page source. Sim­i­lar­ly to math ren­der­ing, the graph­ics is ren­dered to a SVG that’s em­bed­ded di­rect­ly in the HTML markup.

Plots

Down­load the m/plots.py file, put it in­clud­ing the m/ di­rec­to­ry in­to one of your PLUGIN_PATHS and add m.plots pack­age to your PLUGINS in pelicanconf.py.

PLUGINS += ['m.plots']
M_PLOTS_FONT = 'Source Sans Pro'

Set M_PLOTS_FONT to a font that match­es your CSS theme (it’s Source Sans Pro for builtin m.css themes), note that you need to have the font in­stalled on your sys­tem, oth­er­wise it will fall back to what­ev­er sys­tem font it finds in­stead (for ex­am­ple De­jaVu Sans) and the out­put won’t look as ex­pect­ed. In ad­di­tion you need the Mat­plotlib li­brary in­stalled. Get it via pip or your dis­tri­bu­tion pack­age man­ag­er:

pip3 install matplotlib

The plug­in pro­duces SVG plots that make use of the CSS plot styling.

Bar charts

Cur­rent­ly the on­ly sup­port­ed plot type is a hor­i­zon­tal bar chart, de­not­ed by .. plot:: di­rec­tive with :type: hbar:

.. plot:: Fastest animals
    :type: barh
    :labels:
        Cheetah
        Pronghorn
        Springbok
        Wildebeest
    :units: km/h
    :values: 109.4 88.5 88 80.5
109.4 km/h 88.5 km/h 88.0 km/h 80.5 km/h 0 20 40 60 80 100 km/h Cheetah Pronghorn Springbok Wildebeest Fastest animals

The mul­ti-line :labels: op­tion con­tain val­ue la­bels, one per line. You can spec­i­fy unit la­bel us­ing :units:, par­tic­u­lar val­ues go in­to :values: sep­a­rat­ed by white­space, there should me as many val­ues as la­bels. Hov­er­ing over the bars will show the con­crete val­ue in a ti­tle.

It’s al­so op­tion­al­ly pos­si­ble to add er­ror bars us­ing :error: and con­fig­ure bar col­ors us­ing :colors:. The col­ors cor­re­spond to m.css col­or class­es and you can ei­ther use one col­or for all or one for each val­ue, sep­a­rat­ed by white­space. Bar chart height is cal­cu­lat­ed au­to­mat­i­cal­ly based on amount of val­ues, you can ad­just the bar height us­ing :bar_height:. De­fault val­ue is 0.4.

It’s pos­si­ble to add an ex­tra line of la­bels us­ing :labels_extra:. Again, there should be as many en­tries as pri­ma­ry la­bels and val­ues. To omit an ex­tra la­bel for a val­ue, spec­i­fy it as the reST com­ment ...

.. plot:: Runtime cost
    :type: barh
    :labels:
        Ours minimal
        Ours default
        3rd party
        Full setup
    :labels_extra:
        15 modules
        60 modules
        200 modules
        ..
    :units: µs
    :values: 15.09 84.98 197.13 934.27
    :errors: 0.74 3.65 9.45 25.66
    :colors: success info danger dim
    :bar_height: 0.6
15.09 ± 0.74 µs 84.98 ± 3.65 µs 197.13 ± 9.45 µs 934.27 ± 25.66 µs 0 200 400 600 800 1000 µs Ours minimal Ours default 3rd party Full setup 15 modules 60 modules 200 modules Runtime cost

Graphs

Down­load the m/dot.py file, put it in­clud­ing the m/ di­rec­to­ry in­to one of your PLUGIN_PATHS and add m.dot pack­age to your PLUGINS in pelicanconf.py.

PLUGINS += ['m.dot']
M_DOT_FONT = 'Source Sans Pro'
M_DOT_FONT_SIZE = 16.0

Set M_DOT_FONT and M_DOT_FONT_SIZE to a font that match­es your CSS theme (it’s Source Sans Pro at 16px for builtin m.css themes), note that you need to have the font in­stalled on your sys­tem, oth­er­wise it will fall back to what­ev­er sys­tem font it finds in­stead (for ex­am­ple De­jaVu Sans) and the out­put won’t look as ex­pect­ed. In ad­di­tion you need the Graphviz li­brary in­stalled. Get it via your dis­tri­bu­tion pack­age man­ag­er, for ex­am­ple on Ubun­tu:

sudo apt install graphviz

The plug­in pro­duces SVG graphcs that make use of the CSS graph styling.

Di­rect­ed graphs

The .. digraph:: di­rec­tive us­es the dot tool to pro­duce di­rect­ed graphs. The op­tion­al di­rec­tive ar­gu­ment is graph ti­tle, con­tents is what­ev­er you would put in­side the digraph block. Use the :class: to spec­i­fy a CSS col­or class for the whole graph, it’s al­so pos­si­ble to col­or par­tic­u­lar nodes and edges us­ing the (cur­rent­ly un­doc­u­ment­ed) class at­tribute.

.. digraph:: Finite state machine

    rankdir=LR

    S₁ [shape=circle, class="m-primary", peripheries=2]
    S₂ [shape=circle]
    _  [style=invis]

    _  -> S₁ [class="m-warning"]
    S₁ -> S₂ [label="0"]
    S₂ -> S₁ [label="0"]
    S₁ -> S₁ [label="1"]
    S₂ -> S₂ [label="1"]
Finite state machine S₁ S₁ S₁->S₁ 1 S₂ S₂ S₁->S₂ 0 S₂->S₁ 0 S₂->S₂ 1 _->S₁

For more in­for­ma­tion check the of­fi­cial GraphViz Ref­er­ence, in par­tic­u­lar the ex­ten­sive at­trib­ute doc­u­men­ta­tion.

Un­di­rect­ed graphs

The .. graph:: and .. strict-graph:: di­rec­tives are sim­i­lar to .. digraph::, but al­low undi­rect­ed graphs on­ly. Again these are equiv­a­lent to graph and strict graph in the DOT lan­guage:

.. graph:: A house
    :class: m-success

    { rank=same 0 1 }
    { rank=same 2 4 }

    0 -- 1 -- 2 -- 3 -- 4 -- 0 -- 2 -- 4 --1
    3 [style=solid]
A house 0 0 1 1 0--1 2 2 0--2 1--2 4 4 2--4 3 3 2--3 4--0 4--1 3--4

Graph fig­ure

See the m.com­po­nents plug­in for de­tails about graph fig­ures us­ing the .. graph-figure:: di­rec­tive.

.. graph-figure:: Impenetrable logic

    .. digraph::

        rankdir=LR
        yes [shape=circle, class="m-primary", style=filled]
        no [shape=circle, class="m-primary"]
        yes -> no [label="no", class="m-primary"]
        no -> no [label="no"]

    No.
yes yes no no yes->no no no->no no
Im­pen­e­tra­ble log­ic

No.