neuralogic.dataset package

Submodules

neuralogic.dataset.base module

class BaseDataset

Bases: object

Base class for logic datasets.

dump(queries_fp: Any, examples_fp: Any, sep: str = '\n') → None

Dumps the dataset queries and examples into the provided file-like objects.

Parameters:

• queries_fp (Any) – The file-like object to dump queries into.

• examples_fp (Any) – The file-like object to dump examples into.

• sep (str, optional) – The separator to use between samples. Default: “n”.

class ConvertibleDataset

Bases: BaseDataset

Base class for datasets that can be converted into a standard dataset format.

to_dataset() → Any

Converts the dataset to a standard dataset format.

Returns:

The converted dataset.

Return type:

Any

neuralogic.dataset.csv module

class CSVDataset(csv_files: list[CSVFile] | CSVFile, csv_queries: CSVFile | None = None, mode: Mode = Mode.ONE_EXAMPLE)

Bases: ConvertibleDataset

Represents a dataset composed of one or more CSV files.

add_csv_file(file: CSVFile) → None

set_query_csv_file(file: CSVFile) → None

to_dataset() → Dataset

Converts the CSV files to a Dataset object.

Returns:

The created Dataset object.

Return type:

Dataset

class CSVFile(relation_name: str, csv_source: TextIO | Path, sep: str = ',', value_column: str | int | None = None, default_value: float | int | None = None, value_mapper: Callable | None = None, term_columns: Sequence[str | int] | None = None, header: bool = False, skip_rows: int = 0, n_rows: int | None = None, replace_empty_column: str | float | int = 0)

Bases: object

Represents a single CSV file source and its configuration for conversion to logic relations.

csv_source

default_value

header

n_rows

relation_name

replace_empty_column

sep

skip_rows

term_columns

to_logic_form() → list[BaseRelation | Rule]

Converts the CSV source to a list of logic relations.

Returns:

The list of created logic relations.

Return type:

list[DatasetEntries]

value_column

value_mapper

class Mode(value)

Bases: Enum

Enum representing different modes of creating samples from CSV files.

EXAMPLE_PER_SOURCE = 'example_per_source'

ONE_EXAMPLE = 'one'

ZIP = 'zip'

neuralogic.dataset.db module

class DBDataset(connection: Any, db_sources: list[DBSource] | DBSource, queries_db_source: DBSource | None = None, mode: Mode = Mode.ONE_EXAMPLE)

Bases: ConvertibleDataset

Represents a dataset composed of one or more database sources.

add_db_source(db_source: DBSource) → None

set_queries(db_source: DBSource) → None

to_dataset() → Dataset

Converts the database sources to a Dataset object.

Returns:

The created Dataset object.

Return type:

Dataset

class DBSource(relation_name: str, table_name: str, term_columns: list[str], value_column: str | None = None, default_value: float | int = 1.0, value_mapper: Callable | None = None, skip_rows: int = 0, n_rows: int | None = None, replace_empty_column: str | float | int = 0, sep: str = ',')

Bases: object

Represents a database source (table) and its configuration for conversion to logic relations.

default_value

n_rows

relation_name

replace_empty_column

sep

skip_rows

table_name

term_columns

to_csv(cursor: Any) → CSVFile

Converts the database source to an intermediate CSV representation.

Parameters:

cursor (Any) – The database cursor to use for execution.

Returns:

The intermediate CSVFile object.

Return type:

CSVFile

value_column

value_mapper

neuralogic.dataset.file module

class FileDataset(examples_file: str | None = None, queries_file: str | None = None)

Bases: BaseDataset

FileDataset represents samples stored in files in the NeuraLogic (logic) format.

Parameters:

• examples_file (str | None) – Path to the examples file. Default: None

• queries_file (str | None) – Path to the queries file. Default: None

dump(queries_fp, examples_fp, sep: str = '\n')

Dumps the dataset queries and examples into the provided file-like objects.

Parameters:

• queries_fp (Any) – The file-like object to dump queries into.

• examples_fp (Any) – The file-like object to dump examples into.

• sep (str, optional) – The separator to use between samples. Default: “n”.

neuralogic.dataset.logic module

class Dataset(samples: list[Sample] | Sample | None = None)

Bases: BaseDataset

Dataset encapsulating (learning) samples in the form of logic format, allowing users to fully take advantage of the PyNeuraLogic library.

add(query: BaseRelation | list[BaseRelation] | None, example: list[BaseRelation | Rule] | None) → Dataset

add_example(example)

add_examples(examples: list)

add_queries(queries: list)

add_query(query)

