ILThermoPy API

ilthermopy

This package is a Python interface for the ILThermo 2.0 database that provides additional information about the chemical structure of compounds

ilthermopy.compounds

Compounds object, containing info on compound structures

Type:: Compound

ilthermopy.CheckLastUpdate() → None: Prints date of the last ILThermo 2.0 update

class ilthermopy.PropertyList

Bases: object

Contains info on available physico-chemical properties and their API keys

properties

two-level organized dictionary, interconnecting property types, properties, and their API keys

Type:: dict

key2prop

maps API keys to property names

Type:: dict

prop2key

maps property names to their API keys

Type:: dict

Show() → None: Prints list of properties available in ILThermo 2.0 database formatted as api_key: property_name

ilthermopy.GetCompounds() → Compounds

Initializes Compounds object from pre-readied csv-file

Returns:: Compounds object

ilthermopy.ShowPropertyList() → None: Prints list of properties available in ILThermo 2.0 database

ilthermopy.Search(compound: Optional[str] = None, n_compounds: Optional[typing_extensions.Literal[None, 1, 2, 3]] = None, prop: Optional[str] = None, prop_key: Optional[str] = None, year: Optional[int] = None, author: Optional[str] = None, keywords: Optional[str] = None) → DataFrame

Runs ILThermo search and returns results as a dataframe

Parameters:

compound – chemical formula, CAS registry number, or name (part or full)
n_compounds – number of mixture compounds
prop – name of physico-chemical property, only used if prop_key is not specified
prop_key – key of physico-chemical property (view available via GetPropertyList)
year – publication year
author – author’s last name
keywords – keywords presumably specified in paper’s title

Returns:

dataframe containing main info on found entries

ilthermopy.GetAllEntries() → DataFrame

Returns main info on all available ILThermo entries

Returns:: dataframe containing all currently available entries

ilthermopy.GetEntry(code: str) → Entry

Extracts data entry from ILThermo database

Parameters:: code – data entry ID
Returns:: Entry object

ilthermopy.requests

Request wrappers for ILThermo APIs

ilthermopy.requests.BASE_URL

base URL of the ILThermo 2.0 database

Type:: str

ilthermopy.requests.PROPS_URL

relative URL for the property list API

Type:: str

ilthermopy.requests.SEARCH_URL

relative URL for the search API

Type:: str

ilthermopy.requests.DATA_URL

relative URL for loading entrie’s data

Type:: str

ilthermopy.requests.IMAGE_URL

relative URL for compound’s image API

Type:: str

ilthermopy.requests.GetHomepage() → str

Returns HTML of the ILThermo’s homepage

Returns:: HTML-formatted ILThermo homepage (JS functionality disabled)

ilthermopy.requests.GetPropertyList() → dict

Extracts available ILThermo properties and their API keys

Returns:

dictionary containing two-level structured info on: currently available physchemical properties and their API keys

ilthermopy.requests.GetEntries(compound: Optional[str] = None, n_compounds: Optional[typing_extensions.Literal[None, 1, 2, 3]] = None, prop_key: Optional[str] = None, year: Optional[int] = None, author: Optional[str] = None, keywords: Optional[str] = None) → dict

Wrapper for database search request

Parameters:

compound – chemical formula, CAS registry number, or name (part or full)
n_compounds – number of mixture compounds
prop_key – key of physico-chemical property (view available via GetPropertyList)
year – publication year
author – author’s last name
keywords – keywords presumably specified in paper’s title

Returns:

dictionary containing ILThermo search response

ilthermopy.requests.GetEntryData(setid: str) → dict

Wrapper for loading of data entry

Parameters:

setid – entry ID

Returns:

dictionary containing info on data entry, including reference, compounds,: physico-chemical data, etc.

ilthermopy.requests.GetCompoundImage(idout: str) → bytes

Wrapper for loading of compound’s image

Parameters:: idout – compound ID
Returns:: bytes-formatted PNG image

ilthermopy.data_structs

Main classes for quering the ILThermo 2.0 Database

class ilthermopy.data_structs.PropertyList

Bases: object

Contains info on available physico-chemical properties and their API keys

properties

two-level organized dictionary, interconnecting property types, properties, and their API keys

Type:: dict

key2prop

maps API keys to property names

Type:: dict

prop2key

maps property names to their API keys

Type:: dict

Show() → None: Prints list of properties available in ILThermo 2.0 database formatted as api_key: property_name

class ilthermopy.data_structs.Compound(id: str, name: str, formula: Optional[str] = None, smiles: Optional[str] = None, smiles_error: Optional[str] = None, sample: Optional[Dict[str, str]] = None, mw: Optional[float] = None)

Bases: object

Class describing a chemical compound

id: str: compound ID

name: str: compound name

formula: Optional[str] = None: chemical formula of compound

smiles: Optional[str] = None: chemical structure in SMILES format; SMILES is not provided by ILThermo database, and is retrieved from manually verified data

smiles_error: Optional[str] = None: describes reason why SMILES was not retrieved from pre-readied data; None if SMILES was retrieved successfully

sample: Optional[Dict[str, str]] = None: dictionary containing info on compound’s source, purity, etc.

mw: Optional[float] = None: molar weight, g/mol

ilthermopy.data_structs.ResponseToCompound(response: Dict) → Compound

