開発版ドキュメント · 0.2.3 30c2f8ba · 入門例の検証対象 0.2.3 · 版情報 · 既知の制限

Table#

Overview#

`SegmentTable`(meta)	Segment-keyed analysis table.
`SegmentCell`([value, loader, cacheable])	A single lazy-loadable payload cell.

SegmentTable Class#

class gwexpy.table.segment_table.SegmentTable(meta: DataFrame)#

ベースクラス: object

Segment-keyed analysis table.

Each row holds exactly one span (gwpy.segments.Segment) plus arbitrary meta columns and optional heavy payload columns.

パラメータ:

meta -- pandas.DataFrame with at least a span column whose elements are gwpy.segments.Segment objects.

例外:

ValueError -- If meta does not contain a span column.
TypeError -- If any element of the span column is not a gwpy.segments.Segment.

サンプル

>>> from gwpy.segments import Segment
>>> import pandas as pd
>>> segs = [Segment(0, 4), Segment(4, 8)]
>>> st = SegmentTable(pd.DataFrame({"span": segs}))
>>> len(st)
2

Factory Methods

`from_segments`(segments, **meta_columns)	Create a `SegmentTable` from a sequence of segments.
`from_table`(table[, span])	Create a `SegmentTable` from an existing table.

Column Management

`add_column`(name, data[, kind])	Add a lightweight meta column.
`add_series_column`(name[, data, loader, kind])	Add a payload column (lazy-loadable).

Row-wise Processing

`apply`(func[, in_cols, out_cols, parallel, ...])	Apply func to each row and collect the results as new columns.
`map`(column, func[, out_col, inplace])	Apply func to each value in column.
`crop`(column[, out_col, span_col, inplace])	Crop each row's payload to its `Segment`.
`asd`(column[, out_col])	Apply ASD to each row's `TimeSeries` or `TimeSeriesDict`.

Selection & Conversion

`select`([mask])	Select rows by boolean mask or column conditions.
`fetch`([columns])	Eagerly load all payload cells in columns (default: all).
`materialize`([columns, inplace])	Materialize lazy payload cells (equivalent to `fetch()` in v0.1).
`to_pandas`([meta_only])	Return a `pandas.DataFrame` representation.
`copy`([deep])	Return a copy of this table.

Drawing (Representative APIs)

`segments`(*[, y, color])	Draw each row's span as a horizontal bar.
`overlay_spectra`(column, *[, channel, rows, ...])	Overlay frequency spectra with colour-graded lines.
`plot`([column, row, mode])	General-purpose plot entry.
`scatter`(x, y[, color, selection])	Scatter plot of two scalar columns.
`hist`(column, *[, bins])	Histogram of a scalar column.
`overlay`(column, rows, *[, separate, sharex])	Overlay payload from multiple rows.

classmethod from_segments(segments: Sequence[Any], **meta_columns: Sequence[Any]) → SegmentTable#

Create a SegmentTable from a sequence of segments.

パラメータ:

segments -- Sequence of gwpy.segments.Segment objects.
**meta_columns -- Extra meta columns supplied as keyword arguments. Each value must have the same length as segments.

戻り値の型:

SegmentTable

例外:

ValueError -- If any column length does not match len(segments).

サンプル

>>> from gwpy.segments import Segment
>>> segs = [Segment(0, 4), Segment(4, 8)]
>>> st = SegmentTable.from_segments(segs, label=["a", "b"])

classmethod from_table(table: Any, span: str = 'span') → SegmentTable#

Create a SegmentTable from an existing table.

パラメータ:

table -- A pandas.DataFrame (or compatible object).
span -- Column name to use as the span column. If different from "span", the column is renamed.

戻り値の型:

SegmentTable

例外:

ValueError -- If span column is not found in table.

classmethod read_csv(filepath: str, span_cols: tuple[str, str] = ('start', 'end'), **kwargs: Any) → SegmentTable#

Read a SegmentTable from a CSV file.

パラメータ:

filepath -- Path to the CSV file.
span_cols -- The two column names to use as the span start and end values. Ignored if a column named "span" already exists (containing Segment objects or compatible).
**kwargs -- Forwarded to pandas.read_csv().

戻り値の型:

SegmentTable

classmethod read(filepath: str, span_cols: tuple[str, str] = ('start', 'end'), **kwargs: Any) → SegmentTable#

