4. API Reference¶

The API reference below is primarily geared towards those users that wish to use the UManSysProp client component.

4.1. `umansysprop.client` Module¶

This module contains the client library for interacting with the UManSysProp server. Only one user-accessible class is defined in the module:

4.1.1. UManSysProp¶

class umansysprop.client.UManSysProp(base_url='http://umansysprop.seaes.manchester.ac.uk/')[source]¶

Provides a simple Python interface to the methods provided via the JSON API on the UManSysProp website. Constructing an instance of this class will cause the new instance to query the server for all available methods. Each method will be exposed as a method of the instance, with docstrings obtained from the server. For example:

>>> import umansysprop.client
>>> client = umansysprop.client.UManSysProp()
>>> client.vapour_pressure
<bound method ?.vapour_pressure of <umansysprop.client.UManSysProp object at 0x7f80fbae7b50>>
>>> client.vapour_pressure.__doc__
u"\nCalculates vapour pressures for all specified *compounds* (given..."

The class can be constructed with an alternative base_url if you wish to point it a different server. The base_url parameter defaults to the UManSysProp website.

Methods can be called like a normal Python method, but will result in a request being sent to the web-server, processed, and the JSON-formatted results being re-constructed as a Result list on the client. For example:

>>> result = client.vapour_pressure([
... 'CCCC', 'C(CC(=O)O)C(=O)O', 'C(=O)(C(=O)O)O',
... 'CCCCC/C=C/C/C=C/CC/C=C/CCCC(=O)O'],
... [298.15, 299.15, 300.15, 310.15],
... 'nannoolal', 'nannoolal')
>>> result
[<Table name="pressures">]
>>> result.pressures
<Table name="pressures">
>>> result.pressures.data
{(298.15, u'C(=O)(C(=O)O)O'): -5.196360545314141,
 (298.15, u'C(CC(=O)O)C(=O)O'): -6.33293991047814,
 (298.15, u'CCCC'): 0.22091492301164387,
 (298.15, u'CCCCC/C=C/C/C=C/CC/C=C/CCCC(=O)O'): -9.660331395164858,
 (299.15, u'C(=O)(C(=O)O)O'): -5.151703772558254,
 (299.15, u'C(CC(=O)O)C(=O)O'): -6.281177618554678,
 (299.15, u'CCCC'): 0.2354793193478599,
 (299.15, u'CCCCC/C=C/C/C=C/CC/C=C/CCCC(=O)O'): -9.58901500825095,
 (300.15, u'C(=O)(C(=O)O)O'): -5.107428775107059,
 (300.15, u'C(CC(=O)O)C(=O)O'): -6.229864995169396,
 (300.15, u'CCCC'): 0.24993365754879804,
 (300.15, u'CCCCC/C=C/C/C=C/CC/C=C/CCCC(=O)O'): -9.518352766693454,
 (310.15, u'C(=O)(C(=O)O)O'): -4.684643528880829,
 (310.15, u'C(CC(=O)O)C(=O)O'): -5.74023509658808,
 (310.15, u'CCCC'): 0.38868830156274703,
 (310.15, u'CCCCC/C=C/C/C=C/CC/C=C/CCCC(=O)O'): -8.845815136269506}

Please refer to the reference for Result and Table for more information on accessing the result data.

4.2. `umansysprop.results` Module¶

This module defines the classes used to encapsulate results returned by the UManSysProp server. Each tool method on the client will return an instance of the Result class which in turn contains one or more Table instances.

4.2.1. Result¶

class umansysprop.results.Result(*tables)[source]¶

Represents a list of named Table objects.

The result of a method is represented as a sequence of tables. This class contains a list of Table objects each of which may be retrieved by name, or by index in the list (tables with identical names are not ignored, but only the first table may be retrieved by name).

Note

This class has an extended string representation intended for easy command line debugging. Simply print an instance of the class to view a dump of all the tables contained within it.

4.2.2. Table¶

class umansysprop.results.Table(name, rows, cols, func=None, data=None, title='', rows_title=None, cols_title=None, rows_unit=None, cols_unit=None)[source]¶

Represents a single table in a Result.

A tool is expected to return a sequence of Table objects in a Result object. Each table has a name (which can be used to access it in the Result object), an ordered list of keys for rows and cols, and a function which is used to derive the data for each cell. The function accepts two arguments, the row and column key in that order, and is expected to return a scalar value. The reason for constructing a table in this manner (lazy evaluation) is that it enables renderers to query the table structure and layout without necessarily calculating anything. Calculated data is cached on the assumption that such calculations are expensive.

