@synsci/cli-darwin-x64 1.1.76 → 1.1.78

package/bin/skills/datamol/references/io_module.md

@@ -0,0 +1,109 @@
+# Datamol I/O Module Reference
+
+The `datamol.io` module provides comprehensive file handling for molecular data across multiple formats.
+
+## Reading Molecular Files
+
+### `dm.read_sdf(filename, sanitize=True, remove_hs=True, as_df=True, mol_column='mol', ...)`
+Read Structure-Data File (SDF) format.
+- **Parameters**:
+  - `filename`: Path to SDF file (supports local and remote paths via fsspec)
+  - `sanitize`: Apply sanitization to molecules
+  - `remove_hs`: Remove explicit hydrogens
+  - `as_df`: Return as DataFrame (True) or list of molecules (False)
+  - `mol_column`: Name of molecule column in DataFrame
+  - `n_jobs`: Enable parallel processing
+- **Returns**: DataFrame or list of molecules
+- **Example**: `df = dm.read_sdf("compounds.sdf")`
+
+### `dm.read_smi(filename, smiles_column='smiles', mol_column='mol', as_df=True, ...)`
+Read SMILES file (space-delimited by default).
+- **Common format**: SMILES followed by molecule ID/name
+- **Example**: `df = dm.read_smi("molecules.smi")`
+
+### `dm.read_csv(filename, smiles_column='smiles', mol_column=None, ...)`
+Read CSV file with optional automatic SMILES-to-molecule conversion.
+- **Parameters**:
+  - `smiles_column`: Column containing SMILES strings
+  - `mol_column`: If specified, creates molecule objects from SMILES column
+- **Example**: `df = dm.read_csv("data.csv", smiles_column="SMILES", mol_column="mol")`
+
+### `dm.read_excel(filename, sheet_name=0, smiles_column='smiles', mol_column=None, ...)`
+Read Excel files with molecule handling.
+- **Parameters**:
+  - `sheet_name`: Sheet to read (index or name)
+  - Other parameters similar to `read_csv`
+- **Example**: `df = dm.read_excel("compounds.xlsx", sheet_name="Sheet1")`
+
+### `dm.read_molblock(molblock, sanitize=True, remove_hs=True)`
+Parse MOL block string (molecular structure text representation).
+
+### `dm.read_mol2file(filename, sanitize=True, remove_hs=True, cleanupSubstructures=True)`
+Read Mol2 format files.
+
+### `dm.read_pdbfile(filename, sanitize=True, remove_hs=True, proximityBonding=True)`
+Read Protein Data Bank (PDB) format files.
+
+### `dm.read_pdbblock(pdbblock, sanitize=True, remove_hs=True, proximityBonding=True)`
+Parse PDB block string.
+
+### `dm.open_df(filename, ...)`
+Universal DataFrame reader - automatically detects format.
+- **Supported formats**: CSV, Excel, Parquet, JSON, SDF
+- **Example**: `df = dm.open_df("data.csv")` or `df = dm.open_df("molecules.sdf")`
+
+## Writing Molecular Files
+
+### `dm.to_sdf(mols, filename, mol_column=None, ...)`
+Write molecules to SDF file.
+- **Input types**:
+  - List of molecules
+  - DataFrame with molecule column
+  - Sequence of molecules
+- **Parameters**:
+  - `mol_column`: Column name if input is DataFrame
+- **Example**:
+  ```python
+  dm.to_sdf(mols, "output.sdf")
+  # or from DataFrame
+  dm.to_sdf(df, "output.sdf", mol_column="mol")
+  ```
+
+### `dm.to_smi(mols, filename, mol_column=None, ...)`
+Write molecules to SMILES file with optional validation.
+- **Format**: SMILES strings with optional molecule names/IDs
+
+### `dm.to_xlsx(df, filename, mol_columns=None, ...)`
+Export DataFrame to Excel with rendered molecular images.
+- **Parameters**:
+  - `mol_columns`: Columns containing molecules to render as images
+- **Special feature**: Automatically renders molecules as images in Excel cells
+- **Example**: `dm.to_xlsx(df, "molecules.xlsx", mol_columns=["mol"])`
+
+### `dm.to_molblock(mol, ...)`
+Convert molecule to MOL block string.
+
+### `dm.to_pdbblock(mol, ...)`
+Convert molecule to PDB block string.
+
+### `dm.save_df(df, filename, ...)`
+Save DataFrame in multiple formats (CSV, Excel, Parquet, JSON).
+
+## Remote File Support
+
+All I/O functions support remote file paths through fsspec integration:
+- **Supported protocols**: S3 (AWS), GCS (Google Cloud), Azure, HTTP/HTTPS
+- **Example**:
+  ```python
+  dm.read_sdf("s3://bucket/compounds.sdf")
+  dm.read_csv("https://example.com/data.csv")
+  ```
+
+## Key Parameters Across Functions
+
+- **`sanitize`**: Apply molecule sanitization (default: True)
+- **`remove_hs`**: Remove explicit hydrogens (default: True)
+- **`as_df`**: Return DataFrame vs list (default: True for most functions)
+- **`n_jobs`**: Enable parallel processing (None = all cores, 1 = sequential)
+- **`mol_column`**: Name of molecule column in DataFrames
+- **`smiles_column`**: Name of SMILES column in DataFrames

