natcap.invest.reporting package

Submodules

natcap.invest.reporting.html module

Utilities for creating simple HTML report files.

class natcap.invest.reporting.html.Element(tag, content='', end_tag=True, **attrs)

Bases: object

Represents a generic HTML element.

Any Element object can be passed to HTMLDocument.add()

Example

doc = html.HTMLDocument(…) details_elem = doc.add(html.Element(‘details’)) details_elem.add(

html.Element(‘img’, src=’images/my_pic.png’, end_tag=False))
add(elem)

Add a child element (which is returned for convenience).

html()

Returns an HTML string for this element (and its children).

class natcap.invest.reporting.html.HTMLDocument(uri, title, header)

Bases: object

Utility class for creating simple HTML files.

Example usage:

# Create the document object. doc = html.HTMLDocument(‘myfile.html’, ‘My Page’, ‘A Page About Me’)

# Add some text. doc.write_header(‘My Early Life’) doc.write_paragraph(‘I lived in a small barn.’)

# Add a table. table = doc.add(html.Table()) table.add_row([‘Age’, ‘Weight’], is_header=True) table.add_row([‘1 year’, ‘20 pounds’]) table.add_row([‘2 years’, ‘40 pounds’])

# Add an arbitrary HTML element. # Note that the HTML ‘img’ element doesn’t have an end tag. doc.add(html.Element(‘img’, src=’images/my_pic.png’, end_tag=False))

# Create the file. doc.flush()

add(elem)

Add an arbitrary element to the body of the document.

elem - any object that has a method html() to output HTML markup

Return the added element for convenience.

flush()

Create a file with the contents of this document.

insert_table_of_contents(max_header_level=2)

Insert an auto-generated table of contents.

The table of contents is based on the headers in the document.

write_header(text, level=2)

Convenience method to write a header.

write_paragraph(text)

Convenience method to write a paragraph.

class natcap.invest.reporting.html.Table(**attr)

Bases: object

Represents and renders HTML tables.

add_row(cells, is_header=False, cell_attr=None, do_formatting=True)

Writes a table row with the given cell data.

cell_attr - attributes for each cell. If provided, it must be the
same length as cells. Each entry should be a dictionary mapping attribute key to value.
add_two_level_header(outer_headers, inner_headers, row_id_header)

Adds a two level header to the table.

In this header, each outer header appears on the top row, and each inner header appears once beneath each outer header.

For example, the following code:

table.add_two_level_header(
outer_headers=[‘Weight’, ‘Value’], inner_headers=[‘Mean, Standard deviation’], row_id_header=’Farm ID’)

produces the following header:

Weight Value

Farm ID Mean Standard Deviation Mean Standard deviation

html()

Return the HTML string for the table.

natcap.invest.reporting.html.cell_format(data)

Formats the data to put in a table cell.

natcap.invest.reporting.table_generator module

A helper module for generating html tables that are represented as Strings

natcap.invest.reporting.table_generator.add_checkbox_column(col_list, row_list, checkbox_pos=1)

Insert a new column into the list of column dictionaries so that it is the second column dictionary found in the list. Also add the checkbox column header to the list of row dictionaries and subsequent checkbox value

‘col_list’- a list of dictionaries that defines the column

structure for the table (required). The order of the columns from left to right is depicted by the index of the column dictionary in the list. Each dictionary in the list has the following keys and values:

‘name’ - a string for the column name (required) ‘total’ - a boolean for whether the column should be

totaled (required)
‘row_list’ - a list of dictionaries that represent the rows. Each

dictionaries keys should match the column names found in ‘col_list’ (required) Example: [{col_name_1: value, col_name_2: value, …},

{col_name_1: value, col_name_2: value, …}, …]
checkbox_pos - an integer for the position of the checkbox
column. Defaulted at 1 (optional)
returns - a tuple of the updated column and rows list of dictionaries
in that order
natcap.invest.reporting.table_generator.add_totals_row(col_headers, total_list, total_name, checkbox_total, tdata_tuples)

Construct a totals row as an html string. Creates one row element with data where the row gets a class name and the data get a class name if the corresponding column is a totalable column

col_headers - a list of the column headers in order (required)

total_list - a list of booleans that corresponds to ‘col_headers’ and
indicates whether a column should be totaled (required)
total_name - a string for the name of the total row, ex: ‘Total’, ‘Sum’
(required)
checkbox_total - a boolean value that distinguishes whether a checkbox
total row is being added or a regular total row. Checkbox total row is True. This will determine the row class name and row data class name (required)
tdata_tuples - a list of tuples where the first index in the tuple is a
boolean which indicates if a table data element has a attribute class. The second index is the String value of that class or None (required)
return - a string representing the html contents of a row which should
later be used in a ‘tfoot’ element
natcap.invest.reporting.table_generator.generate_table(table_dict, attributes=None)

Takes in a dictionary representation of a table and generates a String of the the table in the form of hmtl

table_dict - a dictionary with the following arguments:
‘cols’- a list of dictionaries that defines the column

structure for the table (required). The order of the columns from left to right is depicted by the index of the column dictionary in the list. Each dictionary in the list has the following keys and values:

