Python API Reference

Lib_pod5 Reference

Submodules

Module contents

POD5 Format

Bindings for the POD5 file format

class Calibration(offset: float, scale: float)[source]

Bases: object

Parameters to convert the signal data to picoamps.

Parameters:

  • offset (float) – Calibration offset used to convert raw ADC data into pA readings.

  • scale (float) – Calibration scale factor used to convert raw ADC data into pA readings.

__init__(offset: float, scale: float) → None
classmethod from_range(offset: float, adc_range: float, digitisation: float) → Calibration[source]

Create a Calibration instance from offset, adc_range and digitisation

offset: float

Calibration offset used to convert raw ADC data into pA readings.

scale: float

Calibration scale factor used to convert raw ADC data into pA readings.

class CompressedRead(read_id: ~uuid.UUID, pore: ~pod5.pod5_types.Pore, calibration: ~pod5.pod5_types.Calibration, read_number: int, start_sample: int, median_before: float, end_reason: ~pod5.pod5_types.EndReason, run_info: ~pod5.pod5_types.RunInfo, num_minknow_events: int = 0, tracked_scaling: ~pod5.pod5_types.ShiftScalePair = <factory>, predicted_scaling: ~pod5.pod5_types.ShiftScalePair = <factory>, num_reads_since_mux_change: int = 0, time_since_mux_change: float = 0.0, signal_chunks: ~typing.List[~numpy.ndarray[~typing.Any, ~numpy.dtype[~numpy.uint8]]] = <factory>, signal_chunk_lengths: ~typing.List[int] = <factory>)[source]

Bases: BaseRead

POD5 Read Data with a compressed signal.

Parameters:

  • read_id (UUID) – The read_id of this read as UUID.

  • pore (Pore) – Pore data.

  • calibration (Calibration) – Calibration data.

  • read_number (int) – The read number on channel. This is increasing but typically not necessarily consecutive.

  • start_sample (int) – The number samples recorded on this channel before the read started.

  • median_before (float) – The level of current in the well before this read.

  • end_reason (EndReason) – EndReason data.

  • run_info (RunInfo) – RunInfo data.

  • signal_chunks (List[numpy.array[uint8]]) – Compressed signal data in chunks.

  • signal_chunk_lengths (List[int]) – Chunk lengths (number of samples) of signal data before compression.

__init__(read_id: ~uuid.UUID, pore: ~pod5.pod5_types.Pore, calibration: ~pod5.pod5_types.Calibration, read_number: int, start_sample: int, median_before: float, end_reason: ~pod5.pod5_types.EndReason, run_info: ~pod5.pod5_types.RunInfo, num_minknow_events: int = 0, tracked_scaling: ~pod5.pod5_types.ShiftScalePair = <factory>, predicted_scaling: ~pod5.pod5_types.ShiftScalePair = <factory>, num_reads_since_mux_change: int = 0, time_since_mux_change: float = 0.0, signal_chunks: ~typing.List[~numpy.ndarray[~typing.Any, ~numpy.dtype[~numpy.uint8]]] = <factory>, signal_chunk_lengths: ~typing.List[int] = <factory>) → None
property decompressed_signal: ndarray[Any, dtype[int16]]

Decompress and return the chunked signal data as a contiguous numpy array.

Returns:

decompressed_signal – Decompressed signal data

Return type:

numpy.array[int16]

property sample_count: int

Return the total number of samples in the uncompressed signal.

signal_chunk_lengths: List[int]

Chunk lengths (number of samples) of signal data before compression.

signal_chunks: List[ndarray[Any, dtype[uint8]]]

Compressed signal data in chunks.

class EndReason(reason: EndReasonEnum, forced: bool)[source]

Bases: object

Data on why the Read ended.

Parameters:

  • reason (EndReasonEnum) – The end reason enumeration.

  • forced (bool) – True if it is a ‘forced’ read break.

__init__(reason: EndReasonEnum, forced: bool) → None
forced: bool

True if it is a ‘forced’ read break (e.g. mux_change, unblock), False otherwise.