add_sample(sample: Sample) → Dataset

add_samples(samples: list[Sample]) → Dataset

generate_features(feature_depth: int = 1, count_groundings: bool = True)

samples

set_examples(examples: list)

set_queries(queries: list)

set_samples(samples: list[Sample])

class Sample(query: BaseRelation | list[BaseRelation] | None, example: Sequence[BaseRelation | Rule] | BaseRelation | Rule | None)

Bases: object

draw(**kwargs)

example

query

neuralogic.dataset.pddl module

class PDDLDataset(domain: str, problems: str | list[str], include_actions: bool = True)

Bases: ConvertibleDataset

PDDLDataset converts PDDL domain and problem files into a logic dataset. It supports creating samples from the initial state and using the goal state as a query.

to_dataset() → Dataset

Converts the PDDL domain and problems into a NeuraLogic Dataset.

Returns:

The created Dataset object containing Samples.

Return type:

Dataset

neuralogic.dataset.tensor module

class Data(x: Sequence, edge_index: Sequence, y: Sequence | float | int = 0.0, edge_attr: Sequence | None = None, y_mask: Sequence | None = None)

Bases: object

The Data instance stores information about one specific graph instance.

Example

For example, the directed graph \(G = (V, E)\), where \(E = \{(0, 1), (1, 2), (2, 0)\}\), node features \(X = \{[0], [1], [0]\}\) and target nodes’ labels \(Y = \{0, 1, 0\}\) would be represented as:

data = Data(
    x=[[0], [1], [0]],
    edge_index=[
        [0, 1, 2],
        [1, 2, 0],
    ],
    y=[0, 1, 0],
)

Parameters:

• x (Sequence) – Sequence of node features.

• edge_index (Sequence) – Edges represented via a graph connectivity format - matrix [[...src], [...dst]].

• y (Union[Sequence, float, int]) – Sequence of labels of all nodes or one graph label.

• edge_attr (Sequence | None) – Optional sequence of edge features. Default: None

• y_mask (Sequence | None) – Optional sequence of node ids to generate queries for. Default: None (all nodes)

static from_pyg(data) → List[Data]

Converts a PyTorch Geometric Data instance into a list of PyNeuraLogic Data instances. The conversion supports train_mask, test_mask and val_mask attributes - for each mask the conversion yields a new data instance.

Parameters:

data – The PyTorch Geometric Data instance

Returns:

The list of PyNeuraLogic Data instances

static get_query(y, output_name: str = 'predict', one_hot_encode_labels: bool = False, max_classes=1, index: int | None = None)

to_logic_form(feature_name: str = 'node_feature', edge_name: str = 'edge', output_name: str = 'predict', one_hot_encode_labels=False, one_hot_decode_features=False, one_hot_decode_edge_features=False, max_classes=1) → Tuple

class TensorDataset(data: List[Data], one_hot_encode_labels: bool = False, one_hot_decode_features: bool = False, one_hot_decode_edge_features: bool = False, number_of_classes: int = 1, feature_name: str = 'node_feature', edge_name: str = 'edge', output_name: str = 'predict')

Bases: ConvertibleDataset

The TensorDataset holds a list of Data instances - a list of graphs represented in a tensor format.

Parameters:

• data (List[Data]) – List of data (graph) instances.

• one_hot_encode_labels (bool) – Turn numerical labels into one hot encoded vectors - e.g., label 2 would be turned into a vector [0, 0, 1, .., 0] of length number_of_classes. Default: False

• one_hot_decode_features (bool = False) – Turn one hot encoded feature vectors into a scalar - e.g., feature vector [0, 0, 1] would be turned into a predicate <feature_name>_2. Default: False

• one_hot_decode_edge_features (bool = False) – Turn one hot encoded edge feature vectors into a scalar - e.g., edge feature vector [0, 0, 1] would be turned into a predicate <edge_name>_2. Default: False

• number_of_classes (int) – Specifies the number of classes for converting numerical labels to one hot encoded vectors. Default: 1

• feature_name (str) – Specify the node feature predicate name used for converting into the logic format. Default: "node_feature"

• edge_name (str) – Specify the edge predicate name used for converting into the logic format. Default: "edge"

• output_name (str) – Specify the output predicate name used for converting into the logic format. Default: "predict"

add_data(data: Data)

dump(queries_fp, examples_fp, sep: str = '\n')

Dumps the dataset queries and examples into the provided file-like objects.

Parameters:

• queries_fp (Any) – The file-like object to dump queries into.

• examples_fp (Any) – The file-like object to dump examples into.

• sep (str, optional) – The separator to use between samples. Default: “n”.

