Reporting Package

Table Generator

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

HTML

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.extract_datasource_table_by_key(datasource_uri, key_field)

Return vector attribute table of first layer as dictionary.

Create a dictionary lookup table of the features in the attribute table of the datasource referenced by datasource_uri.

Parameters:
  • datasource_uri (string) – a uri to an OGR datasource
  • key_field – a field in datasource_uri that refers to a key value for each row such as a polygon id.
Returns:

returns a dictionary of the

form {key_field_0: {field_0: value0, field_1: value1}…}

Return type:

attribute_dictionary (dict)

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.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