# Saiph TK

> ETL (Extract, Transform, Load) toolkit for molecular data file conversion and processing

## Links
- [Full Documentation](https://docs.eyesopen.com/toolkits/python/saiphtk/index.html)
- [Code Examples](https://docs.eyesopen.com/toolkits/python/saiphtk/examples.html)
- [API Reference](https://docs.eyesopen.com/toolkits/python/saiphtk/api.html)

## Core API - Function Quick Reference

### File Converters

**OEMolFileConverter()**
  Use for: Converting any OEChem-readable molecular file format to OERecord format
  Example: `converter = OEMolFileConverter(); converter.Open("molecules.sdf", options)`
  See: https://docs.eyesopen.com/toolkits/python/saiphtk/OESaiphClasses/OEMolFileConverter.html

**OESmilesFileConverter()**
  Use for: Converting SMILES files (SMI, ISM, CAN, CXSMILES, USM) to OERecord format
  Example: `converter = OESmilesFileConverter(); converter.Open("molecules.smi", options)`
  See: https://docs.eyesopen.com/toolkits/python/saiphtk/OESaiphClasses/OESmilesFileConverter.html

**OECSVFileConverter()**
  Use for: Converting CSV files to OERecord format
  Example: `converter = OECSVFileConverter(); converter.Open("data.csv", options)`
  See: https://docs.eyesopen.com/toolkits/python/saiphtk/OESaiphClasses/OECSVFileConverter.html

**OEDUFileConverter()**
  Use for: Converting Design Unit files to OERecord format
  Example: `converter = OEDUFileConverter(); converter.Open("design_units.oedu")`
  See: https://docs.eyesopen.com/toolkits/python/saiphtk/OESaiphClasses/OEDUFileConverter.html

**OEShapeQueryConverter()**
  Use for: Converting Shape Query files to OERecord format
  Example: `converter = OEShapeQueryConverter(); converter.Open("query.sq")`
  See: https://docs.eyesopen.com/toolkits/python/saiphtk/OESaiphClasses/OEShapeQueryConverter.html

**ArchiveConverter()** (Python only)
  Use for: Converting tarball or zip archives containing molecular files to OERecord
  Example: `for record in ArchiveConverter("molecules.tar.gz"): process(record)`
  See: https://docs.eyesopen.com/toolkits/python/saiphtk/OESaiphClasses/ArchiveConverter.html

### Converter Operations

**converter.Open(filename: str, options: OEConversionOptionsBase = None) -> bool**
  Use for: Opening a file for conversion with optional conversion settings
  Example: `success = converter.Open("input.sdf", mol_options)`
  See: Converter class documentation

**converter.GetNextRecord(record: OEMolRecord) -> SaiphReturnCode**
  Use for: Iterating through file records one at a time
  Example: `while converter.GetNextRecord(record) == SaiphReturnCode.Success: process(record)`
  Returns: Success, Fail, or EndOfFile
  See: Converter class documentation

### Conversion Options

**OEMolConversionOptions()**
  Use for: Configuring molecular file conversion behavior (SD data, conformers, generic data)
  Example: `opts = OEMolConversionOptions(); opts.SetClearSDData(True)`
  See: https://docs.eyesopen.com/toolkits/python/saiphtk/OESaiphClasses/OEMolConversionOptions.html

**OECSVConversionOptions()**
  Use for: Configuring CSV file conversion (delimiter settings)
  Example: `opts = OECSVConversionOptions(); opts.SetDelimiter(',')`
  See: https://docs.eyesopen.com/toolkits/python/saiphtk/OESaiphClasses/OECSVConversionOptions.html

**OERecordToCSVOptions()**
  Use for: Configuring OERecord to CSV conversion (delimiter settings)
  Example: `opts = OERecordToCSVOptions(); opts.SetDelimiter('\t')`
  See: https://docs.eyesopen.com/toolkits/python/saiphtk/OESaiphClasses/OERecordToCSVOptions.html

### Record Conversion Functions

**GetConverter(filename: str) -> OEConverterBase**
  Use for: Automatically selecting the best converter for a file based on extension
  Example: `converter = GetConverter("molecules.sdf")`
  See: https://docs.eyesopen.com/toolkits/python/saiphtk/OESaiphFunctions/GetConverter.html

**OEMolToRecord(mol: OEMolBase, record: OERecord) -> bool**
  Use for: Converting an OEMol object to an OERecord
  Example: `success = OEMolToRecord(molecule, record)`
  See: https://docs.eyesopen.com/toolkits/python/saiphtk/OESaiphFunctions/OEMolToRecord.html

**OERecordToMol(record: OERecord, mol: OEMolBase) -> bool**
  Use for: Converting an OERecord back to an OEMol object
  Example: `success = OERecordToMol(record, molecule)`
  See: https://docs.eyesopen.com/toolkits/python/saiphtk/OESaiphFunctions/OERecordToMol.html

**OERecordToDesignUnit(record: OERecord, du: OEDesignUnit) -> bool**
  Use for: Converting an OERecord to an OEDesignUnit object
  Example: `success = OERecordToDesignUnit(record, design_unit)`
  See: https://docs.eyesopen.com/toolkits/python/saiphtk/OESaiphFunctions/OERecordToDesignUnit.html

### Direct File Conversion

**OERecordToCSV()**
  Use for: Directly converting record-based files to CSV format
  Example: `converter = OERecordToCSV(); converter.Open("input.sdf", "output.csv", options)`
  See: https://docs.eyesopen.com/toolkits/python/saiphtk/OESaiphClasses/OERecordToCSV.html

**read_record_file_to_dataframe(filename: str, options: OEConversionOptionsBase = None) -> DataFrame** (Python only)
  Use for: Converting any OEChem-readable file directly to a Pandas DataFrame
  Example: `df = read_record_file_to_dataframe("molecules.sdf")`
  Requires: Pandas library installed
  See: https://docs.eyesopen.com/toolkits/python/saiphtk/OESaiphFunctions/read_record_file_to_dataframe.html

### Conversion Options Methods

**options.SetClearSDData(clear: bool)**
  Use for: Controlling whether SD data is cleared during conversion
  Example: `options.SetClearSDData(True)`
  Common in: OEMolConversionOptions

**options.SetMolTitleColumn(column: str)**
  Use for: Specifying which column to use as molecule title
  Example: `options.SetMolTitleColumn("compound_id")`
  Common in: OEMolConversionOptions

**options.SetDelimiter(delim: str)**
  Use for: Setting the delimiter character for CSV files
  Example: `options.SetDelimiter('\t')`
  Common in: OECSVConversionOptions, OERecordToCSVOptions

**options.SetGenericData(key: str, value: str)**
  Use for: Adding custom metadata to conversion options
  Example: `options.SetGenericData("source", "vendor_library")`
  Common in: OEConversionOptionsBase subclasses

**options.GetGenericData(key: str) -> str**
  Use for: Retrieving custom metadata from conversion options
  Example: `source = options.GetGenericData("source")`
  Common in: OEConversionOptionsBase subclasses

## Common Patterns - Complete Working Examples

### Pattern: Convert SDF File to OERecords

```python
from openeye.oechem import OEMolRecord
from openeye.oesaiph import OEMolFileConverter, OEMolConversionOptions, SaiphReturnCode

# Setup converter with options
converter = OEMolFileConverter()
options = OEMolConversionOptions()
options.SetClearSDData(False)  # Keep SD data

# Open file and iterate through records
converter.Open("molecules.sdf", options)
record = OEMolRecord()
while converter.GetNextRecord(record) == SaiphReturnCode.Success:
    # Process each record
    print(f"Processing record: {record.GetTitle()}")
```
Use when: You need to process molecular files record-by-record with control over conversion settings

### Pattern: Auto-Select Converter for Any File

```python
from openeye.oechem import OEMolRecord
from openeye.oesaiph import GetConverter, SaiphReturnCode

# Automatically get the right converter
converter = GetConverter("molecules.smi")

# Open and process
converter.Open("molecules.smi")
record = OEMolRecord()
while converter.GetNextRecord(record) == SaiphReturnCode.Success:
    # Process record
    data = record.GetData()
    print(f"Record has {len(data)} fields")
```
Use when: You want automatic converter selection based on file extension without specifying converter type

### Pattern: Convert SMILES File with Custom Title Column

```python
from openeye.oechem import OEMolRecord
from openeye.oesaiph import OESmilesFileConverter, OEMolConversionOptions, SaiphReturnCode

# Setup with title column specification
converter = OESmilesFileConverter()
options = OEMolConversionOptions()
options.SetMolTitleColumn("compound_id")

# Process SMILES file
converter.Open("compounds.smi", options)
record = OEMolRecord()
while converter.GetNextRecord(record) == SaiphReturnCode.Success:
    title = record.GetTitle()
    print(f"Compound: {title}")
```
Use when: Processing SMILES files where molecule names are in a specific column

### Pattern: Convert OERecord to OEMol

```python
from openeye.oechem import OEGraphMol, OEMolRecord
from openeye.oesaiph import OERecordToMol, OEMolFileConverter, SaiphReturnCode

# Get record from file
converter = OEMolFileConverter()
converter.Open("molecules.sdf")
record = OEMolRecord()
converter.GetNextRecord(record)

# Convert to OEMol
mol = OEGraphMol()
if OERecordToMol(record, mol):
    print(f"Converted to molecule with {mol.NumAtoms()} atoms")
```
Use when: You need to convert OERecord back to OEMol for molecular operations

### Pattern: Convert OEMol to OERecord

```python
from openeye.oechem import OEGraphMol, OEMolRecord, OESmilesToMol
from openeye.oesaiph import OEMolToRecord

# Create molecule
mol = OEGraphMol()
OESmilesToMol(mol, "CCO")
mol.SetTitle("ethanol")

# Convert to record
record = OEMolRecord()
if OEMolToRecord(mol, record):
    print(f"Created record: {record.GetTitle()}")
    print(f"Record data: {record.GetData()}")
```
Use when: You need to convert OEMol to OERecord format for storage or transmission

### Pattern: Convert File Directly to Pandas DataFrame

```python
from openeye.oesaiph import read_record_file_to_dataframe
from openeye.oesaiph import OEMolConversionOptions

# Setup options
options = OEMolConversionOptions()
options.SetClearSDData(False)

# Convert to DataFrame
df = read_record_file_to_dataframe("molecules.sdf", options)
print(f"Loaded {len(df)} molecules")
print(df.head())
```
Use when: You want to quickly load molecular data into Pandas for analysis (requires Pandas installed)

### Pattern: Process CSV File with Custom Delimiter

```python
from openeye.oechem import OEMolRecord
from openeye.oesaiph import OECSVFileConverter, OECSVConversionOptions, SaiphReturnCode

# Setup CSV converter with tab delimiter
converter = OECSVFileConverter()
options = OECSVConversionOptions()
options.SetDelimiter('\t')

# Process tab-delimited file
converter.Open("data.tsv", options)
record = OEMolRecord()
while converter.GetNextRecord(record) == SaiphReturnCode.Success:
    data = record.GetData()
    print(f"Row data: {data}")
```
Use when: Processing CSV/TSV files with non-standard delimiters

### Pattern: Convert Design Unit File to Records

```python
from openeye.oechem import OEMolRecord
from openeye.oesaiph import OEDUFileConverter, SaiphReturnCode

# Setup Design Unit converter
converter = OEDUFileConverter()
converter.Open("design_units.oedu")

# Process each design unit
record = OEMolRecord()
while converter.GetNextRecord(record) == SaiphReturnCode.Success:
    print(f"Design unit: {record.GetTitle()}")
    # Access design unit data from record
```
Use when: Processing OEDesignUnit files in record format

### Pattern: Convert OERecord to OEDesignUnit

```python
from openeye.oechem import OEMolRecord, OEDesignUnit
from openeye.oesaiph import OERecordToDesignUnit, OEDUFileConverter, SaiphReturnCode

# Get record from DU file
converter = OEDUFileConverter()
converter.Open("design_units.oedu")
record = OEMolRecord()
converter.GetNextRecord(record)

# Convert to OEDesignUnit
du = OEDesignUnit()
if OERecordToDesignUnit(record, du):
    print(f"Converted to design unit: {du.GetTitle()}")
```
Use when: You need to convert OERecord back to OEDesignUnit for docking or structure operations

### Pattern: Convert File to CSV Format

```python
from openeye.oesaiph import OERecordToCSV, OERecordToCSVOptions

# Setup CSV output options
converter = OERecordToCSV()
options = OERecordToCSVOptions()
options.SetDelimiter(',')

# Convert SDF to CSV
converter.Open("molecules.sdf", "output.csv", options)
print("Conversion complete")
```
Use when: You need to convert molecular files directly to CSV format for spreadsheet analysis

### Pattern: Process Compressed Archive Files (Python)

```python
from openeye.oesaiph import ArchiveConverter

# Process all files in archive
for record in ArchiveConverter("molecules.tar.gz"):
    print(f"Processing: {record.GetTitle()}")
    data = record.GetData()
    # Process each record from archive
```
Use when: You have molecular data in compressed archives (tar.gz, zip) and want to process without extracting

### Pattern: Set Schema for Shape Query Extraction

```python
from openeye.oechem import OEMolRecord
from openeye.oesaiph import OEShapeQueryConverter, SaiphReturnCode

# Setup Shape Query converter
converter = OEShapeQueryConverter()
converter.Open("query.sq")

# Extract shape query records
record = OEMolRecord()
while converter.GetNextRecord(record) == SaiphReturnCode.Success:
    # Process shape query data
    print(f"Shape query: {record.GetTitle()}")
```
Use when: Processing Shape Query files for shape-based virtual screening

### Pattern: Handle Conversion Errors

```python
from openeye.oechem import OEMolRecord
from openeye.oesaiph import OEMolFileConverter, SaiphReturnCode

converter = OEMolFileConverter()
if not converter.Open("molecules.sdf"):
    print("Failed to open file")
    exit(1)

record = OEMolRecord()
while True:
    result = converter.GetNextRecord(record)
    if result == SaiphReturnCode.Success:
        # Process record
        pass
    elif result == SaiphReturnCode.EndOfFile:
        break
    else:  # SaiphReturnCode.Fail
        print(f"Error processing record")
```
Use when: You need robust error handling during file conversion

## API Decision Guide

- **For converting any molecular file format**: use `OEMolFileConverter` (works with any OEIsReadable format)
- **For SMILES-specific files**: use `OESmilesFileConverter` (optimized for SMI, ISM, CAN, CXSMILES, USM)
- **For CSV/TSV files**: use `OECSVFileConverter` (handles delimiter configuration)
- **For Design Unit files**: use `OEDUFileConverter` (specialized for .oedu format)
- **For Shape Query files**: use `OEShapeQueryConverter` (specialized for .sq format)
- **For compressed archives**: use `ArchiveConverter` (Python only, auto-detects file types in tar/zip)
- **For automatic converter selection**: use `GetConverter(filename)` (chooses based on file extension)

- **OEMolFileConverter vs OESmilesFileConverter**: use OEMolFileConverter for general molecular formats (SDF, MOL2, etc.), use OESmilesFileConverter specifically for SMILES variants when you need SMILES-specific handling

- **For direct CSV output**: use `OERecordToCSV` (converts files directly to CSV without iteration)
- **For Pandas integration**: use `read_record_file_to_dataframe` (Python only, requires Pandas)

- **For OERecord → OEMol conversion**: use `OERecordToMol` (when you need molecular operations)
- **For OEMol → OERecord conversion**: use `OEMolToRecord` (when you need record format)
- **For OERecord → OEDesignUnit conversion**: use `OERecordToDesignUnit` (when working with docking)

- **For controlling SD data**: use `OEMolConversionOptions.SetClearSDData()` (True to remove, False to keep)
- **For custom molecule titles**: use `OEMolConversionOptions.SetMolTitleColumn()` (specify column name)
- **For CSV delimiters**: use `OECSVConversionOptions.SetDelimiter()` or `OERecordToCSVOptions.SetDelimiter()`

## Common Parameters & Types

**OEMolRecord**: Container for molecular record data
  - Create with: `record = OEMolRecord()`
  - Common in: All converter GetNextRecord() methods, OEMolToRecord, OERecordToMol
  - Gotcha: Must be reused in iteration loops (passed to GetNextRecord repeatedly)
  - Methods: `GetTitle()`, `GetData()`, `SetTitle()`

**OEMolConversionOptions**: Configuration for molecular file conversion
  - Create with: `options = OEMolConversionOptions()`
  - Common in: OEMolFileConverter, OESmilesFileConverter
  - Key methods: `SetClearSDData(bool)`, `SetMolTitleColumn(str)`, `SetGenericData(key, value)`
  - Typical use: Configure SD data handling and title column selection

**OECSVConversionOptions**: Configuration for CSV file conversion
  - Create with: `options = OECSVConversionOptions()`
  - Common in: OECSVFileConverter
  - Key methods: `SetDelimiter(str)`
  - Typical values: `','` for CSV, `'\t'` for TSV

**OERecordToCSVOptions**: Configuration for record-to-CSV conversion
  - Create with: `options = OERecordToCSVOptions()`
  - Common in: OERecordToCSV
  - Key methods: `SetDelimiter(str)`
  - Typical values: `','` for CSV, `'\t'` for TSV

**SaiphReturnCode**: Enum for conversion operation results
  - Values: `Success`, `Fail`, `EndOfFile`
  - Common in: All GetNextRecord() return values
  - Usage: `if result == SaiphReturnCode.Success:` for success checking
  - Gotcha: Check for `EndOfFile` to properly terminate iteration loops

**OEConversionOptionsBase**: Base class for all conversion options
  - Create with: Use specific subclass (OEMolConversionOptions, OECSVConversionOptions, etc.)
  - Common in: All converter Open() methods as optional parameter
  - Key methods: `SetGenericData(key, value)`, `GetGenericData(key)`
  - Use: Store custom metadata across conversions

**OEMolBase**: Base molecular object (OEGraphMol, OEMol)
  - Create with: `mol = OEGraphMol()` or `mol = OEMol()`
  - Common in: OERecordToMol, OEMolToRecord
  - Gotcha: Must be initialized before passing to conversion functions

**OEDesignUnit**: Design unit object for protein-ligand complexes
  - Create with: `du = OEDesignUnit()`
  - Common in: OERecordToDesignUnit, OEDUFileConverter
  - Use: Working with prepared protein-ligand structures for docking

## Return Types & Error Handling

```python
# Pattern 1: SaiphReturnCode returns (most common)
from openeye.oesaiph import SaiphReturnCode

result = converter.GetNextRecord(record)
if result == SaiphReturnCode.Success:
    # Process successful record
    pass
elif result == SaiphReturnCode.EndOfFile:
    # Normal termination
    break
else:  # SaiphReturnCode.Fail
    # Handle error
    print("Error processing record")

# Pattern 2: Boolean returns for conversion functions
success = OEMolToRecord(mol, record)
if not success:
    print("Conversion failed")
    # Handle error

success = OERecordToMol(record, mol)
if not success:
    print("Conversion failed")
    # Handle error

# Pattern 3: Boolean returns for file opening
if not converter.Open("file.sdf", options):
    print("Failed to open file")
    exit(1)

# Pattern 4: Iterator pattern (Python ArchiveConverter)
try:
    for record in ArchiveConverter("archive.tar.gz"):
        # Process each record
        pass
except Exception as e:
    print(f"Error processing archive: {e}")

# Pattern 5: DataFrame returns (Python only)
try:
    df = read_record_file_to_dataframe("molecules.sdf")
    if df is None or df.empty:
        print("No data loaded")
except Exception as e:
    print(f"Error loading DataFrame: {e}")