API Reference 

Returns:

An IlluminaSampleSheet object representing the parsed sample sheet.

elsheeto.facade.parse_illumina_v1(path, config=None)[source]

Parse an Illumina v1 sample sheet from the given file path.

This is a convenience function that runs all parsing stages internally.

Parameters:

path (str | Path) – The file path to the Illumina v1 sample sheet CSV file.
config (ParserConfiguration | None) – Optional parser configuration.

Return type:

Returns:

An IlluminaSampleSheet object representing the parsed sample sheet.

elsheeto.facade.write_illumina_v1_to_string(sheet, config=None)[source]

Write an Illumina v1 sample sheet to a CSV string.

Parameters:

sheet (IlluminaSampleSheet) – The IlluminaSampleSheet to write.
config (WriterConfiguration | None) – Optional writer configuration. If None, default configuration is used.

Return type:

str

Returns:

The sample sheet in CSV format as a string.

elsheeto.facade.write_illumina_v1_to_file(sheet, path, config=None)[source]

Write an Illumina v1 sample sheet to a CSV file.

Parameters:

sheet (IlluminaSampleSheet) – The IlluminaSampleSheet to write.
path (str | Path) – The file path where the CSV should be written.
config (WriterConfiguration | None) – Optional writer configuration. If None, default configuration is used.

Return type:

None

elsheeto.facade.parse_aviti_from_data(data, config=None)[source]

Parse an Aviti sample sheet from the given CSV data.

This is a convenience function that runs all parsing stages internally.

Parameters:

data (str) – The CSV data as a string.
config (ParserConfiguration | None) – Optional parser configuration.

Return type:

Returns:

An AvitiSheet object representing the parsed sample sheet.

elsheeto.facade.parse_aviti(path, config=None)[source]

Parse an Aviti sample sheet from the given file path.

This is a convenience function that runs all parsing stages internally.

Parameters:

path (str | Path) – The file path to the Aviti sample sheet CSV file.
config (ParserConfiguration | None) – Optional parser configuration.

Return type:

Returns:

An AvitiSheet object representing the parsed sample sheet.

elsheeto.facade.write_aviti_to_string(sheet, config=None)[source]

Write an Aviti sample sheet to CSV string format.

This is a convenience function that provides a simple API for exporting Aviti sample sheets to CSV format.

Parameters:

sheet (AvitiSheet) – The AvitiSheet to write.
config (WriterConfiguration | None) – Optional writer configuration.

Return type:

str

Returns:

The CSV content as a string.

elsheeto.facade.write_aviti_to_file(sheet, path, config=None)[source]

Write an Aviti sample sheet to a CSV file.

This is a convenience function that provides a simple API for exporting Aviti sample sheets to CSV files.

Parameters:

sheet (AvitiSheet) – The AvitiSheet to write.
path (str | Path) – The file path where the CSV should be written.
config (WriterConfiguration | None) – Optional writer configuration.

Return type:

None

Models

Data Models - Common

class elsheeto.models.common.ParsedSheetType(*values)[source]

Bases: str, Enum

Resulting sheet type after raw CSV parsing in stage 1.

SECTIONLESS = 'sectionless': Sectionless.

SECTIONED = 'sectioned': Multi-section sheet.

Data Models - Utils

class elsheeto.models.utils.CaseInsensitiveDict(data: Mapping[_KT, _VT] | None = None)[source]

class elsheeto.models.utils.CaseInsensitiveDict(data: Iterable[tuple[_KT, _VT]] | None = None)

Bases: MutableMapping, Generic

A case-insensitive dictionary that preserves original key casing.

Parameters:: data (Mapping[TypeVar(_KT), TypeVar(_VT)] | Iterable[tuple[TypeVar(_KT), TypeVar(_VT)]] | None)

__init__(data=None)[source]

Parameters:: data (Mapping[TypeVar(_KT), TypeVar(_VT)] | Iterable[tuple[TypeVar(_KT), TypeVar(_VT)]] | None)

lower_items()[source]

Return type:: Iterator[tuple[TypeVar(_KT), TypeVar(_VT)]]

copy()[source]

Return type:: CaseInsensitiveDict[TypeVar(_KT), TypeVar(_VT)]

getkey(key)[source]

Parameters:: key (TypeVar(_KT))
Return type:: TypeVar(_KT)

classmethod fromkeys(iterable, value)[source]

Parameters:

iterable (Iterable[TypeVar(_KT)])
value (TypeVar(_VT))

Return type:

CaseInsensitiveDict[TypeVar(_KT), TypeVar(_VT)]

classmethod __get_pydantic_core_schema__(source_type, handler)[source]

Generate pydantic core schema for validation and serialization.

Parameters:

source_type (Any)
handler (GetCoreSchemaHandler)

Return type:

Data Models - Stage 1 (Raw CSV)

Models for storing the result of stage 1 CSV sectioned CSV parsing.

Stage 1 is raw CSV parsing and splitting into sections. Here, only consistency checks of columns are made per-section or globally.

class elsheeto.models.csv_stage1.ParsedRawSection(**data)[source]

Bases: BaseModel

Representation of a parsed section in a sectioned CSV file.

Parameters:: data (Any)

name: str: Name of the section.

num_columns: int: Number of columns in the section, 0 if there are no data rows.

data: Annotated[list[list[str]]]: Data rows in the section.

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class elsheeto.models.csv_stage1.ParsedRawSheet(**data)[source]

Bases: BaseModel

Representation of a parsed raw sectioned CSV file.

Parameters:: data (Any)

delimiter: str: Delimiter used in the file.

sheet_type: ParsedSheetType: Resulting sheet type.

sections: Annotated[list[ParsedRawSection]]: Parsed sections in the sheet, a single one with name “” (empty string) if sectionless.

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Data Models - Stage 2 (Structured)

