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.

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, scale])	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, scale])	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 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. Uses villeneuve’s leap-second + TDB-TT secular term conversion.

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 strings.

Parameters:: scale (str | TimeScale | None) – Interpret the stored MJD values in this scale before formatting. Defaults to the table’s stored scale. Useful for cross-scale formatting (e.g. an MJD TDB table formatted as if it were MJD UTC).
Return type:: list[str]
Returns:: list[str] – One ISO string per row, always with the trailing Z.

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 (AnyOrbits) – 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=TimeScale.TDB)[source]

Create evenly spaced epochs between start and end.

Return type:

Epochs

Parameters:

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

classmethod arange(start, end, step=1.0, scale=TimeScale.TDB)[source]

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

Return type:

Epochs

Parameters:

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

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=TimeScale.TDB)[source]

Construct from MJD values + an explicit scale.

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

Return type:

Epochs

Parameters:

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

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

classmethod from_jd(jd, scale=TimeScale.TDB)[source]

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

Return type:

Epochs

Parameters:

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

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.

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

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

classmethod concat(*epochs)[source]

Concatenate multiple Epochs tables.

All inputs must share the same time scale.

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