Transforms entry data API response to the Compound object

Parameters:: response – dictionary describing compound in entry data API response, e.g. r[‘components’][0]
Returns:: Compound object

class ilthermopy.data_structs.Reference(full: Optional[str], title: Optional[str])

Bases: object

Class describing a scientific paper

full: Optional[str]: reference text without title

title: Optional[str]: title of the paper

class ilthermopy.data_structs.Entry(id: str, ref: Reference, property: str, property_type: str, phases: List[str], components: List[Compound], num_components: int, num_phases: int, num_data_points: int, expmeth: Optional[str], solvent: Optional[str], constraints: Optional[str], data: DataFrame, header: Dict[str, str], footnotes: Optional[str], response: Dict)

Bases: object

Class describing data entry

id: str: data entry ID

ref: Reference: source of physico-chemical data

property: str: measured property

property_type: str: type of measured property

phases: List[str]: list of phases (phase names)

components: List[Compound]: list of chemical components

num_components: int: number of chemical components

num_phases: int: number of phases

num_data_points: int: number of data points

expmeth: Optional[str]: experimental method

solvent: Optional[str]: solvent

constraints: Optional[str]: experimental constraints

data: DataFrame: experimental data in tabular format; columns are formatted as Vi and dVi, where Vi is i-th property, and dVi is a corresponding measurement error

header: Dict[str, str]: fullnames of the dataframe’s columns

footnotes: Optional[str]: notes to the provided data

response: Dict: data entry API response

ilthermopy.data_structs.ResponseToData(response: Dict) → Tuple[DataFrame, Dict]

Extracts and formats data from data entry API response

Parameters:: response – data entry API response
Returns:: dataframe containing experimental data, and dictionary, mapping dataframe’s column names to fullnames, containing property name, measurement unit, and phase name

ilthermopy.data_structs.ResponseToEntry(code: str, response: Dict) → Entry

Transforms data entry API response to Entry object

Parameters:

code – data entry ID
response – data entry API response

Returns:

Entry object

ilthermopy.data_structs.GetEntry(code: str) → Entry

Extracts data entry from ILThermo database

Parameters:: code – data entry ID
Returns:: Entry object

ilthermopy.compound_list

Loads pre-readied info on compounds structure

ilthermopy.compound_list.compounds

Compounds object, containing info on compound structures

Type:: Compounds

class ilthermopy.compound_list.Compounds(data: DataFrame, id2smiles: Dict[str, str], name2smiles: Dict[str, str])

Bases: object

Contains info on compounds’ structure

data: DataFrame: dataframe, containing compound’s ID, name, chemical formula (all extracted from ILThermo 2.0), and manually verified SMILES

id2smiles: Dict[str, str]: dictionary mapping ILThermo’s compound ids to SMILES

name2smiles: Dict[str, str]: dictionary mapping ILThermo’s compound names to SMILES

ilthermopy.compound_list.GetCompounds() → Compounds

Initializes Compounds object from pre-readied csv-file

Returns:: Compounds object

ilthermopy.search

Search-related functions

ilthermopy.search.ShowPropertyList() → None: Prints list of properties available in ILThermo 2.0 database

ilthermopy.search.Search(compound: Optional[str] = None, n_compounds: Optional[typing_extensions.Literal[None, 1, 2, 3]] = None, prop: Optional[str] = None, prop_key: Optional[str] = None, year: Optional[int] = None, author: Optional[str] = None, keywords: Optional[str] = None) → DataFrame

Runs ILThermo search and returns results as a dataframe

Parameters:

compound – chemical formula, CAS registry number, or name (part or full)
n_compounds – number of mixture compounds
prop – name of physico-chemical property, only used if prop_key is not specified
prop_key – key of physico-chemical property (view available via GetPropertyList)
year – publication year
author – author’s last name
keywords – keywords presumably specified in paper’s title

Returns:

dataframe containing main info on found entries

ilthermopy.search.GetAllEntries() → DataFrame

Returns main info on all available ILThermo entries

Returns:: dataframe containing all currently available entries

ilthermopy.updates

Checks if ilthermopy package is up-to-date with ILThermo 2.0 database

ilthermopy.updates.CheckLastUpdate() → None: Prints date of the last ILThermo 2.0 update

ilthermopy.misc

Miscellaneous functions

ilthermopy.misc.format_formula(formula: str) → str

Formats chemical formula from ILThermo format to the alphabetically-ordered one

Parameters:: formula – HTML-formatted chemical formula in ILThermo 2.0 format
Returns:: Alphabetically ordered chemical formula

Examples

>>> format_formula('C<SUB>4</SUB>H<SUB>10</SUB>O')
'C4 H10 O'

ilthermopy.errors

Custom errors for the package

exception ilthermopy.errors.ILThermoSearchError(errors)

Bases: Exception

Custom error for unsuccessful search queries

Parameters:: errors (list of str) – error list in search response

errors

error list

Type:: list of str

message

human readable string describing the exception

Type:: str

exception ilthermopy.errors.ILThermoResponseError(api_name: str, error: str)

Bases: Exception

Custom error for unexpected responses

Parameters:

api_name (str) – ILThermo’s API
error (str) – text of the error

api_name

ILThermo’s API

Type:: str

error

text of the error

Type:: str

message

human readable string describing the exception

Type:: str