Models for storing the result of stage 1 CSV sectioned CSV parsing.

Stage 2 is converting the stage 1 results into key/value and data payload header sections.

class elsheeto.models.csv_stage2.HeaderSection(**data)[source]

Bases: BaseModel

Representation of a header section in a stage 2 sample sheet.

Parameters:: data (Any)

name: str: Original section name (e.g., “header”, “reads”, “settings”)

rows: Annotated[list[list[str]]]: List of header rows as lists of strings preserving original structure

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property key_values: dict[str, str]

Get key-value pairs as a dictionary for backward compatibility.

Only considers rows with exactly 2 non-empty values as key-value pairs.

class elsheeto.models.csv_stage2.DataSection(**data)[source]

Bases: BaseModel

Representation of the data section in a stage 2 sample sheet.

Parameters:: data (Any)

headers: Annotated[list[str]]: Header names.

header_to_index: Annotated[dict[str, int]]: Header to index map.

data: Annotated[list[list[str]]]: Data rows.

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class elsheeto.models.csv_stage2.ParsedSheet(**data)[source]

Bases: BaseModel

Representation of a stage 2 sample sheet.

Parameters:: data (Any)

delimiter: str: Delimiter used in the file.

sheet_type: ParsedSheetType: Resulting sheet type.

header_sections: Annotated[list[HeaderSection]]: Zero or more key/value header sections in the sheet.

data_section: DataSection: Single data section in the sheet.

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Data Models - Illumina v1

Illumina sample sheet v1 specific models.

The Stage 2 results are converted into these models in Stage 3.

class elsheeto.models.illumina_v1.IlluminaHeader(**data)[source]

Bases: BaseModel

Representation of the Illumina v1 Header section.

Parameters:: data (Any)

iem_file_version: str | None: Optional IEMFileVersion field.

investigator_name: str | None: Optional Investigator Name field.

experiment_name: str | None: Optional Experiment Name field.

date: str | None: Optional Date field.

workflow: str: Required Workflow field.

application: str | None: Optional Application field.

instrument_type: str | None: Optional Instrument Type field.

assay: str | None: Optional Assay field.

index_adapters: str | None: Optional Index Adapters field.

description: str | None: Optional Description field.

chemistry: str | None: Chemistry field, must be set to amplicon (case insensitive) for dual indexing.

run: str | None: Optional Run field.

extra_metadata: CaseInsensitiveDict[str, Any]: Optional extra metadata for fields not explicitly defined.

model_config: ClassVar[ConfigDict] = {'frozen': True}: Model configuration.

class elsheeto.models.illumina_v1.IlluminaReads(**data)[source]

Bases: BaseModel

Representation of the Illumina v1 Reads section.

Parameters:: data (Any)

read_lengths: list[int]: List of read lengths.

model_config: ClassVar[ConfigDict] = {'frozen': True}: Model configuration.

class elsheeto.models.illumina_v1.IlluminaSettings(**data)[source]

Bases: BaseModel

Representation of the Illumina v1 Settings section.

Note that these are mainly used for running old Illumina pipelines and we just store key/value maps here.

Parameters:: data (Any)

data: CaseInsensitiveDict[str, Any]: Key/value data in the settings section.

extra_metadata: Annotated[CaseInsensitiveDict[str, Any]]: Optional extra metadata.

model_config: ClassVar[ConfigDict] = {'frozen': True}: Model configuration.

class elsheeto.models.illumina_v1.IlluminaSample(**data)[source]

Bases: BaseModel

One entry in the Illumina v1 Data section.

Parameters:: data (Any)

lane: int | None: Optional Lane field.

sample_id: str: Sample_ID field.

sample_name: str | None: Optional Sample_Name field.

sample_plate: str | None: Optional Sample_Plate field.

sample_well: str | None: Optional Sample_Well field.

index_plate_well: str | None: Optional Index_Plate_Well field.

inline_id: str | None: Optional Inline_ID field.

i7_index_id: str | None: Optional I7_Index_ID field.

index: str | None: index field.

i5_index_id: str | None: Optional I5_Index_ID field.

index2: str | None: index2 field.

sample_project: str | None: Optional Sample_Project field.

description: str | None: Optional Description field.

extra_metadata: CaseInsensitiveDict[str, Any]: Optional extra metadata for fields not explicitly defined.

model_config: ClassVar[ConfigDict] = {'frozen': True}: Model configuration.

class elsheeto.models.illumina_v1.IlluminaSampleSheet(**data)[source]

Bases: BaseModel

Representation of an Illumina v1 sample sheet.

See Illumina documentation for details.

Parameters:: data (Any)

header: IlluminaHeader: The Illumina Header section.

reads: IlluminaReads | None: The Illumina Reads section.

settings: IlluminaSettings | None: The Illumina v1 Settings section.

data: list[IlluminaSample]: The Illumina Data section.

model_config: ClassVar[ConfigDict] = {'frozen': True}: Model configuration.

with_sample_added(sample, position=None)[source]

Create a new sheet with an additional sample.

Parameters:

sample (IlluminaSample) – The sample to add.
position (int | None) – Optional position to insert the sample. If None, appends to the end.

Return type:

Returns:

A new IlluminaSampleSheet with the sample added.

Example

>>> from elsheeto.models.illumina_v1 import IlluminaSample, IlluminaSampleSheet, IlluminaHeader, IlluminaReads
>>> header = IlluminaHeader()
>>> sheet = IlluminaSampleSheet(header=header, reads=None, settings=None, data=[])
>>> new_sample = IlluminaSample(sample_id="Test", sample_name="TestSample")
>>> modified_sheet = sheet.with_sample_added(new_sample)
>>> len(modified_sheet.data)
1

with_sample_removed(sample_identifier)[source]

Create a new sheet with a sample removed by Sample_ID or index.

Parameters:

sample_identifier (str | int) – The Sample_ID (string) or index (int) of the sample to remove.

