Class ReflectionTable

Nested Relationships

Nested Types

Class Documentation

class ReflectionTable

Public Types

using BoolEnum = h5dispatch::BoolEnum

Re-exported type aliase for convenience.

Public Functions

ReflectionTable()
ReflectionTable(const std::vector<uint64_t> &experiment_ids, const std::vector<std::string> &identifiers)

Constructs a ReflectionTable with given experiment IDs and identifiers.

Parameters:

  • experiment_ids – A vector of experiment IDs.

  • identifiers – A vector of identifiers.

ReflectionTable(const std::string &h5_filepath)

Constructs a ReflectionTable from an HDF5 file.

This constructor loads datasets from the specified HDF5 file and populates the table with the data.

Parameters:

h5_filepath – The path to the HDF5 file.

const std::vector<uint64_t> &get_experiment_ids() const

Get the list of experiment IDs.

void set_experiment_ids(const std::vector<uint64_t> &ids)

Set the list of experiment IDs.

const std::vector<std::string> &get_identifiers() const

Get the list of identifiers.

void set_identifiers(const std::vector<std::string> &ids)

Set the list of identifiers.

std::pair<uint64_t, std::string> generate_new_attributes()

Generate a new experiment ID and identifier.

This function generates a new experiment ID and a random identifier, adds them to the internal metadata, and returns them as a pair.

std::vector<std::string> get_column_names() const

Get a list of all column names in the table.

size_t size() const

Returns the number of rows (reflections) in the table.

All columns are required to share the same row count, so this is the length of any column. Returns 0 if the table has no columns.

template<typename T>
inline std::optional<mdspan_type<T>> column(const std::string &name)

Retrieves a view (mdspan) of a typed column by name.

Looks for a column matching both the given name and type T. On a mutable table the view is writable; on a const table the overload below returns a read-only view.

Note

The view is only valid while the column exists in this table.

Template Parameters:

T – The expected type of the column (e.g., int, double).

Parameters:

name – The name of the column to retrieve.

Returns:

An optional containing the mdspan view, or std::nullopt if no column with this name holds T.

template<typename T>
inline std::optional<mdspan_type<const T>> column(const std::string &name) const

Read-only view of a typed column on a const table.

template<typename ...Predicates>
inline std::vector<size_t> find_rows(logic::LogicalOp op, const Predicates&... conds) const

Finds all rows matching any or all of the given typed predicates.

This function accepts any number of typed predicates, each bound to a specific column. It returns the union or intersection of all matching rows, depending on the specified logical operation.

Uses a parameter pack to accept a variadic number of predicates, and expands them into individual calls to evaluate_column_predicate. The resulting vectors are combined based on the logical operator.

Template Parameters:

Predicates – Parameter pack of ColumnPredicate<T> types.

Parameters:

  • op – Logical combination (AND or OR).

  • conds – The predicates to apply to rows.

Returns:

A vector of row indices matching the logical combination.

template<typename ...Predicates>
inline std::vector<size_t> find_rows(const Predicates&... conds) const

Finds all rows matching all of the given typed predicates.

This overload enables simpler syntax when AND is desired (default). Because default parameters don’t work with parameter packs, we provide this wrapper to make the interface intuitive.

Template Parameters:

Predicates – Parameter pack of ColumnPredicate<T> types.

Parameters:

conds – The predicates to apply to rows.

Returns:

A vector of row indices matching all predicates.

ReflectionTable select(const std::vector<size_t> &selected_rows) const

Returns a new ReflectionTable with only the specified rows.

Parameters:

selected_rows – The list of row indices to retain.

Returns:

A new ReflectionTable containing only the selected rows.

ReflectionTable select(const std::vector<bool> &mask) const

Returns a new ReflectionTable from a boolean mask.

Converts a boolean mask into row indices and calls index-based select.

Parameters:

mask – A boolean mask, where true indicates a row to keep.

Returns:

A new ReflectionTable containing only the selected rows.

template<typename T>
inline void add_column(const std::string &name, const std::vector<size_t> &shape, const std::vector<T> &column_data)

Adds a new column to the table with arbitrary shape.

This is the most general column-adding interface. You must specify the full shape of the column explicitly. The column is stored using a flat data buffer matching this shape in row-major order.

Template Parameters:

T – The data type of the column (e.g., double, int, std::array<T, N>).

Parameters:

  • name – The name of the column.

  • shape – A vector describing the shape of the column (e.g., {N} for 1D, {N, M} for 2D).

  • column_data – A flat vector of T values, whose total number of elements must match the product of shape.

Throws:

std::runtime_error – if shape does not match existing row count (if table is non-empty).

template<typename T>
inline void add_column(const std::string &name, const std::vector<T> &column_data)

Adds a 1D column to the table.

This is a convenience overload for scalar or vector-style columns where each row has a single value. Internally calls the shape-based overload with a shape of {N}.

Template Parameters:

T – The data type of the column (e.g., int, double).

Parameters:

  • name – The name of the column.

  • column_data – A vector of T values, one per row.

template<typename T>
inline void add_column(const std::string &name, const size_t rows, const size_t cols, const std::vector<T> &column_data)

Adds a 2D column to the table from row and column dimensions.

Use this for matrix-style data where each row is a fixed-length vector. Internally calls the shape-based overload with a shape of {rows, cols}.

Template Parameters:

T – The data type of the column elements.

Parameters:

  • name – The name of the column.

  • rows – Number of rows (typically must match existing row count).

  • cols – Number of columns per row.

  • column_data – Flat vector of values in row-major order (size must be rows * cols).

template<typename T>
inline void update_column(const std::string &name, const std::vector<size_t> &shape, const std::vector<T> &column_data)

Replaces the data of an existing column.

Unlike add_column, this requires a column of the given name to already exist and replaces it in place (preserving column order). The replacement is wholesale, so the element type and shape may change, but the new row count must match the rest of the table.

Template Parameters:

T – The data type of the column.

Parameters:

  • name – The name of the (existing) column to update.

  • shape – A vector describing the shape of the new column data.

  • column_data – A flat vector of T values for the column.

Throws:

std::runtime_error – if no column with name exists or the row count does not match the other columns.

template<typename T>
inline void update_column(const std::string &name, const std::vector<T> &column_data)

Replaces an existing 1D column.

template<typename T>
inline void update_column(const std::string &name, const size_t rows, const size_t cols, const std::vector<T> &column_data)

Replaces an existing 2D column.

void write(std::string_view filename, std::string_view group = "/dials/processing/group_0") const

Writes all columns to an HDF5 file under the given group.

This function iterates through all stored columns and writes each one to disk as its h5dispatch::H5TypeTraits datatype. A column that HDF5 fails to write is skipped with a warning.

Parameters:

  • filename – Output HDF5 file path.

  • group – Target group inside the HDF5 file (defaults to /dials/processing/group_0).