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 ValueFarm 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 stringreturns - 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