Parsing and interfaces#

JSON#

Parse to and from a JSON string/file format for isotherms.

The _parser_version variable documents any changes to the format, and is used to check for any deprecations.

pygaps.parsing.json.isotherm_to_json(isotherm, path=None, **args_to_json)[source]#

Convert an isotherm object to a json representation.

If the path is specified, the isotherm is saved as a file, otherwise it is returned as a string. Structure is inspired by the NIST format.

Parameters:

  • isotherm (Isotherm) -- Isotherm to be written to json.

  • path (str, None) -- Path to the file to be written.

  • args_to_json (dict) -- Custom arguments to be passed to "json.dump".

Returns:

None or str -- If path is None, returns the resulting json format as a string. Otherwise returns None.

pygaps.parsing.json.isotherm_from_json(str_or_path, fmt=None, loading_key='loading', pressure_key='pressure', **isotherm_parameters)[source]#

Read a pyGAPS isotherm from a file or from a string.

Structure is inspired by the NIST format.

Parameters:

  • str_or_path (str) -- The isotherm in a json string format or a path to where one can be read.

  • loading_key (str) -- The title of the pressure data in the json provided.

  • pressure_key -- The title of the loading data in the json provided.

  • fmt ({None, 'NIST'}, optional) -- If the format is set to NIST, then the json format a specific version used by the NIST database of adsorbents.

Other Parameters:

isotherm_parameters -- Any other options to be overridden in the isotherm creation.

Returns:

Isotherm -- The isotherm contained in the json string or file.

AIF#

An AIF (adsorption information file) parsing implementation.

Format developed in this publication:

Evans, Jack D., Volodymyr Bon, Irena Senkovska, and Stefan Kaskel. ‘A Universal Standard Archive File for Adsorption Data’. Langmuir, 2 April 2021, acs.langmuir.1c00122. https://doi.org/10.1021/acs.langmuir.1c00122.

pygaps.parsing.aif.isotherm_to_aif(isotherm: PointIsotherm, path: str | None = None)[source]#

Convert isotherm into an AIF representation [1].

If the path is specified, the isotherm is saved as a file, otherwise it is returned as a string.

Parameters:

  • isotherm (Isotherm) -- Isotherm to be written to AIF.

  • path (str, None) -- Path to the file to be written.

Returns:

str (optional) -- String representation of the AIF, if path not provided.

References

pygaps.parsing.aif.isotherm_from_aif(str_or_path: str, **isotherm_parameters: dict)[source]#

Parse an isotherm from an AIF format (file or raw string) [2].

Parameters:

  • str_or_path (str) -- The isotherm in a AIF string format or a path to where one can be read.

  • isotherm_parameters -- Any other options to be overridden in the isotherm creation.

Returns:

Isotherm -- The isotherm contained in the AIF file or string.

References

CSV#

Parse to and from a CSV string/file format for isotherms.

The _parser_version variable documents any changes to the format, and is used to check for any deprecations.

pygaps.parsing.csv.isotherm_to_csv(isotherm, path=None, separator=',')[source]#

Convert isotherm into a CSV representation.

If the path is specified, the isotherm is saved as a file, otherwise it is returned as a string.

Parameters:

  • isotherm (Isotherm) -- Isotherm to be written to csv.

  • path (str, None) -- Path to the file to be written.

  • separator (str, optional) -- Separator used int the csv file. Defaults to '',''.

Returns:

str (optional) -- String representation of the CSV, if path not provided.

pygaps.parsing.csv.isotherm_from_csv(str_or_path, separator=',', **isotherm_parameters)[source]#

Load an isotherm from a CSV file.

Parameters:

  • str_or_path (str) -- The isotherm in a CSV string format or a path to where one can be read.

  • separator (str, optional) -- Separator used int the csv file. Defaults to ,.

  • isotherm_parameters -- Any other options to be overridden in the isotherm creation.

Returns:

Isotherm -- The isotherm contained in the csv string or file.

Excel#

Parse to and from a Excel format for isotherms.

The _parser_version variable documents any changes to the format, and is used to check for any deprecations.

