Add IonizableGroup class for sophisticated modeling of molecules with…

[dragon-ai-agent]

… multiple ionizable groups

This commit implements the feature requested in issue #38 to extend modeling of multiple ionizable groups by pairing them with pKa values.

Changes Made

Schema Changes (src/chemrof/schema/chemrof.yaml)

1. New Class: IonizableGroup

   • Represents a specific ionizable functional group instance within a molecule
   • Pairs functional group type with pKa value
   • Includes optional position and description fields for disambiguation
   • Extends DomainEntity

2. New Slots:

   • has_ionizable_groups: Links ChemicalEntity to IonizableGroup instances
   • functional_group_type: Specifies the type of functional group (e.g., carboxyl, amino)
   • pka_value: The pKa value for the specific ionizable group (required)
   • group_position: Optional position identifier (e.g., C2, N-terminal, alpha)
   • group_description: Optional human-readable description to distinguish groups

3. Added slot to ChemicalEntity:

   • Added has_ionizable_groups to the ChemicalEntity slots list

Example Instances

1. Molecule-citric_acid_with_ionizable_groups.yaml

   • Demonstrates citric acid with three carboxyl groups
   • Each group has a distinct pKa value (3.13, 4.76, 6.40)
   • Uses group_description to distinguish between identical functional groups

2. SmallMolecule-glutamic_acid_with_ionizable_groups.yaml

   • Demonstrates L-glutamic acid with mixed ionizable groups
   • Two carboxyl groups (pKa 2.10, 4.07)
   • One amino group (pKa 9.47)
   • Shows how to model molecules with different functional group types

Design Rationale

• Backwards compatible: Existing pka_ionization_constant slot remains unchanged
• Flexible: Supports both simple cases (single pKa) and complex cases (multiple groups)
• Extensible: Optional position and description fields accommodate various use cases
• Standards-aligned: Follows chemical informatics conventions
• Computational utility: Enables downstream analysis of ionization states

Use Cases Addressed

✅ Citric acid: Three carboxyl groups with distinct pKa values
✅ Amino acids: Mixed ionizable groups (carboxyl + amino)
✅ Complex molecules: Distinguished by position or description
✅ Group-pKa association: Clear linkage between functional group and its pKa

All examples validate successfully against the updated schema.

@dragon-ai-agent

[claude]

Claude finished @dragon-ai-agent's task —— View job

---

Code Review for PR #46: Add IonizableGroup class

Reviewing the implementation of IonizableGroup class for sophisticated modeling of molecules with multiple ionizable groups.

Todo List:

• Read repository guidelines (CLAUDE.md)
• Examine schema changes in chemrof.yaml
• Review example instances
• Test examples against schema (requires approval for make commands)
• Analyze code quality and design
• Check for potential issues
• Provide comprehensive feedback

Review Feedback

✅ Strengths

1. Excellent Design Architecture

• Clean separation of concerns with IonizableGroup as a separate domain entity
• Backwards compatible design maintaining existing pka_ionization_constant slot
• Well-structured inheritance from DomainEntity
• Proper LinkML schema conventions followed

2. Comprehensive Documentation

• Excellent class and slot descriptions with clear examples
• Helpful comments explaining usage patterns
• Good use cases documented in comments

3. Practical Examples

• Real-world chemical examples (citric acid, glutamic acid)
• Demonstrates both single functional group type (citric acid) and mixed types (glutamic acid)
• Proper use of CHEBI identifiers for chemical entities
• Correct chemical data (verified pKa values)

4. Schema Quality

• Appropriate data types (float for pka_value, string for descriptive fields)
• Required field correctly identified (pka_value)
• Proper multivalued relationship configuration with inlined structure

⚠️ Areas for Improvement

1. Data Validation Concerns src/chemrof/schema/chemrof.yaml:2150-2170

pka_value:
  range: float
  required: true

• Issue: No validation constraints on pKa values
• Recommendation: Add reasonable bounds (e.g., -2.0 to 20.0) to prevent invalid chemical data
• Example: minimum_value: -2.0 and maximum_value: 20.0

2. Functional Group Type Standardization src/chemrof/schema/chemrof.yaml:2140-2150

functional_group_type:
  range: string

• Issue: Open string field allows inconsistent naming
• Recommendation: Consider adding an enum with common functional groups or reference to a controlled vocabulary (e.g., CHEBI functional group identifiers)
• Alternative: Add pattern validation or examples in schema

3. ID Convention Inconsistency src/data/examples/valid/Molecule-citric_acid_with_ionizable_groups.yaml:13

- id: CHEBI:30769-ionizable-1

• Issue: Manual ID construction could lead to conflicts
• Recommendation: Document ID naming conventions or consider auto-generation patterns

4. Missing Contextual Information

• Issue: IonizableGroup doesn't inherit temperature/pressure context from parent molecule
• Impact: pKa values are context-dependent but context is only at molecule level
• Recommendation: Consider adding context inheritance documentation or explicit context fields

🔍 Technical Considerations

1. Performance: Inlined multivalued structure is appropriate for typical molecule complexity

2. Extensibility: Design allows for future additions (e.g., multiple pKa values per group, temperature-dependent pKa)

3. Compatibility: No breaking changes to existing schema - excellent backwards compatibility

🧪 Test Coverage Assessment

• Examples cover key use cases (multiple identical groups, mixed group types)
• Real chemical data validates practical applicability
• Missing: Edge cases like unusual functional groups or extreme pKa values

📋 Minor Issues

1. Schema Consistency src/chemrof/schema/chemrof.yaml:2160

group_position:
  range: string

• Consider adding pattern validation for common position notations (C1, C2, N-terminal, etc.)

2. Documentation Gap

• Missing examples of how this integrates with existing pka_ionization_constant usage patterns

🎯 Overall Assessment

This is a high-quality implementation that thoughtfully addresses the requirements. The design is chemically sound, technically well-implemented, and maintains excellent backwards compatibility. The examples demonstrate real-world applicability with accurate chemical data.

Recommendation: ✅ Approve with minor suggestions

The implementation successfully enables sophisticated modeling of molecules with multiple ionizable groups while maintaining schema integrity and usability.

---