Return type:

Returns:

A new IlluminaSampleSheet with the sample removed.

Raises:

ValueError – If no sample with the given Sample_ID is found.
IndexError – If the sample index is out of range.

Example

>>> from elsheeto.models.illumina_v1 import IlluminaSample, IlluminaSampleSheet, IlluminaHeader
>>> header = IlluminaHeader()
>>> sample = IlluminaSample(sample_id="Test", sample_name="TestSample")
>>> sheet = IlluminaSampleSheet(header=header, reads=None, settings=None, data=[sample])
>>> modified_sheet = sheet.with_sample_removed("Test")
>>> len(modified_sheet.data)
0

with_sample_modified(sample_identifier, **updates)[source]

Create a new sheet with a sample modified by Sample_ID or index.

Parameters:

sample_identifier (str | int) – The Sample_ID (string) or index (int) of the sample to modify.
**updates – Fields to update on the sample.

Return type:

Returns:

A new IlluminaSampleSheet with the sample modified.

Raises:

ValueError – If no sample with the given Sample_ID is found or invalid field provided.
IndexError – If the sample index is out of range.

Example

>>> from elsheeto.models.illumina_v1 import IlluminaSample, IlluminaSampleSheet, IlluminaHeader
>>> header = IlluminaHeader()
>>> sample = IlluminaSample(sample_id="Test", sample_name="TestSample")
>>> sheet = IlluminaSampleSheet(header=header, reads=None, settings=None, data=[sample])
>>> modified_sheet = sheet.with_sample_modified("Test", sample_project="NewProject")
>>> modified_sheet.data[0].sample_project
'NewProject'

with_samples_filtered(predicate)[source]

Create a new sheet with samples filtered by a predicate function.

Parameters:: predicate – A function that takes an IlluminaSample and returns bool.
Return type:: IlluminaSampleSheet
Returns:: A new IlluminaSampleSheet with filtered samples.

Example

>>> from elsheeto.models.illumina_v1 import IlluminaSample, IlluminaSampleSheet, IlluminaHeader
>>> header = IlluminaHeader()
>>> samples = [IlluminaSample(sample_id="S1", sample_project="ProjectA"),
...            IlluminaSample(sample_id="S2", sample_project="ProjectB")]
>>> sheet = IlluminaSampleSheet(header=header, reads=None, settings=None, data=samples)
>>> # Keep only samples from ProjectA
>>> modified_sheet = sheet.with_samples_filtered(
...     lambda s: s.sample_project == "ProjectA"
... )
>>> len(modified_sheet.data)
1

with_header_field_updated(field_name, value)[source]

Create a new sheet with a header field updated.

Parameters:

field_name (str) – The name of the header field to update.
value (str | None) – The new value for the field.

Return type:

Returns:

A new IlluminaSampleSheet with the header field updated.

Example

>>> from elsheeto.models.illumina_v1 import IlluminaSampleSheet, IlluminaHeader
>>> header = IlluminaHeader()
>>> sheet = IlluminaSampleSheet(header=header, reads=None, settings=None, data=[])
>>> modified_sheet = sheet.with_header_field_updated("experiment_name", "NewExperiment")
>>> modified_sheet.header.experiment_name
'NewExperiment'

with_header_updated(**updates)[source]

Create a new sheet with multiple header fields updated.

Parameters:: **updates – Fields to update on the header.
Return type:: IlluminaSampleSheet
Returns:: A new IlluminaSampleSheet with the header updated.

Example

>>> from elsheeto.models.illumina_v1 import IlluminaSampleSheet, IlluminaHeader
>>> header = IlluminaHeader()
>>> sheet = IlluminaSampleSheet(header=header, reads=None, settings=None, data=[])
>>> modified_sheet = sheet.with_header_updated(
...     experiment_name="NewExperiment",
...     investigator_name="Dr. Smith"
... )
>>> modified_sheet.header.experiment_name
'NewExperiment'

with_reads_updated(read_lengths)[source]

Create a new sheet with read lengths updated.

Parameters:: read_lengths (list[int]) – List of read lengths.
Return type:: IlluminaSampleSheet
Returns:: A new IlluminaSampleSheet with the reads section updated.

Example

>>> from elsheeto.models.illumina_v1 import IlluminaSampleSheet, IlluminaHeader
>>> header = IlluminaHeader()
>>> sheet = IlluminaSampleSheet(header=header, reads=None, settings=None, data=[])
>>> modified_sheet = sheet.with_reads_updated([150, 150])
>>> modified_sheet.reads.read_lengths
[150, 150]

with_setting_added(key, value)[source]

Create a new sheet with a setting added or updated.

Parameters:

key (str) – The setting key.
value (str) – The setting value.

Return type:

Returns:

A new IlluminaSampleSheet with the setting added/updated.

Example

>>> from elsheeto.models.illumina_v1 import IlluminaSampleSheet, IlluminaHeader
>>> header = IlluminaHeader()
>>> sheet = IlluminaSampleSheet(header=header, reads=None, settings=None, data=[])
>>> modified_sheet = sheet.with_setting_added("Adapter", "ATCG")
>>> modified_sheet.settings.data["Adapter"]
'ATCG'

with_settings_updated(settings)[source]

Create a new sheet with multiple settings added or updated.

Parameters:: settings (Mapping[str, str]) – Dictionary of key-value pairs to add/update.
Return type:: IlluminaSampleSheet
Returns:: A new IlluminaSampleSheet with the settings added/updated.

Example

>>> from elsheeto.models.illumina_v1 import IlluminaSampleSheet, IlluminaHeader
>>> header = IlluminaHeader()
>>> sheet = IlluminaSampleSheet(header=header, reads=None, settings=None, data=[])
>>> modified_sheet = sheet.with_settings_updated({
...     "Adapter": "ATCG",
...     "TrimAdapter": "True"
... })
>>> len(modified_sheet.settings.data)
2

