Sequence Module¶

Batch analysis and sequence management.

ChemstationAPI.controllers.sequence_module.SequenceModule ¶

SequenceModule(communicator: ChemstationCommunicator)

Sequence management for automated batch analysis execution.

Provides comprehensive sequence management including Excel-based sequence creation, row-by-row editing, file operations, and execution control. Sequences enable automated analysis of multiple samples with different methods and parameters.

Sequence Table Structure

VialNumber: Carousel position for sample (1-48)
Method: CE method name for analysis (.M file)
SampleName: Descriptive name for sample identification
SampleInfo: Additional sample metadata and notes
DataFileName: Custom data file naming (optional)
InjVial: Alternative injection vial (for special applications)

Excel Integration

Import sequence parameters from Excel spreadsheets
Flexible column mapping for different Excel formats
Automatic method validation during import
Support for custom data organization schemes

Execution Control

Start/pause/resume sequence execution
Progress monitoring and time estimation
Error handling with automatic continuation
Manual intervention capability during runs

Attributes:

Name	Type	Description
`comm`		ChemStation communicator for sequence operations.
`method`		Methods module for method validation and operations.

Initialize Sequence module with communicator and methods access.

Parameters:

Name	Type	Description	Default
`communicator`	`ChemstationCommunicator`	ChemStation communication interface for sequence operations.	required

Functions¶

modify_sequence_row ¶

modify_sequence_row(row: int, vial_sample: str = '', method: str = '', sample_name: str = '', sample_info: str = '', data_file_name: str = '') -> None

Modify parameters in specific sequence table row.

Updates individual row in the sequence table with new parameters. Only specified parameters are modified; empty parameters remain unchanged. This allows selective editing of sequence entries without affecting other rows.

Parameters:

Name	Type	Description	Default
`row`	`int`	Row number in sequence table (1-based indexing). Corresponds to analysis order in the sequence.	required
`vial_sample`	`str`	Carousel position for sample vial (1-48). Empty string leaves current value unchanged.	`''`
`method`	`str`	CE method name (without .M extension) for this analysis. Examples: "CE_Protein", "MEKC_Drugs", "CZE_Inorganics"	`''`
`sample_name`	`str`	Descriptive sample name for identification and data files. Examples: "BSA_Standard", "Unknown_001", "QC_Sample"	`''`
`sample_info`	`str`	Additional sample metadata, experimental conditions, or notes. Examples: "pH 7.4 buffer", "Dilution 1:10", "Replicate 3"	`''`
`data_file_name`	`str`	Custom data filename (optional, auto-generated if empty).	`''`

Raises:

Type	Description
`SequenceError`	If sequence modification fails or row doesn't exist.
`ValidationError`	If method name is invalid or doesn't exist.
`ValueError`	If row number is out of valid range.

Examples:

Modify sample vial and method:

>>> seq.modify_sequence_row(
...     row=1,
...     vial_sample="15",
...     method="CE_Protein_Analysis"
... )

Update sample information only:

>>> seq.modify_sequence_row(
...     row=3,
...     sample_name="Unknown_Sample_001",
...     sample_info="Customer sample, urgent analysis"
... )

Change method for specific analysis:

>>> seq.modify_sequence_row(
...     row=5,
...     method="MEKC_SmallMolecules"
... )

Note

Sequence must be loaded before modification
Changes are made to memory, use save_sequence() to persist
Method validation performed if method parameter provided
Row numbering starts from 1 (not 0)

prepare_sequence_table ¶

prepare_sequence_table(excel_file_path: str, sequence_name: str = None, sheet_name: int = 0, vial_column: str = None, method_column: str = None, filename_column: str = None, sample_name_column: str = None, sample_info_column: str = None, replicate_column: str = None) -> None

Import and create sequence table from Excel spreadsheet.

Loads sequence parameters from Excel file and creates/updates ChemStation sequence table. Provides flexible column mapping to accommodate different Excel formats and naming conventions. Excel application is briefly opened during processing to ensure proper data handling.

Column Mapping

Each parameter maps Excel columns to sequence table fields: - vial_column → VialNumber: Carousel positions - method_column → Method: CE method names
- sample_name_column → SampleName: Sample identifiers - sample_info_column → SampleInfo: Additional metadata - filename_column → DataFileName: Custom data file names - replicate_column → InjVial: Replicate/injection parameters

Parameters:

Name	Type	Description	Default
`excel_file_path`	`str`	Full path to Excel file containing sequence data. File should contain headers in first row.	required
`sequence_name`	`str`	Existing sequence to load before modification. If None, modifies currently loaded sequence.	`None`
`sheet_name`	`int`	Excel worksheet index to read (0-based, default: first sheet).	`0`
`vial_column`	`str`	Excel column name containing vial positions. Examples: "Vial", "Position", "Vial_Number"	`None`
`method_column`	`str`	Excel column name containing method names. Examples: "Method", "CE_Method", "Analysis_Method"	`None`
`sample_name_column`	`str`	Excel column name containing sample names. Examples: "Sample", "Sample_Name", "ID"	`None`
`sample_info_column`	`str`	Excel column name containing sample metadata. Examples: "Info", "Description", "Notes"	`None`
`filename_column`	`str`	Excel column name containing custom filenames. Examples: "Filename", "Data_File", "Output_Name"	`None`
`replicate_column`	`str`	Excel column name containing replicate information. Examples: "Replicate", "Injection", "Rep_Number"	`None`