pygaps.parsing.excel.isotherm_to_xl(isotherm, path)[source]#

Save an isotherm to an excel file.

Parameters:

  • isotherm (Isotherm) -- Isotherm to be written to excel.

  • path (str) -- Path to the file to be written.

pygaps.parsing.excel.isotherm_from_xl(path, *isotherm_parameters)[source]#

Load an isotherm from a pyGAPS Excel file.

Parameters:

  • path (str) -- Path to the file to be read.

  • isotherm_parameters -- Any other options to be overridden in the isotherm creation.

Returns:

Isotherm -- The isotherm contained in the excel file.

Apparatus files#

Parse aa file generated by commercial apparatus.

Parameters:

  • path (str) -- the location of the file.

  • manufacturer ({'mic', 'bel', '3p'}) -- Manufacturer of the apparatus.

  • fmt ({'xl', 'txt', ...}) -- The format of the import for the isotherm.

returns:

PointIsotherm

Sqlite#

This module contains the sql interface for data manipulation.

pygaps.parsing.sqlite.with_connection(func)[source]#

Contextmanager for sqlite connection.

pygaps.parsing.sqlite.adsorbate_to_db(adsorbate: Adsorbate, db_path: str = None, autoinsert_properties: bool = True, overwrite: bool = False, verbose: bool = True, **kwargs: dict)[source]#

Upload an adsorbate to the database.

If overwrite is set to true, the adsorbate is overwritten. Overwrite is done based on adsorbate.name

Parameters:

  • adsorbate (Adsorbate) -- Adsorbate class to upload to the database.

  • db_path (str, None) -- Path to the database. If none is specified, internal database is used.

  • overwrite (bool) -- Whether to upload the adsorbate or overwrite it. WARNING: Overwrite is done on ALL fields.

  • verbose (bool) -- Extra information printed to console.

pygaps.parsing.sqlite.adsorbates_from_db(db_path: str = None, verbose: bool = True, **kwargs: dict) → list[Adsorbate][source]#

Get database adsorbates and their properties.

The number of adsorbates is usually small, so all can be loaded in memory at once.

Parameters:

  • db_path (str, None) -- Path to the database. If none is specified, internal database is used.

  • verbose (bool) -- Extra information printed to console.

Returns:

list -- list of Adsorbates

pygaps.parsing.sqlite.adsorbate_delete_db(adsorbate: Adsorbate, db_path: str = None, verbose: bool = True, **kwargs: dict)[source]#

Delete adsorbate from the database.

Parameters:

  • adsorbate (Adsorbate or str) -- The Adsorbate class to delete or its name.

  • db_path (str, None) -- Path to the database. If none is specified, internal database is used.

  • verbose (bool) -- Extra information printed to console.

pygaps.parsing.sqlite.adsorbate_property_type_to_db(type_dict, db_path: str = None, overwrite: bool = False, verbose: bool = True, **kwargs: dict)[source]#

Uploads an adsorbate property type.

The type_dict takes the form of:

{
    'type' : 'the_type',
    'unit': 'the_unit',
    'description': 'the_description'
}
Parameters:

  • type_dict (dict) -- A dictionary that contains property type.

  • db_path (str, None) -- Path to the database. If none is specified, internal database is used.

  • overwrite (bool) -- Whether to upload the property type or overwrite it. WARNING: Overwrite is done on ALL fields.

  • verbose (bool) -- Extra information printed to console.

pygaps.parsing.sqlite.adsorbate_property_types_from_db(db_path: str = None, verbose: bool = True, **kwargs: dict) → list[dict][source]#

Get all adsorbate property types.

Parameters:

  • db_path (str, None) -- Path to the database. If none is specified, internal database is used.

  • verbose (bool) -- Extra information printed to console.

Returns:

dict -- dict of property types

pygaps.parsing.sqlite.adsorbate_property_type_delete_db(property_type, db_path: str = None, verbose: bool = True, **kwargs: dict)[source]#

Delete property type in the database.

Parameters:

  • property_type (str) -- Name of the property type to delete.

  • db_path (str, None) -- Path to the database. If none is specified, internal database is used.

  • verbose (bool) -- Extra information printed to console.