‘name’ - a string for the column name (required) ‘total’ - a boolean for whether the column should be

totaled (required)
‘attr’ - a dictionary that has key value pairs for
optional tag attributes (optional). Ex: ‘attr’: {‘class’: ‘offsets’}
‘td_class’ - a String to assign as a class name to
the table data tags under the column. Each table data tag under the column will have a class attribute assigned to ‘td_class’ value (optional)
‘rows’ - a list of dictionaries that represent the rows. Each

dictionaries keys should match the column names found in ‘cols’ (possibly empty list) (required) Example: [{col_name_1: value, col_name_2: value, …},

{col_name_1: value, col_name_2: value, …}, …]
‘checkbox’ - a boolean value for whether there should be a
checkbox column. If True a ‘selected total’ row will be added to the bottom of the table that will show the total of the columns selected (optional)
‘checkbox_pos’ - an integer value for in which column
position the the checkbox column should appear (optional)
‘total’- a boolean value for whether there should be a constant
total row at the bottom of the table that sums the column values (optional)
‘attributes’ - a dictionary of html table attributes. The attribute
name is the key which gets set to the value of the key. (optional) Example: {‘class’: ‘sorttable’, ‘id’: ‘parcel_table’}

returns - a string representing an html table

natcap.invest.reporting.table_generator.get_dictionary_values_ordered(dict_list, key_name)

Generate a list, with values from ‘key_name’ found in each dictionary in the list of dictionaries ‘dict_list’. The order of the values in the returned list match the order they are retrieved from ‘dict_list’

dict_list - a list of dictionaries where each dictionary has the same
keys. Each dictionary should have at least one key:value pair with the key being ‘key_name’ (required)
key_name - a String or Int for the key name of interest in the
dictionaries (required)
return - a list of values from ‘key_name’ in ascending order based
on ‘dict_list’ keys
natcap.invest.reporting.table_generator.get_row_data(row_list, col_headers)

Construct the rows in a 2D List from the list of dictionaries, using col_headers to properly order the row data.

‘row_list’ - a list of dictionaries that represent the rows. Each

dictionaries keys should match the column names found in ‘col_headers’. The rows will be ordered the same as they are found in the dictionary list (required) Example: [{‘col_name_1’:‘9/13’, ‘col_name_3’:’expensive’,

‘col_name_2’:’chips’},
{‘col_name_1’:‘3/13’, ‘col_name_2’:’cheap’,
‘col_name_3’:’peanuts’},
{‘col_name_1’:‘5/12’, ‘col_name_2’:’moderate’,
‘col_name_3’:’mints’}]
col_headers - a List of the names of the column headers in order
example : [col_name_1, col_name_2, col_name_3…]

return - a 2D list with each inner list representing a row

Module contents

natcap.invest.reporting package.

natcap.invest.reporting.add_head_element(param_args)

Generates a string that represents a valid element in the head section of an html file. Currently handles ‘style’ and ‘script’ elements, where both the script and style are locally embedded

param_args - a dictionary that holds the following arguments:

param_args[‘format’] - a string representing the type of element to
be added. Currently : ‘script’, ‘style’ (required)
param_args[‘data_src’] - a string URI path for the external source
of the element OR a String representing the html (DO NOT include html tags, tags are automatically generated). If a URI the file is read in as a String. (required)
param_args[‘input_type’] - ‘Text’ or ‘File’. Determines how the
input from ‘data_src’ is handled (required)
‘attributes’ - a dictionary that has key value pairs for
optional tag attributes (optional). Ex: ‘attributes’: {‘class’: ‘offsets’}

returns - a string representation of the html head element

natcap.invest.reporting.add_text_element(param_args)

Generates a string that represents a html text block. The input string should be wrapped in proper html tags

param_args - a dictionary with the following arguments:

param_args[‘text’] - a string

returns - a string

natcap.invest.reporting.build_table(param_args)

Generates a string representing a table in html format.

param_args - a dictionary that has the parameters for building up the

html table. The dictionary includes the following:

‘attributes’ - a dictionary of html table attributes. The attribute
name is the key which gets set to the value of the key. (optional) Example: {‘class’: ‘sorttable’, ‘id’: ‘parcel_table’}
param_args[‘sortable’] - a boolean value that determines whether the
table should be sortable (required)
param_args[‘data_type’] - a string depicting the type of input to
build the table from. Either ‘shapefile’, ‘csv’, or ‘dictionary’ (required)
param_args[‘data’] - a URI to a csv or shapefile OR a list of

dictionaries. If a list of dictionaries the data should be represented in the following format: (required)

[{col_name_1: value, col_name_2: value, …},
{col_name_1: value, col_name_2: value, …}, …]
param_args[‘key’] - a string that depicts which column (csv) or
field (shapefile) will be the unique key to use in extracting the data into a dictionary. (required for ‘data_type’ ‘shapefile’ and ‘csv’)
param_args[‘columns’] - a list of dictionaries that defines the

column structure for the table (required). The order of the columns from left to right is depicted by the index of the column dictionary in the list. Each dictionary in the list has the following keys and values:

‘name’ - a string for the column name (required) ‘total’ - a boolean for whether the column should be

totaled (required)
‘attr’ - a dictionary that has key value pairs for
optional tag attributes (optional). Ex: ‘attr’: {‘class’: ‘offsets’}
‘td_class’ - a String to assign as a class name to
the table data tags under the column. Each table data tag under the column will have a class attribute assigned to ‘td_class’ value (optional)
param_args[‘total’] - a boolean value where if True a constant
total row will be placed at the bottom of the table that sums the columns (required)

returns - a string that represents an html table

natcap.invest.reporting.data_dict_to_list(data_dict)

Abstract out inner dictionaries from data_dict into a list, where the inner dictionaries are added to the list in the order of their sorted keys

data_dict - a dictionary with unique keys pointing to dictionaries.
Could be empty (required)

returns - a list of dictionaries, or empty list if data_dict is empty

natcap.invest.reporting.generate_report(args)

Generate an html page from the arguments given in ‘reporting_args’

reporting_args[title] - a string for the title of the html page
(required)
reporting_args[sortable] - a boolean value indicating whether
the sorttable.js library should be added for table sorting functionality (optional)
reporting_args[totals] - a boolean value indicating whether
the totals_function.js script should be added for table totals functionality (optional)
reporting_args[out_uri] - a URI to the output destination for the html
page (required)
reporting_args[elements] - a list of dictionaries that represent html

elements to be added to the html page. (required) If no elements are provided (list is empty) a blank html page will be generated. The 3 main element types are ‘table’, ‘head’, and ‘text’. All elements share the following arguments:

‘type’ - a string that depicts the type of element being add.
Currently ‘table’, ‘head’, and ‘text’ are defined (required)
‘section’ - a string that depicts whether the element belongs
in the body or head of the html page. Values: ‘body’ | ‘head’ (required)

Table element dictionary has at least the following additional arguments:

‘attributes’ - a dictionary of html table attributes. The
attribute name is the key which gets set to the value of the key. (optional) Example: {‘class’: ‘sorttable’, ‘id’: ‘parcel_table’}
‘sortable’ - a boolean value for whether the tables columns
should be sortable (required)
‘checkbox’ - a boolean value for whether there should be a
checkbox column. If True a ‘selected total’ row will be added to the bottom of the table that will show the total of the columns selected (optional)
‘checkbox_pos’ - an integer value for in which column
position the the checkbox column should appear (optional)
‘data_type’ - one of the following string values:
‘shapefile’|’hg csv’|’dictionary’. Depicts the type of data structure to build the table from (required)
‘data’ - either a list of dictionaries if ‘data_type’ is

‘dictionary’ or a URI to a CSV table or shapefile if ‘data_type’ is ‘shapefile’ or ‘csv’ (required). If a list of dictionaries, each dictionary should have keys that represent the columns, where each dictionary is a row (list could be empty) How the rows are ordered are defined by their index in the list. Formatted example: [{col_name_1: value, col_name_2: value, …},

{col_name_1: value, col_name_2: value, …}, …]
‘key’ - a string that defines which column or field should be
used as the keys for extracting data from a shapefile or csv table ‘key_field’. (required for ‘data_type’ = ‘shapefile’ | ‘csv’)
‘columns’- a list of dictionaries that defines the column

structure for the table (required). The order of the columns from left to right is depicted by the index of the column dictionary in the list. Each dictionary in the list has the following keys and values:

‘name’ - a string for the column name (required) ‘total’ - a boolean for whether the column should be

totaled (required)
‘attr’ - a dictionary that has key value pairs for
optional tag attributes (optional). Ex: ‘attr’: {‘class’: ‘offsets’}
‘td_class’ - a String to assign as a class name to
the table data tags under the column. Each table data tag under the column will have a class attribute assigned to ‘td_class’ value (optional)
‘total’- a boolean value for whether there should be a constant
total row at the bottom of the table that sums the column values (optional)

Head element dictionary has at least the following additional arguments:

‘format’ - a string representing the type of head element being
added. Currently ‘script’ (javascript) and ‘style’ (css style) accepted (required)
‘data_src’- a URI to the location of the external file for
either the ‘script’ or the ‘style’ OR a String representing the html script or style (DO NOT include the tags) (required)
‘input_type’ - a String, ‘File’ or ‘Text’ that refers to how
‘data_src’ is being passed in (URI vs String) (required).
‘attributes’ - a dictionary that has key value pairs for
optional tag attributes (optional). Ex: ‘attributes’: {‘id’: ‘muni_data’}

Text element dictionary has at least the following additional arguments:

‘text’- a string to add as a paragraph element in the html page
(required)

returns - nothing

natcap.invest.reporting.u(string)
natcap.invest.reporting.write_html(html_obj, out_uri)

Write an html file to ‘out_uri’ from html element represented as strings in ‘html_obj’

html_obj - a dictionary with two keys, ‘head’ and ‘body’, that point to

lists. The list for each key is a list of the htmls elements as strings (required) example: {‘head’:[‘elem_1’, ‘elem_2’,…],

‘body’:[‘elem_1’, ‘elem_2’,…]}

out_uri - a URI for the output html file

returns - nothing