dhg.experiments

Base Class

class dhg.experiments.BaseTask(work_root, data, model_builder, train_builder, evaluator, device, structure_builder=None, study_name=None, overwrite=True)[source]

Bases: object

The base class of Auto-experiment in DHG.

Parameters

work_root (Optional[Union[str, Path]]) – User’s work root to store all studies.
data (dict) – The dictionary to store input data that used in the experiment.
model_builder (Callable) – The function to build a model with a fixed parameter trial.
train_builder (Callable) – The function to build a training configuration with two fixed parameters trial and model.
evaluator (dhg.metrics.BaseEvaluator) – The DHG evaluator object to evaluate performance of the model in the experiment.
device (torch.device) – The target device to run the experiment.
structure_builder (Optional[Callable]) – The function to build a structure with a fixed parameter trial. The structure can be dhg.Graph, dhg.DiGraph, dhg.BiGraph, and dhg.Hypergraph.
study_name (Optional[str]) – The name of this study. If set to None, the study name will be generated automatically according to current time. Defaults to None.
overwrite (bool) – The flag that whether to overwrite the existing study. Different studies are identified by the study_name. Defaults to True.

experiment(trial)[source]

Run the experiment for a given trial.

Parameters: trial (optuna.Trial) – The optuna.Trial object.

run(max_epoch, num_trials=1, direction='maximize')[source]

Run experiments with automatically hyper-parameter tuning.

Parameters

max_epoch (int) – The maximum number of epochs to train for each experiment.
num_trials (int) – The number of trials to run. Defaults to 1.
direction (str) – The direction to optimize. Defaults to "maximize".

test(data=None, model=None)

Test the model.

Parameters

data (dict, optional) – The input data if set to None, the specified data in the intialization of the experiments will be used. Defaults to None.
model (nn.Module, optional) – The model if set to None, the trained best model will be used. Defaults to None.

abstract train(data, model, optimizer, criterion)[source]

Train model for one epoch.

Parameters

data (dict) – The input data.
model (nn.Module) – The model.
optimizer (torch.optim.Optimizer) – The model optimizer.
criterion (nn.Module) – The loss function.

validate(data, model)

Validate the model.

Parameters

data (dict) – The input data.
model (nn.Module) – The model.

Vertex Classification Task

class dhg.experiments.VertexClassificationTask(work_root, data, model_builder, train_builder, evaluator, device, structure_builder=None, study_name=None, overwrite=True)[source]

Bases: dhg.experiments.base.BaseTask

The auto-experiment class for the vertex classification task.

Parameters

work_root (Optional[Union[str, Path]]) – User’s work root to store all studies.
data (dict) – The dictionary to store input data that used in the experiment.
model_builder (Callable) – The function to build a model with a fixed parameter trial.
train_builder (Callable) – The function to build a training configuration with two fixed parameters trial and model.
evaluator (dhg.metrics.BaseEvaluator) – The DHG evaluator object to evaluate performance of the model in the experiment.
device (torch.device) – The target device to run the experiment.
structure_builder (Optional[Callable]) – The function to build a structure with a fixed parameter trial. The structure can be dhg.Graph, dhg.DiGraph, dhg.BiGraph, and dhg.Hypergraph.
study_name (Optional[str]) – The name of this study. If set to None, the study name will be generated automatically according to current time. Defaults to None.
overwrite (bool) – The flag that whether to overwrite the existing study. Different studies are identified by the study_name. Defaults to True.

experiment(trial)[source]

Run the experiment for a given trial.

Parameters: trial (optuna.Trial) – The optuna.Trial object.

run(max_epoch, num_trials=1, direction='maximize')[source]

Run experiments with automatically hyper-parameter tuning.

Parameters

max_epoch (int) – The maximum number of epochs to train for each experiment.
num_trials (int) – The number of trials to run. Defaults to 1.
direction (str) – The direction to optimize. Defaults to "maximize".

test(data=None, model=None)

Test the model.

Parameters

data (dict, optional) – The input data if set to None, the specified data in the intialization of the experiments will be used. Defaults to None.
model (nn.Module, optional) – The model if set to None, the trained best model will be used. Defaults to None.

