API reference

readtable(path) -> Table | RefTable | ConcatTable

Read the metadata (description, keywords, data-manager bindings, row count) of the casacore table directory at path. Column data is not read.

Returns a RefTable or ConcatTable when path is a reference / concatenation table (its parent(s) are opened recursively); otherwise a plain Table.

precision controls the in-memory element type of TpFloat / TpComplex columns (the on-disk Float32 / ComplexF32 bytes are never changed; Float64 / ComplexF64 / Bool are never narrowed):

Override per column with column(t, name; precision=…).

A shared (read) lock on <path>/table.lock is held only while table.dat is slurped; the row count then comes from the table.lock sync blob when present (as casacore does), else from table.dat. The lazy storage-manager reads that a later column() triggers are not locked – they rely on the writers' atomic renames.

MeasurementSet(path; precision=nothing) -> MeasurementSet

Open the MAIN table of a Measurement Set directory and read its metadata. Subtables are read on first access via getproperty / subtable.

precision is forwarded to readtable for the MAIN table (:half — the default — reads DATA etc. as ComplexF16; :full, Float16 and BFloat16 also accepted). Subtables always open at :full.

subtable(ms, name) -> Table

Read (and cache) the subtable referenced by keyword name in MAIN.

subtablenames(ms) -> Vector{String}

The names of ms's subtables ("ANTENNA", "SPECTRAL_WINDOW", …). Open one with subtable(ms, name) or ms.NAME.

Common supertype of the casacore table kinds this package can read: Table (a plain table), RefTable (a row-number reference into a parent table), and ConcatTable (a virtual row-wise concatenation of same-schema tables). All three answer nrow / columnnames / columndesc / keywords / subtables / column and interoperate with Tables.jl.

Table <: AbstractTable

A plain on-disk casacore table, as returned by readtable for a table.dat of subtype "PlainTable" (the MS MAIN table and every standard subtable). Column data is read lazily and on demand through the bound storage managers; cell reads go through column / getcell / t[:NAME]. See also RefTable and ConcatTable for the reference / concatenation kinds, and edit to open one for update.

precision (:half / :full / Float16 / BFloat16) — see readtable.

A casacore RefTable: a persistent row-number reference into a parent table (what a TaQL SELECT ... GIVING '<path>' row selection or table.query writes). Stores no cell data of its own — every read delegates to parent through rows (1-based parent row per ref row).

A casacore ConcatTable: a virtual row-wise concatenation of parts (same-schema tables — e.g. the MAIN table of a MultiMS). offsets is the cumulative row map (length(parts)+1 entries, offsets[end] = total rows). Stores no cell data of its own.

GroupedTable

An in-memory columnar table — the result of groupby, join, or query on one of those. It is a full AbstractTable (so it chains back into query / groupby / join) and a Tables.jl source. Access columns with gt.OUTNAME, gt["OUTNAME"], column(gt, "OUTNAME"), DataFrame(gt), or persist with write_table(dst, "T", gt; nrow=nrow(gt)).

names and cols are reserved field names (reached via getfield); a column literally named names / cols is accessible only through gt["names"] / column(gt, "cols").

A reference to a subtable stored as a TpTable keyword value.

column(t::Table, name; precision=nothing) -> Column

A lazy AbstractVector over a column: col[i] reads one cell, col[r] a range, col[:] the whole column (fast path).

precision (nothing follows t.precision; otherwise :half / :full / Float16 / BFloat16 / Float32 — see readtable): :half narrows only a TpComplex column (to ComplexF16); Float16 / BFloat16 narrow any Float32 / ComplexF32 column to that scalar type / its Complex; :full keeps the column wide.

column(ms, sub, name; precision=nothing) -> Column

A lazy AbstractVector over subtable sub's column name (a MeasurementSet convenience for column(subtable(ms, sub), name; precision)) — completes the getcolumn(ms, sub, name) / getcell(ms, sub, name, row) family with the lazy verb they're both built on, found missing in the same sweep.