with_settings_field_updated(key, value)[source]

Create a new sheet with a single settings field updated.

Parameters:

key (str) – The settings key to update.
value (str) – The new value for the settings key.

Return type:

Returns:

A new IlluminaSampleSheet with the settings field updated.

Example

>>> from elsheeto.models.illumina_v1 import IlluminaSampleSheet, IlluminaHeader
>>> header = IlluminaHeader()
>>> sheet = IlluminaSampleSheet(header=header, reads=None, settings=None, samples=[])
>>> modified_sheet = sheet.with_settings_field_updated("Adapter", "ATCG")
>>> modified_sheet.settings.data["Adapter"]
'ATCG'

to_csv(config=None)[source]

Export the sheet to CSV format.

Parameters:: config (WriterConfiguration | None) – Optional writer configuration. If None, default configuration is used.
Return type:: str
Returns:: The sheet in CSV format as a string.

Example

>>> from elsheeto.models.illumina_v1 import IlluminaSampleSheet, IlluminaHeader
>>> header = IlluminaHeader()
>>> sheet = IlluminaSampleSheet(header=header, reads=None, settings=None, data=[])
>>> csv_content = sheet.to_csv()
>>> "[Header]" in csv_content
True

class elsheeto.models.illumina_v1.IlluminaSheetBuilder[source]

Bases: object

Mutable builder for constructing IlluminaSampleSheet instances.

This builder provides a fluent API for complex modifications while maintaining type safety and validation. The builder is mutable during construction but produces immutable IlluminaSampleSheet instances.

Examples

Create a new sheet from scratch:

>>> from elsheeto.models.illumina_v1 import IlluminaSheetBuilder, IlluminaSample
>>> builder = IlluminaSheetBuilder()
>>> sheet = (builder
...     .add_sample(IlluminaSample(sample_id="Sample1", sample_name="Test"))
...     .set_header_field("experiment_name", "Test")
...     .build())

Modify an existing sheet:

>>> from elsheeto.models.illumina_v1 import IlluminaSample, IlluminaSampleSheet, IlluminaHeader
>>> header = IlluminaHeader()
>>> existing_sheet = IlluminaSampleSheet(header=header, reads=None, settings=None, data=[IlluminaSample(sample_id="Old")])
>>> builder = IlluminaSheetBuilder.from_sheet(existing_sheet)
>>> modified = (builder
...     .remove_sample_by_id("Old")
...     .add_sample(IlluminaSample(sample_id="NewSample", sample_name="New"))
...     .build())

__init__()[source]: Initialize an empty builder.

classmethod from_sheet(sheet)[source]

Create a builder initialized with data from an existing sheet.

Parameters:: sheet (IlluminaSampleSheet) – The existing IlluminaSampleSheet to copy data from.
Return type:: IlluminaSheetBuilder
Returns:: A new builder containing the sheet’s data.

add_sample(sample)[source]

Add a sample to the sheet.

Parameters:: sample (IlluminaSample) – The sample to add.
Return type:: IlluminaSheetBuilder
Returns:: This builder for method chaining.

add_samples(samples)[source]

Add multiple samples to the sheet.

Parameters:: samples (list[IlluminaSample]) – The samples to add.
Return type:: IlluminaSheetBuilder
Returns:: This builder for method chaining.

remove_sample(sample)[source]

Remove a sample from the sheet.

Parameters:: sample (IlluminaSample | str | int) – Sample to remove. Can be: - IlluminaSample instance - str: sample_id to find and remove - int: index of sample to remove
Return type:: IlluminaSheetBuilder
Returns:: This builder for method chaining.
Raises:: ValueError – If sample is not found or index is out of range.

remove_sample_by_id(sample_id)[source]

Remove a sample by its Sample_ID.

Parameters:: sample_id (str) – The Sample_ID of the sample to remove.
Return type:: IlluminaSheetBuilder
Returns:: This builder for method chaining.
Raises:: ValueError – If no sample with the given Sample_ID is found.

remove_samples_by_project(project)[source]

Remove all samples with the specified Sample_Project.

Parameters:: project (str) – The Sample_Project name to match.
Return type:: IlluminaSheetBuilder
Returns:: This builder for method chaining.

update_sample_by_id(sample_id, **updates)[source]

Update a sample by its Sample_ID.

Parameters:

sample_id (str) – The Sample_ID of the sample to update.
**updates – Fields to update on the sample.

Return type:

Returns:

This builder for method chaining.

Raises:

ValueError – If no sample with the given Sample_ID is found or invalid field provided.

clear_samples()[source]

Remove all samples from the sheet.

Return type:: IlluminaSheetBuilder
Returns:: This builder for method chaining.

set_header_field(field_name, value)[source]

Set a header field value.

Parameters:

field_name (str) – The name of the header field (snake_case or display name).
value (str | None) – The value to set.

Return type:

Returns:

This builder for method chaining.

set_header_fields(fields)[source]

Set multiple header fields.

Parameters:: fields (Mapping[str, str | None]) – Dictionary of field names to values.
Return type:: IlluminaSheetBuilder
Returns:: This builder for method chaining.

clear_header_fields()[source]

Clear all header fields (except workflow which has a default).

Return type:: IlluminaSheetBuilder
Returns:: This builder for method chaining.

set_read_lengths(read_lengths)[source]

Set the read lengths.

Parameters:: read_lengths (list[int]) – List of read lengths.
Return type:: IlluminaSheetBuilder
Returns:: This builder for method chaining.

add_read_length(read_length)[source]

Add a read length.

Parameters:: read_length (int) – The read length to add.
Return type:: IlluminaSheetBuilder
Returns:: This builder for method chaining.

clear_read_lengths()[source]

Clear all read lengths.