Read a SegmentTable from a CSV file.

パラメータ:

filepath -- Path to the CSV file.
span_cols -- The two column names to use as the span start and end values. Ignored if a column named "span" already exists (containing Segment objects or compatible).
**kwargs -- Forwarded to pandas.read_csv().

戻り値の型:

SegmentTable

add_column(name: str, data: Sequence[Any], kind: str = 'meta') → None#

Add a lightweight meta column.

パラメータ:

name -- Column name. Must not already exist.
data -- Sequence of values; length must equal len(self).
kind -- Column kind — "meta" or "object".

例外:

ValueError -- If name already exists, length mismatch, or kind is not "meta" or "object".

add_series_column(name: str, data: Sequence[Any] | None = None, loader: Sequence[Callable[[], Any]] | Callable[[int], Callable[[], Any]] | None = None, kind: str = 'timeseries') → None#

Add a payload column (lazy-loadable).

パラメータ:

name -- Column name. Must not already exist.
data -- Sequence of concrete payload objects, one per row. Exclusive with loader (but one of the two must be provided).
loader -- Either a sequence of zero-argument callables (one per row), or a single callable that accepts the row index and returns a zero-argument callable.
kind -- Payload kind. Must be one of: "timeseries", "timeseriesdict", "frequencyseries", "frequencyseriesdict", "object".

例外:

ValueError -- If both data and loader are None, or if length mismatches.
ValueError -- If kind is not a valid payload kind.

property columns: list[str]#: Ordered list of all column names (meta then payload).

property schema: dict[str, str]#: Mapping of column name → kind.

row(i: int) → RowProxy#

Return a dict-like proxy for row i.

パラメータ:: i -- 0-based row index.
例外:: IndexError -- If i is out of range.

apply(func: Callable[[RowProxy], dict[str, Any]], in_cols: list[str] | None = None, out_cols: list[str] | None = None, parallel: bool = False, inplace: bool = False) → SegmentTable#

Apply func to each row and collect the results as new columns.

パラメータ:

func -- Callable that receives a RowProxy and returns a dict[str, object].
in_cols -- Hint for which columns are read (ignored in v0.1).
out_cols -- Expected keys of func's return dict. If given, the actual keys must match exactly.
parallel -- If True, falls back to sequential execution in v0.1.
inplace -- If True, add columns to self; otherwise return a new SegmentTable.

戻り値:

Either self (inplace=True) or a new table.

戻り値の型:

SegmentTable

例外:

TypeError -- If func does not return a dict.
ValueError -- If out_cols is given and the actual keys do not match.

map(column: str, func: Callable[[Any], Any], out_col: str | None = None, inplace: bool = False) → SegmentTable#

Apply func to each value in column.

パラメータ:

column -- Source column name.
func -- Callable that receives the cell value and returns a new value.
out_col -- Output column name. Defaults to column + "_mapped".
inplace -- Whether to modify self in place.

戻り値の型:

SegmentTable

crop(column: str, out_col: str | None = None, span_col: str = 'span', inplace: bool = False) → SegmentTable#

Crop each row's payload to its Segment.

パラメータ:

column -- Payload column containing TimeSeries or TimeSeriesDict.
out_col -- Output column name; defaults to column + "_cropped".
span_col -- Column name for the span (default "span").
inplace -- Whether to modify self in place.

例外:

TypeError -- If the payload is not TimeSeries or TimeSeriesDict.

asd(column: str, out_col: str | None = None, **kwargs: Any) → SegmentTable#

Apply ASD to each row's TimeSeries or TimeSeriesDict.

パラメータ:

column -- Payload column.
out_col -- Output column name; defaults to column + "_asd".
**kwargs -- Forwarded to asd().

戻り値の型:

SegmentTable

select(mask: Sequence[bool] | None = None, **conditions: Any) → SegmentTable#

Select rows by boolean mask or column conditions.

パラメータ:

mask -- Boolean sequence of length len(self).
**conditions -- Simple equality conditions, e.g. label="glitch".

戻り値:

A new SegmentTable with only the selected rows.

戻り値の型:

SegmentTable

例外:

ValueError -- If mask length is not equal to len(self).
KeyError -- If a condition column does not exist.