Column{T} <: AbstractVector{T}

A lazy view of one table column, returned by column and t[:NAME]. Indexing reads on demand: col[i] fetches one cell, col[:] takes the storage manager's whole-column fast path, col[r] a row subset. T is the best-known element type — a scalar, a fixed-shape Array{E,N}, or Array{E} when the rank is only known once a cell is read.

getcolumn(t, name; precision=nothing) -> Vector / Vector{Array}

Read an entire column's data (eager; equivalent to column(t, name; precision)[:]).

getcell(t, name, row; precision=nothing) -> value

Read one cell (row is 1-based).

Each call resolves name to a Column (a columndesc lookup + opening/looking up the bound data-manager instance), which in a for row in ...; getcell(t, name, row); end loop used to dominate the actual per-cell read cost – it no longer does for a plain Table (Phase 426: the Column is kept with the table, so a repeated getcell costs about a cached column(t, name)[row] plus a dictionary lookup, ~40 ns instead of ~470 ns); other table kinds (RefTable, ConcatTable, ...) still resolve the name on every call, so for those cache the lazy column once and index into that: col = column(t, name); for row in ...; col[row]; end.

BlockColumn{T,N} <: AbstractVector{AbstractArray{T,N}}

The lazy whole-column return value of a fixed-shape array column's bulk read (Phase 236) — SSM- or TiledStMan-backed columns like UVW, DATA, or FLAG. Every row's cell shares ONE backing buffer built up front; getindex computes that row's reshape(view(...)) on demand instead of building nrow such wrapper objects eagerly (Phase 234/235's own fix already made each data manager build the shared buffer, but still wrapped it into an eager Vector of nrow view objects — the BlockColumn here is stored instead, with no further per-row cost until something actually indexes it).

Behaves like any other AbstractVector — every existing consumer (Tables.jl, the TaQL engine, edit.jl, copyms) already treats a column's [:] result as an opaque AbstractVector of AbstractArray cells (TiledStMan's narrow-precision bulk path has returned non-Array-typed view wrappers since Phase 35/68), so this is a drop-in, non-breaking change to what getcolumn/column(t,name)[:] already returned. collect(col) (or Array.(col)) forces genuine per-row materialisation when an owned copy is actually needed — exactly what _read_cells (create.jl, used by copyms/copytable) already does for every array-cell column, lazy or not.

rawblock exposes the underlying buffer directly as one real (cellshape..., nrow) Array, with NO per-row indirection at all, for a caller doing a bulk numeric operation across the whole column.

rawblock(t, name; precision=nothing) -> Array

The raw (cellshape..., nrow) block underlying a fixed-shape array column's bulk read — the SAME buffer column(t, name)[:] (a BlockColumn) lazily slices per row, exposed directly with NO per-row indirection at all (size(result) == (cellshape..., nrow), zero-copy reshape). Only a fixed-shape SSM/TiledStMan array column (DATA, FLAG, UVW, a subtable's POSITION, …) has a block representation — a scalar column or a variable-shape/indirect array column (CHAN_FREQ, …) raises a clear ArgumentError.

nrow(t) -> Int

Number of rows in table t (a Table, RefTable, ConcatTable or GroupedTable).

columnnames(t) -> Vector{String}

The column names of table t, in schema order.

columnunit(t, name) -> Unitful.Units | Tuple | nothing

The physical unit of column name, from its QuantumUnits keyword, as a Unitful unit. nothing when the column has no unit keyword; a Tuple for a genuinely mixed-unit column. Needs the Unitful extension — import Unitful, UnitfulAngles, UnitfulAstro.

qcolumn(t, name; precision=nothing) -> Vector

The whole column with its unit attached as Unitful quantities (materialised, not a lazy Column). A unitless column is returned unchanged. Needs the Unitful extension.

UNITS_NO_JULIA_COUNTERPART

casacore units that no third-party Julia package (Unitful / UnitfulAngles / UnitfulAstro) implements, and how MeasurementSets handles each:

• :pseudo — registered as a dimensionless unit by the Unitful extension (so Jy/beam parses to Jy beam⁻¹, dimensionally Jy).
• :nounits — mapped to Unitful.NoUnits (casacore's canonical dimensionless markers).
• :unsupported — raises a clear error; use the suggested replacement.
• :dimension — exists in Unitful but with a different dimension than casacore (casacore treats it as a base dimension).

columndesc(t, name) -> ColumnDesc

The ColumnDesc (type, cell shape, keywords, storage-manager binding) for column name of table t. Throws KeyError if there is no such column. The keyword record of the result is a copy: changing an array inside it does not change the table.

ColumnDesc

Description of one table column: its name, element type (a CasaType), cell shape (a CellShape — () scalar, a Dims tuple, VariableShape, or VariableDims), comment, per-column keywords (a Record, holding units / MEASINFO / engine config), and the storage-manager manager type + group (instance) it is bound to. Obtained from columndesc; the fields are read-only.

TableDesc

A table's schema: its name, format version, the public and private keyword sets (each a Record), and the ordered list of ColumnDesc columns. Reachable as t.desc on a Table; most code uses columnnames / columndesc / keywords instead.

keywords(t) -> Record

The table-level keyword set of t as a Record (MS_VERSION, MEASURE_REFERENCE, subtable references, …). Per-column keywords live on columndesc(t, name).keywords. The result is a copy: changing an array inside it does not change the table.

subtables(t::Table) -> Vector{Pair{String,String}}

Keyword name => subtable directory path, for every TpTable keyword.

An ordered casacore (Table)Record: field name -> value, with the on-disk types.

CasaType

Enum mirroring casacore's DataType — the element type of a column or keyword value (TpBool, TpInt, TpFloat, TpComplex, TpString, the TpArray* variants, TpInt64, …). It is the type field of a ColumnDesc; juliatype(t) gives the corresponding Julia type.

Cell-shape descriptor for a column:

• () — scalar
• a Dims tuple — array with a fixed cell shape
• VariableShape — array, fixed dimensionality, per-row-variable shape
• VariableDims — array whose dimensionality itself varies per row

An array column with a fixed number of axes but a per-row-variable cell shape (casacore ndim > 0 with no declared shape, e.g. DATA, FLAG_CATEGORY). ndim is that number of axes when known (a column read from disk always knows it) and 0 when not (VariableShape(), e.g. one inferred from data – which cannot know it for a zero-row column).

An array column whose dimensionality itself varies per row (casacore ndim == -1, e.g. ASSOC_SPW_ID).

Whether column c holds arrays (shape other than ()).

SCHEMAVER2 :: Dict{String,StdTable}

The MS version 2 standard schema (NRAO Memo 229 §5), keyed by table name ("MAIN", "ANTENNA", "SPECTRAL_WINDOW", …). Use stdtable / stdcolumns to query it and validate to check a table against it.

StdTable

The standard-schema definition of one MS table: its name, columns (StdColumn), required keywords, and (MAIN only) required subtables. Looked up in SCHEMAVER2 / via stdtable(name).

StdColumn

One column of the MS v2 standard schema (NRAO Memo 229 §5): its name, type (CasaType), cell shape, unit, whether it is required, and a comment. Reachable via stdcolumns / stdtable(name).columns.

stdtable(name) -> StdTable

The standard MS v2 definition for table name ("MAIN", "ANTENNA", …).

stdcolumns(name) -> Vector{StdColumn}

The standard-schema columns of MS v2 table name — shorthand for stdtable(name).columns (a copy, so the schema cannot be changed through it).

validate(t::AbstractTable; table="MAIN") -> Vector{String}

Check t against the standard schema for table. Returns a list of issues (missing required column, element-type mismatch, missing required subtable, unexpected keyword value); empty means conformant. Never throws.

validate(ms::MeasurementSet) -> Vector{String}

Validate MAIN and every present standard subtable.