opatio.card.datacard module¶

class opatio.card.datacard.CardHeader(numTables: int, indexOffset: int, cardSize: int, comment: str, reserved: bytes = b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00', magicNumber: str = 'CARD', headerSize: int = 256)[source]¶

Bases: OPATEntity

Represents the header of a data card.

numTables¶

Number of tables in the data card.

Type:: int

indexOffset¶

Offset to the index section in bytes.

Type:: int

cardSize¶

Total size of the data card in bytes.

Type:: int

comment¶

Comment section of the header.

Type:: str

reserved¶

Reserved for future use (default is 100 null bytes).

Type:: bytes

magicNumber¶

Magic number to validate the data card (default is “CARD”).

Type:: str

headerSize¶

Fixed size of the data card header (default is 256 bytes).

Type:: int

ascii() → str[source]¶

Get the ASCII representation of the card header.

Returns:: The ASCII representation.
Return type:: str

Examples

>>> header = CardHeader(numTables=1, indexOffset=256, cardSize=512, comment="Example")
>>> print(header.ascii())
========== Card Header ==========
>> Magic Number: CARD
>> Number of Tables: 1
>> Header Size: 256
>> Index Offset: 256
>> Card Size: 512
>> Comment: Example

cardSize: int¶

comment: str¶

copy()[source]¶

Create a copy of the card header.

Returns:: A copy of the card header.
Return type:: CardHeader

Examples

>>> header = CardHeader(numTables=1, indexOffset=256, cardSize=512, comment="Example")
>>> header_copy = header.copy()
>>> header_copy == header
True

headerSize: int = 256¶

indexOffset: int¶

magicNumber: str = 'CARD'¶

numTables: int¶

reserved: bytes = b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00'¶

set_comment(comment: str)[source]¶

Set the comment of the data card.

Parameters:: comment (str) – The comment to set.
Raises:: ValueError – If the comment string exceeds 128 characters.

Examples

>>> header = CardHeader(numTables=0, indexOffset=0, cardSize=0, comment="")
>>> header.set_comment("This is a comment.")

class opatio.card.datacard.CardIndexEntry(tag: str, byteStart: int, byteEnd: int, numColumns: int, numRows: int, columnName: str, rowName: str, size: int = 1, reserved: bytes = b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00')[source]¶

Bases: OPATEntity

Represents an entry in the index of a data card.

tag¶

Tag to identify the table.

Type:: str

byteStart¶

Byte start position of the table relative to the start of the card.

Type:: int

byteEnd¶

Byte end position of the table relative to the start of the card.

Type:: int

numColumns¶

Number of columns in the table.

Type:: int

numRows¶

Number of rows in the table.

Type:: int

columnName¶

Name of the column.

Type:: str

rowName¶

Name of the row.

Type:: str

size¶

Length of the row entry (default is 1). Maximum is 2^64 - 1.

Type:: int

reserved¶

Reserved for future use (default is 12 null bytes).

Type:: bytes

ascii() → str[source]¶

Get the ASCII representation of the card index.

Returns:: The ASCII representation.
Return type:: str

Examples

>>> index = CardIndexEntry(tag="Example", byteStart=0, byteEnd=64, numColumns=4, numRows=4, columnName="col", rowName="row", size=1)
>>> print(index.ascii())
Example  |        0 |       64 |        4 |        4 | col      | row       | 1

byteEnd: int¶

byteStart: int¶

columnName: str¶

copy()[source]¶

Create a copy of the card index entry.

Returns:: A copy of the card index entry.
Return type:: CardIndexEntry

Examples

>>> index = CardIndexEntry(tag="Example", byteStart=0, byteEnd=64, numColumns=4, numRows=4, columnName="col", rowName="row")
>>> index_copy = index.copy()
>>> index_copy == index
True

numColumns: int¶

numRows: int¶

reserved: bytes = b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00'¶

rowName: str¶

size: int = 1¶

tag: str¶

class opatio.card.datacard.DataCard[source]¶

Bases: OPATEntity

Represents a data card containing a header, index, and tables.

header¶

Header of the data card.

Type:: CardHeader

index¶

Index of the data card, mapping tags to index entries.

Type:: Dict[str, CardIndexEntry]

tables¶

Tables in the data card, mapped by their tags.

Type:: Dict[str, OPATTable]

add_table(tag: str, table: OPATTable, columnName: str = 'columnValues', rowName: str = 'rowValues')[source]¶: Add a table to the data card.

sha256() → bytes[source]¶: Compute the SHA-256 hash of the data card, including all tables and their data.

ascii() → str[source]¶: Get the ASCII representation of the data card.

copy() → DataCard[source]¶: Create a deep copy of the data card.

add_table(tag: str, table: OPATTable, columnName: str = 'columnValues', rowName: str = 'rowValues')[source]¶

Add a table to the data card.

Parameters:

tag (str) – Tag to identify the table.
table (OPATTable) – The table to add.
columnName (str, optional) – Name of the column (default is “columnValues”).
rowName (str, optional) – Name of the row (default is “rowValues”).

Raises:

TypeError – If table is not an OPATTable or tag is not a string.
ValueError – If a table with the same tag already exists.

Examples

>>> card = DataCard()
>>> table = OPATTable(columnValues=[1.0, 2.0], rowValues=[3.0, 4.0], data=[[5.0, 6.0], [7.0, 8.0]])
>>> card.add_table(tag="Example", table=table)

ascii() → str[source]¶

Get the ASCII representation of the data card.

Returns:: The ASCII representation.
Return type:: str

Examples

>>> card = DataCard()
>>> print(card.ascii())

copy()[source]¶

Create a copy of the data card.

Returns:: A copy of the data card.
Return type:: DataCard

Examples

>>> card = DataCard()
>>> card_copy = card.copy()
>>> card_copy == card
True

header: CardHeader¶

index: Dict[str, CardIndexEntry]¶

keys() → List[str][source]¶

Get the list of table tags in the data card.

Returns:: A list of tags corresponding to the tables in the data card.
Return type:: List[str]

Examples

>>> card = DataCard()
>>> table1 = OPATTable(columnValues=[1.0, 2.0], rowValues=[3.0, 4.0], data=[[5.0, 6.0], [7.0, 8.0]])
>>> table2 = OPATTable(columnValues=[1.5, 2.5], rowValues=[3.5, 4.5], data=[[9.0, 10.0], [11.0, 12.0]])
>>> card.add_table(tag="Table1", table=table1)
>>> card.add_table(tag="Table2", table=table2)
>>> print(card.keys())
['Table1', 'Table2']

sha256() → bytes[source]¶

Compute the SHA-256 hash of the data card.

Returns:: The SHA-256 hash of the data card.
Return type:: bytes

Examples

>>> card = DataCard()
>>> table = OPATTable(columnValues=[1.0, 2.0], rowValues=[3.0, 4.0], data=[[5.0, 6.0], [7.0, 8.0]])
>>> card.add_table(tag="Example", table=table)
>>> card.sha256()

tables: Dict[str, OPATTable]¶

Bases: OPATEntity

Represents the data of a single table in an OPAT file.

columnValues¶

Column values of the table.

Type:: Iterable[float]

rowValues¶

Row values of the table.

Type:: Iterable[float]

data¶

Data of the table, stored as a 2D or 3D array.

Type:: npt.ArrayLike

Notes

This class is primarily used internally by opatio. Advanced users may create their own tables using this class if needed.

ascii() → str[source]¶

Get the ASCII representation of the OPAT table.

Returns:: The ASCII representation.
Return type:: str

Examples

>>> table = OPATTable(columnValues=[1.0, 2.0], rowValues=[3.0, 4.0], data=[[5.0, 6.0], [7.0, 8.0]])
>>> print(table.ascii())

columnValues: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]¶

static compute_col_width(size: int, floatWidth: int) → int[source]¶

Compute the total width of a cell for ASCII representation.

Parameters:

size (int) – Number of floats in the cell.
floatWidth (int) – Width of each float.

Returns:

Total width of the cell.

Return type:

int

copy()[source]¶

Create a copy of the OPAT table.

Returns:: A copy of the OPAT table.
Return type:: OPATTable

Examples

>>> table = OPATTable(columnValues=[1.0, 2.0], rowValues=[3.0, 4.0], data=[[5.0, 6.0], [7.0, 8.0]])
>>> table_copy = table.copy()
>>> table_copy == table
True

data: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]¶

format_centered(value: float, floatWidth: int) → str[source]¶

Format a float value centered in a fixed-width field.

Parameters:

value (float) – The value to format.
floatWidth (int) – The width of the float.

Returns:

The formatted string.

Return type:

str

rowValues: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]¶

sha256() → _Hash[source]¶

Compute the SHA-256 checksum of the given data.

Returns:: The SHA-256 checksum.
Return type:: bytes
Raises:: ValueError – If the data cannot be cast to a numpy array.

Examples

>>> table = OPATTable(columnValues=[1.0, 2.0], rowValues=[3.0, 4.0], data=[[5.0, 6.0], [7.0, 8.0]])
>>> table.sha256()

property size: int¶

Get the size of the table, which is 1 for 2D data or the third dimension for 3D data.

Returns:: The size of the table.
Return type:: int