Return type:: IlluminaSheetBuilder
Returns:: This builder for method chaining.

add_setting(key, value)[source]

Add or update a setting.

Parameters:

key (str) – The setting key.
value (str) – The setting value.

Return type:

Returns:

This builder for method chaining.

add_settings(settings)[source]

Add or update multiple settings.

Parameters:: settings (Mapping[str, str]) – Dictionary of key-value pairs to add.
Return type:: IlluminaSheetBuilder
Returns:: This builder for method chaining.

update_settings_field(key, value)[source]

Update a single settings field.

Parameters:

key (str) – The settings key to update.
value (str) – The new value for the settings key.

Return type:

Returns:

This builder for method chaining.

Raises:

ValueError – If no settings have been set.

remove_setting(key)[source]

Remove a setting.

Parameters:: key (str) – The key to remove.
Return type:: IlluminaSheetBuilder
Returns:: This builder for method chaining.
Raises:: KeyError – If the key is not found.

clear_settings()[source]

Remove all settings.

Return type:: IlluminaSheetBuilder
Returns:: This builder for method chaining.

set_header(header)[source]

Set the complete header by copying its fields.

Parameters:: header (IlluminaHeader)
Return type:: IlluminaSheetBuilder

update_header_field(field_name, value)[source]

Update a specific header field. Alias for set_header_field.

Parameters:

field_name (str)
value (str | None)

Return type:

set_reads(reads)[source]

Set the complete reads configuration.

Parameters:: reads (IlluminaReads)
Return type:: IlluminaSheetBuilder

update_reads(read_lengths)[source]

Update the read lengths. Alias for set_read_lengths.

Parameters:: read_lengths (list[int])
Return type:: IlluminaSheetBuilder

set_settings(settings)[source]

Set the complete settings by copying its data.

Parameters:: settings (IlluminaSettings)
Return type:: IlluminaSheetBuilder

update_sample(identifier, **updates)[source]

Update a sample by identifier.

Parameters:: identifier (str | int)
Return type:: IlluminaSheetBuilder

build()[source]

Build the immutable IlluminaSampleSheet instance.

Return type:: IlluminaSampleSheet
Returns:: A new IlluminaSampleSheet with the builder’s data.
Raises:: ValidationError – If the data is invalid.

Data Models - Aviti

Aviti sample sheet (aka Sequencing Manifest) specific models.

The Stage 2 results are converted into these models in Stage 3.

class elsheeto.models.aviti.AvitiSample(**data)[source]

Bases: BaseModel

Representation of a single Aviti sample.

Parameters:: data (Any)

sample_name: str: Required value from SampleName column.

index1: str: Required value from Index1 column - can contain composite indices separated by +.

index2: str: Optional value from Index2 column - can contain composite indices separated by +.

lane: str | None: Optional value from Lane column.

project: str | None: Optional value from Project column.

external_id: str | None: Optional value from ExternalId column.

description: str | None: Optional value from Description column.

extra_metadata: CaseInsensitiveDict[str, Any]: Optional extra metadata for unknown fields.

model_config: ClassVar[ConfigDict] = {'frozen': True}: Model configuration.

classmethod validate_index1(v)[source]

Validate index1 sequence.

Parameters:: v (str) – The index sequence(s), potentially composite.
Return type:: str
Returns:: The validated index sequence.
Raises:: ValueError – If index is invalid.

classmethod validate_index2(v)[source]

Validate index2 sequence.

Parameters:: v (str) – The index sequence(s), potentially composite.
Return type:: str
Returns:: The validated index sequence.
Raises:: ValueError – If index is invalid.

class elsheeto.models.aviti.AvitiRunValues(**data)[source]

Bases: BaseModel

Representation of the RunValues section of an Aviti sample sheet.

Parameters:: data (Any)

data: CaseInsensitiveDict[str, Any]: Key-value pairs from the RunValues section.

extra_metadata: CaseInsensitiveDict[str, Any]: Optional extra metadata.

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class elsheeto.models.aviti.AvitiSettingEntry(**data)[source]

Bases: BaseModel

Representation of a single setting entry that may be lane-specific.

Parameters:: data (Any)

name: str: Setting name/key.

value: str: Setting value.

lane: str | None: Optional lane specification (e.g., “1+2”, “1”, “2”, etc.).

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class elsheeto.models.aviti.AvitiSettingEntries(**data)[source]

Bases: BaseModel

Collection of Aviti setting entries with convenience methods for retrieval.

Parameters:: data (Any)

entries: list[AvitiSettingEntry]: List of setting entries (may include lane-specific settings).

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

get_all_by_key(key)[source]

Get all setting entries with the specified key.

Parameters:: key (str) – Setting name to search for.
Return type:: list[AvitiSettingEntry]
Returns:: List of all setting entries with the specified key.

get_by_key(key)[source]

Get exactly one setting entry with the specified key.

Parameters:: key (str) – Setting name to search for.
Return type:: AvitiSettingEntry
Returns:: The single setting entry with the specified key.
Raises:: ValueError – If zero or more than one entry found with the key.

get_by_key_and_lane(key, lane)[source]

Get exactly one setting entry with exact key and lane match.

Parameters:

key (str) – Setting name to search for.
lane (str | None) – Lane specification to match exactly (None for no lane).

Return type:

AvitiSettingEntry

Returns:

The setting entry with exact key and lane match.

Raises:

ValueError – If zero or more than one entry found with the key and lane combination.

class elsheeto.models.aviti.AvitiSettings(**data)[source]

Bases: BaseModel

Representation of the Settings section of an Aviti sample sheet.

Supports both simple key-value pairs and lane-specific settings with 3-column structure.

Parameters:: data (Any)

settings: AvitiSettingEntries: Collection of setting entries (may include lane-specific settings).

extra_metadata: CaseInsensitiveDict[str, Any]: Optional extra metadata.

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property data: CaseInsensitiveDict[str, Any]

