Column subset handles¶

Lightweight selector objects returned by hdu["name"] and hdu[["a", "b"]] on rustfits.CompressedTableHDU and rustfits.AsciiTableHDU. Not typically constructed directly — they expose the same read / write / __getitem__ / __setitem__ surface as the parent table but restricted to the selected column(s).

The uncompressed rustfits.TableHDU returns analogous selector objects from hdu["name"] / hdu[["a","b"]], but those types are not exposed as Python names — they’re identifiable only by the methods they support, matching the duck-typed pattern.

class rustfits.CompressedSingleColumnSubset¶

Bases: object

A deferred handle for one column of a CompressedTableHDU.

The compressed-table counterpart of SingleColumnSubset. Returned by hdu["name"] when hdu is a CompressedTableHDU. Add [rows] to trigger the read:

col = compressed_hdu["RA"]
subset = col[100:200]            # decodes only overlapping tiles

Writing via [rows] = value is supported and routes to the same per-tile decode → modify → re-encode path as CompressedTableHDU.__setitem__.

__getitem__(key, /)¶: Return self[key].

__setitem__(key, value, /)¶: Set self[key] to value.

read(*, rows=None, scale=True, mask_null=False)¶

Read this column.

Returns a plain (non-structured) ndarray of the column’s values — same shape as self[rows] with the rows key. All kwargs map to the matching CompressedTableHDU.read() arguments.

Parameters:

rows (slice, int, or iterable of int, optional) – Row subset to read. None (default) reads every row.
scale (bool, default True) – Apply TSCALn / TZEROn scaling on the way out.
mask_null (bool, default False) – Currently raises NotImplementedError on compressed tables (parity with CompressedTableHDU.read()).

Returns:

data – The column’s values.

Return type:

ndarray

write(data, *, rows=None)¶

Write this column.

With rows=None (default) writes all NAXIS2 rows — equivalent to hdu[name] = data. With rows=<spec> writes only the named rows — equivalent to self[rows] = data (the __setitem__ form). Re-encodes every affected tile and appends the new compressed bytes to the heap; old tile bytes become orphans (reclaim with CompressedTableHDU.repack()).

Parameters:

data (ndarray) – For rows=None, a length-NAXIS2 ndarray of the column’s expected dtype and per-cell shape (for VLA columns, an Object-dtype ndarray). For rows=<spec>, the shape must match what self[rows] = data would accept.
rows (slice, int, or iterable of int, optional) – Restrict the write to these rows. None (default) writes every row.

class rustfits.CompressedColumnSubset¶

Bases: object

A deferred handle for a column subset of a CompressedTableHDU.

The compressed-table counterpart of ColumnSubset. Returned by hdu[[name1, name2, ...]] when hdu is a CompressedTableHDU. Add [rows] to read or assign to write:

pos = compressed_hdu[["RA", "DEC"]]
subset = pos[100:200]
compressed_hdu[["RA", "DEC"]][bad_rows] = corrected

__getitem__(key, /)¶: Return self[key].

__setitem__(key, value, /)¶: Set self[key] to value.

read(*, rows=None, scale=True, mask_null=False)¶

Read these columns.

Returns a structured ndarray with the subset’s named fields — same shape as self[rows] with the rows key. All kwargs map to the matching CompressedTableHDU.read() arguments.

Parameters:

rows (slice, int, or iterable of int, optional) – Row subset to read. None (default) reads every row.
scale (bool, default True) – Apply TSCALn / TZEROn scaling on the way out.
mask_null (bool, default False) – Currently raises NotImplementedError on compressed tables (parity with CompressedTableHDU.read()).

Returns:

data – One row per selected source row; one field per column in the subset.

Return type:

structured ndarray

write(data, *, rows=None)¶

Write this subset.

With rows=None (default) writes all NAXIS2 rows — equivalent to hdu[[names...]] = data. With rows=<spec> writes only the named rows — equivalent to self[rows] = data (the __setitem__ form). Each named column is re-encoded per affected tile; the other columns’ stored bytes are untouched. Old tile bytes for modified columns become orphans (reclaim with CompressedTableHDU.repack()).

Parameters:

data (structured ndarray) – For rows=None, a length-NAXIS2 structured ndarray with the subset’s named fields. For rows=<spec>, the shape must match what self[rows] = data would accept. Extra fields are tolerated (matched by name); missing fields raise.
rows (slice, int, or iterable of int, optional) – Restrict the write to these rows. None (default) writes every row.

class rustfits.AsciiSingleColumnSubset¶

Bases: object

A deferred handle for one column of a AsciiTableHDU.

Returned by hdu["name"] (a single str/bytes column name). Carries a reference to the parent table and the column name; no I/O happens at construction. Add [rows] to trigger the read:

col = hdu["RA"]          # no I/O, returns a subset handle
all_ra  = col[:]         # read every row
subset  = col[100:200]   # read 100 rows
fancy   = col[[7, 3, 9]] # read three rows in that order

Writing to [rows] mutates only that column:

hdu["FLAG"][bad_rows] = -99

Equivalent to AsciiTableHDU.read_column() for reads and to the cell / slice forms of AsciiTableHDU.__setitem__ for writes; the subset object exists so the hdu["name"][...] idiom composes naturally.

__getitem__(key, /)¶: Return self[key].

__setitem__(key, value, /)¶: Set self[key] to value.

read(*, rows=None, as_bytes=False, scale=True, mask_null=False)¶: Read this column.

write(data, *, rows=None)¶

Write this column.

With rows=None (default) writes every row — equivalent to hdu["name"] = data. With rows=<spec> writes only the named rows — equivalent to self[rows] = data (the __setitem__ form). Other columns’ bytes are untouched in both cases.

class rustfits.AsciiColumnSubset¶

Bases: object

A deferred handle for a column subset of a AsciiTableHDU.

Returned by hdu[[name1, name2, ...]] (an iterable of str/bytes column names). Carries a reference to the parent table and the column list; no I/O happens at construction. Add [rows] to trigger the read:

pos = hdu[["RA", "DEC"]]
all_pos = pos[:]              # structured ndarray w/ 2 fields
subset  = pos[100:200]

Writing to [rows] mutates only those columns; the value must be a structured ndarray with the matching field names (extras tolerated for forward compatibility):

hdu[["RA", "DEC"]][bad_rows] = corrected

Equivalent to AsciiTableHDU.read() with columns= for reads, and to the multi-column form of AsciiTableHDU.__setitem__ for writes. The subset object exists so the hdu[[...]][...] idiom composes naturally.

__getitem__(key, /)¶: Return self[key].

__setitem__(key, value, /)¶: Set self[key] to value.

read(*, rows=None, scale=True, mask_null=False)¶: Read these columns.

write(data, *, rows=None)¶

Write these columns.

With rows=None (default) writes every row — equivalent to hdu[[names...]] = data (the multi-column form). With rows=<spec> writes only the named rows — equivalent to self[rows] = data (the __setitem__ form).