The row and column keys can be any immutable value (immutability is required as they will form keys in a dict at evaluation time). Keys which are tuples will be treated specially as renderers. For example, if each row key is a 2-tuple, then each row in the resulting table will have two row headers in two separate columns at the left of the table. This can aid in representing data with more than 2 dimensions in a table.

Consider a result set keyed by values A, B, and C. The table can be constructed with a series of 2-tuple row keys (A, B), while the column can be scalar C values. The resulting table will be rendered as follows:

		C1	C2	C3
A1	B1	data	data	data
A1	B2	data	data	data
A2	B1	data	data	data
A2	B2	data	data	data

Optional attributes also exist for title, rows_title, cols_title, rows_unit, and cols_unit (these all default to an empty string if omitted). In the case that tuples are used for row or column keys, the corresponding title and unit values must be tuples as well.

Note

Like Result, this class has an extended string representation intended for easy command line debugging. Printing an instance of this class will produce a human readable string representation of the table’s row and column keys along with the calculated data.

as_ndarray¶: Returns the content of the table as a numpy ndarray with the shape (rows, cols). Rows and columns will be in the order given by the rows and cols attributes. Please note that row and column keys are not included in the resulting array (as ndarrays purposely do not support heterogeneous data types).

Warning

Accessing this property will implicitly import the numpy module. This is not done during module import to avoid creating an explicit dependency on numpy.

as_dataframe¶: Returns the content of the table as a pandas DataFrame. The rows and cols attributes will be included as the index and columns of the resulting DataFrame.

Warning

Accessing this property will implicitly import the pandas module. This is not done during module import to avoid creating an explicit dependency on pandas.

col_dims¶: The number of dimensions within the column keys. If this is greater than one, then cols is a sequence of tuples.

col_titles¶: Returns cols_title as a tuple, regardless. This property is intended to make renderers simpler.

cols¶

An ordered sequence of keys for the columns of the table. If col_dims is greater than one, this this is a sequence of tuples. These values, combined with rows can be used to index data in display order like so:

for row in table.rows:
    for col in table.cols:
        print(table.data[(row, col)])

cols_iter¶: Returns an iterator over cols where each key is returned as a tuple, regardless.

cols_title¶: A string or tuple of strings giving the title of each column dimension. Note that if col_dims is 1, this may be either a string or a 1-tuple containing a string. The associated col_titles attribute may be easier to work with.

cols_unit¶: A string or tuple of strings giving the units of each column dimension. Note that if col_dims is 1, this may be either a string or a 1-tuple containing a string. The associated col_units attribute may be easier to work with.

data¶: The data contained within the table. This is presented as a dict keyed by (row_key, col_key) tuples. To retrieve data in the same order as it should be presented, iterate over the rows and cols attributes.

data_iter¶: Returns an iterator over data where each key, value combination is returned as a tuple of (row_key, col_key, value), and each row and column key is returned as a tuple, regardless of the number of row and column dimensions. Furthermore, items are returned in declared row then column order. This property is intended to make renderers simpler.

name¶: The name of the table. This is intended for scripting usage and as such will only ever contain a string beginning with an alphabetic character followed by zero or more alphanumeric characters or underscores.

row_dims¶: The number of dimensions within the row keys. If this is greater than one, then rows is a sequence of tuples.

row_titles¶: Returns rows_title as a tuple, regardless. This property is intended to make renderers simpler.

rows¶

An ordered sequence of keys for the rows of the table. If row_dims is greater than one, then this is a sequence of tuples. These values, combined with cols can be used to index data in display order like so:

for row in table.rows:
    for col in table.cols:
        print(table.data[(row, col)])

rows_iter¶: Returns an iterator over rows where each key is returned as a tuple, regardless. This property is intended to make renderers simpler.

rows_title¶: A string or tuple of strings giving the title of each row dimension. Note that if row_dims is 1, this may be either a string or a 1-tuple containing a string. The associated row_titles attribute may be easier to work with.

rows_unit¶: A string or tuple of strings giving the units of each row dimension. Note that if row_dims is 1, this may be either a string or a 1-tuple containing a string. The associated row_units attribute may be easier to work with.

title¶: The human readable title of the table, typically rendered in the web interface as the table’s caption.