pycut

[sam-grant]

Added the pycut module and companion demo notebook

A comprehensive framework for managing complex analysis cut flows.

Features

Cut definition and management

• add_cut(name, description, mask, active=True, group=None) - Define analysis cuts with boolean masks
• toggle_cut(cut_dict) - Enable/disable individual cuts using dictionary mapping
• toggle_group(group_dict) - Enable/disable entire groups of cuts

Cut flow generation

• create_cut_flow(data) - Generate detailed cut flow showing progressive event retention
• format_cut_flow(cut_flow) - Format cut flow as pandas DataFrame
• combine_cut_flows(cut_flow_list) - Combine multiple cut flows (useful for multiprocessing)

Selection application

• combine_cuts(cut_names=None, active_only=True) - Generate combined boolean mask from selected cuts
• get_active_cuts() - Retrieve currently active cuts for inspection

State management

• save_state(state_name) - Save current cut configuration for later restoration
• restore_state(state_name) - Restore previously saved cut configuration
• restore_original_state() - Reset all cuts to their initial active states
• list_saved_states() - Display all available saved configurations

Organisation and inspection

• get_groups() - Retrieve cuts organised by group membership
• list_groups() - Display summary of all groups and their cut contents

Typical workflow

1. Define cuts using add_cut() with appropriate groups
2. Generate baseline cut flow with create_cut_flow()
3. Save nominal configuration with save_state()
4. Create alternative configurations using toggle_cut() or toggle_group()
5. Compare efficiencies between configurations
6. Apply selected cuts using combine_cuts() for analysis
7. Restore configurations as needed with restore_state()

The module integrates well with the broader pyutils ecosystem, working with data processed by pyprocess and selections created by pyselect.

[sophiemiddleton]

nice!