Get simple key-value pairs for backward compatibility.

For lane-specific settings, only returns the first occurrence of each setting name.

get_settings_by_lane(lane=None)[source]

Get settings filtered by lane specification.

Parameters:: lane (str | None) – Lane specification to filter by (e.g., “1”, “2”, “1+2”). If None, returns settings without lane specification.
Return type:: CaseInsensitiveDict[str, Any]
Returns:: Dictionary of setting name to value for the specified lane.

get_all_lanes()[source]

Get all unique lane specifications used in settings.

Return type:: set[str]
Returns:: Set of all lane specifications (excluding None).

class elsheeto.models.aviti.AvitiSheet(**data)[source]

Bases: BaseModel

Representation of an Aviti sample sheet (officially known as Sequencing Manifest).

By the documentation, a minimal configuration looks as follows (section header above samples does not matter).

` [RunValues] KeyName,Value [Settings] SettingName, Value [Samples] SampleName, Index1, Index2, `

The following is the extended version:

` [RunValues] KeyName,Value [Settings] SettingName, Value [Samples] SampleName, Index1, Index2, Lane, Project, ExternalId, Description `

Parameters:: data (Any)

run_values: AvitiRunValues | None: The RunValues section.

settings: AvitiSettings | None: The Settings section.

samples: list[AvitiSample]: The Samples section.

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

with_sample_added(sample)[source]

Create a new sheet with an additional sample.

Parameters:: sample (AvitiSample) – The sample to add.
Return type:: AvitiSheet
Returns:: A new AvitiSheet with the sample added.

Example

>>> from elsheeto.models.aviti import AvitiSample, AvitiSheet
>>> sheet = AvitiSheet(samples=[])
>>> new_sample = AvitiSample(sample_name="Test", index1="ATCG")
>>> modified_sheet = sheet.with_sample_added(new_sample)
>>> len(modified_sheet.samples)
1

with_sample_removed(sample_name)[source]

Create a new sheet with a sample removed by name.

Parameters:: sample_name (str) – The name of the sample to remove.
Return type:: AvitiSheet
Returns:: A new AvitiSheet with the sample removed.
Raises:: ValueError – If no sample with the given name is found.

Example

>>> from elsheeto.models.aviti import AvitiSample, AvitiSheet
>>> sample = AvitiSample(sample_name="OldSample", index1="ATCG")
>>> sheet = AvitiSheet(samples=[sample])
>>> modified_sheet = sheet.with_sample_removed("OldSample")
>>> len(modified_sheet.samples)
0

with_sample_modified(sample_name, **updates)[source]

Create a new sheet with a sample modified by name.

Parameters:

sample_name (str) – The name of the sample to modify.
**updates – Fields to update on the sample.

Return type:

Returns:

A new AvitiSheet with the sample modified.

Raises:

ValueError – If no sample with the given name is found.

Example

>>> from elsheeto.models.aviti import AvitiSample, AvitiSheet
>>> sample = AvitiSample(sample_name="Sample1", index1="ATCG")
>>> sheet = AvitiSheet(samples=[sample])
>>> modified_sheet = sheet.with_sample_modified("Sample1", project="NewProject")
>>> modified_sheet.samples[0].project
'NewProject'

with_samples_filtered(predicate)[source]

Create a new sheet with samples filtered by a predicate function.

Parameters:: predicate – A function that takes an AvitiSample and returns bool.
Return type:: AvitiSheet
Returns:: A new AvitiSheet with filtered samples.

Example

>>> from elsheeto.models.aviti import AvitiSample, AvitiSheet
>>> samples = [AvitiSample(sample_name="S1", index1="ATCG", project="MyProject"),
...            AvitiSample(sample_name="S2", index1="GCTA", project="OtherProject")]
>>> sheet = AvitiSheet(samples=samples)
>>> # Keep only samples from a specific project
>>> modified_sheet = sheet.with_samples_filtered(
...     lambda s: s.project == "MyProject"
... )
>>> len(modified_sheet.samples)
1

with_run_value_added(key, value)[source]

Create a new sheet with a run value added or updated.

Parameters:

key (str) – The run value key.
value (str) – The run value.

Return type:

Returns:

A new AvitiSheet with the run value added/updated.

Example

>>> from elsheeto.models.aviti import AvitiSheet
>>> sheet = AvitiSheet(samples=[])
>>> modified_sheet = sheet.with_run_value_added("Experiment", "Test123")
>>> modified_sheet.run_values.data["Experiment"]
'Test123'

with_run_values_updated(values)[source]

Create a new sheet with multiple run values added or updated.

Parameters:: values (Mapping[str, str]) – Dictionary of key-value pairs to add/update.
Return type:: AvitiSheet
Returns:: A new AvitiSheet with the run values added/updated.

Example

>>> from elsheeto.models.aviti import AvitiSheet
>>> sheet = AvitiSheet(samples=[])
>>> modified_sheet = sheet.with_run_values_updated({
...     "Experiment": "Test123",
...     "Date": "2024-01-01"
... })
>>> len(modified_sheet.run_values.data)
2

with_setting_added(name, value, lane=None)[source]

Create a new sheet with a setting added.

Parameters:

name (str) – The setting name.
value (str) – The setting value.
lane (str | None) – Optional lane specification.

Return type:

Returns:

A new AvitiSheet with the setting added.

Example

>>> from elsheeto.models.aviti import AvitiSheet
>>> sheet = AvitiSheet(samples=[])
>>> modified_sheet = sheet.with_setting_added("ReadLength", "150", "1+2")
>>> setting = modified_sheet.settings.settings.get_by_key_and_lane("ReadLength", "1+2")
>>> setting.value
'150'

to_csv(config=None)[source]

Export the sheet to CSV format.

