pybloqs 1.2.13

Data Visualization and Report Building

PyBloqs is a flexible framework for visualizing data and automated creation of reports.

pybloqs in use in ipython notebook

It works with Pandas, matplotlib and highcharts. PyBloqs creates atomic blocks containing text, tables (from Pandas DataFrame), plots (matplotlib or highcharts) or images. All blocks can be styled with CSS. Each block can be created and displayed separately for fast development turnover. Lists of blocks can be stacked together to form reports. Reports can be displayed as HTML in the browser or exported in a variety of formats (including HTML, PDF, SVG, PNG).

Quickstart

Install PyBloqs

For a minimal install without HighCharts support run:

pip install pybloqs

or when installing in development mode:

python setup.py develop

This will allow you to run the example code below.

External dependencies

For full functionality, PyBloqs requires the following 3rd party programs and libraries. For some, the file location must be specified at install time:

pip install --install-option="INSTALL OPTIONS" git+https://github.com/manahl/pybloqs.git

e.g.

pip install --install-option="--highcharts=~/node_modules/highcharts/,~/node_modules/highcharts-heatmap/" git+https://github.com/manahl/pybloqs.git

• Libraries bundled with PyBloqs:
• jsinflate.js (https://github.com/augustl/js-inflate; MIT License)
• jquery.js (https://jquery.com; MIT License)
• jquery-DataTables.js (https://datatables.net; MIT License)
• wkhtmltopdf/wkhtmltoimage (http://wkhtmltopdf.org/; LGPLv3):

wkhtmltopdf is not bundled with PyBloqs. You need to install it from your distribution’s repository (Linux) or download it from the project page (https://wkhtmltopdf.org) . The binaries wkhtmltopdf and wkhtmltoimage are used for file output other than HTML. PyBloqs will search for the binaries on the system path. If you would like to use a local copy of the binaries, install with following option:

--wkhtmltopdf=/path/to/binary

When installing in development mode you can load wkhtmltopdf explicitly:

python setup.py load_wkhtmltopdf --wkhtmltopdf=/path/to/binary

• Node.js with comander and puppeteer (optional; for PDF output with ‘chrome_headless’ backend). Please make sure these are available globally. In development mode, you can run

  npm install
  

  in the main PyBloqs directory.

• Bokeh (optional). To install Bokeh dependency, you can use:

  pip install pybloqs[bokeh]
  

• Plotly (optional). To install Plotly dependency, you can use:

  pip install pybloqs[plotly]
  

• HighCharts (optional; proprietary license, see https://shop.highsoft.com/highcharts-t2):

Highcharts is not bundled with PyBloqs. To create blocks with Highcharts plots, you need to download Highcharts separately (e.g. with npm install highcharts, npm install highcharts-heatmap etc.), and provide the path to your highcharts installation. Please make sure you have the right license for Highcharts. For full functionality you will need the following highcharts packages: highcharts, highcharts-heatmap, highcharts-funnel, highcharts-exporting, highcharts-export-csv (this example assumes, npm installed files into directory ~/node_modules).

--highcharts=~/node_modules/highcharts/,
~/node_modules/highcharts-heatmap/,~/node_modules/highcharts-funnel,~/node_modules/highcharts-exporting,
~/node_modules/highcharts-export-csv

When installing in development mode you can load highcharts explicitly (this example assumes, npm installed files into directory ~/node_modules)

python setup.py load_highcharts --highcharts=~/node_modules/highcharts/,~/node_modules/highcharts-heatmap/,\
~/node_modules/highcharts-funnel,~/node_modules/highcharts-exporting,~/node_modules/highcharts-export-csv

Using PyBloqs

from pybloqs import Block, HStack, VStack
import pandas as pd
from matplotlib import pyplot as plt

text_block = Block('This is a text block', styles={'text-align':'center', 'color':'blue'})
text_block.show()

df = pd.DataFrame([[1., 2.],[3.,4.]], columns =['a', 'b'])
table_block = Block(df)
table_block.show()

plot_block = Block(plt.plot(df['a'], df['b']))
plot_block.show()

plot_and_table = HStack([plot_block, table_block])
report = VStack([text_block, plot_and_table])
report.show()
report.save('report.pdf')

Configuration

You can specify per-user default parameters in a yaml-formatted file ~/.pybloqs.cfg. This config file allows you to setup a call setup and login sequence against an smtplib.SMTP (https://docs.python.org/2/library/smtplib.html#smtplib.SMTP) object. The following works for Google gmail - more details here (https://support.google.com/a/answer/176600?hl=en)

smtp_kwargs:
  host: smtp.gmail.com
  port: 587
smtp_pre_login_calls:
- !!python/tuple
  - ehlo
  - {}
- !!python/tuple
  - starttls
  - {}
- !!python/tuple
  - ehlo
  - {}
smtp_login:
  user: [e-mail]
  password: a_secret
public_dir: /tmp
tmp_html_dir: /tmp
user_email_address: [e-mail]

Documentation

Have a look at the detailed documentation.

Requirements

PyBloqs works with:

• matplotlib
• Pandas
• html5lib
• lxml
• jinja2
• markdown
• beautifulsoup4
• docutils

Acknowledgements

PyBloqs has been under active development at Man AHL since 2013.

Original concept and implementation: Tom Farnbauer

Contributors:

• Dominik Christ
• Barry Fitzgerald
• Wilfred Hughes
• James Munro
• Bogdan Cozmaciuc
• Dave Jepson
• Jason Matthews
• Rhodri Richards
• Doug Bruce
• Jonathan Nye
• Matthew Dodds
• Han Wei Teo
• Manjunath Goudreddy
• Edwin Flores
• … and many others …

Contributions welcome!

License

PyBloqs is licensed under the GNU LGPL v2.1. A copy of which is included in LICENSE

Changelog

1.0.0 (2017-04-07)

• Initial public release

1.0.1 (2017-04-13)

• Integration with pypi and ReadTheDocs.
• Installation on Mac and Windows.

1.0.2 (2017-04-26)

• Metadata and badge for Python version.
• Python 3 compatibility changes, part 1.
• Installation with Coveralls.

1.0.3 (2017-04-26)

• Bugfix: Import of urlparse corrected, fixes Block.show() .

1.1.0 (2017-05-10)

• jQuery DataTables support.
• HTML anchors.
• Bugfix: Width of HTML-body no longer hard-coded.

1.1.1 (2017-05-10)

• Bugfix: Static data including DataTables CSS.

1.1.2 (2017-06-2)

• Bugfix: Image size for Matplotlib figure no longer truncated to whole number.
• Updated download path for wkhtmltopdf in CI setup.

1.1.3 (2017-06-6)

• Bugfix: Expansion of user home directory for show().
• Bugfix: Flexible definition of default type handling for Block() that allows updating.

1.1.4 (2017-06-22)

• Bugfix: When applying operator on rows or columns (e.g. in totals row), replace nan with zero.

1.1.5 (2017-08-22)

• Bugfix: Multi-index formatter can now digest DataFrame with nun-unique multi-index.
• Bugfix: ReadTheDocs autodoc build fixed.

1.1.6 (2017-08-23)

• Bugfix: Unicode meta tag set in html output and unicode strings working wit Raw() block.

1.1.7 (2018-02-23)

• Feature: More SMTP options
• Feature: UTF-8 email mime-type
• Feature: Allow BCC for email

1.1.8 (2018-03-26)

• Bugfix: FmtHighlightText - explicitly set non-bold for column header
• Feature: Add page break example to documentation
• Bugfix: Pass apply_to_header_and_index to base class on all formatters

1.1.9 (2018-09-19)

• Bugfix: Indexing error in table.html with non-unique indices
• Bugfix: Removed Pandas warning in tests
• Remove WidePanel, update ipynb
• Feature: Add support for specifying different text colors for MultiIndex levels
• Feature: Add a context manager for temporarily setting plot format/DPI

1.2.0 (2018-11-21)

• Feature: Python 3 support
• Feature: Support for Bokeh plots
• Feature: Support for Plotly plots
• Feature: Allow use of different HTML conversion backends
• Feature: Added Chrome-headless backend for HTML->PDF conversion
• Updated CircleCI configuration to version 2

1.2.1 (2018-11-23)

• Bugfix: Removed pybloqs.plot import from top-level init.py
• Bugfix: puppeteer.js now included in egg/wheel packaging

1.2.2 (2018-11-27)

• Bugfix: Added missing formatter arg for wkhtmltox failure logging

1.2.3 (2018-12-03)

• Bugfix: Ensured python2 strings were being correctly encoded

1.2.4 (2019-03-27)

• Bugfix: Maintain static import ordering

1.2.5 (2019-06-25)

• Bugfix: Totals Row formatter no longer inserts NaN for non-numeric columns.

1.2.6 (2019-07-17)

• Feature: Passing kwargs to plotly plot function.

1.2.7 (2019-08-06)

• Bugfix: Use require.js for Plotly and Highcharts inside Jupyter
• Moved id_precision to user_config
• Use tmp_html_dir everywhere

1.2.8 (2020-08-25)

• Bugfix: Use colgroup tag for FmtHeader width specification
• Bugfix: Do not merge MultiIndex cells if parent cells not merged
• Bugfix: Pass actual header cell contents to formatter methods
• Feature: Add ability to vertically merge MultiIndex labels

1.2.9 (2020-12-02)

• Bugfix: Fix header positions when index is a MultiIndex
• Bugfix: Fix MultiIndex styling
• Feature: Add formatter for vertical-align

1.2.10 (2020-12-03)

• Bugfix: Pass only single row name into formatter from jinja table template

1.2.11 (2020-12-03)

• Bugfix: Stop MultiIndex flattening columns from being rendered

1.2.12 (2022-01-18)

• Feature: Add CommonTableFormatter builder to configuring table formatting
• Bugfix: Fix striped background for table formatting
• Deprecate Python 2.7, make Python 3.6 minimum required version

1.2.13 (2022-01-25)

• Bugfix: Fix output of Plotly blocks no longer showing in newer versions of Jupyter
• Bugfix: Add static output to Bokeh and Plotly to enable sending within email body