package/bin/skills/datamol/references/reactions_data.md

@@ -0,0 +1,218 @@
+# Datamol Reactions and Data Modules Reference
+
+## Reactions Module (`datamol.reactions`)
+
+The reactions module enables programmatic application of chemical transformations using SMARTS reaction patterns.
+
+### Applying Chemical Reactions
+
+#### `dm.reactions.apply_reaction(rxn, reactants, as_smiles=False, sanitize=True, single_product_group=True, rm_attach=True, product_index=0)`
+Apply a chemical reaction to reactant molecules.
+- **Parameters**:
+  - `rxn`: Reaction object (from SMARTS pattern)
+  - `reactants`: Tuple of reactant molecules
+  - `as_smiles`: Return SMILES strings (True) or molecule objects (False)
+  - `sanitize`: Sanitize product molecules
+  - `single_product_group`: Return single product (True) or all product groups (False)
+  - `rm_attach`: Remove attachment point markers
+  - `product_index`: Which product to return from reaction
+- **Returns**: Product molecule(s) or SMILES
+- **Example**:
+  ```python
+  from rdkit import Chem
+
+  # Define reaction: alcohol + carboxylic acid → ester
+  rxn = Chem.rdChemReactions.ReactionFromSmarts(
+      '[C:1][OH:2].[C:3](=[O:4])[OH:5]>>[C:1][O:2][C:3](=[O:4])'
+  )
+
+  # Apply to reactants
+  alcohol = dm.to_mol("CCO")
+  acid = dm.to_mol("CC(=O)O")
+  product = dm.reactions.apply_reaction(rxn, (alcohol, acid))
+  ```
+
+### Creating Reactions
+
+Reactions are typically created from SMARTS patterns using RDKit:
+```python
+from rdkit.Chem import rdChemReactions
+
+# Reaction pattern: [reactant1].[reactant2]>>[product]
+rxn = rdChemReactions.ReactionFromSmarts(
+    '[1*][*:1].[1*][*:2]>>[*:1][*:2]'
+)
+```
+
+### Validation Functions
+
+The module includes functions to:
+- **Check if molecule is reactant**: Verify if molecule matches reactant pattern
+- **Validate reaction**: Check if reaction is synthetically reasonable
+- **Process reaction files**: Load reactions from files or databases
+
+### Common Reaction Patterns
+
+**Amide formation**:
+```python
+# Amine + carboxylic acid → amide
+amide_rxn = rdChemReactions.ReactionFromSmarts(
+    '[N:1].[C:2](=[O:3])[OH]>>[N:1][C:2](=[O:3])'
+)
+```
+
+**Suzuki coupling**:
+```python
+# Aryl halide + boronic acid → biaryl
+suzuki_rxn = rdChemReactions.ReactionFromSmarts(
+    '[c:1][Br].[c:2][B]([OH])[OH]>>[c:1][c:2]'
+)
+```
+
+**Functional group transformations**:
+```python
+# Alcohol → ester
+esterification = rdChemReactions.ReactionFromSmarts(
+    '[C:1][OH:2].[C:3](=[O:4])[Cl]>>[C:1][O:2][C:3](=[O:4])'
+)
+```
+
+### Workflow Example
+
+```python
+import datamol as dm
+from rdkit.Chem import rdChemReactions
+
+# 1. Define reaction
+rxn_smarts = '[C:1](=[O:2])[OH:3]>>[C:1](=[O:2])[Cl:3]'  # Acid → acid chloride
+rxn = rdChemReactions.ReactionFromSmarts(rxn_smarts)
+
+# 2. Apply to molecule library
+acids = [dm.to_mol(smi) for smi in acid_smiles_list]
+acid_chlorides = []
+
+for acid in acids:
+    try:
+        product = dm.reactions.apply_reaction(
+            rxn,
+            (acid,),  # Single reactant as tuple
+            sanitize=True
+        )
+        acid_chlorides.append(product)
+    except Exception as e:
+        print(f"Reaction failed: {e}")
+
+# 3. Validate products
+valid_products = [p for p in acid_chlorides if p is not None]
+```
+
+### Key Concepts
+
+- **SMARTS**: SMiles ARbitrary Target Specification - pattern language for reactions
+- **Atom Mapping**: Numbers like [C:1] preserve atom identity through reaction
+- **Attachment Points**: [1*] represents generic connection points
+- **Reaction Validation**: Not all SMARTS reactions are chemically reasonable
+
+---
+
+## Data Module (`datamol.data`)
+
+The data module provides convenient access to curated molecular datasets for testing and learning.
+
+### Available Datasets
+
+#### `dm.data.cdk2(as_df=True, mol_column='mol')`
+RDKit CDK2 dataset - kinase inhibitor data.
+- **Parameters**:
+  - `as_df`: Return as DataFrame (True) or list of molecules (False)
+  - `mol_column`: Name for molecule column
+- **Returns**: Dataset with molecular structures and activity data
+- **Use case**: Small dataset for algorithm testing
+- **Example**:
+  ```python
+  cdk2_df = dm.data.cdk2(as_df=True)
+  print(cdk2_df.shape)
+  print(cdk2_df.columns)
+  ```
+
+#### `dm.data.freesolv()`
+FreeSolv dataset - experimental and calculated hydration free energies.
+- **Contents**: 642 molecules with:
+  - IUPAC names
+  - SMILES strings
+  - Experimental hydration free energy values
+  - Calculated values
+- **Warning**: "Only meant to be used as a toy dataset for pedagogic and testing purposes"
+- **Not suitable for**: Benchmarking or production model training
+- **Example**:
+  ```python
+  freesolv_df = dm.data.freesolv()
+  # Columns: iupac, smiles, expt (kcal/mol), calc (kcal/mol)
+  ```
+
+#### `dm.data.solubility(as_df=True, mol_column='mol')`
+RDKit solubility dataset with train/test splits.
+- **Contents**: Aqueous solubility data with pre-defined splits
+- **Columns**: Includes 'split' column with 'train' or 'test' values
+- **Use case**: Testing ML workflows with proper train/test separation
+- **Example**:
+  ```python
+  sol_df = dm.data.solubility(as_df=True)
+
+  # Split into train/test
+  train_df = sol_df[sol_df['split'] == 'train']
+  test_df = sol_df[sol_df['split'] == 'test']
+
+  # Use for model development
+  X_train = dm.to_fp(train_df[mol_column])
+  y_train = train_df['solubility']
+  ```
+
+### Usage Guidelines
+
+**For testing and tutorials**:
+```python
+# Quick dataset for testing code
+df = dm.data.cdk2()
+mols = df['mol'].tolist()
+
+# Test descriptor calculation
+descriptors_df = dm.descriptors.batch_compute_many_descriptors(mols)
+
+# Test clustering
+clusters = dm.cluster_mols(mols, cutoff=0.3)
+```
+
+**For learning workflows**:
+```python
+# Complete ML pipeline example
+sol_df = dm.data.solubility()
+
+# Preprocessing
+train = sol_df[sol_df['split'] == 'train']
+test = sol_df[sol_df['split'] == 'test']
+
+# Featurization
+X_train = dm.to_fp(train['mol'])
+X_test = dm.to_fp(test['mol'])
+
+# Model training (example)
+from sklearn.ensemble import RandomForestRegressor
+model = RandomForestRegressor()
+model.fit(X_train, train['solubility'])
+predictions = model.predict(X_test)
+```
+
+### Important Notes
+
+- **Toy Datasets**: Designed for pedagogical purposes, not production use
+- **Small Size**: Limited number of compounds suitable for quick tests
+- **Pre-processed**: Data already cleaned and formatted
+- **Citations**: Check dataset documentation for proper attribution if publishing
+
+### Best Practices
+
+1. **Use for development only**: Don't draw scientific conclusions from toy datasets
+2. **Validate on real data**: Always test production code on actual project data
+3. **Proper attribution**: Cite original data sources if using in publications
+4. **Understand limitations**: Know the scope and quality of each dataset