classmethod from_reason_with_default_forced(reason: EndReasonEnum) → EndReason[source]

Return a new EndReason instance with the ‘forced’ flag set to the expected default for the given reason

property name: str

Return the reason name as a lower string

reason: EndReasonEnum

The end reason enumeration

class EndReasonEnum(value)[source]

Bases: Enum

EndReason Enumeration

DATA_SERVICE_UNBLOCK_MUX_CHANGE = 3
MUX_CHANGE = 1
SIGNAL_NEGATIVE = 5
SIGNAL_POSITIVE = 4
UNBLOCK_MUX_CHANGE = 2
UNKNOWN = 0
class Pore(channel: int, well: int, pore_type: str)[source]

Bases: object

Data for the pore that the Read was acquired on

Parameters:

  • channel (int) – 1-indexed channel.

  • well (int) – 1-indexed well.

  • pore_type (PoreType) – The pore type present in the well.

__init__(channel: int, well: int, pore_type: str) → None
channel: int

1-indexed channel.

pore_type: str

Name of the pore type present in the well.

well: int

1-indexed well.

class Read(read_id: ~uuid.UUID, pore: ~pod5.pod5_types.Pore, calibration: ~pod5.pod5_types.Calibration, read_number: int, start_sample: int, median_before: float, end_reason: ~pod5.pod5_types.EndReason, run_info: ~pod5.pod5_types.RunInfo, num_minknow_events: int = 0, tracked_scaling: ~pod5.pod5_types.ShiftScalePair = <factory>, predicted_scaling: ~pod5.pod5_types.ShiftScalePair = <factory>, num_reads_since_mux_change: int = 0, time_since_mux_change: float = 0.0, signal: ~numpy.ndarray[~typing.Any, ~numpy.dtype[~numpy.int16]] = <factory>)[source]

Bases: BaseRead

POD5 Read Data with an uncompressed signal

Parameters:

  • read_id (UUID) – The read_id of this read as UUID.

  • pore (Pore) – Pore data.

  • calibration (Calibration) – Calibration data.

  • read_number (int) – The read number on channel. This is increasing but typically not necessarily consecutive.

  • start_sample (int) – The number samples recorded on this channel before the read started.

  • median_before (float) – The level of current in the well before this read.

  • end_reason (EndReason) – EndReason data.

  • run_info (RunInfo) – RunInfo data.

  • signal (numpy.array[int16]) – Uncompressed signal data.

__init__(read_id: ~uuid.UUID, pore: ~pod5.pod5_types.Pore, calibration: ~pod5.pod5_types.Calibration, read_number: int, start_sample: int, median_before: float, end_reason: ~pod5.pod5_types.EndReason, run_info: ~pod5.pod5_types.RunInfo, num_minknow_events: int = 0, tracked_scaling: ~pod5.pod5_types.ShiftScalePair = <factory>, predicted_scaling: ~pod5.pod5_types.ShiftScalePair = <factory>, num_reads_since_mux_change: int = 0, time_since_mux_change: float = 0.0, signal: ~numpy.ndarray[~typing.Any, ~numpy.dtype[~numpy.int16]] = <factory>) → None
property sample_count: int

Return the total number of samples in the uncompressed signal.

signal: ndarray[Any, dtype[int16]]

Uncompressed signal data.

class ReadRecord(reader: Reader, batch: ReadRecordBatch, row: int, batch_signal_cache: Optional[List[ndarray[Any, dtype[int16]]]] = None, selected_batch_index: Optional[int] = None)[source]

Bases: object

Represents the data for a single read from a pod5 record.

__init__(reader: Reader, batch: ReadRecordBatch, row: int, batch_signal_cache: Optional[List[ndarray[Any, dtype[int16]]]] = None, selected_batch_index: Optional[int] = None)[source]
property byte_count: int

Get the number of bytes used to store the reads data.

calibrate_signal_array(signal_array_adc: ndarray[Any, dtype[int16]]) → ndarray[Any, dtype[float32]][source]

Transform an array of int16 signal data from ADC space to pA.

Return type:

A numpy array of signal data with float32 type.

property calibration: Calibration

Get the calibration data associated with the read.

property calibration_digitisation: int

Get the digitisation value used by the sequencer.

Intended to assist workflows ported from legacy file formats.

property calibration_range: float

Get the calibration range value.

Intended to assist workflows ported from legacy file formats.

property end_reason: EndReason

Get the end reason data associated with the read.

property end_reason_index: int

Get the dictionary index of the end reason data associated with the read. This property is the same as the EndReason enumeration value.

property has_cached_signal: bool

Get if cached signal is available for this read.

property median_before: float

Get the median before level (in pico amps) for the read.

property num_minknow_events: float

Find the number of minknow events in the read.

property num_reads_since_mux_change: int

Number of selected reads since the last mux change on this reads channel.

property num_samples: int

Get the number of samples in the reads signal data.

property pore: Pore

Get the pore data associated with the read.

property predicted_scaling: ShiftScalePair

Find the predicted scaling value in the read.

property read_id: UUID

Get the unique read identifier for the read as a UUID.

property read_number: int

Get the integer read number of the read.

property run_info: RunInfo

Get the run info data associated with the read.

property run_info_index: int

Get the dictionary index of the run info data associated with the read.

property sample_count: int

Get the number of samples in the reads signal data.

property signal: ndarray[Any, dtype[int16]]

Get the full signal for the read.

Returns:

A numpy array of signal data with int16 type.

Return type:

numpy.ndarray[int16]

signal_for_chunk(index: int) → ndarray[Any, dtype[int16]][source]

Get the signal for a given chunk of the read.

Returns:

A numpy array of signal data with int16 type for the specified chunk.

Return type:

numpy.ndarray[int16]

property signal_pa: ndarray[Any, dtype[float32]]

Get the full signal for the read, calibrated in pico amps.

Returns:

A numpy array of signal data in pico amps with float32 type.

Return type:

numpy.ndarray[float32]

property signal_rows: List[SignalRowInfo]

Get all signal rows for the read

Returns:

A list of signal row data (as SignalRowInfo) in the read.

Return type:

list[SignalRowInfo]

property start_sample: int

Get the absolute sample which the read started.

property time_since_mux_change: float

Time in seconds since the last mux change on this reads channel.

to_read() → Read[source]

Create a mutable pod5.pod5_types.Read from this ReadRecord instance.

Return type:

pod5.pod5_types.Read

property tracked_scaling: ShiftScalePair

Find the tracked scaling value in the read.

class ReadRecordBatch(reader: Reader, batch: RecordBatch)[source]

Bases: object

Read data for a batch of reads.

__init__(reader: Reader, batch: RecordBatch)[source]
property cached_sample_count_column: ndarray[Any, dtype[uint64]]

Get the sample counts from the cached signal data

property cached_samples_column: List[ndarray[Any, dtype[int16]]]

Get the samples column from the cached signal data

property columns: ReadRecordV3Columns

Return the data from this batch as a ReadRecordColumns instance

get_read(row: int) → ReadRecord[source]

Get the ReadRecord at row index

property num_reads: int

Return the number of rows in this RecordBatch

property read_id_column: FixedSizeBinaryArray

Get the column of read ids for this batch

property read_number_column: UInt32Array

Get the column of read numbers for this batch

reads() → Generator[ReadRecord, None, None][source]

Iterate all reads in this batch.

Yields:

ReadRecord – ReadRecord instances in the file.

set_cached_signal(signal_cache: Pod5SignalCacheBatch) → None[source]

Set the signal cache

set_selected_batch_rows(selected_batch_rows: Iterable[int]) → None[source]

Set the selected batch rows

class Reader(path: Union[PathLike, str])[source]

Bases: object

The base reader for POD5 data

__init__(path: Union[PathLike, str])[source]

Open a pod5 filepath for reading

property batch_count: int

Find the number of read batches available in the file.

close() → None[source]

Close files handles

property file_identifier: UUID
property file_version: Version
property file_version_pre_migration: Version
get_batch(index: int) → ReadRecordBatch[source]

