empyrean.Epochs¶

class Epochs(table, **kwargs)[source]

Bases: Table

Epochs as Modified Julian Dates with an explicit time scale.

The time scale is a table-level attribute (not per-row) because mixing scales within a single coordinate set is not meaningful. All scale= arguments throughout this class accept either a string ("utc" / "tdb", case-insensitive) or a TimeScale enum value.

Every empyrean entry point that takes a time takes one of these. A bare list, array or float is refused: it carries no time scale, and the same number read as UTC and as TDB names two instants about 69 seconds apart. Naming the scale is the point — see from_mjd(), whose scale argument is required.

Parameters:

mjd (array-like) – Modified Julian Date values.
scale (str or TimeScale) – Time scale: "tdb" or "utc".
table (Table)
kwargs (AttributeValueType)

Examples

>>> epochs = Epochs.from_mjd([60200.0, 60201.0], scale="tdb")
>>> epochs.scale
'tdb'

Methods

`__init__`(table, **kwargs)
`apply_mask`(mask)	Return a new table with rows filtered to match a boolean mask.
`arange`(start, end[, step])	Create epochs from `start` to `end` (exclusive) with a fixed step.
`as_column`([nullable, metadata])	Embed the Table as a column in another Table.
`attributes`()	Return a dictionary of the table's attributes.
`chunk_counts`()	Returns the number of discrete memory chunks that make up each of the Table's underlying arrays.
`column`(column_name)	Returns the column with the given name as a raw pyarrow ChunkedArray.
`concat`(*epochs)	Concatenate multiple `Epochs` tables.
`drop_duplicates`([subset, keep])	Drop duplicate rows from a ~quivr.Table.
`empty`(**kwargs)	Create an empty instance of the table.
`flattened_table`()	Completely flatten the Table's underlying Arrow table, taking into account any nested structure, and return the data table itself.
`fragmented`()	Returns true if the Table has any fragmented arrays.
`from_astropy`(time)	Create Epochs from an `astropy.time.Time` object.
`from_csv`(input_file[, validate])	Read a table from a CSV file.
`from_dataframe`(df[, validate])	Load a DataFrame into the Table.
`from_feather`(path[, validate])	Read a table from a Feather file.
`from_flat_dataframe`(df[, validate])	Load a flattened DataFrame into the Table.
`from_iso`(iso_strings[, scale])	Create Epochs from ISO 8601 UTC strings.
`from_jd`(jd, scale)	Construct from Julian Date values (converts to MJD = JD - 2400000.5).
`from_kwargs`([validate, permit_nulls])	Create a Table instance from keyword arguments.
`from_mjd`(mjd, scale)	Construct from MJD values + an explicit scale.
`from_orbits`(orbits, dt)	Create epochs offset from the orbits' common epoch.
`from_parquet`(path[, memory_map, ...])	Read a table from a Parquet file.
`from_pyarrow`(table[, validate, permit_nulls])	Create a new table from a pyarrow Table.
`invalid_mask`()	Return a boolean mask indicating which rows are invalid.
`is_valid`()	Validate the table against the schema.
`jd`()	Return Julian Date values in the stored scale (= MJD + 2400000.5).
`linspace`(start, end[, num])	Create evenly spaced epochs between `start` and `end`.
`mjd_tdb`()	Return MJD values in TDB as a numpy array.
`mjd_utc`()	Return MJD values in UTC as a numpy array.
`now`([scale])	Construct a single-row Epochs at "right now" in the requested scale.
`null_mask`()	Return a boolean mask indicating which rows of the entire table are null.
`nulls`(size, **kwargs)	Create a table with nulls.
`select`(column_name, value)	Select from the table by exact match, returning a new Table which only contains rows for which the value in column_name equals value.
`separate_invalid`()	Separates rows that have invalid data from those that have valid data.
`set_column`(name, data)	Return a copy of the table with a particular column replaced with new data.
`sort_by`(by)	Sorts the Table by the given column name (or multiple columns).
`take`(row_indices)	Return a new Table with only the rows at the given indices.
`to_astropy`()	Convert to an `astropy.time.Time` object.
`to_csv`(path[, attribute_columns])	Write the table to a CSV file.
`to_dataframe`([flatten, attr_handling])	Returns self as a pandas DataFrame.
`to_feather`(path, **kwargs)	Write the table to a Feather file.
`to_iso`([scale])	Format epochs as ISO 8601 UTC wall-clock strings.
`to_numpy`()	Return the MJD column as a numpy `float64` array.
`to_parquet`(path, **kwargs)	Write the table to a Parquet file.
`to_scale`(scale)	Convert to the named scale (`"utc"` or `"tdb"`).
`to_structarray`()	Returns self as a StructArray.
`to_tdb`()	Convert to TDB.
`to_utc`()	Convert to UTC.
`unique_indices`([subset, keep])	Get the indices of the first or last occurrence of each unique row in the table.
`validate`()	Validate the table against the schema, raising an exception if invalid.
`where`(expr)	Return a new table with rows filtered to match an expression.
`with_table`(table)

