Best Practices

1. Name Entities Clearly

# Good
layout.df['qc_visual_rating'] = ratings
layout.df['processing_batch_id'] = batch

# Avoid
layout.df['x'] = values  # What is x?
layout.df['status'] = status  # Status of what?

2. Document Custom Entities

layout.custom_entities = {
    'qc_visual_rating': 'Manual QC rating (pass/fail/review)',
    'processing_batch_id': 'Batch ID from processing pipeline',
}

3. Preserve Entity Types

layout.df['age'] = layout.df['age'].astype(int)
layout.df['qc_grade'] = layout.df['qc_grade'].astype('category')

4. Handle Missing Values

# Be explicit
layout.df['status'].fillna('pending', inplace=True)

# Or filter in queries
completed = layout.get(status='complete')  # Won't match NaN