Get a read batch in the file.

Returns:

The requested batch as a ReadRecordBatch.

Return type:

ReadRecordBatch

property inner_file_reader: Pod5FileReader

Access the inner c_api Pod5FileReader - use with caution

property is_vbz_compressed: bool

Return if this file’s signal is compressed

property num_reads: int

Find the number of reads in the file.

property path: Path

Return the path to this pod5 file

read_batches(selection: Optional[List[str]] = None, batch_selection: Optional[Iterable[int]] = None, missing_ok: bool = False, preload: Optional[Set[str]] = None) → Generator[ReadRecordBatch, None, None][source]

Iterate batches in the file, optionally selecting certain rows.

Parameters:

  • selection (iterable[str]) – The read ids to walk in the file.

  • batch_selection (iterable[int]) – The read batches to walk in the file.

  • missing_ok (bool) – If selection contains entries not found in the file, an error will be raised.

  • preload (set[str]) – Columns to preload - “samples” and “sample_count” are valid values

Return type:

An iterable of ReadRecordBatch in the file.

property read_ids: List[str]

Return all read_ids as a list of strings.

For the most performant implementation consider Reader.read_ids_raw

property read_ids_raw: ChunkedArray

Return chunked arrow array of read ids.

To get read ids as string use Reader.read_ids

property read_table: RecordBatchFileReader

Access the pod5 read table

reads(selection: Optional[Iterable[str]] = None, missing_ok: bool = False, preload: Optional[Set[str]] = None) → Generator[ReadRecord, None, None][source]

Iterate reads in the file, optionally filtering for certain read ids.

Parameters:

  • selection (iterable[str]) – The read ids to walk in the file.

  • missing_ok (bool) – If selection contains entries not found in the file, an error will be raised.

  • preload (set[str]) – Columns to preload - “samples” and “sample_count” are valid values

Return type:

An iterable of ReadRecord in the file.

property reads_table_version: int
property run_info_table: RecordBatchFileReader

Access the pod5 run_info table

property signal_batch_row_count: int

Return signal batch row count

property signal_table: RecordBatchFileReader

Access the pod5 signal table - use with caution

property writing_software: str
class RunInfo(acquisition_id: str, acquisition_start_time: datetime, adc_max: int, adc_min: int, context_tags: Dict[str, str], experiment_name: str, flow_cell_id: str, flow_cell_product_code: str, protocol_name: str, protocol_run_id: str, protocol_start_time: datetime, sample_id: str, sample_rate: int, sequencing_kit: str, sequencer_position: str, sequencer_position_type: str, software: str, system_name: str, system_type: str, tracking_id: Dict[str, str])[source]

Bases: object

Higher-level information about the Reads that correspond to a part of an experiment, protocol or acquisition

Parameters:

  • acquisition_id (str) – A unique identifier for the acquisition.

  • acquisition_start_time (datetime.datetime) – This is the clock time for sample 0

  • adc_max (int) – The maximum ADC value that might be encountered.

  • adc_min (int) – The minimum ADC value that might be encountered.

  • context_tags (Dict[str, str]) – The context tags for the run. (For compatibility with fast5).

  • experiment_name (str) – The user-supplied name for the experiment being run.

  • flow_cell_id (str) – Uniquely identifies the flow cell the data was captured on.

  • flow_cell_product_code (str) – Identifies the type of flow cell the data was captured on.

  • protocol_name (str) – The name of the protocol that was run.

  • protocol_run_id (str) – The unique identifier for the protocol run that produced this data.

  • protocol_start_time (datetime.datetime) – When the protocol that the acquisition was part of started.

  • sample_id (str) – A user-supplied name for the sample being analysed.

  • sample_rate (int) – The number of samples acquired each second on each channel.

  • sequencing_kit (str) – The type of sequencing kit used to prepare the sample.

  • sequencer_position (str) – The sequencer position the data was collected on.

  • sequencer_position_type (str) – The type of sequencing hardware the data was collected on.

  • software (str) – A description of the software that acquired the data.

  • system_name (str) – The name of the system the data was collected on.

  • system_type (str) – The type of system the data was collected on.

  • tracking_id (Dict[str, str]) – The tracking id for the run. (For compatibility with fast5).

