Contents

Tables

This section describes the types related to the table concept.

Type

Description

table

A common implementation of the table concept. Base class for other table types.

table_metadata

An implementation of table metadata concept.

data_layout

An enumeration of data layouts used to store contiguous data blocks inside the table.

feature_type

An enumeration of feature types used in oneDAL to define set of available operations onto the data.

Requirements on table types

Each implementation of table concept shall:

  1. Follow the definition of the table concept and its restrictions (e.g., immutability).

  2. Be derived from the oneapi::dal::table class. The behavior of this class can be extended, but cannot be weaken.

  3. Be reference-counted.

  4. Every new oneapi::dal::table sub-type shall define a unique id number - the “kind” that represents objects of that type in runtime.

The following listing provides an example of table API to illustrate table kinds and copy-assignment operation:

using namespace onedal;

// Creating homogen_table sub-type.
dal::homogen_table table1 = homogen_table::wrap(queue, data_ptr, row_count, column_count);

// table1 and table2 share the same data (no data copy is performed)
dal::table table2 = table1;

// Creating an empty table
dal::table table3;

std::cout << table1.get_kind()     == table2.get_kind() << std::endl; // true
std::cout << homogen_table::kind() == table2.get_kind() << std::endl; // true
std::cout << table2.get_kind()     == table3.get_kind() << std::endl; // false

// Referring table3 to the table2.
table3 = table2;
std::cout << table2.get_kind() == table3.get_kind() << std::endl; // true

Table types

oneDAL defines a set of classes that implement the table concept for a specific data format:

Table type

Description

homogen table

A dense table that contains contiguous homogeneous data.

Programming interface

All types and functions in this section shall be declared in the oneapi::dal namespace and be available via inclusion of the oneapi/dal/table/common.hpp header file.

Table

A base implementation of the table concept. The table type and all of its subtypes shall be reference-counted:

  1. The instance shall store a pointer to table implementation that holds all property values and data

  2. The reference count indicating how many table objects refer to the same implementation.

  3. The table shall increment the reference count for it to be equal to the number of table objects sharing the same implementation.

  4. The table shall decrement the reference count when the table goes out of the scope. If the reference count is zero, the table shall free its implementation.

class table {
public:
    table();

    table(const table& other);

    table(table&& other);

    table& operator=(const table& other);

    table& operator=(table&& other);

    bool has_data() const noexcept;

    std::int64_t get_column_count() const;

    std::int64_t get_row_count() const;

    const table_metadata& get_metadata() const;

    std::int64_t get_kind() const;

    data_layout get_data_layout() const;
};
class table

Constructors

table()

An empty table constructor: creates the table instance with zero number of rows and columns. Implementation shall be set to the special “empty” object that returns all the property values set to default (see Properties section).

table(const table &other)

Creates a new table instance which shares implementation with \(other\).

table(table &&other)

Creates a new table instance and moves implementation from \(other\) into it.

Public Methods

table &operator=(const table &other)

Replaces the implementation by another one from \(other\).

table &operator=(table &&other)

Swaps the implementation of this object and \(other\).

bool has_data() const noexcept

Indicates whether a table contains non-zero number of rows and columns.

Properties

std::int64_t column_count = 0

The number of columns in the table.

Getter & Setter
std::int64_t get_column_count() const
std::int64_t row_count = 0

The number of rows in the table.

Getter & Setter
std::int64_t get_row_count() const
const table_metadata &metadata = table_metadata()

The metadata object that holds additional information about the data within the table.

Getter & Setter
const table_metadata & get_metadata() const
std::int64_t kind = empty_table_kind

The runtime id of the table type. Each table sub-type shall have its unique kind. An empty table (see the default constructor) shall have a unique kind value as well.

Getter & Setter
std::int64_t get_kind() const
data_layout data_layout = data_layout::unknown

The layout of the data within the table.

Getter & Setter
data_layout get_data_layout() const

Table metadata

An implementation of the table metadata concept. Holds additional information about data within the table. The objects of table_metadata shall be reference-counted.

class table_metadata {
public:
    table_metadata();

    table_metadata(const array<data_type>& dtypes, const array<feature_type>& ftypes);

    std::int64_t get_feature_count() const;

    const feature_type& get_feature_type(std::int64_t feature_index) const;

    const data_type& get_data_type(std::int64_t feature_index) const;
};
class table_metadata

Constructors

table_metadata()

Creates the metadata instance without information about the features. The feature_count shall be set to zero. The data_type and feature_type properties shall not be initialized.

table_metadata(const array<data_type> &dtypes, const array<feature_type> &ftypes)

Creates the metadata instance from external information about the data types and the feature types.

Parameters

  • dtypes – The data types of the features. Shall be assigned into the data_type property.

  • ftypes – The feature types. Shall be assigned into the feature_type property.

Preconditions
dtypes.get_count() == ftypes.get_count()

Properties

std::int64_t feature_count

The number of features that metadata contains information about.

Getter & Setter
std::int64_t get_feature_count() const
const feature_type &feature_type

Feature types in the metadata object. Shall be within the range [0, feature_count).

Getter & Setter
const feature_type & get_feature_type(std::int64_t feature_index) const
const data_type &data_type

Data types of the features in the metadata object. Shall be within the range [0, feature_count).

Getter & Setter
const data_type & get_data_type(std::int64_t feature_index) const

Data layout

An implementation of the data layout concept.

enum class data_layout { unknown, row_major, column_major };
enum class data_layout
data_layout::unknown

Represents the data layout that is undefined or unknown at this moment.

data_layout::row_major

The data block elements are stored in raw-major layout.

data_layout::column_major

The data block elements are stored in column_major layout.

Feature type

An implementation of the logical data types.

enum class feature_type { nominal, ordinal, interval, ratio };
enum class feature_type
feature_type::nominal

Represents the type of Nominal feature.

feature_type::ordinal

Represents the type of Ordinal feature.

feature_type::interval

Represents the type of Interval feature.

feature_type::ratio

Represents the type of Ratio feature.

CSV data source Homogeneous table