to(device)[source]

Move the input data to the target device.

Parameters: device (torch.device) – The specified target device to store the input data.

train(data, model, optimizer, criterion)[source]

Train model for one epoch.

Parameters

data (dict) – The input data.
model (nn.Module) – The model.
optimizer (torch.optim.Optimizer) – The model optimizer.
criterion (nn.Module) – The loss function.

validate(data, model)

Validate the model.

Parameters

data (dict) – The input data.
model (nn.Module) – The model.

property vars_for_DL: Return a name list for available variables for deep learning in the vertex classification task. The name list includes features, structure, labels, train_mask, val_mask, and test_mask.

On Graph

class dhg.experiments.GraphVertexClassificationTask(work_root, data, model_builder, train_builder, evaluator, device, study_name=None, overwrite=True)[source]

Bases: dhg.experiments.vertex_classification.VertexClassificationTask

The auto-experiment class for the vertex classification task on graph.

Parameters

work_root (Optional[Union[str, Path]]) – User’s work root to store all studies.
data (dict) – The dictionary to store input data that used in the experiment.
model_builder (Callable) – The function to build a model with a fixed parameter trial.
train_builder (Callable) – The function to build a training configuration with two fixed parameters trial and model.
evaluator (dhg.metrics.BaseEvaluator) – The DHG evaluator object to evaluate performance of the model in the experiment.
device (torch.device) – The target device to run the experiment.
structure_builder (Optional[Callable]) – The function to build a structure with a fixed parameter trial. The structure should be dhg.Graph.
study_name (Optional[str]) – The name of this study. If set to None, the study name will be generated automatically according to current time. Defaults to None.
overwrite (bool) – The flag that whether to overwrite the existing study. Different studies are identified by the study_name. Defaults to True.

experiment(trial)[source]

Run the experiment for a given trial.

Parameters: trial (optuna.Trial) – The optuna.Trial object.

run(max_epoch, num_trials=1, direction='maximize')[source]

Run experiments with automatically hyper-parameter tuning.

Parameters

max_epoch (int) – The maximum number of epochs to train for each experiment.
num_trials (int) – The number of trials to run. Defaults to 1.
direction (str) – The direction to optimize. Defaults to "maximize".

test(data=None, model=None)

Test the model.

Parameters

data (dict, optional) – The input data if set to None, the specified data in the intialization of the experiments will be used. Defaults to None.
model (nn.Module, optional) – The model if set to None, the trained best model will be used. Defaults to None.

to(device)[source]

Move the input data to the target device.

Parameters: device (torch.device) – The specified target device to store the input data.

train(data, model, optimizer, criterion)[source]

Train model for one epoch.

Parameters

data (dict) – The input data.
model (nn.Module) – The model.
optimizer (torch.optim.Optimizer) – The model optimizer.
criterion (nn.Module) – The loss function.

validate(data, model)

Validate the model.

Parameters

data (dict) – The input data.
model (nn.Module) – The model.

property vars_for_DL: Return a name list for available variables for deep learning in the vertex classification on graph. The name list includes features, structure, labels, train_mask, val_mask, and test_mask.

On Hypergraph

class dhg.experiments.HypergraphVertexClassificationTask(work_root, data, model_builder, train_builder, evaluator, device, structure_builder=None, study_name=None, overwrite=True)[source]

Bases: dhg.experiments.vertex_classification.VertexClassificationTask

The auto-experiment class for the vertex classification task on hypergraph.

Parameters

work_root (Optional[Union[str, Path]]) – User’s work root to store all studies.
data (dict) – The dictionary to store input data that used in the experiment.
model_builder (Callable) – The function to build a model with a fixed parameter trial.
train_builder (Callable) – The function to build a training configuration with two fixed parameters trial and model.
evaluator (dhg.metrics.BaseEvaluator) – The DHG evaluator object to evaluate performance of the model in the experiment.
device (torch.device) – The target device to run the experiment.
structure_builder (Optional[Callable]) – The function to build a structure with a fixed parameter trial. The structure should be dhg.Hypergraph.
study_name (Optional[str]) – The name of this study. If set to None, the study name will be generated automatically according to current time. Defaults to None.
overwrite (bool) – The flag that whether to overwrite the existing study. Different studies are identified by the study_name. Defaults to True.

experiment(trial)[source]

Run the experiment for a given trial.

Parameters: trial (optuna.Trial) – The optuna.Trial object.

run(max_epoch, num_trials=1, direction='maximize')[source]

Run experiments with automatically hyper-parameter tuning.

Parameters

max_epoch (int) – The maximum number of epochs to train for each experiment.
num_trials (int) – The number of trials to run. Defaults to 1.
direction (str) – The direction to optimize. Defaults to "maximize".

test(data=None, model=None)

Test the model.

Parameters

data (dict, optional) – The input data if set to None, the specified data in the intialization of the experiments will be used. Defaults to None.
model (nn.Module, optional) – The model if set to None, the trained best model will be used. Defaults to None.

to(device)[source]

Move the input data to the target device.

Parameters: device (torch.device) – The specified target device to store the input data.

train(data, model, optimizer, criterion)[source]

Train model for one epoch.

Parameters

data (dict) – The input data.
model (nn.Module) – The model.
optimizer (torch.optim.Optimizer) – The model optimizer.
criterion (nn.Module) – The loss function.

validate(data, model)

Validate the model.

Parameters

data (dict) – The input data.
model (nn.Module) – The model.

property vars_for_DL: Return a name list for available variables for deep learning in the vertex classification on hypergraph. The name list includes features, structure, labels, train_mask, val_mask, and test_mask.

Recommender Task

On User-Item Bipartite Graph

class dhg.experiments.UserItemRecommenderTask(work_root, data, model_builder, train_builder, evaluator, device, structure_builder=None, study_name=None, overwrite=True)[source]

Bases: dhg.experiments.base.BaseTask

The auto-experiment class for the recommender task on user-item bipartite graph.

Parameters

work_root (Optional[Union[str, Path]]) – User’s work root to store all studies.
data (dict) – The dictionary to store input data that used in the experiment.
model_builder (Callable) – The function to build a model with a fixed parameter trial.
train_builder (Callable) – The function to build a training configuration with two fixed parameters trial and model.
evaluator (dhg.metrics.BaseEvaluator) – The DHG evaluator object to evaluate performance of the model in the experiment.
device (torch.device) – The target device to run the experiment.
structure_builder (Optional[Callable]) – The function to build a structure with a fixed parameter trial. The structure should be dhg.DiGraph.
study_name (Optional[str]) – The name of this study. If set to None, the study name will be generated automatically according to current time. Defaults to None.
overwrite (bool) – The flag that whether to overwrite the existing study. Different studies are identified by the study_name. Defaults to True.

experiment(trial)[source]

Run the experiment for a given trial.

Parameters: trial (optuna.Trial) – The optuna.Trial object.

run(max_epoch, num_trials=1, direction='maximize')[source]

Run experiments with automatically hyper-parameter tuning.

Parameters

max_epoch (int) – The maximum number of epochs to train for each experiment.
num_trials (int) – The number of trials to run. Defaults to 1.
direction (str) – The direction to optimize. Defaults to "maximize".

test(data=None, model=None)

Test the model.

Parameters

data (dict, optional) – The input data if set to None, the specified data in the intialization of the experiments will be used. Defaults to None.
model (nn.Module, optional) – The model if set to None, the trained best model will be used. Defaults to None.

to(device)[source]

Move the input data to the target device.

Parameters: device (torch.device) – The specified target device to store the input data.

train(data, model, optimizer, criterion)[source]

Train model for one epoch.

Parameters

data (dict) – The input data.
model (nn.Module) – The model.
optimizer (torch.optim.Optimizer) – The model optimizer.
criterion (nn.Module) – The loss function.

validate(data, model)

Validate the model.

Parameters

data (dict) – The input data.
model (nn.Module) – The model.

property vars_for_DL: Return a name list for available deep learning variables for the recommender task on user-item bipartite graph. The name list includes structure.