__init__(acquisition_id: str, acquisition_start_time: datetime, adc_max: int, adc_min: int, context_tags: Dict[str, str], experiment_name: str, flow_cell_id: str, flow_cell_product_code: str, protocol_name: str, protocol_run_id: str, protocol_start_time: datetime, sample_id: str, sample_rate: int, sequencing_kit: str, sequencer_position: str, sequencer_position_type: str, software: str, system_name: str, system_type: str, tracking_id: Dict[str, str]) → None
acquisition_id: str

A unique identifier for the acquisition - note that readers should not depend on this uniquely determining the other fields in the run_info, or being unique among the dictionary keys.

acquisition_start_time: datetime

This is the clock time for sample 0

adc_max: int

The maximum ADC value that might be encountered. This is a hardware constraint.

adc_min: int

The minimum ADC value that might be encountered. This is a hardware constraint.

context_tags: Dict[str, str]

The context tags for the run. (For compatibility with fast5).

experiment_name: str

The user-supplied name for the experiment being run.

flow_cell_id: str

Uniquely identifies the flow cell the data was captured on. This is written on the flow cell case.

flow_cell_product_code: str

Identifies the type of flow cell the data was captured on.

protocol_name: str

The name of the protocol that was run.

protocol_run_id: str

The unique identifier for the protocol run that produced this data.

protocol_start_time: datetime

When the protocol that the acquisition was part of started.

sample_id: str

A user-supplied name for the sample being analysed.

sample_rate: int

The number of samples acquired each second on each channel.

sequencer_position: str

The sequencer position the data was collected on. For removable positions, like MinION Mk1Bs, this is unique (e.g. ‘MN12345’), while for integrated positions it is not (e.g. ‘X1’ on a GridION).

sequencer_position_type: str

The type of sequencing hardware the data was collected on. For example: ‘MinION Mk1B’ or ‘GridION’ or ‘PromethION’.

sequencing_kit: str

The type of sequencing kit used to prepare the sample.

software: str

A description of the software that acquired the data. For example: ‘MinKNOW 21.05.12 (Bream 5.1.6, Configurations 16.2.1, Core 5.1.9, Guppy 4.2.3)’.

system_name: str

The name of the system the data was collected on. This might be a sequencer serial (eg: ‘GXB1234’) or a host name (e.g. ‘Lab PC’).

system_type: str

The type of system the data was collected on. For example, ‘GridION Mk1’ or ‘PromethION P48’. If the system is not a Nanopore sequencer with built-in compute, this will be a description of the operating system (e.g. ‘Ubuntu 20.04’).

tracking_id: Dict[str, str]

The tracking id for the run. (For compatibility with fast5).

class Writer(path: Union[PathLike, str], software_name: str = 'Python API')[source]

Bases: object

Pod5 File Writer

__init__(path: Union[PathLike, str], software_name: str = 'Python API')[source]

Open a pod5 file for Writing.

Parameters:

  • path (os.PathLike, str) – The path to the pod5 file to create

  • software_name (str) – The name of the application used to create this pod5 file

add(obj: Union[EndReason, str, RunInfo]) → int[source]

Add a EndReason, PoreType, or RunInfo object to the Pod5 file (if it doesn’t already exist) and return the index of this object in the Pod5 file.

Parameters:

obj (EndReason, PoreType, RunInfo) – Object to find in this Pod5 file, adding it if it doesn’t exist already

Returns:

index – The index of the object in the Pod5 file

Return type:

int

add_read(read: Union[Read, CompressedRead]) → None[source]

Add a record to the open POD5 file with either compressed or uncompressed signal data depending on the given type of Read.

Parameters:

read (Read, CompressedRead) – POD5 Read or CompressedRead object to add as a record to the POD5 file.

add_reads(reads: Sequence[Union[Read, CompressedRead]]) → None[source]