Parameters:: config (WriterConfiguration | None) – Optional writer configuration. If None, default configuration is used.
Return type:: str
Returns:: The sheet in CSV format as a string.

Example

>>> from elsheeto.models.aviti import AvitiSheet
>>> sheet = AvitiSheet(samples=[])
>>> csv_content = sheet.to_csv()
>>> "[Samples]" in csv_content
True

class elsheeto.models.aviti.AvitiSheetBuilder[source]

Bases: object

Mutable builder for constructing AvitiSheet instances.

This builder provides a fluent API for complex modifications while maintaining type safety and validation. The builder is mutable during construction but produces immutable AvitiSheet instances.

Examples

Create a new sheet from scratch:

>>> builder = AvitiSheetBuilder()
>>> sheet = (builder
...     .add_sample(AvitiSample(sample_name="Sample1", index1="ATCG"))
...     .add_run_value("Experiment", "Test")
...     .build())

Modify an existing sheet:

>>> from elsheeto.models.aviti import AvitiSample, AvitiSheet
>>> existing_sheet = AvitiSheet(samples=[AvitiSample(sample_name="Old", index1="AAAA")])
>>> builder = AvitiSheetBuilder.from_sheet(existing_sheet)
>>> modified = (builder
...     .remove_sample_by_name("Old")
...     .add_sample(AvitiSample(sample_name="NewSample", index1="GCTA"))
...     .build())

__init__()[source]: Initialize an empty builder.

classmethod from_sheet(sheet)[source]

Create a builder initialized with data from an existing sheet.

Parameters:: sheet (AvitiSheet) – The existing AvitiSheet to copy data from.
Return type:: AvitiSheetBuilder
Returns:: A new builder containing the sheet’s data.

add_sample(sample)[source]

Add a sample to the sheet.

Parameters:: sample (AvitiSample) – The sample to add.
Return type:: AvitiSheetBuilder
Returns:: This builder for method chaining.

add_samples(samples)[source]

Add multiple samples to the sheet.

Parameters:: samples (list[AvitiSample]) – The samples to add.
Return type:: AvitiSheetBuilder
Returns:: This builder for method chaining.

remove_sample(sample)[source]

Remove a sample from the sheet.

Parameters:: sample (AvitiSample) – The sample to remove.
Return type:: AvitiSheetBuilder
Returns:: This builder for method chaining.
Raises:: ValueError – If the sample is not found.

remove_sample_by_name(sample_name)[source]

Remove a sample by its name.

Parameters:: sample_name (str) – The name of the sample to remove.
Return type:: AvitiSheetBuilder
Returns:: This builder for method chaining.
Raises:: ValueError – If no sample with the given name is found.

remove_samples_by_project(project)[source]

Remove all samples with the specified project.

Parameters:: project (str) – The project name to match.
Return type:: AvitiSheetBuilder
Returns:: This builder for method chaining.

update_sample_by_name(sample_name, **updates)[source]

Update a sample by its name.

Parameters:

sample_name (str) – The name of the sample to update.
**updates – Fields to update on the sample.

Return type:

Returns:

This builder for method chaining.

Raises:

ValueError – If no sample with the given name is found.

clear_samples()[source]

Remove all samples from the sheet.

Return type:: AvitiSheetBuilder
Returns:: This builder for method chaining.

add_run_value(key, value)[source]

Add or update a run value.

Parameters:

key (str) – The run value key.
value (str) – The run value.

Return type:

Returns:

This builder for method chaining.

add_run_values(values)[source]

Add or update multiple run values.

Parameters:: values (Mapping[str, str]) – Dictionary of key-value pairs to add.
Return type:: AvitiSheetBuilder
Returns:: This builder for method chaining.

remove_run_value(key)[source]

Remove a run value.

Parameters:: key (str) – The key to remove.
Return type:: AvitiSheetBuilder
Returns:: This builder for method chaining.
Raises:: KeyError – If the key is not found.

clear_run_values()[source]

Remove all run values.

Return type:: AvitiSheetBuilder
Returns:: This builder for method chaining.

add_setting(name, value, lane=None)[source]

Add a setting entry.

Parameters:

name (str) – The setting name.
value (str) – The setting value.
lane (str | None) – Optional lane specification.

Return type:

Returns:

This builder for method chaining.

add_settings(settings)[source]

Add multiple setting entries.

Parameters:: settings (list[AvitiSettingEntry]) – List of setting entries to add.
Return type:: AvitiSheetBuilder
Returns:: This builder for method chaining.

remove_settings_by_name(name)[source]

Remove all settings with the specified name.

Parameters:: name (str) – The setting name to remove.
Return type:: AvitiSheetBuilder
Returns:: This builder for method chaining.

remove_settings_by_name_and_lane(name, lane)[source]

Remove settings with exact name and lane match.

Parameters:

name (str) – The setting name to remove.
lane (str | None) – The lane specification to match.

Return type:

Returns:

This builder for method chaining.

clear_settings()[source]

Remove all settings.

Return type:: AvitiSheetBuilder
Returns:: This builder for method chaining.

build()[source]

Build the immutable AvitiSheet instance.

Return type:: AvitiSheet
Returns:: A new AvitiSheet with the builder’s data.
Raises:: ValidationError – If the data is invalid.

Parsers

Parser - Common

Shared models / value objects for CSV parsing configuration.

class elsheeto.parser.common.CsvDelimiter(*values)[source]

Bases: str, Enum

Enumeration of common CSV delimiters.

AUTO = 'auto': Auto-detect

COMMA = 'comma': Comma (,)

TAB = 'tab': Tab (t)

SEMICOLON = 'semicolon': Semicolon (;)

candidate_delimiters()[source]

Return candidate delimiters for the given enum value.

Return type:: list[str]

class elsheeto.parser.common.ColumnConsistency(*values)[source]

Bases: str, Enum

Modes for handling inconsistent columns in CSV files.