to_dataset() → Dataset

Converts the dataset to a standard dataset format.

Returns:

The converted dataset.

Return type:

Any

Module contents

class BaseDataset

Bases: object

Base class for logic datasets.

dump(queries_fp: Any, examples_fp: Any, sep: str = '\n') → None

Dumps the dataset queries and examples into the provided file-like objects.

Parameters:

• queries_fp (Any) – The file-like object to dump queries into.

• examples_fp (Any) – The file-like object to dump examples into.

• sep (str, optional) – The separator to use between samples. Default: “n”.

class CSVDataset(csv_files: list[CSVFile] | CSVFile, csv_queries: CSVFile | None = None, mode: Mode = Mode.ONE_EXAMPLE)

Bases: ConvertibleDataset

Represents a dataset composed of one or more CSV files.

add_csv_file(file: CSVFile) → None

set_query_csv_file(file: CSVFile) → None

to_dataset() → Dataset

Converts the CSV files to a Dataset object.

Returns:

The created Dataset object.

Return type:

Dataset

class CSVFile(relation_name: str, csv_source: TextIO | Path, sep: str = ',', value_column: str | int | None = None, default_value: float | int | None = None, value_mapper: Callable | None = None, term_columns: Sequence[str | int] | None = None, header: bool = False, skip_rows: int = 0, n_rows: int | None = None, replace_empty_column: str | float | int = 0)

Bases: object

Represents a single CSV file source and its configuration for conversion to logic relations.

csv_source

default_value

header

n_rows

relation_name

replace_empty_column

sep

skip_rows

term_columns

to_logic_form() → list[BaseRelation | Rule]

Converts the CSV source to a list of logic relations.

Returns:

The list of created logic relations.

Return type:

list[DatasetEntries]

value_column

value_mapper

class ConvertibleDataset

Bases: BaseDataset

Base class for datasets that can be converted into a standard dataset format.

to_dataset() → Any

Converts the dataset to a standard dataset format.

Returns:

The converted dataset.

Return type:

Any

class DBDataset(connection: Any, db_sources: list[DBSource] | DBSource, queries_db_source: DBSource | None = None, mode: Mode = Mode.ONE_EXAMPLE)

Bases: ConvertibleDataset

Represents a dataset composed of one or more database sources.

add_db_source(db_source: DBSource) → None

set_queries(db_source: DBSource) → None

to_dataset() → Dataset

Converts the database sources to a Dataset object.

Returns:

The created Dataset object.

Return type:

Dataset

class DBSource(relation_name: str, table_name: str, term_columns: list[str], value_column: str | None = None, default_value: float | int = 1.0, value_mapper: Callable | None = None, skip_rows: int = 0, n_rows: int | None = None, replace_empty_column: str | float | int = 0, sep: str = ',')

Bases: object

Represents a database source (table) and its configuration for conversion to logic relations.

default_value

n_rows

relation_name

replace_empty_column

sep

skip_rows

table_name

term_columns

to_csv(cursor: Any) → CSVFile

Converts the database source to an intermediate CSV representation.

Parameters:

cursor (Any) – The database cursor to use for execution.

Returns:

The intermediate CSVFile object.

Return type:

CSVFile

value_column

value_mapper

class Data(x: Sequence, edge_index: Sequence, y: Sequence | float | int = 0.0, edge_attr: Sequence | None = None, y_mask: Sequence | None = None)

Bases: object

The Data instance stores information about one specific graph instance.

Example

For example, the directed graph \(G = (V, E)\), where \(E = \{(0, 1), (1, 2), (2, 0)\}\), node features \(X = \{[0], [1], [0]\}\) and target nodes’ labels \(Y = \{0, 1, 0\}\) would be represented as:

data = Data(
    x=[[0], [1], [0]],
    edge_index=[
        [0, 1, 2],
        [1, 2, 0],
    ],
    y=[0, 1, 0],
)

Parameters:

• x (Sequence) – Sequence of node features.

• edge_index (Sequence) – Edges represented via a graph connectivity format - matrix [[...src], [...dst]].

• y (Union[Sequence, float, int]) – Sequence of labels of all nodes or one graph label.

• edge_attr (Sequence | None) – Optional sequence of edge features. Default: None

• y_mask (Sequence | None) – Optional sequence of node ids to generate queries for. Default: None (all nodes)

static from_pyg(data) → List[Data]

Converts a PyTorch Geometric Data instance into a list of PyNeuraLogic Data instances. The conversion supports train_mask, test_mask and val_mask attributes - for each mask the conversion yields a new data instance.

Parameters:

data – The PyTorch Geometric Data instance

Returns:

The list of PyNeuraLogic Data instances

static get_query(y, output_name: str = 'predict', one_hot_encode_labels: bool = False, max_classes=1, index: int | None = None)

to_logic_form(feature_name: str = 'node_feature', edge_name: str = 'edge', output_name: str = 'predict', one_hot_encode_labels=False, one_hot_decode_features=False, one_hot_decode_edge_features=False, max_classes=1) → Tuple

class Dataset(samples: list[Sample] | Sample | None = None)

Bases: BaseDataset

Dataset encapsulating (learning) samples in the form of logic format, allowing users to fully take advantage of the PyNeuraLogic library.

add(query: BaseRelation | list[BaseRelation] | None, example: list[BaseRelation | Rule] | None) → Dataset

add_example(example)

add_examples(examples: list)

add_queries(queries: list)

add_query(query)

add_sample(sample: Sample) → Dataset

add_samples(samples: list[Sample]) → Dataset

generate_features(feature_depth: int = 1, count_groundings: bool = True)

samples

set_examples(examples: list)

set_queries(queries: list)

set_samples(samples: list[Sample])

class FileDataset(examples_file: str | None = None, queries_file: str | None = None)

Bases: BaseDataset

FileDataset represents samples stored in files in the NeuraLogic (logic) format.

Parameters:

• examples_file (str | None) – Path to the examples file. Default: None

• queries_file (str | None) – Path to the queries file. Default: None

dump(queries_fp, examples_fp, sep: str = '\n')

Dumps the dataset queries and examples into the provided file-like objects.

Parameters:

• queries_fp (Any) – The file-like object to dump queries into.

• examples_fp (Any) – The file-like object to dump examples into.

• sep (str, optional) – The separator to use between samples. Default: “n”.

class Mode(value)

Bases: Enum

Enum representing different modes of creating samples from CSV files.

EXAMPLE_PER_SOURCE = 'example_per_source'

ONE_EXAMPLE = 'one'

ZIP = 'zip'

class PDDLDataset(domain: str, problems: str | list[str], include_actions: bool = True)

Bases: ConvertibleDataset

PDDLDataset converts PDDL domain and problem files into a logic dataset. It supports creating samples from the initial state and using the goal state as a query.

to_dataset() → Dataset

Converts the PDDL domain and problems into a NeuraLogic Dataset.

Returns:

The created Dataset object containing Samples.

Return type:

Dataset

class Sample(query: BaseRelation | list[BaseRelation] | None, example: Sequence[BaseRelation | Rule] | BaseRelation | Rule | None)

Bases: object

draw(**kwargs)

example

query

class TensorDataset(data: List[Data], one_hot_encode_labels: bool = False, one_hot_decode_features: bool = False, one_hot_decode_edge_features: bool = False, number_of_classes: int = 1, feature_name: str = 'node_feature', edge_name: str = 'edge', output_name: str = 'predict')

Bases: ConvertibleDataset

The TensorDataset holds a list of Data instances - a list of graphs represented in a tensor format.

Parameters:

• data (List[Data]) – List of data (graph) instances.

• one_hot_encode_labels (bool) – Turn numerical labels into one hot encoded vectors - e.g., label 2 would be turned into a vector [0, 0, 1, .., 0] of length number_of_classes. Default: False

• one_hot_decode_features (bool = False) – Turn one hot encoded feature vectors into a scalar - e.g., feature vector [0, 0, 1] would be turned into a predicate <feature_name>_2. Default: False

• one_hot_decode_edge_features (bool = False) – Turn one hot encoded edge feature vectors into a scalar - e.g., edge feature vector [0, 0, 1] would be turned into a predicate <edge_name>_2. Default: False

• number_of_classes (int) – Specifies the number of classes for converting numerical labels to one hot encoded vectors. Default: 1

• feature_name (str) – Specify the node feature predicate name used for converting into the logic format. Default: "node_feature"

• edge_name (str) – Specify the edge predicate name used for converting into the logic format. Default: "edge"

• output_name (str) – Specify the output predicate name used for converting into the logic format. Default: "predict"

add_data(data: Data)

dump(queries_fp, examples_fp, sep: str = '\n')

Dumps the dataset queries and examples into the provided file-like objects.

Parameters:

• queries_fp (Any) – The file-like object to dump queries into.

• examples_fp (Any) – The file-like object to dump examples into.

• sep (str, optional) – The separator to use between samples. Default: “n”.

to_dataset() → Dataset

Converts the dataset to a standard dataset format.

Returns:

The converted dataset.

Return type:

Any