pygaps.parsing.sqlite.material_to_db(material: Material, db_path: str = None, autoinsert_properties: bool = True, overwrite: bool = False, verbose: bool = True, **kwargs: dict)[source]#

Upload a material to the database.

If overwrite is set to true, the material is overwritten. Overwrite is done based on material.name

Parameters:

  • material (Material) -- Material class to upload to the database.

  • db_path (str, None) -- Path to the database. If none is specified, internal database is used.

  • overwrite (bool) -- Whether to upload the material or overwrite it. WARNING: Overwrite is done on ALL fields.

  • verbose (bool) -- Extra information printed to console.

pygaps.parsing.sqlite.materials_from_db(db_path: str = None, verbose: bool = True, **kwargs: dict) → list[Material][source]#

Get all materials and their properties.

The number of materials is usually small, so all can be loaded in memory at once.

Parameters:

  • db_path (str, None) -- Path to the database. If none is specified, internal database is used.

  • verbose (bool) -- Extra information printed to console.

Returns:

list -- list of Materials

pygaps.parsing.sqlite.material_delete_db(material: Material, db_path: str = None, verbose: bool = True, **kwargs: dict)[source]#

Delete material from the database.

Parameters:

  • material (Material or str) -- Material class to upload to the database.

  • db_path (str, None) -- Path to the database. If none is specified, internal database is used.

  • verbose (bool) -- Extra information printed to console.

pygaps.parsing.sqlite.material_property_type_to_db(type_dict: dict, db_path: str = None, overwrite: bool = False, verbose: bool = True, **kwargs: dict)[source]#

Uploads a material property type.

The type_dict takes the form of:

{
    'type' : 'the_type',
    'unit': 'the_unit',
    'description': 'the_description'
}
Parameters:

  • type_dict (dict) -- A dictionary that contains property type.

  • db_path (str, None) -- Path to the database. If none is specified, internal database is used.

  • overwrite (bool) -- Whether to upload the property type or overwrite it. WARNING: Overwrite is done on ALL fields.

  • verbose (bool) -- Extra information printed to console.

pygaps.parsing.sqlite.material_property_types_from_db(db_path: str = None, verbose: bool = True, **kwargs: dict) → list[dict][source]#

Get all material property types.

Parameters:

  • db_path (str, None) -- Path to the database. If none is specified, internal database is used.

  • verbose (bool) -- Extra information printed to console.

Returns:

dict -- dict of property types

pygaps.parsing.sqlite.material_property_type_delete_db(material_prop_type: dict, db_path: str = None, verbose: bool = True, **kwargs: dict)[source]#

Delete material property type in the database.

Parameters:

  • material_prop_type (str) -- The type to delete.

  • db_path (str, None) -- Path to the database. If none is specified, internal database is used.

  • verbose (bool) -- Extra information printed to console.

pygaps.parsing.sqlite.isotherm_to_db(isotherm: BaseIsotherm | PointIsotherm | ModelIsotherm, db_path: str = None, autoinsert_material: bool = True, autoinsert_adsorbate: bool = True, verbose: bool = True, **kwargs: dict)[source]#

Uploads isotherm to the database.

If overwrite is set to true, the isotherm is overwritten. Overwrite is done based on isotherm.iso_id

Parameters:

  • isotherm (Isotherm) -- Isotherm, PointIsotherm or ModelIsotherm to upload to the database.

  • db_path (str, None) -- Path to the database. If none is specified, internal database is used.

  • autoinsert_material (bool, True) -- Whether to automatically insert an isotherm material if it is not found in the database.

  • autoinsert_adsorbate (bool, True) -- Whether to automatically insert an isotherm adsorbate if it is not found in the database.

  • verbose (bool, True) -- Extra information printed to console.

pygaps.parsing.sqlite.isotherms_from_db(criteria: dict = None, db_path: str = None, verbose: bool = True, **kwargs: dict) → list[BaseIsotherm | PointIsotherm | ModelIsotherm][source]#

Get isotherms with the selected criteria from the database.

