Reporting in HTML Format

You can either use the pre-made Model.xhtml_report() to generate a report on a model, or you can roll your own using a combination of xhtml_* components and custom elements. For example, you might make a custom table to hold some facts about your model or data:

>>> from larch.util.xhtml import XML_Builder
>>> def report_valueoftime(m):
...             from larch.roles import P
...             VoT_cents_per_minute = P.tottime / P.totcost
...             VoT_dollars_per_hour = (P.tottime * 60) / (P.totcost * 100)
...             x = XML_Builder("div", {'class':"value_of_time"})
...             x.h2("Implied Value of Time", anchor=1)
...             with x.block("table"):
...                     with x.block("tr"):
...                             x.th("Units")
...                             x.th("Value")
...                     with x.block("tr"):
...                             x.td("cents per minute")
...                             x.td(VoT_cents_per_minute.strf(m, fmt="{:.1f}\xa2/minute"))
...                     with x.block("tr"):
...                             x.td("dollars per hour")
...                             x.td(VoT_dollars_per_hour.strf(m, fmt="${:.2f}/hr"))
...             return x.close()

You can attach that function to a model using Model.new_xhtml_section() like this:

>>> m = larch.Model.Example(1, pre=True)
>>> m.new_xhtml_section(lambda: report_valueoftime(m), 'valueoftime')

Now the report section is available under the name ‘valueoftime’, so you can include it in a Model.xhtml() or Model.html() report, obtaining either a xhtml section or a fully built html file:

>>> m.xhtml( 'title', 'params', 'valueoftime' )
<larch.util.xhtml.Elem 'div' at ...>
>>> m.html( 'title', 'params', 'valueoftime' )
b'<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head>...</head><body>...</body></html>'

You probably won’t need any more customization of the html output, but if you do you can get it, using a more complex but lower level python code. So you could incorporate that table into a model report like this:

>>> from larch.util.xhtml import XHTML
>>> m = larch.Model.Example(1, pre=True)
>>> with XHTML(quickhead=m) as f:
...             f.append( m.xhtml_title() )
...             f.append( report_valueoftime(m) )
...             f.append( m.xhtml_params() )
...             print(f.dump())
...
b'<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head>...</html>'

Instead of printing to the console, you can send it to a file and open in your favorite browser. Then it might look like this:

_images/reporting1_render.png

There are a variety of xhtml components that can be used in roll your own report writing:

Model.xhtml_report(cats=None, raw_xml=False, throw_exceptions=False, filename=None, popup=True, **format)
Model.xhtml_title(**format)

Generate a div element containing the model title in a H1 tag.

The title used is taken from the title of the model. There are no format keywords that are relevant for this method.

Returns:A div containing the model title.
Return type:larch.util.xhtml.Elem
Model.xhtml_params(groups=None, display_inital=False, display_id=False, **format)

Generate a div element containing the model parameters in a table.

Parameters:
  • groups (None or list) – An ordered list of parameters names and/or categories. If given, this list will be used to order the resulting table.
  • display_inital (bool) – Should the initial values of the parameters (the starting point for estimation) be included in the report. Defaults to False.
Returns:

A div containing the model parameters.

Return type:

larch.util.xhtml.Elem

>>> from larch.util.categorize import Categorizer, Renamer
>>> m = larch.Model.Example(1, pre=True)
>>> param_groups = [
...     Categorizer('Level of Service',
...                         Renamer('Total Time', 'tottime'),
...                         Renamer('Total Cost', 'totcost')  ),
...     Categorizer('Alternative Specific Constants', 'ASC.*'),
...     Categorizer('Income', 'hhinc.*'),
... ]
>>> elem = m.xhtml_params()
>>> elem
<larch.util.xhtml.Elem 'div' ...>
>>> html = elem.tostring()
>>> html
b'<div ...>'
_images/render_xhtml_params_html.png
Model.xhtml_ll(**format)

Generate a div element containing the model estimation statistics.

Returns:A div containing the model parameters.
Return type:larch.util.xhtml.Elem
>>> from larch.util.xhtml import XHTML
>>> m = larch.Model.Example(1, pre=True)
>>> m.xhtml('title', 'll')
<larch.util.xhtml.Elem 'div' ...>
>>> html = m.html('title', 'll')
>>> html
b'<!DOCTYPE html ...>'
_images/render_xhtml_ll_html.png
Model.xhtml_data(max_alts=50, **format)

Generate a div element containing the summary statistics for choice and availability.

Note that the choice and availability must be provisioned (loaded into the model) to generate these summary statistics.

Returns:A div containing the summary statistics for choice and availability.
Return type:larch.util.xhtml.Elem
>>> from larch.util.xhtml import XHTML
>>> m = larch.Model.Example(1, pre=True)
>>> m.df = larch.DT.Example('MTC')
>>> m.provision()
>>> with XHTML(quickhead=m) as f:
...     f.append(m.xhtml_title())
...     f.append(m.xhtml_data())
...     html = f.dump()
>>> html
b'<!DOCTYPE html ...>'
_images/render_xhtml_data_html.png
Model.xhtml_utilitydata(**format)

Summary statistics for the data used in the utility function.

Note that the utility data must be provisioned (loaded into the model) to generate these summary statistics.

Returns:A div containing the summary statistics for choice and availability.
Return type:larch.util.xhtml.Elem
>>> from larch.util.xhtml import XHTML
>>> m = larch.Model.Example(1, pre=True)
>>> m.df = larch.DT.Example('MTC')
>>> m.provision()
>>> with XHTML(quickhead=m) as f:
...     f.append(m.xhtml_title())
...     f.append(m.xhtml_utilitydata())
...     html = f.dump()
>>> html
b'<!DOCTYPE html ...>'
_images/render_xhtml_utilitydata_html.png