Table Attributes#

Attributes are descriptors attached to Table classes. They describe scalar values associated with an entire table of data. Instead of repeating the value for every row, attributes efficiently store it just once.

Attributes are preserved through serialization, because they are stored in table metadata.

Example usage:

import quivr as qv

class Observations(qv.Table):
    x = qv.Float64Column()
    y = qv.Float64Column()
    z = qv.Float64Column()

    reference_frame = qv.StringAttribute(default="earth")


 obs = Observations.from_kwargs(
    x=[1, 2, 3],
    y=[4, 5, 6]
    z=[7, 8, 9],
    reference_frame="mars"
 )

 print(obs.reference_frame)  # prints 'mars'

Mutability#

By default, attributes are immutable: they can be set when a Table instance is created, but they cannot be modified. If you need an attribute to be mutable, you can do so by passing mutable=True to the Attribute constructor:

class Dataset(qv.Table):
    measurements = qv.Int64Column()
    source = qv.StringAttribute(mutable=True)

p = Dataset.from_kwargs(measurements=[1, 2, 3], source="earth")
p.source = "mars"  # only if p.source is mutable!

Mutability can have confusing behavior when working with nested tables (like with Table.as_column()). When you chain accessors to access a sub-table, your changes to that sub-table’s attributes won’t be reflected back in the original table unless you explicitly re-attach the sub-table to the parent. This is easier to explain with code:

class Dataset(qv.Table):
    measurements = qv.Int64Column()
    source = qv.StringAttribute(mutable=True)

class Database(qv.Table):
    datasets = Dataset.as_column()

d = Database.from_kwargs(
    datasets=Dataset.from_kwargs(
        measurements=[1, 2, 3],
        source="earth",
    )
)
# Don't do this:
d.datasets.source = "mars"
print(d.datasets.source)  # prints "earth" - the value is unchanged!

# Do this instead:
ds = d.datasets
ds.source = "mars"
d.datasets = ds
print(d.datasets.source)  # Now prints "mars"

Reference#

class quivr.StringAttribute(default=None, mutable=False)#

StringAttribute represents a string which is stored as UTF-8 bytes in Table metadata.

Parameters:: default (Optional[str]) – The default value for this attribute. If no default is provided, then the attribute must be set whenever constructing a table that uses it.

class quivr.FloatAttribute(default=None, mutable=False, nbytes=8)#

FloatAttribute represents a floating-point number which is stored as little-endian bytes in Table metadata.

The number of bytes used to store the float must be specified up-front.

Parameters:

default (Optional[float]) – The default value for this attribute. If no default is provided, then the attribute must be set whenever constructing a table that uses it.
nbytes (int) – The number of bytes to use to store the float. Must be 2, 4 or 8.

class quivr.IntAttribute(default=None, mutable=False, nbytes=8, signed=True)#

IntAttribute represents an integer which is stored as little-endian bytes in Table metadata.

The number of bytes used to store the integer must be specified up-front, as well as whether it is signed.

Parameters:

default (Optional[int]) – The default value for this attribute. If no default is provided, then the attribute must be set whenever constructing a table that uses it.
nbytes (int) – The number of bytes to use to store the integer. Must be 1, 2, 4 or 8.
signed (bool) – Whether the integer is signed or unsigned.