Parameters:

  • criteria (dict, None) -- Dictionary of isotherm parameters on which to filter database from base parameters ('material', 'adsorbate', 'temperature', 'type'). For example {'material': 'm1', 'temperature': '77'}. Parameters must exist for the filtering to take place otherwise all results are returned.

  • db_path (str, None) -- Path to the database. If none is specified, internal database is used.

  • verbose (bool) -- Extra information printed to console.

Returns:

list -- list of Isotherms

pygaps.parsing.sqlite.isotherm_delete_db(iso_id: str | BaseIsotherm | PointIsotherm | ModelIsotherm, db_path: str = None, verbose: bool = True, **kwargs: dict)[source]#

Delete isotherm in the database.

Parameters:

  • isotherm (Isotherm or Isotherm.iso_id) -- The Isotherm object to delete from the database or its ID.

  • db_path (str, None) -- Path to the database. If none is specified, internal database is used.

  • verbose (bool) -- Extra information printed to console.

pygaps.parsing.sqlite.isotherm_type_to_db(type_dict: dict, db_path: str = None, overwrite: bool = False, verbose: bool = True, **kwargs: dict)[source]#

Upload an isotherm type.

The type_dict takes the form of:

{
    'type' : 'the_type',
    'unit': 'the_unit',
    'description': 'the_description'
}
Parameters:

  • type_dict (dict) -- A dictionary that contains isotherm type.

  • db_path (str, None) -- Path to the database. If none is specified, internal database is used.

  • overwrite (bool) -- Whether to upload the isotherm type or overwrite it. WARNING: Overwrite is done on ALL fields.

  • verbose (bool) -- Extra information printed to console.

pygaps.parsing.sqlite.isotherm_types_from_db(db_path: str = None, verbose: bool = True, **kwargs: dict) → list[dict][source]#

Get all isotherm types.

Parameters:

  • db_path (str, None) -- Path to the database. If none is specified, internal database is used.

  • verbose (bool) -- Extra information printed to console.

Returns:

dict -- dict of isotherm types

pygaps.parsing.sqlite.isotherm_type_delete_db(iso_type: str, db_path: str = None, verbose: bool = True, **kwargs: dict)[source]#

Delete isotherm type in the database.

Parameters:

  • data_type (str) -- The type to delete.

  • db_path (str, None) -- Path to the database. If none is specified, internal database is used.

  • verbose (bool) -- Extra information printed to console.

pygaps.parsing.sqlite.isotherm_property_type_to_db(type_dict: dict, db_path: str = None, overwrite: bool = False, verbose: bool = True, **kwargs: dict)[source]#

Uploads a property type.

The type_dict takes the form of:

{
    'type' : 'the_type',
    'unit': 'the_unit',
    'description': 'the_description'
}
Parameters:

  • type_dict (dict) -- A dictionary that contains property type.

  • db_path (str, None) -- Path to the database. If none is specified, internal database is used.

  • overwrite (bool) -- Whether to upload the property type or overwrite it. WARNING: Overwrite is done on ALL fields.

  • verbose (bool) -- Extra information printed to console.

pygaps.parsing.sqlite.isotherm_property_types_from_db(db_path: str = None, verbose: bool = True, **kwargs: dict) → list[dict][source]#

Get all isotherm property types.

Parameters:

  • db_path (str, None) -- Path to the database. If none is specified, internal database is used.

  • verbose (bool) -- Extra information printed to console.

Returns:

dict -- dict of property types

pygaps.parsing.sqlite.isotherm_property_type_delete_db(property_type: str, db_path: str = None, verbose: bool = True, **kwargs: dict)[source]#

Delete isotherm property type in the database.

Parameters:

  • property_type (str) -- Property type to delete.

  • db_path (str, None) -- Path to the database. If none is specified, internal database is used.

  • verbose (bool) -- Extra information printed to console.

NIST ISODB#

Interaction with the NIST ISODB.

pygaps.parsing.isodb.isotherm_from_isodb(filename)[source]#

Load an isotherm from the NIST ISODB.

Parameters:

filename (str) -- ISODB filename to retrieve using the API.

Returns:

Isotherm -- The isotherm from ISODB.