Raises:

Type	Description
`FileNotFoundError`	If Excel file doesn't exist at specified path.
`ValidationError`	If referenced methods don't exist in method directory.
`SequenceError`	If sequence loading or Excel processing fails.
`PermissionError`	If unable to access Excel file or create temp files.

Examples:

Basic sequence import:

>>> seq.prepare_sequence_table(
...     excel_file_path="C:\Data\sample_list.xlsx",
...     vial_column="Vial_Position",
...     method_column="Analysis_Method",
...     sample_name_column="Sample_ID"
... )

Import with existing sequence:

>>> seq.prepare_sequence_table(
...     excel_file_path="sequence_data.xlsx",
...     sequence_name="Protein_Analysis_Batch",
...     sheet_name=1,  # Second worksheet
...     vial_column="Pos",
...     method_column="Method",
...     sample_name_column="Sample",
...     sample_info_column="Notes"
... )

Complex mapping with all parameters:

>>> seq.prepare_sequence_table(
...     excel_file_path="complex_sequence.xlsx",
...     vial_column="Carousel_Position",
...     method_column="CE_Method_Name", 
...     sample_name_column="Sample_Identifier",
...     sample_info_column="Experimental_Conditions",
...     filename_column="Custom_Filename",
...     replicate_column="Injection_Number"
... )

Note

Excel file must be accessible (not open in another application)
Method names are validated against method directory
Temporary Excel file created during processing
Sequence is automatically saved after import
Excel application briefly visible during processing

start ¶

start() -> None

Start execution of the current sequence.

Begins automated execution of the loaded sequence, processing samples in order according to the sequence table. The sequence will run continuously until completion, pause, or error.

Raises:

Type	Description
`SequenceError`	If sequence cannot start or no sequence is loaded.
`SystemError`	If instrument is not ready for sequence execution.

Example

seq.start()

Note

Sequence must be loaded and validated before starting
Instrument enters sequence mode with limited manual control
Progress can be monitored via system status methods
Use pause() to temporarily halt sequence execution

pause ¶

pause() -> None

Pause the currently running sequence.

Pauses sequence execution after the current method completes. The sequence will not abort the current analysis but will stop before starting the next sample in the sequence.

Raises:

Type	Description
`SequenceError`	If no sequence is running or pause fails.

Example

seq.pause()

Note

Current analysis completes before pausing
Sequence can be resumed with resume() method
Manual operations possible while paused
Pause takes effect between sequence entries

resume ¶

resume() -> None

Resume a paused sequence from where it stopped.

Continues sequence execution from the next pending sample in the sequence table. All remaining samples will be processed according to their specified parameters.

Raises:

Type	Description
`SequenceError`	If no sequence is paused or resume fails.

Example

seq.resume()

Note

Resumes from next unprocessed sample
All sequence parameters remain unchanged
Instrument returns to automated sequence mode
Manual changes made during pause are preserved

load_sequence ¶

load_sequence(seq_name: str, seq_dir: str = '_SEQPATH$') -> None

Load an existing sequence from file.

Loads a saved sequence file (.S) into ChemStation memory, making it the current active sequence for editing or execution.

Parameters:

Name	Type	Description	Default
`seq_name`	`str`	Sequence filename (without .S extension). Examples: "Protein_Batch_Analysis", "Daily_QC_Sequence"	required
`seq_dir`	`str`	Directory containing sequence files. Defaults to ChemStation sequence directory (_SEQPATH$).	`'_SEQPATH$'`

Raises:

Type	Description
`SequenceError`	If sequence file cannot be loaded.
`ValidationError`	If sequence file doesn't exist.
`FileNotFoundError`	If sequence directory is invalid.

Examples:

Load standard sequence:

>>> seq.load_sequence("Protein_Analysis_Batch")

Load from custom directory:

>>> seq.load_sequence("TestSeq", "C:\Custom\Sequences\")

Note

Sequence loading overwrites current sequence in memory
All unsaved changes to current sequence are lost
Sequence parameters become active immediately

save_sequence ¶

save_sequence(seq_name: str = '_SEQFILE$', seq_dir: str = '_SEQPATH$') -> None

Save current sequence to file.

Saves the sequence table and parameters to a .S file for later use. If no name specified, overwrites the current sequence file.

Parameters:

Name	Type	Description	Default
`seq_name`	`str`	Filename for saved sequence (without .S extension). Defaults to current sequence name (_SEQFILE$).	`'_SEQFILE$'`
`seq_dir`	`str`	Directory for saving sequence. Defaults to ChemStation sequence directory (_SEQPATH$).	`'_SEQPATH$'`

Raises:

Type	Description
`SequenceError`	If sequence cannot be saved.
`PermissionError`	If insufficient write permissions.

Examples:

Save with new name:

>>> seq.save_sequence("Modified_Protein_Sequence")

Overwrite current sequence:

>>> seq.save_sequence()  # Updates current sequence file

Note

Saved sequence includes all table data and parameters
Existing files with same name are overwritten
.S extension added automatically