oepandas-mae

Maestro file format support for oepandas. Reads and writes .mae, .mae.gz, and .maegz files as pandas DataFrames following oepandas conventions.

This only requires a valid OpenEye Toolkit license. You do not need to have any Schrodinger software installed.

Installation

Install as an oepandas extra:

pip install oepandas[mae]

Or install standalone:

pip install oepandas-mae

Requirements: Python 3.10+, oepandas >= 3.2.0, oemaestro >= 0.8.1, OpenEye Toolkits

Quick Start

import oepandas as oepd

df = oepd.read_mae("tests/assets/5.maegz")
print(df)

Prints:

                                            Molecule          Title ...
0  <oechem.OEMol; proxy of <Swig Object of type '...        Aspirin ...
1  <oechem.OEMol; proxy of <Swig Object of type '...      Ibuprofen ...
2  <oechem.OEMol; proxy of <Swig Object of type '...  Acetaminophen ...
3  <oechem.OEMol; proxy of <Swig Object of type '...       Caffeine ...
4  <oechem.OEMol; proxy of <Swig Object of type '...       Diazepam ...

[5 rows x 16 columns]

Usage

Column Naming

Rename the molecule and title columns, or suppress the title column entirely:

import oepandas as oepd
df = oepd.read_mae("tests/assets/5.maegz", molecule_column="Mol", title_column="Name")
df = oepd.read_mae("tests/assets/5.maegz", no_title=True)

Selecting Columns

Use usecols to include only specific data columns:

df = read_mae("tests/assets/5.maegz", usecols=["NumAcceptors", "NumDonors"])

Numeric Conversion

CT property values are strings by default. Use numeric to convert columns:

# Convert a single column
df = read_mae("file.mae", numeric="pdb_tfactor")

# Convert multiple columns
df = read_mae("file.mae", numeric=["pdb_tfactor", "occupancy"])

# Specify downcast types
df = read_mae("file.mae", numeric={"pdb_tfactor": "float", "atom_count": "integer"})

SMILES Columns

Add SMILES string columns alongside the molecule objects:

df = oepd.read_mae("file.mae", add_smiles=True)
# Creates a "Molecule SMILES" column

Conformer Grouping

Consecutive structures in a Maestro file can be grouped into multi-conformer molecules:

df = read_mae("file.mae", conformer_test="absolute")

Available conformer tests:

• "default" -- groups consecutive molecules with matching titles
• "absolute" -- requires identical atom/bond ordering, properties, and title
• "absolute_canonical" -- requires matching canonical SMILES
• "isomeric" -- like absolute, but also requires matching stereochemistry
• "omega" -- like isomeric, plus invertible nitrogen stereochemistry

Tag Formatting

Maestro property keys follow a type_owner_name convention (e.g., r_pdb_PDB_CRYST1_a). By default, only the name portion is used as the column name. Control this with tags:

import oepandas as oepd
from oepandas_mae import TAG_ALL, TAG_NAME, TAG_NONE

# Default: clean names only (e.g., "PDB_CRYST1_a")
df = oepd.read_mae("file.mae")

# Full Maestro keys (e.g., "r_pdb_PDB_CRYST1_a")
df = oepd.read_mae("file.mae", tags=TAG_ALL)

# No data columns (molecules and titles only)
df = oepd.read_mae("file.mae", tags=TAG_NONE)

Perception Control

Control post-parse chemical perception with the perception parameter:

from oepandas_mae import read_mae, PERCEPTION_NONE

df = oepd.read_mae("file.mae", perception=PERCEPTION_NONE)

By default, only limited molecule perception occurs in order to respect what is specified in the Maestro file.

Configuration Object

For repeated use, pass an OEMaestroReaderConfig object. Keyword arguments override config values:

from oepandas_mae import read_mae, OEMaestroReaderConfig, TAG_ALL

config = OEMaestroReaderConfig()
config.tags = TAG_ALL

df = oepd.read_mae("file.mae", config=config)
df = oepd.read_mae("file.mae", config=config, tags=TAG_NAME)  # tags overrides config

Writing Maestro Files

Write a DataFrame back to a Maestro file with the chem accessor:

import oepandas as oepd

df = oepd.read_mae("tests/assets/5.maegz")
df.chem.to_mae("out.mae")

Data column values are stored as typed Maestro CT properties. The Maestro type is inferred from each column's pandas dtype (int → i_, float → r_, bool → b_, everything else → s_), so numeric columns round-trip as numbers. A column whose name is already a full Maestro key (e.g. r_m_pdb_tfactor) is written verbatim, preserving its exact type and owner.

# Choose the molecule/title columns and restrict which data columns are written
df.chem.to_mae("out.mae", molecule_column="Molecule", title_column="Title", columns=["NumDonors"])

# Compressed output (auto-detected from the extension)
df.chem.to_mae("out.mae.gz")

# Append to an existing file (not supported for compressed files)
df.chem.to_mae("out.mae", append=True)

# Write the DataFrame index and set the owner segment for clean column names
df.chem.to_mae("out.mae", index=True, index_tag="row_id", default_owner="myapp")

Extra molecule columns are written as SMILES strings. If two columns resolve to the same Maestro key, to_mae raises a ValueError rather than silently dropping data.

License

MIT