Add Read objects (with uncompressed signal data) as records in the open POD5 file.

Parameters:

reads (Sequence of Read or CompressedRead exclusively) – List of Read object to be added to this POD5 file

close() → None[source]

Close the FileWriter handle

contains(obj: Union[EndReason, RunInfo]) → bool[source]

Test if this Pod5 file contains the given object.

Parameters:

obj (EndReason, RunInfo) – Object to find in this Pod5 file

Return type:

True if obj has already been added to this file

find(obj: Union[EndReason, RunInfo]) → int[source]

Returns the index of obj in this Pod5 file raising a KeyError if it is missing.

Parameters:

obj (EndReason, RunInfo) – Obj instance to find in this Pod5 file

Return type:

The index of the object in this Pod5 file

Raises:

KeyError – If the object is not in this file

property path: Path

Return the path to the pod5 file

property software_name: str

Return the software name used to open this file

format_read_id_to_str(arg0: numpy.ndarray[numpy.uint8]) → list

Format an array of read ids to string

format_read_ids(read_ids: Union[ndarray[Any, dtype[uint8]], FixedSizeBinaryArray]) → List[str][source]

Convert a packed array of read_ids and convert them to a list of strings.

Parameters:

read_ids (numpy.ndarray[uint8], pa.lib.FixedSizeBinaryArray) – Packed read_ids from a numpy.ndarray or read directly from pod5 file

Returns:

read_ids – A list of converted read_ids as strings

Return type:

list[str]

load_read_id_iterable(arg0: Iterable, arg1: numpy.ndarray[numpy.uint8]) → int

Load an iterable of read ids into a numpy array of data

pack_read_ids(read_ids: Collection[str], invalid_ok: bool = False) → ndarray[Any, dtype[uint8]][source]

Convert a Collection of read_id strings to a numpy.ndarray in preparation for writing to pod5 files.

Parameters:

read_ids (Collection[str]) – Collection of well-formatted read_id strings

Returns:

packed_read_ids – Repacked read_ids ready for writing to pod5 files.

Return type:

numpy.ndarray[uint8]

vbz_compress_signal(signal: ndarray[Any, dtype[int16]]) → ndarray[Any, dtype[uint8]][source]

Compress a numpy array of signal data

Parameters:

signal (numpy.ndarray[int16]) – The array of signal data to compress.

Returns:

compressed_signal – The compressed signal data as a numpy.ndarray[uint8] (byte array)

Return type:

numpy.array[uint8]

vbz_decompress_signal(compressed_signal: Union[ndarray[Any, dtype[uint8]], memoryview], sample_count: int) → ndarray[Any, dtype[int16]][source]

Decompress a contiguous (not-chunked) numpy array of compressed signal data

Parameters:

  • compressed_signal (numpy.ndarray[uint8]) – The array of compressed signal data to decompress.

  • sample_count (int) – The number of samples in the original signal

Return type:

A decompressed signal array numpy.ndarray[int16]

vbz_decompress_signal_chunked(compressed_signal_chunks: List[ndarray[Any, dtype[uint8]]], sample_counts: List[int]) → ndarray[Any, dtype[int16]][source]

Decompress a chunks of numpy array of compressed signal data

Parameters:

  • compressed_signal_chunks (List[numpy.ndarray[uint8]]) – A list of compressed signal data chunks to decompress.

  • sample_counts (List[int]) – The number of samples in the original signal chunks

Return type:

A decompressed signal array numpy.ndarray[int16]

Raises:

ValueError – Inconsistent parameter lengths

vbz_decompress_signal_into(compressed_signal: Union[ndarray[Any, dtype[uint8]], memoryview], output_array: ndarray[Any, dtype[int16]]) → ndarray[Any, dtype[int16]][source]

Decompress a numpy array of compressed signal data into the destination “output_array”

Parameters:

  • compressed_signal (numpy.ndarray[uint8]) – The array of compressed signal data to decompress.

  • output_array (numpy.ndarray[int16]) – The destination location for signal

Return type:

A decompressed signal array numpy.ndarray[int16]