tesliper.writing.xlsx_writer

Data export to excel files.

Classes

XlsxWriter(destination[, mode, filename])

Writes extracted data to .xlsx file.
class tesliper.writing.xlsx_writer.XlsxWriter(destination: Union[str, pathlib.Path], mode: str = 'x', filename: str = 'tesliper-output.${ext}')[source]

Writes extracted data to .xlsx file.

Parameters

  • destination (str or pathlib.Path) – Directory, to which generated files should be written.

  • mode (str) – Specifies how writing to file should be handled. Should be one of characters: ‘a’ (append to existing file), ‘x’ (only write if file doesn’t exist yet), or ‘w’ (overwrite file if it already exists).

  • filename (str or string.Template) – Filename of created .xlsx file or a template for generation of the name using make_name() method.

write(data: List) → None[source]

Writes DataArray-like objects to disk, decides how to write them based on the type of each object. If some types of given objects are not supported by this writer, data of this type is ignored and a warning is emitted.

Parameters

data (List) – DataArray-like objects that should be written to disk.

generic(data: List[Union[tesliper.glassware.arrays.DataArray, tesliper.glassware.arrays.IntegerArray, tesliper.glassware.arrays.FloatArray, tesliper.glassware.arrays.BooleanArray, tesliper.glassware.arrays.InfoArray]], name_template: Union[str, string.Template] = '${cat}.${det}')[source]

Writes generic data from multiple DataArray-like objects to a single sheet. Said objects should provide a single value for each conformer.

Parameters

  • data – DataArray objects that are to be exported.

  • name_template – Template that will be used to generate filenames. Refer to make_name() documentation for details on supported placeholders.

overview(energies: Sequence[tesliper.glassware.arrays.Energies], frequencies: Optional[tesliper.glassware.arrays.DataArray] = None, stoichiometry: Optional[tesliper.glassware.arrays.InfoArray] = None, name_template: Union[str, string.Template] = '${cat}')[source]

Writes summarized information from multiple Energies objects to xlsx file. Creates a worksheet with energy values and calculated populations for each energy object given, as well as number of imaginary frequencies and stoichiometry of conformers if frequencies and stoichiometry are provided, respectively.

Parameters

  • energies (list of glassware.Energies) – Energies objects that are to be exported

  • frequencies (glassware.DataArray, optional) – DataArray object containing frequencies

  • stoichiometry (glassware.InfoArray, optional) – InfoArray object containing stoichiometry information

  • name_template (str or string.Template) – Template that will be used to generate filenames, defaults to “${cat}”. Refer to make_name() documentation for details on supported placeholders.

energies(energies: tesliper.glassware.arrays.Energies, corrections: Optional[tesliper.glassware.arrays.FloatArray] = None, name_template: Union[str, string.Template] = 'distribution-${genre}')[source]

Writes detailed information from multiple Energies objects to xlsx file. Creates one worksheet for each Energies object provided. The sheet contains energy values, energy difference to lowest-energy conformer, Boltzmann factor, population of each conformer and corrections, if those are provided.

Parameters

  • energies (list of glassware.Energies) – Energies objects that are to be exported

  • corrections (list of glassware.DataArray) – DataArray objects containing energies corrections

  • name_template (str or string.Template) – Template that will be used to generate filenames, defaults to “distribution-${genre}”. Refer to make_name() documentation for details on supported placeholders.

spectral_data(band: tesliper.glassware.arrays.SpectralActivities, data: Iterable[tesliper.glassware.arrays.SpectralData], name_template: Union[str, string.Template] = '${conf}.${cat}-${det}')[source]

Writes SpectralData objects to xlsx file (one sheet for each conformer).

Parameters

  • band (glassware.SpectralActivities) – object containing information about band at which transitions occur; it should be frequencies for vibrational data and wavelengths or excitation energies for electronic data

  • data (iterable of glassware.SpectralData) – SpectralData objects that are to be serialized; all should contain information for the same conformers. Assumes that all data’s elements have the same spectra_type, which is passed to the name_template as “det”.

  • name_template (str or string.Template) – Template that will be used to generate filenames, defaults to “${conf}.${cat}-${det}”. Refer to make_name() documentation for details on supported placeholders.