Attributes

`mjd`	A column for storing 64-bit floating point numbers.
`scale`	StringAttribute represents a string which is stored as UTF-8 bytes in Table metadata.
`schema`
`table`

mjd: A column for storing 64-bit floating point numbers.

scale

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

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

to_tdb()[source]

Convert to TDB.

Returns self unchanged if already TDB. Applies the engine’s leap-second table for UTC↔TAI↔TT and the full periodic Fairhead & Bretagnon (1990) series for TT↔TDB — not a secular-only truncation, so the few-millisecond annual term is carried. Cross-validated against astropy (ERFA) in tests/test_time_scale_astropy_parity.py, where the two agree bit for bit over the modern era.

Return type:: Epochs

to_utc()[source]

Convert to UTC.

Returns self unchanged if already UTC.

Return type:: Epochs

to_scale(scale)[source]

Convert to the named scale ("utc" or "tdb").

Return type:: Epochs
Parameters:: scale (str | TimeScale)

classmethod from_iso(iso_strings, scale=TimeScale.UTC)[source]

Create Epochs from ISO 8601 UTC strings.

Parameters:

iso_strings (Sequence[str]) – ISO 8601 UTC timestamps, e.g. ["2029-04-13T21:46:00.000Z"]. The trailing Z is required.
scale (str | TimeScale) – Output scale. "utc" returns MJD UTC; "tdb" runs the UTC→TDB leap-second + Fairhead/Bretagnon conversion before returning MJD TDB.

Return type:

Epochs

Returns:

Epochs – Length-N table.

to_iso(scale=None)[source]

Format epochs as ISO 8601 UTC wall-clock strings.

The output is always the UTC wall-clock time of the stored instant, interpreting the stored MJD in the table’s own scale. A TDB table therefore comes back as UTC ISO with the TDB→UTC offset applied (≈69 s at 2026 epochs) — not the raw TDB clock reading relabelled Z.

Parameters:: scale (str | TimeScale | None) – Guard only. If given it must equal the table’s stored scale; to_iso does not reinterpret the stored instant in a different scale. A mismatched scale raises rather than silently relabelling the clock reading. To format the instant as if it lived in another scale, convert first — epochs.to_scale(x).to_iso() (or epochs.to_utc().to_iso() / epochs.to_tdb().to_iso()), which apply the real leap-second + TDB−TT conversion.
Return type:: list[str]
Returns:: list[str] – One ISO string per row, always with the trailing Z.
Raises:: ValueError – If scale is given and differs from the table’s stored scale.

classmethod from_astropy(time)[source]

Create Epochs from an astropy.time.Time object.

Parameters:

time (AstropyTime) – The astropy scale must be "tdb" or "utc".

Return type:

Epochs

Returns:

Epochs

Raises:

ImportError – If astropy is not installed.
TypeError – If the input is not an astropy Time object.
ValueError – If the time scale is not "tdb" or "utc".

to_astropy()[source]

Convert to an astropy.time.Time object.

Return type:: AstropyTime
Returns:: astropy.time.Time
Raises:: ImportError – If astropy is not installed.

classmethod from_orbits(orbits, dt)[source]

Create epochs offset from the orbits’ common epoch.

All orbits must share the same epoch. The output has one epoch per dt value, shared across all orbits during propagation.

Parameters:

orbits (CartesianOrbits | KeplerianOrbits | CometaryOrbits | SphericalOrbits) – Orbits table. All orbits must share the same epoch.
dt (ndarray | Sequence[float]) – Time offsets in days from the orbit epoch.

Return type:

Epochs

Returns:

Epochs – Epochs in TDB at orbit_epoch + dt.

classmethod linspace(start, end, num=50, *, scale)[source]

Create evenly spaced epochs between start and end.

start and end are MJD in scale, which is required (see from_mjd()) and keyword-only here because num sits between them.

Return type:

Epochs

Parameters:

start (float)
end (float)
num (int)
scale (str | TimeScale)

>>> Epochs.linspace(60500.0, 60510.0, 11, scale="tdb").scale
'tdb'

classmethod arange(start, end, step=1.0, *, scale)[source]

Create epochs from start to end (exclusive) with a fixed step.

start, end and step are MJD (and days) in scale, which is required (see from_mjd()) and keyword-only here because step sits between them.

Return type:

Epochs

Parameters:

start (float)
end (float)
step (float)
scale (str | TimeScale)

>>> Epochs.arange(60500.0, 60505.0, 1.0, scale="tdb").scale
'tdb'

to_numpy()[source]

Return the MJD column as a numpy float64 array.

Return type:: ndarray

mjd_tdb()[source]

Return MJD values in TDB as a numpy array.

Converts internally if stored in another scale; returns the existing column directly when already TDB (no copy).

Return type:: ndarray

mjd_utc()[source]

Return MJD values in UTC as a numpy array.

Return type:: ndarray

jd()[source]

Return Julian Date values in the stored scale (= MJD + 2400000.5).

Return type:: ndarray

classmethod from_mjd(mjd, scale)[source]

Construct from MJD values + an explicit scale.

Single-line shorthand for Epochs.from_kwargs(mjd=..., scale=...).

scale is required and has no default. A Modified Julian Date is a clock reading, not an instant: 61000.5 UTC and 61000.5 TDB are about 69 seconds apart today, and the gap grows with every leap second. Which one you mean is a modelling statement, so it is stated here rather than inherited from a default.

Return type:

Epochs

Parameters:

mjd (float | Sequence[float] | ndarray)
scale (str | TimeScale)

>>> Epochs.from_mjd(60500.0, scale="tdb").scale
'tdb'
>>> Epochs.from_mjd([60500.0, 60501.0], scale="utc").scale
'utc'

classmethod from_jd(jd, scale)[source]

Construct from Julian Date values (converts to MJD = JD - 2400000.5).

scale is required, for the reason given on from_mjd().

Return type:

Epochs

Parameters:

jd (float | Sequence[float] | ndarray)
scale (str | TimeScale)

>>> Epochs.from_jd(2460500.5, scale="tdb").scale
'tdb'

classmethod now(scale=TimeScale.UTC)[source]

Construct a single-row Epochs at “right now” in the requested scale.

Uses the system clock (datetime.now(timezone.utc)) and the native ISO→MJD converter — no astropy dependency. scale keeps its "utc" default: the operation names its own clock.

Return type:: Epochs
Parameters:: scale (str | TimeScale)

classmethod concat(*epochs)[source]

Concatenate multiple Epochs tables.

All inputs must share the same time scale.

Return type:: Epochs
Parameters:: epochs (Epochs)

schema: ClassVar[Schema] = mjd: double not null