fetch(columns: list[str] | None = None) → None#

Eagerly load all payload cells in columns (default: all).

パラメータ:: columns -- List of payload column names to load. None loads all.

materialize(columns: list[str] | None = None, inplace: bool = True) → SegmentTable | None#

Materialize lazy payload cells (equivalent to fetch() in v0.1).

パラメータ:

columns -- Payload columns to materialize. None means all.
inplace -- If True (default), mutate self. If False, return a copy with the payload loaded.

戻り値:

None if inplace=True; new table if inplace=False.

戻り値の型:

SegmentTable or None

to_pandas(meta_only: bool = True) → DataFrame#

Return a pandas.DataFrame representation.

パラメータ:: meta_only -- If True (default), return only the meta columns. If False, payload columns are appended as object columns containing the resolved cell values.
戻り値の型:: pandas.DataFrame

copy(deep: bool = False) → SegmentTable#

Return a copy of this table.

パラメータ:: deep -- If False (default), meta is copied and payload cells are referenced (shallow). If True, payload values are also deep-copied where possible.
戻り値の型:: SegmentTable

clear_cache() → None#: Discard all cached payload values, forcing re-load on next access.

plot(column: str | None = None, *, row: int | None = None, mode: str | None = None, **kwargs: Any) → Any#: General-purpose plot entry. Requires both column and row.

scatter(x: str, y: str, color: str | None = None, *, selection: Any | None = None, **kwargs: Any) → Any#: Scatter plot of two scalar columns.

hist(column: str, *, bins: int = 10, **kwargs: Any) → Any#: Histogram of a scalar column.

segments(*, y: str | None = None, color: str | None = None, **kwargs: Any) → Any#

Draw each row's span as a horizontal bar.

This is one of the two representative APIs of SegmentTable (alongside overlay_spectra()).

overlay(column: str, rows: list[int], *, separate: bool = False, sharex: bool = True, **kwargs: Any) → Any#: Overlay payload from multiple rows.

overlay_spectra(column: str, *, channel: str | None = None, rows: list[int] | None = None, color_by: str | None = None, sort_by: str | None = None, cmap: str = 'viridis', alpha: float = 0.7, linewidth: float = 0.8, colorbar: bool = True, colorbar_label: str | None = None, xscale: str = 'log', yscale: str = 'log', xlim: Any | None = None, ylim: Any | None = None, ax: Any | None = None) → Any#

Overlay frequency spectra with colour-graded lines.

Representative API of SegmentTable for frequency-domain visualisation (alongside segments() for time-domain).

display(max_rows: int = 20, max_cols: int = 8, meta_only: bool = False) → DataFrame#

Return a summary pandas.DataFrame for interactive display.

パラメータ:

max_rows -- Maximum rows to include.
max_cols -- Maximum columns to include.
meta_only -- If True, omit payload columns.

戻り値の型:

pandas.DataFrame

SegmentCell Class#

class gwexpy.table.segment_cell.SegmentCell(value: Any | None = None, loader: Callable[[], Any] | None = None, cacheable: bool = True)#

ベースクラス: object

A single lazy-loadable payload cell.

パラメータ:

value (Any | None) -- The concrete payload object. May be None when a loader is set.
loader (collections.abc.Callable[[], Any] | None) -- A zero-argument callable that returns the payload. Ignored when value is already set.
cacheable (bool) -- When True (default) the result of loader is stored in value after the first call, so subsequent calls return directly.

サンプル

>>> cell = SegmentCell(loader=lambda: 42, cacheable=True)
>>> cell.get()
42
>>> cell.is_loaded()
True

value: Any | None = None#

loader: Callable[[], Any] | None = None#

cacheable: bool = True#

get() → Any#

Return the payload, loading it if necessary.

戻り値:: The resolved payload.
戻り値の型:: object
例外:: ValueError -- If both value and loader are None.

is_loaded() → bool#: Return True if the value has been loaded (or was set directly).

clear() → None#: Discard the cached value so the next get() call re-invokes the loader.

Module Contents#

SegmentTable — segment-keyed analysis container.

Each row represents one analysis unit defined by a Segment (a half-open time interval [start, end)). Columns may be lightweight meta values or heavy payload objects such as TimeSeries. Payload columns are stored as SegmentCell instances that support lazy loading and optional caching.