Raises

ValueError – if data is an empty sequence

spectral_activities(band: tesliper.glassware.arrays.SpectralActivities, data: Iterable[tesliper.glassware.arrays.SpectralActivities], name_template: Union[str, string.Template] = '${conf}.${cat}-${det}')[source]

Writes SpectralActivities objects to xlsx file (one sheet for each conformer).

Parameters

  • band (glassware.SpectralActivities) – object containing information about band at which transitions occur; it should be frequencies for vibrational data and wavelengths or excitation energies for electronic data

  • data (iterable of glassware.SpectralActivities) – SpectralActivities objects that are to be serialized; all should contain information for the same conformers. Assumes that all data’s elements have the same spectra_type, which is passed to the name_template as “det”.

  • name_template (str or string.Template) – Template that will be used to generate filenames, defaults to “${conf}.${cat}-${det}”. Refer to make_name() documentation for details on supported placeholders.

Raises

ValueError – if data is an empty sequence

spectra(spectra: tesliper.glassware.spectra.Spectra, name_template: Union[str, string.Template] = '${genre}')[source]

Writes given spectra collectively to one sheet of xlsx workbook.

Parameters

  • spectra (glassware.Spectra) – Spectra object, that is to be serialized

  • name_template (str or string.Template) – Template that will be used to generate filenames, defaults to “${genre}”. Refer to make_name() documentation for details on supported placeholders.

single_spectrum(spectrum: tesliper.glassware.spectra.SingleSpectrum, name_template: Union[str, string.Template] = '${cat}.${genre}-${det}')[source]

Writes SingleSpectrum object to new sheet of xlsx workbook.

Parameters

  • spectrum (glassware.SingleSpectrum) – spectrum, that is to be serialized

  • name_template (str or string.Template) – Template that will be used to generate sheet names, defaults to “${cat}.${genre}-${det}”. Refer to make_name() documentation for details on supported placeholders.

_get_handle(template: Union[str, string.Template], template_params: dict, open_params: Optional[dict] = None) → Iterator[IO]

Helper method for creating files. Given additional kwargs will be passed to Path.open() method. Implemented as context manager for use with with statement.

Parameters

  • template (str or string.Template) – Template that will be used to generate filenames.

  • template_params (dict) – Dictionary of {identifier: value} for .make_name method.

  • open_params (dict, optional) – Arguments for Path.open() used to open file.

Yields

  • IO – file handle, will be closed automatically after with statement exits

  • meta public:

_iter_handles(filenames: Iterable[str], template: Union[str, string.Template], template_params: dict, open_params: Optional[dict] = None) → Iterator[IO]

Helper method for iteration over generated files. Given additional kwargs will be passed to Path.open() method.

Parameters

  • filenames (list of str) – list of source filenames, used as value for ${conf} placeholder in name_template

  • template_params (dict) – Dictionary of {identifier: value} for .make_name method.

  • open_params (dict, optional) – arguments for Path.open() used to open file.

Yields

  • TextIO – file handle, will be closed automatically on next iteration

  • meta public:

property destination: pathlib.Path

Directory, to which generated files should be written.

Raises

FileNotFoundError – If given destination doesn’t exist or is not a directory.

Type

pathlib.Path

static distribute_data(data: List) → Tuple[Dict[str, List], Dict[str, Any]]

Sorts given data by genre category for use by specialized writing methods.

Returns

  • distr (dict) – Dictionary with DataArray-like objects, sorted by their type. Each {key: value} pair is {name of the type in lowercase format: list of DataArray objects of this type}.

  • extras (dict) – Spacial-case genres: extra information used by some writer methods when exporting data. Available {key: value} pairs (if given in data) are:

    corrections: dict of {“energy genre”: FloatArray},
    frequencies: Bands,
    wavelengths: Bands,
    excitation: Bands,
    stoichiometry: InfoArray,
    charge: IntegerArray,
    multiplicity: IntegerArray

geometry(geometry: tesliper.glassware.arrays.Geometry, charge: Optional[Union[tesliper.glassware.arrays.IntegerArray, Sequence[int], int]] = None, multiplicity: Optional[Union[tesliper.glassware.arrays.IntegerArray, Sequence[int], int]] = None, name_template: Union[str, string.Template] = '')

Interface for writing single object with geometry of each conformer. Evoked when handling Geometry objects.

Parameters

  • geometry – Positions of atoms in each conformer. Mandatory in custom implementation.

  • charge – Value of each structure’s charge. Mandatory in custom implementation.

  • multiplicity – Value of each structure’s multiplicity. Mandatory in custom implementation.

  • name_template – Template that defines naming scheme for files generated by this method. May be omitted in custom implementation.

Raises

NotImplementedError – Whenever called, this is an interface that should not be used directly.

make_name(template: Union[str, string.Template], conf: str = '', num: Union[str, int] = '', genre: str = '', cat: str = '', det: str = '', ext: str = '') → str

Create filename using given template and given or global values for known identifiers. The identifier should be used in the template as "${identifier}" where “identifier” is the name of identifier. Available names and their meaning are:

${ext} - appropriate file extension
${conf} - name of the conformer
${num} - number of the file according to internal counter
${genre} - genre of exported data
${cat} - category of produced output
${det} - category-specific detail

The ${ext} identifier is filled with the value of Writers extension attribute if not explicitly given as parameter to this method’s call. Values for other identifiers should be provided by the caller.

Parameters

  • template (str or string.Template) – Template that will be used to generate filenames. It should contain only known identifiers, listed above.

  • conf (str) – value for ${conf} identifier, defaults to empty string.

  • num (str or int) – value for ${str} identifier, defaults to empty string.

  • genre (str) – value for ${genre} identifier, defaults to empty string.

  • cat (str) – value for ${cat} identifier, defaults to empty string.

  • det (str) – value for ${det} identifier, defaults to empty string.

  • ext (str) – value for ${ext} identifier, defaults to empty string.

Raises

ValueError – If given template or string contains any unexpected identifiers.

Examples

Must be first subclassed and instantiated:

>>> class MyWriter(WriterBase):
>>>     extension = "foo"
>>> wrt = MyWriter("/path/to/some/directory/")

>>> wrt.make_name(template="somefile.${ext}")
"somefile.foo"
>>> wrt.make_name(template="${conf}.${ext}")
".foo"  # conf is empty string by default
>>> wrt.make_name(template="${conf}.${ext}", conf="conformer")
"conformer.foo"
>>> wrt.make_name(template="Unknown_identifier_${bla}.${ext}")
Traceback (most recent call last):
ValueError: Unexpected identifiers given: bla.
property mode

Specifies how writing to file should be handled. Should be one of characters: “a”, “x”, or “w”. “a” - append to existing file; “x” - only write if file doesn’t exist yet; “w” - overwrite file if it already exists.

Raises

ValueError – If given anything other than “a”, “x”, or “w”.

transitions(transitions: tesliper.glassware.arrays.Transitions, wavelengths: tesliper.glassware.arrays.Bands, only_highest=True, name_template: Union[str, string.Template] = '${conf}.${cat}-${det}')[source]

Writes electronic transitions data to xlsx file (one sheet for each conformer).

Parameters

  • transitions (glassware.Transitions) – Electronic transitions data that should be serialized.

  • wavelengths (glassware.ElectronicActivities) – Object containing information about wavelength at which transitions occur.

  • only_highest (bool) – Specifies if only transition of highest contribution to given band should be reported. If False all transition are saved to file. Defaults to True.

  • name_template (str or string.Template) – Template that will be used to generate filenames, defaults to “${conf}.${cat}-${det}”. Refer to make_name() documentation for details on supported placeholders.