STRICT_SECTIONED = 'strict_sectioned': Strict mode requiring consistent columns in each section.

STRICT_GLOBAL = 'strict_global': Strict mode requiring consistent columns globally.

LOOSE = 'loose': Loose mode allowing variable columns.

PAD = 'pad': Pad missing cells silently without warnings.

WARN_AND_PAD = 'warn_and_pad': Warning mode - pad missing cells and issue warnings.

class elsheeto.parser.common.ParserConfiguration(**data)[source]

Bases: BaseModel

Configuration for a generic (sectioned) CSV parser.

Allows for configuring common parameters used when parsing CSV-like files that are sectioned as common for sequencing sample sheets.

Parameters:: data (Any)

delimiter: CsvDelimiter: Delimiter used in the CSV file, or auto-detect.

require_section_headers: bool: Whether section headers are required.

ignore_empty_lines: bool: Whether to ignore empty lines.

comment_prefixes: list[str]: Line prefixes to recognize as comments.

column_consistency: ColumnConsistency: Column consistency configuration.

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Parser - Stage 1 (Raw CSV)

Implementation of stage 1 parser.

Here, we parse the sectioned CSV files. This is done as follows.

The file is first line-by-line, performing splitting at section headings.
Each section is then interpreted as CSV and converted into ParsedRawSection objects. Depending on the parser configuration, the column delimiter is guessed globally and column counts are enforced either per-section or globally.

elsheeto.parser.stage1.LOGGER = <Logger elsheeto.parser.stage1 (WARNING)>: The module logger.

class elsheeto.parser.stage1.Parser(config)[source]

Bases: object

Splitter for sectioned CSV files.

Run CSV sniffer on the data to determine the delimiter.
Split the data into sections based on section headers.
Run global or per-section column consistency checks.
Return a ParsedRawSheet object.

Parameters:: config (ParserConfiguration)

__init__(config)[source]

Initialize the splitter with the given configuration.

Parameters:: config (ParserConfiguration)

parse(*, data)[source]

Parse the given sectioned CSV data into a ParsedRawSheet.

Parameters:: data (str) – The sectioned CSV data as a string.
Return type:: ParsedRawSheet
Returns:: The parsed raw sheet containing sections and metadata.

elsheeto.parser.stage1.from_csv(*, data, config)[source]

Parse the given sectioned CSV data.

Parameters:

data (str) – The sectioned CSV data as a string.
config (ParserConfiguration)

Return type:

ParsedRawSheet

Returns:

The parsed raw sheet.

Parser - Stage 2 (Structured)

Implementation of stage 2 parser.

Stage 2 converts the raw sectioned data from stage 1 into structured content: - Key-value sections (Header, Settings, etc.) become HeaderSection objects - Tabular sections (Data, Samples, etc.) become DataSection objects

The parser determines section types based on content structure and known patterns.

elsheeto.parser.stage2.LOGGER = <Logger elsheeto.parser.stage2 (WARNING)>: The module logger.

class elsheeto.parser.stage2.Parser(config)[source]

Bases: object

Stage 2 parser that converts raw sectioned data into structured content.

Converts ParsedRawSheet (stage 1) into ParsedSheet (stage 2) by: - Identifying section types (key-value vs tabular) - Converting key-value sections to HeaderSection objects - Converting tabular sections to DataSection objects - Applying configuration-based transformations

Parameters:: config (ParserConfiguration)

__init__(config)[source]

Initialize the parser with the given configuration.

Parameters:: config (ParserConfiguration) – Parser configuration to use.

parse(*, raw_sheet)[source]

Convert raw sectioned data into structured content.

Parameters:: raw_sheet (ParsedRawSheet) – The raw parsed sheet from stage 1.
Return type:: ParsedSheet
Returns:: The structured parsed sheet.

elsheeto.parser.stage2.from_stage1(*, raw_sheet, config)[source]

Convert raw sectioned data into structured content.

Parameters:

raw_sheet (ParsedRawSheet) – The raw parsed sheet from stage 1.
config (ParserConfiguration) – Parser configuration to use.

Return type:

ParsedSheet

Returns:

The structured parsed sheet.

Parser - Illumina v1

Implementation of stage 3 parser for Illumina v1 sample sheets.

Stage 3 converts the structured content from stage 2 into platform-specific validated models. This module handles Illumina v1 sample sheet format conversion.

elsheeto.parser.illumina_v1.LOGGER = <Logger elsheeto.parser.illumina_v1 (WARNING)>: The module logger.

class elsheeto.parser.illumina_v1.Parser(config)[source]

Bases: object

Stage 3 parser for Illumina v1 sample sheets.

Converts ParsedSheet (stage 2) into IlluminaSampleSheet by: - Mapping header sections to IlluminaHeader - Converting reads data to IlluminaReads - Parsing settings into IlluminaSettings - Validating and converting data rows to IlluminaSample objects - Applying Illumina v1 specific validation rules

Parameters:: config (ParserConfiguration)

__init__(config)[source]

Initialize the parser with the given configuration.

Parameters:: config (ParserConfiguration) – Parser configuration to use.

parse(*, parsed_sheet)[source]

Convert structured sheet data into Illumina v1 sample sheet.

Parameters:

parsed_sheet (ParsedSheet) – The structured parsed sheet from stage 2.

Return type:

Returns:

The validated Illumina v1 sample sheet.

Raises:

ValueError – If the sheet cannot be converted to Illumina v1 format.
ValidationError – If the data doesn’t meet Illumina v1 requirements.

elsheeto.parser.illumina_v1.from_stage2(*, parsed_sheet, config)[source]

Convert structured sheet data into Illumina v1 sample sheet.

Parameters:

parsed_sheet (ParsedSheet) – The structured parsed sheet from stage 2.
config (ParserConfiguration) – Parser configuration to use.

Return type: