opatio.base.opat module

class opatio.base.opat.OPAT

Bases: object

A class representing an OPAT (Open Parameterized Array Table) instance. OPAT is a structured binary file format developed by the 4D-STAR collaboration for storing all tabular data needed for 4DSSE. OPAT is liscensed under the GNU General Public License v3.0. You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

This class provides methods for managing headers, catalogs, and data cards, as well as saving OPAT files.

header

The header object containing metadata for the OPAT instance.

Type:

Header

catalog

A dictionary mapping index vectors to catalog entries.

Type:

Dict[FloatVectorIndex, CardCatalogEntry]

cards

A dictionary mapping index vectors to data cards.

Type:

Dict[FloatVectorIndex, DataCard]

set_version(version: int) → int

Sets the version of the OPAT header.

set_source(source: str) → str

Sets the source information in the OPAT header.

set_comment(comment: str) → str

Sets the comment in the OPAT header.

set_numIndex(numIndex: int) → int

Sets the number of indices in the OPAT header.

pop_card(indexVector: FloatVectorIndex | Iterable[float]) → DataCard

Removes and returns a card from the catalog and cards dictionary. The organization of the file will be updated to reflect the removal of the card.

add_card(indexVector: FloatVectorIndex | Iterable[float], card: DataCard)

Adds a data card to the catalog and cards dictionary. The organization of the file will be updated to reflect the addition of the card.

Notes

If a card already exists at the given indexVector, it will first be popped then readded with any updates applied

add_table(indexVector: FloatVectorIndex | Iterable[float], tag: str, columnValues: Iterable[float], rowValues: Iterable[float], data: Iterable[Iterable[float]], card: DataCard = ..., columnName: str = 'columnValues', rowName: str = 'rowValues') → DataCard

Adds a table to a data card and stores it in the catalog. The organization of the file will be updated to reflect the addition of the table. The card will be added to the catalog and the organization of the file will be updated to reflect the addition of the table.

Notes

If a card already exists at the given indexVector, it will first be popped then readded with any updates applied

save_as_ascii(filename: str) → str

Saves the OPAT instance as a human-readable ASCII file. This file is not a valid OPAT file in and of itself, but is meant to be human-readable for debugging purposes.

save(filename: str) → str

Saves the OPAT instance as a binary file. The file will be saved in the specified format and will be a valid OPAT file.

Examples

>>> opat = OPAT()
>>> opat.set_version(1)
>>> opat.set_source("example_source")
>>> opat.set_comment("This is a test comment.")

add_card(indexVector: FloatVectorIndex | Iterable[float], card: DataCard)

Adds a data card to the catalog and cards dictionary.

Parameters:

• indexVector (Union[FloatVectorIndex, Iterable[float]]) – The index vector for the card.

• card (DataCard) – The data card to add.

Raises:

• TypeError – If the card is not an instance of DataCard.

• RuntimeError – If an error occurs while removing an existing card.

Examples

>>> opat = OPAT()
>>> opat.set_numIndex(2)
>>> indexVector = [1.0, 2.0]
>>> card = DataCard()
>>> opat.add_card(indexVector, card)

add_table(indexVector: FloatVectorIndex | Iterable[float], tag: str, columnValues: Iterable[float], rowValues: Iterable[float], data: Iterable[Iterable[float]], card: DataCard = Ellipsis, columnName: str = 'columnValues', rowName: str = 'rowValues') → DataCard

Adds a table to a data card and stores it in the catalog.

Parameters:

• indexVector (Union[FloatVectorIndex, Iterable[float]]) – The index vector for the card.

• tag (str) – The tag for the table.

• columnValues (Iterable[float]) – The column values for the table.

• rowValues (Iterable[float]) – The row values for the table.

• data (Iterable[Iterable[float]]) – The 2D data array for the table.

• card (DataCard, optional) – The data card to add the table to. If not provided, a new card is created.

• columnName (str, optional) – The name of the column values. Default is “columnValues”.

• rowName (str, optional) – The name of the row values. Default is “rowValues”.

Returns:

The updated data card.

Return type:

DataCard

Raises:

• ValueError – If the data cannot be converted to float64 or has invalid dimensions.

• TypeError – If the tag is not a string.

• AssertionError – If the dimensions of the data, columnValues, or rowValues are invalid.

Examples

>>> opat = OPAT()
>>> opat.set_numIndex(2)
>>> indexVector = [1.0, 2.0]
>>> tag = "data"
>>> columnValues = [1.0, 2.0, 3.0]
>>> rowValues = [4.0, 5.0]
>>> data = [[1.0, 2.0], [3.0, 4.0], [5.0, 6.0]]
>>> opat.add_table(indexVector, tag, columnValues, rowValues, data)

property indexVectors: List[FloatVectorIndex]

Returns a list of index vectors in the catalog.

This property provides a convenient way to access all index vectors stored in the catalog.

Returns:

A list of index vectors.

Return type:

List[FloatVectorIndex]

Examples

>>> opat = OPAT()
>>> opat.set_numIndex(2)
>>> indexVector1 = (1.0, 2.0)
>>> indexVector2 = (3.0, 4.0)
>>> card1 = DataCard()
>>> card2 = DataCard()
>>> opat.add_card(indexVector1, card1)
>>> opat.add_card(indexVector2, card2)
>>> print(opat.indexVectors)
[FloatVectorIndex((1.0, 2.0)), FloatVectorIndex((3.0, 4.0))]

pop_card(indexVector: FloatVectorIndex | Iterable[float]) → DataCard

Removes and returns a card from the catalog and cards dictionary.

Parameters:

indexVector (Union[FloatVectorIndex, Iterable[float]]) – The index vector of the card to remove.

Returns:

The removed data card.

Return type:

DataCard

Raises:

KeyError – If the index vector is not found in the catalog.

Examples

>>> opat = OPAT()
>>> opat.set_numIndex(2)
>>> indexVector = [1.0, 2.0]
>>> card = DataCard()
>>> opat.add_card(indexVector, card)
>>> removed_card = opat.pop_card(indexVector)
>>> print(removed_card)

save(filename: str) → str

Saves the OPAT instance as a binary file.

Parameters:

filename (str) – The name of the file to save.

Returns:

The name of the saved file.

Return type:

str

Raises:

RuntimeError – If the file cannot be saved.

Examples

>>> opat = OPAT()
>>> filename = "opat_binary.opat"
>>> opat.save(filename)
>>> print(f"File saved as {filename}")

save_as_ascii(filename: str) → str

Saves the OPAT instance as a human-readable ASCII file.

Parameters:

filename (str) – The name of the file to save.

Returns:

The name of the saved file.

Return type:

str

Examples

>>> opat = OPAT()
>>> filename = "opat_ascii.txt"
>>> opat.save_as_ascii(filename)
>>> print(f"File saved as {filename}")

set_comment(comment: str) → str

Sets the comment in the OPAT header.

Parameters:

comment (str) – The comment to set.

Returns:

The updated comment.

Return type:

str

set_numIndex(numIndex: int) → int

Sets the number of indices in the OPAT header.

Parameters:

numIndex (int) – The number of indices to set. Must be greater than 0.

Returns:

The updated number of indices.

Return type:

int

Raises:

ValueError – If numIndex is less than 1.

set_source(source: str) → str

Sets the source information in the OPAT header.

Parameters:

source (str) – The source information to set.

Returns:

The updated source information.

Return type:

str

set_version(version: int) → int

Sets the version of the OPAT header.

Parameters:

version (int) – The version number to set.

Returns:

The updated version number.

Return type:

int

size() → Tuple[int, int]

Returns the size of the OPAT instance.

The size is defined as the number of indexes per card and the number of cards. For example, an OPAT file might have a size of (2, 126).

Returns:

A tuple representing the size of the OPAT instance.

Return type:

Tuple[int, int]

Examples

>>> opat = OPAT()
>>> opat.set_numIndex(2)
>>> indexVector = (1.0, 2.0)
>>> card = DataCard()
>>> opat.add_card(indexVector, card)
>>> print(opat.size())
(2, 1)