



  

Reports 0.3.1 documentation

 [Reports](index.html#document-index) 

 latest

 

* [1. References](index.html#document-references)

* [changelog](index.html#document-Changelog)

[Reports](index.html#document-index)

* [Docs](index.html#document-index) »

* Reports 0.3.1 documentation

* [Edit on GitHub](https://github.com/cokelaer/reports/blob/master/doc/source/index.rst)

---

Reports documentation[¶](#reports-documentation "Permalink to this headline")

=============================================================================

Current version: 0.3.1, February 16, 2017

[![](https://badge.fury.io/py/reports.svg)](https://pypi.python.org/pypi/reports)

[![https://travis-ci.org/cokelaer/reports.svg?branch=master](https://travis-ci.org/cokelaer/reports.svg?branch=master)](https://travis-ci.org/cokelaer/reports)

[![https://coveralls.io/repos/github/cokelaer/reports/badge.svg?branch=master](https://coveralls.io/repos/github/cokelaer/reports/badge.svg?branch=master)](https://coveralls.io/github/cokelaer/reports?branch=master)

[![Documentation Status](http://readthedocs.org/projects/reports/badge/?version=latest)](http://reports.readthedocs.org/en/latest/?badge=latest)

| Python version: | Python 2.7, 3.4 and 3.5 |

| documentation: | [On readthedocs](http://reports.readthedocs.org/) |

| Issues: | Please fill form on [On github](https://github.com/cokelaer/reports/issues) |

Reports is a simple Python package that provides tools to create HTML

documents. It is based on a set of JINJA templates and a class called

**Report**. In addition tools such as HTMLTable can help in the creation of HTML

table to be included in the report.

The package relies on Pandas for the HTML table creation, as shown in the

example below.

We provide a simple JINJA example (stored with the pacakge in

./share/data/templates/generic directory) and we let the users design their own

templates.

This is used in [GDSCTools](http://gdsctools.readthedocs.org) and

[Sequana](http://sequana.readthedocs.org) packages.

Usage[¶](#usage "Permalink to this headline")

=============================================

Example[¶](#example "Permalink to this headline")

-------------------------------------------------

Here below, we show the code used to create this [example](_static/report/index.html).

```

# We will create a Report and insert an HTML table in it

from reports import Report, HTMLTable

# Let us create some data. It will be a HTML table built using Pandas

# but you could create the HTML table code yourself.

import pandas as pd

# create a dataframe to play with. Note that there is a numeric column

# In addition, there is a column (Entry name) that will be transformed into URLs

df = pd.DataFrame({

    "Entry name":["ZAP70\_HUMAN", "TBK1\_HUMAN"],

    "Entry": ["P43403", "Q9UHD2"],

    "Frequency": [0.5,0.9]})

# From reports, we convert the dataframe into a HTMLTable

table = HTMLTable(df)

# a numeric column can be colorized

table.add\_bgcolor('Frequency', cmap="copper")

# part of URLs can be added to the content of a column

table.add\_href('Entry', url='http://uniprot.org/uniprot/', suffix="")

html = table.to\_html()

# Create a generic report. It has a set of tags that can be filled

# using the \*\*jinja\*\* attribute.

r = Report("generic")

# set the \*\*summary\*\* tag with the HTML code of the table

r.jinja['summary'] = html

# Generate and show the report

r.create\_report(onweb=True)

```

See the results in [example](_static/report/index.html)

Using your own JINJA template[¶](#using-your-own-jinja-template "Permalink to this headline")

---------------------------------------------------------------------------------------------

Create a directory called **test** and add a file called **index.html**

Add this code:

```

<h1> {{ title }} </h1>

<p> Number of reads : {{ reads }} </p>

```

Now, create your HTML files:

```

from reports import Report

report = Report("test")

report.jinja['title'] = 'Simple Example'

report.jinja['reads'] = "123456"

report.create\_report(onweb=True)

```

Issues[¶](#issues "Permalink to this headline")

===============================================

Please fill bug report in <https://github.com/cokelaer/reports>

Contributions[¶](#contributions "Permalink to this headline")

=============================================================

Please join <https://github.com/cokelaer/reports>

[References](#id2)[¶](#references "Permalink to this headline")

---------------------------------------------------------------

Contents

* [References](#references)

	+ [Reports](#module-reports.report)

	+ [HTMLTable](#module-reports.htmltable)

### [Reports](#id3)[¶](#module-reports.report "Permalink to this headline")

Base classes to create HTML reports easily

*class* `Report`(*searchpath=None*, *filename='index.html'*, *directory='report'*, *overwrite=True*, *verbose=True*, *template\_filename='index.html'*, *extra\_css\_list=[]*, *extra\_js\_list=[]*, *init\_report=True*)[[source]](_modules/reports/report.html#Report)[¶](#reports.report.Report "Permalink to this definition")

A base class to create HTML pages

The [`Report`](#reports.report.Report "reports.report.Report") is used to

1. fetch Jinja templates and css from a user directory (by default a generic

set of files is provided as an example

2. fetch the CSS and images

3. hold variables and contents within a dictionary (`jinja`)

4. Create the HTML document in a local directory.

```

from report import Report

r = Report()

r.create\_report(onweb=True)

```

The next step is for you to copy the templates in a new directory, edit them

and fill the `jinja` attribute to fulfil your needs:

```

from report import Report

r = Report("myreport\_templates")

r.jinja["section1"] = "<h1></h1>" 

r.create\_report() 

```

Constructor

| Parameters: | * **searchpath** – where to find the jina templates. 

If not provided, uses the generic template

* **filename** – output filename (default to **index.html**)

* **directory** – defaults to **report**

* **overwrite** – default to True

* **verbose** – default to True

* **template\_filename** – entry point of the jinja code

* **extra\_css\_list** – where to find the extra css

* **extra\_js\_list** – where to find the extra css

* **init\_report** ([*bool*](http://docs.python.org/library/functions.html#bool "(in Python v2.7)")) – init the report that is create 

the directories to store css and JS.

 |

`abspath`[¶](#reports.report.Report.abspath "Permalink to this definition")

The absolute path of the document (read only)

`add_dependencies` *= None*[¶](#reports.report.Report.add_dependencies "Permalink to this definition")

flag to add dependencies

`create_report`(*onweb=True*)[[source]](_modules/reports/report.html#Report.create_report)[¶](#reports.report.Report.create_report "Permalink to this definition")

`directory`[¶](#reports.report.Report.directory "Permalink to this definition")

The directory where to save the HTML document

`filename`[¶](#reports.report.Report.filename "Permalink to this definition")

The filename of the HTML document

`get_table_dependencies`(*package='reports'*)[[source]](_modules/reports/report.html#Report.get_table_dependencies)[¶](#reports.report.Report.get_table_dependencies "Permalink to this definition")

Returns dependencies of the pipeline as an HTML/XML table

The dependencies are the python dependencies as returned by

pkg\_resource module.

`get_time_now`()[[source]](_modules/reports/report.html#Report.get_time_now)[¶](#reports.report.Report.get_time_now "Permalink to this definition")

Returns a time stamp

`onweb`()[[source]](_modules/reports/report.html#Report.onweb)[¶](#reports.report.Report.onweb "Permalink to this definition")

Open the HTML document in a browser

`to_html`()[[source]](_modules/reports/report.html#Report.to_html)[¶](#reports.report.Report.to_html "Permalink to this definition")

`write`()[[source]](_modules/reports/report.html#Report.write)[¶](#reports.report.Report.write "Permalink to this definition")

### [HTMLTable](#id4)[¶](#module-reports.htmltable "Permalink to this headline")

Base classes to create HTML reports easily

*class* `HTMLTable`(*df*, *name=None*, *\*\*kargs*)[[source]](_modules/reports/htmltable.html#HTMLTable)[¶](#reports.htmltable.HTMLTable "Permalink to this definition")

Handler to export dataframe into HTML table.

Dataframe in Pandas already have a to\_html method to export the dataframe

into a HTML formatted table. However, we provide here a few handy features:

> 

> * Takes each cell in a given column and creates an HTML

> reference in each cell. See [`add\_href()`](#reports.htmltable.HTMLTable.add_href "reports.htmltable.HTMLTable.add_href") method.

> * add an HTML background into cells (numeric content) of

> a given column using different methods (e.g., normalise).

> See [`add\_bgcolor()`](#reports.htmltable.HTMLTable.add_bgcolor "reports.htmltable.HTMLTable.add_bgcolor")

> 

> 

> 

```

import pandas as pd

df = pd.DataFrame({'A':[1,2,10], 'B':[1,10,2]})

from gdsctools import HTMLTable

html = HTMLTable(df)

```

Note

similar project exists such as prettytable but could not do

exactly what we wanted at the time gdsctools was developed.

Note

Could be moved to biokit or easydev package.

Constructor

| Parameters: | * **df** (*dataframe*) – a pandas dataframe to transform into a table

* **name** ([*str*](http://docs.python.org/library/functions.html#str "(in Python v2.7)")) – not used yet

 |

There is an `pd\_options` attribute to reduce the max column

width or the precision of the numerical values.

`add_bgcolor`(*colname*, *cmap='copper'*, *mode='absmax'*, *threshold=2*)[[source]](_modules/reports/htmltable.html#HTMLTable.add_bgcolor)[¶](#reports.htmltable.HTMLTable.add_bgcolor "Permalink to this definition")

Change column content into HTML paragraph with background color

| Parameters: | * **colname** –

* **cmap** – a colormap (matplotlib) or created using

colormap package (from pypi).

* **mode** – type of normalisation in ‘absmax’, ‘max’, ‘clip’

(see details below)

* **threshold** – used if mode is set to ‘clip’

 |

Colormap have values between 0 and 1 so we need to normalised the data

between 0 and 1. There are 3 mode to normalise the data so far.

If mode is set to ‘absmax’, negatives and positives values are

expected to be found in a range from -inf to inf. Values are

scaled in between [0,1] X’ = (X / M +1) /2. where m is the absolute

maximum. Ideally a colormap should be made of 3 colors, the first

color used for negative values, the second for zeros and third color

for positive values.

If mode is set to ‘clip’, values are clipped to a max value (parameter

*threshold* and values are normalised by that same threshold.

If mode is set to ‘max’, values are normalised by the max.

`add_href`(*colname*, *url=None*, *newtab=False*, *suffix=None*)[[source]](_modules/reports/htmltable.html#HTMLTable.add_href)[¶](#reports.htmltable.HTMLTable.add_href "Permalink to this definition")

default behaviour: takes column content and put into:

```

<a href={content}.html>content</a>

```

This is used to link to local files. If url is provided, you typically

want to link to an external url where the content is an identifier:

```

<a href={url}{content}>content</a>

```

Note that in the first case, *.html* is appended but not in the second

case, which means cell’s content should already have the .html

Also in the second case, a new tab is open whereas in the first case

the url is open in the current tab.

Note

this api may change in the future.

`sort`(*name*, *ascending=True*)[[source]](_modules/reports/htmltable.html#HTMLTable.sort)[¶](#reports.htmltable.HTMLTable.sort "Permalink to this definition")

`to_html`(*index=False*, *escape=False*, *header=True*, *collapse\_table=True*, *class\_outer='table\_outer'*, *\*\*kargs*)[[source]](_modules/reports/htmltable.html#HTMLTable.to_html)[¶](#reports.htmltable.HTMLTable.to_html "Permalink to this definition")

Return HTML version of the table

This is a wrapper of the to\_html method of the pandas dataframe.

| Parameters: | * **index** ([*bool*](http://docs.python.org/library/functions.html#bool "(in Python v2.7)")) – do not include the index

* **escape** ([*bool*](http://docs.python.org/library/functions.html#bool "(in Python v2.7)")) – do not escape special characters

* **header** ([*bool*](http://docs.python.org/library/functions.html#bool "(in Python v2.7)")) – include header

* **collapse\_table** ([*bool*](http://docs.python.org/library/functions.html#bool "(in Python v2.7)")) – long tables are shorten with a scroll bar

* **kargs** – any parameter accepted by

`pandas.DataFrame.to\_html()`

 |

Changelog[¶](#changelog "Permalink to this headline")

=====================================================

changelog[¶](#changelog "Permalink to this headline")

-----------------------------------------------------

| version 0.3.1: | Fix License and RTD |

| version 0.3.0: | Fix call to easydev.precision for the case where data contains

infinite/nan values |

| version 0.2.1: | Fix warnings due to division by zero; add some tests |

| version 0.2.0: | outer class of the table is always used (no check of a minimal size) |

| version 0.1.9: | Add new option to not create the sub directories (css/js...) |

| version 0.1.8: | fix another bug/typo in js\_list |

| version 0.1.7: | fix bug/typo in js\_list |

| version 0.1.6: | extra js can now be added (similarly to the CSS) |

| version 0.1.5: | get\_dependencies now accept an input package argument (defaults

to reports) |

| version 0.1.4: | HTMLTable sorting is confused with the content of scientific

notation that are used as characters. The user should change te dataframe

types but we change the type is we can from object to float.

Second fix is related to CSS. We were already including CSS from reports/resources/css,

from a list of user-defined CSS. We now also include CSS found in the JINJA

searchpath provided by the user. |

| version 0.1.3: |  |

* change css\_path into extra\_css\_list parameter

* change parameter names to allow to get all set of jinja files instead of just one.

| version 0.1.2: |  |

* refactoring: moved ./src/reports into ./reports and mv ./share into ./reports

this was done to ease the modifications of setup.py so that the templates

can be accessed to using python setupy install or develop mode AND pip

install.

| version 0.1.1: |  |

* added jquery javascript

| version 0.1: |  |

* first functional release used in sequana project and gdsctools project

Indices and tables[¶](#indices-and-tables "Permalink to this headline")

=======================================================================

* [Index](genindex.html)

* [Module Index](py-modindex.html)

* [Search Page](search.html)





Generic report

Title undefined

===============

Report created with report (version 0.0.2)

------------------------------------------

---

Example of a header

---

* 1 - [Summary](#Summary)

* 2 - [Dependencies](#Dependencies)

 1 - [Summary](#id1)

--------------------

| Entry | Entry name | Frequency |

| --- | --- | --- |

| [P43403](http://uniprot.org/uniprot/P43403) | ZAP70\_HUMAN | 0.5 |

| [Q9UHD2](http://uniprot.org/uniprot/Q9UHD2) | TBK1\_HUMAN | 0.9 |

 2 - [Dependencies](#id11)

--------------------------

 Tables are sortable: You can click on a field in the header of the table: 

| package | version |

| --- | --- |

| [Jinja2](https://pypi.python.org/pypi/Jinja2) | 2.8 |

| [MarkupSafe](https://pypi.python.org/pypi/MarkupSafe) | 0.23 |

| [colorama](https://pypi.python.org/pypi/colorama) | 0.3.6 |

| [colormap](https://pypi.python.org/pypi/colormap) | 0.9.8 |

| [easydev](https://pypi.python.org/pypi/easydev) | 0.9.12 |

| [numpy](https://pypi.python.org/pypi/numpy) | 1.10.4 |

| [pandas](https://pypi.python.org/pypi/pandas) | 0.17.1 |

| [python-dateutil](https://pypi.python.org/pypi/python-dateutil) | 2.4.2 |

| [pytz](https://pypi.python.org/pypi/pytz) | 2015.7 |

| [reports](https://pypi.python.org/pypi/reports) | 0.0.2 |

| [six](https://pypi.python.org/pypi/six) | 1.10.0 |

---

Created on 2016-03-07 09:00:36 by cokelaer

 Please visit [online](http://report.readthedocs.org)

 documentation for details. 

 

