### Install EasyTPP with Pip

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/get_started/install.md

Install the EasyTPP library using pip for a quick setup.

```bash
pip install easy-tpp
```

--------------------------------

### Install EasyTPP from PyPI or Source

Source: https://context7.com/ant-research/easytemporalpointprocess/llms.txt

Install the EasyTPP library using pip or by cloning the repository and installing from source. Ensure you have Python 3.9+ and create a dedicated conda environment.

```bash
# Install from PyPI
pip install easy-tpp

# Install from source
git clone https://github.com/ant-research/EasyTemporalPointProcess.git
cd EasyTemporalPointProcess
python setup.py install

# Create a dedicated conda environment (Python >= 3.9 required)
conda create -n easytpp python=3.9
conda activate easytpp
pip install torch easy-tpp
```

--------------------------------

### Install EasyTPP from Source

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/get_started/install.md

Clone the EasyTPP repository and install the library from the source code. This method is useful for development or custom modifications.

```bash
git clone https://github.com/ant-research/EasyTemporalPointProcess.git
cd EasyTemporalPointProcess
python setup.py install
```

--------------------------------

### Install PyTorch

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/get_started/install.md

Install PyTorch, ensuring the version is at least 1.8.0. This is the default backend for EasyTPP.

```bash
pip install torch
```

--------------------------------

### Install TensorFlow Backend (Optional)

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/get_started/install.md

Install TensorFlow if you intend to use it as the backend. Both Tensorflow 1.13.1 and 2.x are supported.

```bash
pip install tensorflow
```

--------------------------------

### Generate Documentation Locally

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/README.md

Install documentation dependencies and build the HTML documentation locally. Ensure you are in the docs directory before running make html.

```bash
pip install -r requirements-doc.txt
cd docs
make html
```

--------------------------------

### Install EasyTPP Package

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/notebooks/easytpp_1_dataset.ipynb

Install the EasyTPP library using pip. Use the latest release or the git main branch.

```bash
# ues the latest release
# !pip install easy-tpp

# or use the git main branch
!pip install git+https://github.com/ant-research/EasyTemporalPointProcess.git
```

--------------------------------

### Install EasyTPP Package

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/notebooks/easytpp_3_train_eval.ipynb

Install or upgrade the EasyTPP package using pip. This command ensures you have the latest version for the tutorial.

```python
! pip install --upgrade easy-tpp
```

--------------------------------

### Gatech Dataset Format Example

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/user_guide/dataset.md

Illustrates the expected dictionary structure for datasets in EasyTPP, including `dim_process` and the 'train' key containing event sequences.

```bash
dim_process: 5 # num of event types (no padding)
'train': [[{'idx_event': 2, 'time_since_last_event': 1.0267814, 'time_since_last_same_event': 1.0267814, 'type_event': 3, 'time_since_start': 1.0267814}, {'idx_event': 3, 'time_since_last_event': 0.4029268, 'time_since_last_same_event': 1.4297082, 'type_event': 0, 'time_since_start': 1.4297082},...,],[{}...{}]]
```

--------------------------------

### Example Training Configuration

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/user_guide/run_train_pipeline.md

This YAML configuration file defines parameters for training a temporal point process model. It includes settings for data loading, model architecture, training parameters, and output directories. The `use_tfb: true` option enables TensorBoard for monitoring training progress.

```yaml
data_config:
  train_dir: ../data/conttime/train.pkl
  valid_dir: ../data/conttime/dev.pkl
  test_dir: ../data/conttime/test.pkl
  specs:
    num_event_types_pad: 6
    num_event_types: 5
    event_pad_index: 5
  data_format: pkl
base_config:
  stage: train
  backend: tensorflow
  dataset_id: conttime
  runner_id: std_tpp
  model_id: RMTPP
  base_dir: ./checkpoints/
  exp_id: RMTPP_train
  log_folder: ./checkpoints/98888_4299965824_221205-153425
  saved_model_dir: ./checkpoints/98888_4299965824_221205-153425/models/saved_model
  saved_log_dir: ./checkpoints/98888_4299965824_221205-153425/log
  output_config_dir: ./checkpoints/98888_4299965824_221205-153425/RMTPP_train_output.yaml
model_config:
  hidden_size: 32
  time_emb_size: 16
  num_layers: 2
  num_heads: 2
  mc_num_sample_per_step: 20
  sharing_param_layer: false
  loss_integral_num_sample_per_step: 20
  dropout: 0.0
  use_ln: false
  seed: 2019
  gpu: 0
  thinning_params:
    num_seq: 10
    num_sample: 1
    num_exp: 500
    look_ahead_time: 10
    patience_counter: 5
    over_sample_rate: 5
    num_samples_boundary: 5
    dtime_max: 5
    num_step_gen: 1
  trainer:
    batch_size: 256
    max_epoch: 10
    shuffle: false
    optimizer: adam
    learning_rate: 0.001
    valid_freq: 1
    use_tfb: false
    metrics:
    - acc
    - rmse
    seq_pad_end: true
  is_training: true
  num_event_types_pad: 6
  num_event_types: 5
  event_pad_index: 5
  model_id: RMTPP
```

--------------------------------

### Sequence Padding Example

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/user_guide/dataset.md

Demonstrates how raw event sequences are padded to a maximum length (`max_len`) using default padding values for times and types.

```bash
input: raw event sequence (e_0, e_1, e_2, e_3) and max_len=6 # the max length among all data seqs

output:

        index:    0,          1,         2,         3，      4         5
        dtimes:   0，     t_1-t_0,    t_2-t_1,   t_3-t_2， time_pad, time_pad
        types:    e_0,      e_1,        e_2,       e_3，  type_pad, type_pad
```

--------------------------------

### Generate Project Documentation

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/README.md

Commands to generate project documentation locally using Sphinx. Ensure you are in the 'doc' directory and have installed the required dependencies.

```shell
cd doc
pip install -r requirements.txt
make html
```

--------------------------------

### Data Configuration Example

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/user_guide/run_train_pipeline.md

Configures dataset specifics, including data format, directories for training, validation, and testing data, and data specification details like event types and sequence length.

```yaml
data:
  taxi:
    data_format: pkl
    train_dir: ../data/taxi/train.pkl
    valid_dir: ../data/taxi/dev.pkl
    test_dir: ../data/taxi/test.pkl
    data_spec：
        num_event_types: 7  # num of types excluding pad events.
        pad_token_id: 6    # event type index for pad events
        padding_side: right   # pad at the right end of the sequence
        truncation_side: right   # truncate at the right end of the sequence
        max_len: 100            # max sequence length used as model input
```

--------------------------------

### Configure Pickle Data Loading

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/notebooks/easytpp_1_dataset.ipynb

Example configuration for loading taxi dataset in pickle format. Ensure data files are placed in a 'data' directory.

```yaml
data:
  taxi:
    data_format: pickle
    train_dir:  ./data/taxi/train.pkl
    valid_dir:  ./data/taxi/dev.pkl
    test_dir:  ./data/taxi/test.pkl
```

--------------------------------

### Gatech Dataset Format (Pickle)

Source: https://context7.com/ant-research/easytemporalpointprocess/llms.txt

Example structure for a Gatech-format pickle file used by EasyTPP. Each file is a dictionary containing `dim_process` and lists for `train`, `dev`, and `test` event sequences.

```python
import pickle

example_dataset = {
    'dim_process': 10,
    'train': [
        [
            {'time_since_start': 0.0,    'time_since_last_event': 0.0,    'type_event': 3},
            {'time_since_start': 1.0268, 'time_since_last_event': 1.0268, 'type_event': 7},
            {'time_since_start': 1.4297, 'time_since_last_event': 0.4029, 'type_event': 0},
        ],
    ],
    'dev':  [...],
    'test': [...],
}

with open('./data/taxi/train.pkl', 'wb') as f:
    pickle.dump(example_dataset, f)
```

--------------------------------

### Initialize and Run Model Training

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/notebooks/easytpp_3_train_eval.ipynb

Use this snippet to initialize the model runner from a YAML configuration file and start the training process. Ensure the configuration file path and experiment ID are correctly specified.

```python
from easy_tpp.config_factory import Config\nfrom easy_tpp.runner import Runner\n\nconfig = Config.build_from_yaml_file('./config.yaml', experiment_id='NHP_train')\n\nmodel_runner = Runner.build_from_config(config)\n\nmodel_runner.run()
```

--------------------------------

### Optuna Hyperparameter Optimization Configuration

Source: https://context7.com/ant-research/easytemporalpointprocess/llms.txt

An example YAML configuration for Optuna-based hyperparameter optimization. It defines search spaces using `suggest_*` expressions for learning rate and hidden size.

```yaml
# configs/hpo_config.yaml
pipeline_config_id: hpo_runner_config

data:
  taxi:
    data_format: pkl
    train_dir: ./data/taxi/train.pkl
    valid_dir: ./data/taxi/dev.pkl
    test_dir:  ./data/taxi/test.pkl
    data_specs:
      num_event_types: 10
      pad_token_id: 10
      padding_side: right

hpo:
  storage_uri: sqlite:///hpo_test.db
  is_continuous: False
  framework_id: optuna
  n_trials: 20

NHP_train:
  base_config:
    stage: train
    backend: torch
    dataset_id: taxi
    runner_id: std_tpp
    model_id: NHP
    base_dir: ./checkpoints/
  trainer_config:
    batch_size: 256
    max_epoch: 50
    optimizer: adam
    learning_rate: "suggest_float(1e-4, 1e-2, log=True)"   # Optuna search expression
    valid_freq: 1
    use_tfb: False
    metrics: [acc, rmse]
    seed: 2019
    gpu: -1
  model_config:
    hidden_size: "suggest_categorical([32, 64, 128])"
    loss_integral_num_sample_per_step: 20
    thinning:
      num_exp: 500
      dtime_max: 5
      num_step_gen: 1
```

--------------------------------

### Padded Sequence Example: Time Sequences

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/user_guide/dataset.md

Shows the resulting padded `time_seqs` for a sample event sequence, including padding values.

```bash
# time_seqs
[ 0.0000,  0.8252,  1.3806,  1.8349, 11.0000, 11.0000]
```

--------------------------------

### Training Log Output

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/notebooks/easytpp_3_train_eval.ipynb

This output shows the critical and informational logs during the model training setup, including configuration loading, device selection, and saving checkpoints.

```log
2025-04-06 05:42:18,953 - config.py[pid:60211;line:34:build_from_yaml_file] - CRITICAL: Load pipeline config class RunnerConfig\n2025-04-06 05:42:18,957 - runner_config.py[pid:60211;line:151:update_config] - CRITICAL: train model NHP using CPU with torch backend\n2025-04-06 05:42:18,970 - runner_config.py[pid:60211;line:35:__init__] - INFO: Save the config to ./checkpoints/60211_133800770625536_250406-054218/NHP_train_output.yaml\n2025-04-06 05:42:18,972 - base_runner.py[pid:60211;line:176:save_log] - INFO: Save the log to ./checkpoints/60211_133800770625536_250406-054218/log
```

--------------------------------

### Mask Sequences Example: Batch Non-Pad Mask

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/user_guide/dataset.md

Illustrates the `batch_non_pad_mask` which indicates the positions of actual events versus padding in the sequence.

```bash
# batch_non_pad_mask
[ True,  True,  True,  True, False, False]
```

--------------------------------

### Padded Sequence Example: Type Sequences

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/user_guide/dataset.md

Presents the padded `type_seqs` for a sample event sequence, including the event type indices and padding values.

```bash
# type_seqs
[ 1,  9,  5,  0, 11, 11]
```

--------------------------------

### Padded Sequence Example: Time Delta Sequences

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/user_guide/dataset.md

Displays the padded `time_delta_seqs` for a sample event sequence, reflecting relative time differences and padding.

```bash
# time_delta_seqs
[ 0.0000,  0.8252,  0.5554,  0.4542, 11.0000, 11.0000]
```

--------------------------------

### Run Training Pipeline with EasyTPP

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/user_guide/run_train_pipeline.md

This script demonstrates how to initialize and run the training pipeline using the EasyTPP library. It parses command-line arguments for configuration directory and experiment ID, builds the configuration, and then initializes the runner to execute the training process.

```python
import argparse
from easy_tpp.config_factory import Config
from easy_tpp.runner import Runner


def main():
    parser = argparse.ArgumentParser()

    parser.add_argument('--config_dir', type=str, required=False, default='configs/experiment_config.yaml',
                        help='Dir of configuration yaml to train and evaluate the model.')

    parser.add_argument('--experiment_id', type=str, required=False, default='RMTPP_train',
                        help='Experiment id in the config file.')

    args = parser.parse_args()

    config = Config.build_from_yaml_file(args.config_dir, experiment_id=args.experiment_id)

    model_runner = Runner.build_from_config(config)

    model_runner.run()


if __name__ == '__main__':
    main()
```

--------------------------------

### Launch TensorBoard for Visualization

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/notebooks/easytpp_2_tfb_wb.ipynb

Launches TensorBoard to visualize the training process. The log directory should point to the TensorBoard log files generated during training.

```bash
! tensorboard --logdir "./checkpoints/91053_8345177088_250203-103232/tfb_train/"
```

--------------------------------

### RunnerConfig.get_metric_direction

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/ref/config.md

Gets the direction of a specified metric.

```APIDOC
## RunnerConfig.get_metric_direction

### Description
Gets the direction of a specified metric.

### Parameters
#### Path Parameters
- **metric_name** (str) – The name of the metric. Defaults to 'rmse'.

### Returns
the direction of the metric.
```

--------------------------------

### HPOConfig.storage_path

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/ref/config.md

Gets the storage path for HPO data.

```APIDOC
## HPOConfig.storage_path

### Description
Get the storage protocol

### Returns
the dir of the hpo data storage.

### Return type
str
```

--------------------------------

### HPOConfig.storage_protocol

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/ref/config.md

Gets the storage protocol for HPO results.

```APIDOC
## HPOConfig.storage_protocol

### Description
Get the storage protocol

### Returns
the dir of the storage protocol.

### Return type
str
```

--------------------------------

### utils.Timer

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/ref/utils.md

A utility class to measure the elapsed time between a start and end point.

```APIDOC
## class utils.Timer(unit='m')

Bases: `object`

Count the elapsing time between start and end.

#### __init__(unit='m')

#### start()

#### end()

```

--------------------------------

### Train Model using Config File

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/notebooks/easytpp_2_tfb_wb.ipynb

Builds and runs a model training experiment using a configuration file. Ensure 'config.yaml' exists and is correctly formatted.

```python
from easy_tpp.config_factory import Config
from easy_tpp.runner import Runner

config = Config.build_from_yaml_file('./config.yaml', experiment_id='NHP_train')

model_runner = Runner.build_from_config(config)

model_runner.run()
```

--------------------------------

### Get Stage Information with get_stage

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/ref/utils.md

Retrieves stage information based on the provided stage identifier.

```python
utils.get_stage(stage)
```

--------------------------------

### utils.is_torch_device

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/ref/utils.md

Tests if a given object is a PyTorch device. This function is safe to call even if PyTorch is not installed.

```APIDOC
## utils.is_torch_device(x)

### Description
Tests if x is a torch device or not. Safe to call even if torch is not installed.
```

--------------------------------

### Mask Sequences Example: Attention Mask

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/user_guide/dataset.md

Shows the `attention_mask` used in attention mechanisms, where each event can only attend to past events and itself.

```bash
# attention_mask
[[True,  True,  True,  True,  True,  True],
[False,  True,  True,  True,  True,  True],
[False, False,  True,  True,  True,  True],
[False, False, False,  True,  True,  True],
[False, False, False, False,  True,  True],
[False, False, False, False,  True,  True]]
```

--------------------------------

### Extract Visit Timestamps

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/notebooks/s2p2_preprocess_ehrshot_cpt4.ipynb

Filters for visit occurrences, converts start times to Unix timestamps, and aggregates timestamps per patient.

```python
df_visit = df_dataset[df_dataset['omop_table'] == 'visit_occurrence']
df_visit.loc[:, 'start'] = pd.to_datetime(df_visit['start']).apply(lambda x: int(round(x.timestamp())))
df_visit_time = df_visit[['patient_id', 'start']].drop_duplicates(keep=False)
df_visit_time = df_visit_time.groupby(['patient_id'])['start'].apply(lambda x: sorted(list(set(x)))).reset_index(name='timestamp')
visit_dict = pd.Series(df_visit_time.timestamp.values, index=df_visit_time.patient_id).to_dict()
patient_visit = df_visit_time['patient_id'].to_numpy()
```

--------------------------------

### Initialize TPPDataLoader

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/notebooks/easytpp_1_dataset.ipynb

Initializes the `Config` object by loading from the 'config.yaml' file and then creates an instance of `TPPDataLoader` using the loaded configuration. This prepares the data loading pipeline.

```python
from easy_tpp.config_factory import Config
from easy_tpp.preprocess.data_loader import TPPDataLoader


config = Config.build_from_yaml_file('./config.yaml')
tpp_loader = TPPDataLoader(config)
```

--------------------------------

### RunnerConfig from YAML and Programmatic Modification

Source: https://context7.com/ant-research/easytemporalpointprocess/llms.txt

Demonstrates building a `RunnerConfig` from a YAML file and saving/reloading it. Also shows how to programmatically copy and modify configurations, useful for hyperparameter optimization.

```python
from easy_tpp.config_factory import RunnerConfig
from easy_tpp.config_factory.model_config import BaseConfig, ModelConfig, TrainerConfig
from easy_tpp.config_factory import DataConfig
from omegaconf import OmegaConf

# Build from YAML (standard usage)
config = RunnerConfig.build_from_yaml_file(
    'configs/experiment_config.yaml',
    experiment_id='THP_train'
)

# Save / reload
config.save_to_yaml_file('/tmp/thp_train_output.yaml')
config2 = RunnerConfig.build_from_yaml_file('/tmp/thp_train_output.yaml',
                                             direct_parse=True)

# Programmatic copy + modification (useful in HPO)
config_copy = config.copy()
config_copy.trainer_config.learning_rate = 5e-4
config_copy.model_config.hidden_size = 64
```

--------------------------------

### utils.set_device

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/ref/utils.md

Sets up the computation device (CPU or GPU).

```APIDOC
## utils.set_device(gpu=-1)

### Description
Configures the device to be used for computations, defaulting to CPU.

### Parameters
#### Parameters
- **gpu** (int, optional) – The index of the GPU to use. Defaults to -1, which means CPU.

### Returns
None
```

--------------------------------

### Run Prediction Generation

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/notebooks/easytpp_3_train_eval.ipynb

Initializes the configuration and runner, then executes the prediction generation process. Ensure 'num_gen_step' is specified in the thinning configuration for multi-step predictions.

```python
from easy_tpp.config_factory import Config
from easy_tpp.runner import Runner

config = Config.build_from_yaml_file('./gen_config.yaml', experiment_id='NHP_gen')

model_runner = Runner.build_from_config(config)

model_runner.run()
```

--------------------------------

### Launch Tensorboard from Python

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/advanced/tensorboard.md

Execute this Python script to launch Tensorboard. Ensure the `log_dir` variable points to the correct Tensorboard log directory generated during training.

```python
import os

def main():
    # one can find this dir in the config out file
    log_dir = './checkpoints/NHP_train_taxi_20220527-20:18:30/tfb_train'
    os.system('tensorboard --logdir={}'.format(log_dir))
    return


if __name__ == '__main__':
    main()
```

--------------------------------

### Train Model with EasyTPP Configuration

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/README.md

Use this script to train and evaluate models. It requires a configuration YAML file and an experiment ID. Ensure the data and config directories are set up correctly.

```python
import argparse
from easy_tpp.config_factory import Config
from easy_tpp.runner import Runner

def main():
    parser = argparse.ArgumentParser()

    parser.add_argument('--config_dir', type=str, required=False, default='configs/experiment_config.yaml',
                        help='Dir of configuration yaml to train and evaluate the model.')

    parser.add_argument('--experiment_id', type=str, required=False, default='NHP_train',
                        help='Experiment id in the config file.')

    args = parser.parse_args()

    config = Config.build_from_yaml_file(args.config_dir, experiment_id=args.experiment_id)

    model_runner = Runner.build_from_config(config)

    model_runner.run()


if __name__ == '__main__':
    main()
```

--------------------------------

### Train with TensorBoard Enabled

Source: https://context7.com/ant-research/easytemporalpointprocess/llms.txt

Configure and run training with TensorBoard logging. Ensure the `tfb_train_dir` is printed during training to locate logs. Launch TensorBoard using the printed directory.

```python
config = Config.build_from_yaml_file('configs/experiment_config.yaml', experiment_id='NHP_train')
runner = Runner.build_from_config(config)
runner.run()
```

```python
tfb_train_dir = runner.runner_config.base_config.specs.get('tfb_train_dir')
print(f"TensorBoard train dir: {tfb_train_dir}")
```

```bash
tensorboard --logdir=./checkpoints/75518_4377527680_230530-132355/
```

--------------------------------

### Get Dataset Statistics

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/notebooks/easytpp_1_dataset.ipynb

Retrieves and prints statistical information for the training split of the dataset. This includes distributions of event types, sequence lengths, and timing intervals.

```python
stats = tpp_loader.get_statistics(split='train')
stats
```

--------------------------------

### Measure Time with Timer Class

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/ref/utils.md

The Timer class can be used to measure the elapsed time between starting and ending a process. Initialize with a unit ('m' for minutes by default).

```python
timer = utils.Timer(unit='s')
timer.start()
# ... some process ...
timer.end()
```

--------------------------------

### utils.set_optimizer

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/ref/utils.md

Sets up and returns a PyTorch optimizer.

```APIDOC
## utils.set_optimizer(optimizer, params, lr)

### Description
Initializes and configures a PyTorch optimizer with specified parameters and learning rate.

### Parameters
#### Parameters
- **optimizer** (str) – The name of the optimizer (e.g., 'Adam', 'SGD').
- **params** (dict) – A dictionary containing parameters for the optimizer.
- **lr** (float) – The learning rate for the optimizer.

### Raises
**NotImplementedError** – If the optimizer name is incorrect or the optimizer is not supported.

### Returns
A configured PyTorch optimizer instance.
### Return type
torch.optim
```

--------------------------------

### Mask Sequences Example: Type Mask

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/user_guide/dataset.md

Displays the `type_mask` which uses one-hot vectors to represent event types, with padded events represented by zero vectors.

```bash
# type_mask
[[False,  True, False, False, False, False, False, False, False, False, False],
[False, False, False, False, False, False, False, False, False, True, False],
[False, False, False, False, False,  True, False, False, False, False, False],
[True, False, False, False, False, False, False, False, False, False, False],
[False, False, False, False, False, False, False, False, False, False, False],
[False, False, False, False, False, False, False, False, False, False, False]],
```

--------------------------------

### Run Model Training

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/get_started/quick_start.md

Execute the model training script. This command initiates the training process using the configured data and model parameters.

```bash
python train_nhp.py
```

--------------------------------

### Multi-step Autoregressive Generation

Source: https://context7.com/ant-research/easytemporalpointprocess/llms.txt

Recursively generates a specified number of future events starting from the last observed event. Requires `num_step_gen > 1` in the thinning configuration and `stage: gen` in the base configuration.

```python
# thinning config must have num_step_gen > 1, e.g., num_step_gen: 5
model.eval()

# Returns predicted and ground-truth dtimes/types for the final num_step_gen steps
pred_dtimes, pred_types, true_dtimes, true_types = \
    model.predict_multi_step_since_last_event(batch, forward=False)

print(pred_dtimes.shape)   # [B, num_step_gen + 1]
print(pred_types.shape)    # [B, num_step_gen + 1]
```

--------------------------------

### RunnerConfig.__init__

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/ref/config.md

Initializes the RunnerConfig class with various configuration components.

```APIDOC
## RunnerConfig.__init__

### Description
Initialize the Config class.

### Parameters
#### Path Parameters
- **base_config** (EasyTPP.BaseConfig) – BaseConfig object.
- **model_config** (EasyTPP.ModelConfig) – ModelConfig object.
- **data_config** (EasyTPP.DataConfig) – DataConfig object.
- **trainer_config** (EasyTPP.TrainerConfig) – TrainerConfig object
```

--------------------------------

### List Files in Directory

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/notebooks/easytpp_2_tfb_wb.ipynb

Lists all files and directories recursively in the current directory. Useful for verifying that configuration and checkpoint files were created.

```bash
!ls -R
```

--------------------------------

### HPOConfig.__init__

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/ref/config.md

Initializes the HPOConfig class with parameters for hyperparameter optimization.

```APIDOC
## HPOConfig.__init__

### Description
Initialize the HPO Config

### Parameters
#### Path Parameters
- **framework_id** (str) – hpo framework id.
- **storage_uri** (str) – result storage dir.
- **is_continuous** (bool) – whether to continuously do the optimization.
- **num_trials** (int) – num of trails used in optimization.
- **num_jobs** (int) – num of the jobs.
```

--------------------------------

### HPORunnerConfig.__init__

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/ref/config.md

Initializes the HPORunnerConfig class with HPO and Runner configurations.

```APIDOC
## HPORunnerConfig.__init__

### Description
Initialize the config class

### Parameters
#### Path Parameters
- **hpo_config** (EasyTPP.HPOConfig) – hpo config class.
- **runner_config** (EasyTPP.RunnerConfig) – runner config class.
```

--------------------------------

### Access Dataset Object

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/notebooks/easytpp_1_dataset.ipynb

Prints the loaded dataset object to display its structure and available features. Features include sequence length, time since start, sequence index, time since last event, event type, and process dimension.

```python
dataset
```

--------------------------------

### Create Configuration File

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/notebooks/easytpp_1_dataset.ipynb

Writes YAML content to a 'config.yaml' file. This file defines parameters for data loading and preprocessing, such as data format, directory paths, and specifications for event types and padding.

```python
yaml_content = """
pipeline_config_id: data_config

data_format: json
train_dir: easytpp/taxi  # ./data/taxi/train.json
valid_dir: easytpp/taxi  # ./data/taxi/dev.json
test_dir: easytpp/taxi   # ./data/taxi/test.json
data_specs:
  num_event_types: 10
  pad_token_id: 10
  padding_side: right
"""

# Save the content to a file named config.yaml
with open("config.yaml", "w") as file:
    file.write(yaml_content)
```

--------------------------------

### Run Benchmark Script

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/README.md

Execute the benchmark script to evaluate TPPs using the Taxi dataset. Download the Taxi data and ensure the configuration file is set up before running.

```shell
cd examples
python run_retweet.py
```

--------------------------------

### Define Data Configuration for EasyTPP

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/notebooks/easytpp_3_train_eval.ipynb

Specifies data sources and formats, including training, validation, and test dataset directories. This configuration is essential for preparing the data for model training.

```python
data_config = """
data:
  taxi:
    data_format: json
    train_dir:  ./data/taxi/train.json
    valid_dir:  ./data/taxi/dev.json
    test_dir:  ./data/taxi/test.json

"""
```

--------------------------------

### Define Model Configuration for EasyTPP

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/notebooks/easytpp_3_train_eval.ipynb

Defines the model architecture, hyperparameters, and training settings. This includes base configuration for general parameters and trainer-specific configuration for detailed training options.

```python
model_config = """
NHP_train:
  base_config:
    stage: train
    backend: torch
    dataset_id: taxi
    runner_id: std_tpp
    model_id: NHP # model name
    base_dir: './checkpoints/'
  trainer_config:
    batch_size: 256
    max_epoch: 2
    shuffle: True
    optimizer: adam
    learning_rate: 1.e-3
    valid_freq: 1
    use_tfb: False
    metrics: [ 'acc', 'rmse' ]
    seed: 2019
    gpu: -1
"""
```

--------------------------------

### utils.load_yaml_config

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/ref/utils.md

Loads a YAML configuration file from disk.

```APIDOC
## utils.load_yaml_config(config_dir)

### Description
Loads configuration settings from a YAML file located at the specified path.

### Parameters
#### Parameters
- **config_dir** (str or Path) – The path to the configuration file.

### Returns
The loaded configuration as a dictionary.
### Return type
dict
```

--------------------------------

### Basic Config File Structure

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/user_guide/run_train_pipeline.md

Defines the overall structure of the configuration YAML file for the training pipeline. It includes placeholders for pipeline configuration ID, dataset details, and experiment configurations.

```yaml
pipeline_config_id: ..  # name of the config for guiding the pipeline

data:
    [Dataset ID]:  # name of the dataset, e.g, taxi
        ....

[EXPERIMENT ID]:   # name of the experiment to run
    base_config:
      ....
    model_config:
       ...
```

--------------------------------

### restore

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/ref/wrapper.md

Loads a model checkpoint from a specified directory.

```APIDOC
## restore(ckpt_dir)

### Description
Load the checkpoint to restore the model.

### Parameters
* **ckpt_dir** (*str*) – path for the checkpoint.
```

--------------------------------

### BaseConfig.copy

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/ref/config.md

Creates a copy of the current configuration object.

```APIDOC
## BaseConfig.copy

### Description
Copy the config.

### Returns
a copy of current config.

### Return type
[BaseConfig](#config_factory.BaseConfig)
```

--------------------------------

### Combine and Save EasyTPP Configuration

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/notebooks/easytpp_3_train_eval.ipynb

Combines data and model configurations into a single YAML file and saves it. This file is used to initialize the model runner for the training process.

```python
yaml_content = """
pipeline_config_id: runner_config

data:
    taxi:
        data_format: json
        train_dir: easytpp/taxi  # ./data/taxi/train.json
        valid_dir: easytpp/taxi  # ./data/taxi/dev.json
        test_dir: easytpp/taxi   # ./data/taxi/test.json
        data_specs:
          num_event_types: 10
          pad_token_id: 10
          padding_side: right


NHP_train:
  base_config:
    stage: train
    backend: torch
    dataset_id: taxi
    runner_id: std_tpp
    model_id: NHP # model name
    base_dir: './checkpoints/'
  trainer_config:
    batch_size: 256
    max_epoch: 2
    shuffle: False
    optimizer: adam
    learning_rate: 1.e-3
    valid_freq: 1
    use_tfb: True
    metrics: [ 'acc', 'rmse' ]
    seed: 2019
    gpu: -1
  model_config:
    hidden_size: 32
    loss_integral_num_sample_per_step: 20
    thinning:
      num_seq: 10
      num_sample: 1
      num_exp: 500 # number of i.i.d. Exp(intensity_bound) draws at one time in thinning algorithm
      look_ahead_time: 10
      patience_counter: 5 # the maximum iteration used in adaptive thinning
      over_sample_rate: 5
      num_samples_boundary: 5
      dtime_max: 5
      num_step_gen: 1
"""

# Save the content to a file named config.yaml
with open("config.yaml", "w") as file:
    file.write(yaml_content)
```

--------------------------------

### Running Optuna Hyperparameter Optimization

Source: https://context7.com/ant-research/easytemporalpointprocess/llms.txt

Loads an HPO configuration and initializes an `HyperTuner` object to run the optimization process. It returns the best metric and the corresponding `RunnerConfig`.

```python
from easy_tpp.config_factory import Config
from easy_tpp.hpo import HyperTuner

# Load HPO config
config = Config.build_from_yaml_file('configs/hpo_config.yaml', experiment_id='NHP_train')

# Build the Optuna tuner
tuner = HyperTuner.build_from_config(config, trial_end_callbacks=[])

# Run HPO; returns best metric and best RunnerConfig
best_metric, best_runner_config = tuner.run()
print(f"Best RMSE: {best_metric:.4f}")
print(f"Best hidden_size: {best_runner_config.model_config.hidden_size}")
print(f"Best lr: {best_runner_config.trainer_config.learning_rate}")
```

--------------------------------

### Configure JSON Data Loading (HuggingFace)

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/notebooks/easytpp_1_dataset.ipynb

Recommended configuration for loading taxi dataset in JSON format from HuggingFace. Replace pickle paths with HuggingFace repository names.

```yaml
data:
  taxi:
    data_format: json
    train_dir:  easytpp/taxi
    valid_dir:  easytpp/taxi
    test_dir:  easytpp/taxi
```

--------------------------------

### Configure JSON Data Loading (Local)

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/notebooks/easytpp_1_dataset.ipynb

Alternative configuration for loading JSON data files from a local directory. Specify the paths to your local JSON files.

```yaml
data:
  taxi:
    data_format: json
    train_dir:  ./data/taxi/train.json
    valid_dir:  ./data/taxi/dev.json
    test_dir:  ./data/taxi/test.json
```

--------------------------------

### Config Class Methods

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/ref/config.md

Provides methods for saving, loading, and manipulating configuration objects.

```APIDOC
## class config_factory.Config

### save_to_yaml_file(config_dir)

Save the config into the yaml file ‘config_dir’.

* **Parameters:**
  **config_dir** (*str*) – Target filename.

### build_from_yaml_file(yaml_dir, **kwargs)

Load yaml config file from disk.

* **Parameters:**
  **yaml_dir** (*str*) – Path of the yaml config file.
* **Returns:**
  Config object corresponding to cls.
* **Return type:**
  EasyTPP.Config

### get_yaml_config()

Get the yaml format config from self.

### parse_from_yaml_config(yaml_config)

Parse from the yaml to generate the config object.

* **Parameters:**
  **yaml_config** (*dict*) – configs from yaml file.
* **Returns:**
  Config class for data.
* **Return type:**
  EasyTPP.Config

### copy()

Get a same and freely modifiable copy of self.

### update(config)

Update the config.

* **Parameters:**
  **config** (*dict*) – config dict.
* **Returns:**
  Config class for data.
* **Return type:**
  EasyTPP.Config

### pop(key: str, default_var: Any)

pop out the key-value item from the config.

* **Parameters:**
  * **key** (*str*) – key name.
  * **default_var** (*Any*) – default value to pop.
* **Returns:**
  value to pop.
* **Return type:**
  Any

### get(key: str, default_var: Any)

Retrieve the key-value item from the config.

* **Parameters:**
  * **key** (*str*) – key name.
  * **default_var** (*Any*) – default value to pop.
* **Returns:**
  value to get.
* **Return type:**
  Any

### set(key: str, var_to_set: Any)

Set the key-value item from the config.

* **Parameters:**
  * **key** (*str*) – key name.
  * **var_to_set** (*Any*) – default value to pop.
* **Returns:**
  value to get.
* **Return type:**
  Any
```

--------------------------------

### utils.make_config_string

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/ref/utils.md

Generate a name for config files based on a configuration dictionary.

```APIDOC
## utils.make_config_string(config, max_num_key=4)

### Description
Generates a string representation of a configuration dictionary, useful for naming config files.

### Parameters
#### Parameters
- **config** (dict) – The configuration dictionary.
- **max_num_key** (int, optional) – The maximum number of keys to include in the generated string. Defaults to 4.

### Returns
A concatenated string derived from the config dictionary.
```

--------------------------------

### Runner.build_from_config

Source: https://context7.com/ant-research/easytemporalpointprocess/llms.txt

Instantiates a pipeline runner from a configuration object. It looks up the registered runner class specified by `runner_config.base_config.runner_id`, instantiates it, builds data loaders, and initializes the model.

```APIDOC
## Runner.build_from_config — Instantiate a pipeline runner from config

`Runner.build_from_config` looks up the registered runner class specified by `runner_config.base_config.runner_id` (e.g., `std_tpp`), instantiates it with the config, builds the data loaders, and initializes the model. The `unique_model_dir` flag appends a random suffix to the checkpoint directory to avoid collisions, which is useful in parallel HPO trials.

```python
from easy_tpp.config_factory import Config
from easy_tpp.runner import Runner

config = Config.build_from_yaml_file(
    'configs/experiment_config.yaml',
    experiment_id='NHP_train'
)

# Build the standard TPP runner (std_tpp)
runner = Runner.build_from_config(config)

# Inspect internals
print(runner.runner_config.base_config.model_id)   # 'NHP'
print(runner.get_model_dir())                       # './checkpoints/<id>/models/saved_model'
```
```

--------------------------------

### Instantiate Pipeline Runner from Config

Source: https://context7.com/ant-research/easytemporalpointprocess/llms.txt

Use `Runner.build_from_config` to create a pipeline runner instance based on the provided configuration. This method initializes the runner, data loaders, and model.

```python
from easy_tpp.config_factory import Config
from easy_tpp.runner import Runner

config = Config.build_from_yaml_file(
    'configs/experiment_config.yaml',
    experiment_id='NHP_train'
)

# Build the standard TPP runner (std_tpp)
runner = Runner.build_from_config(config)

# Inspect internals
print(runner.runner_config.base_config.model_id)   # 'NHP'
print(runner.get_model_dir())                       # './checkpoints/<id>/models/saved_model'
```

--------------------------------

### Instantiate TPP Model from Configuration

Source: https://context7.com/ant-research/easytemporalpointprocess/llms.txt

Use the factory method `generate_model_from_config` to create model instances based on a configuration object. This method matches `model_config.model_id` to a registered `TorchBaseModel` subclass.

```python
from easy_tpp.config_factory import Config
from easy_tpp.model.torch_model.torch_basemodel import TorchBaseModel

config = Config.build_from_yaml_file('configs/experiment_config.yaml', experiment_id='SAHP_train')

# Directly instantiate the model from config
model = TorchBaseModel.generate_model_from_config(config.model_config)
print(type(model).__name__)   # 'SAHP'
print(model.hidden_size)      # 32
print(model.num_event_types)  # dataset-dependent, e.g. 10
```

--------------------------------

### Create and Activate Conda Environment

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/get_started/install.md

Create a new Conda environment named 'easytpp' with Python 3.8 and activate it. Ensure your Python version is at least 3.7.0.

```bash
conda create -n easytpp python=3.8
conda activate easytpp
```

--------------------------------

### Configure Pipeline for Tensorboard/W&B

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/notebooks/easytpp_2_tfb_wb.ipynb

This configuration snippet enables Tensorboard and W&B by setting 'use_tfb' to True in the trainer configuration. Ensure your data and model parameters are correctly defined.

```yaml
pipeline_config_id: runner_config

data:
    taxi:
        data_format: json
        train_dir: easytpp/taxi  # ./data/taxi/train.json
        valid_dir: easytpp/taxi  # ./data/taxi/dev.json
        test_dir: easytpp/taxi   # ./data/taxi/test.json
        data_specs:
          num_event_types: 10
          pad_token_id: 10
          padding_side: right


NHP_train:
  base_config:
    stage: train
    backend: torch
    dataset_id: taxi
    runner_id: std_tpp
    model_id: NHP # model name
    base_dir: './checkpoints/'
  trainer_config:
    batch_size: 256
    max_epoch: 2
    shuffle: False
    optimizer: adam
    learning_rate: 1.e-3
    valid_freq: 1
    use_tfb: True
    metrics: [ 'acc', 'rmse' ]
    seed: 2019
    gpu: -1
  model_config:
    hidden_size: 32
    loss_integral_num_sample_per_step: 20
    thinning:
      num_seq: 10
      num_sample: 1
      num_exp: 500 # number of i.i.d. Exp(intensity_bound) draws at one time in thinning algorithm
      look_ahead_time: 10
      patience_counter: 5 # the maximum iteration used in adaptive thinning
      over_sample_rate: 5
      num_samples_boundary: 5
      dtime_max: 5
      num_step_gen: 1

```

--------------------------------

### utils.DefaultRunnerConfig

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/ref/utils.md

Configuration class for default runner settings.

```APIDOC
## class utils.DefaultRunnerConfig

Bases: `object`

#### DEFAULT_DATASET_ID *= 'conttime'*

```

--------------------------------

### Activate Tensorboard in Config

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/advanced/tensorboard.md

Set `use_tfb` to `True` in the `trainer_config` section of your `model_config.yaml` file to enable Tensorboard logging.

```yaml
NHP_train:
  base_config:
    stage: train
    backend: torch
    dataset_id: taxi
    runner_id: std_tpp
    model_id: NHP # model name
    base_dir: './checkpoints/'
  trainer_config:
    batch_size: 256
    max_epoch: 200
    shuffle: False
    optimizer: adam
    learning_rate: 1.e-3
    valid_freq: 1
    use_tfb: True  # Activate the tensorboard
    metrics: [ 'acc', 'rmse' ]
    seed: 2019
    gpu: -1
  model_config:
    hidden_size: 64
    loss_integral_num_sample_per_step: 20
#    pretrained_model_dir: ./checkpoints/75518_4377527680_230530-132355/models/saved_model
    thinning:
      num_seq: 10
      num_sample: 1
      num_exp: 500 # number of i.i.d. Exp(intensity_bound) draws at one time in thinning algorithm
      look_ahead_time: 10
      patience_counter: 5 # the maximum iteration used in adaptive thinning
      over_sample_rate: 5
      num_samples_boundary: 5
      dtime_max: 5
      num_step_gen: 1
```

--------------------------------

### Evaluation Configuration

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/user_guide/run_eval.md

Configure the evaluation task by setting the stage to 'eval' and providing the path to the pretrained model directory. Ensure all necessary parameters for the model and trainer are specified.

```yaml
NHP_eval:
  base_config:
    stage: eval
    backend: torch
    dataset_id: taxi
    runner_id: std_tpp
    base_dir: './checkpoints/'
    model_id: NHP
  trainer_config:
    batch_size: 256
    max_epoch: 1
  model_config:
    hidden_size: 64
    use_ln: False
    seed: 2019
    gpu: 0
    pretrained_model_dir: ./checkpoints/26507_4380788096_231111-101848/models/saved_model  # must provide this dir
    thinning:
      num_seq: 10
      num_sample: 1
      num_exp: 500 # number of i.i.d. Exp(intensity_bound) draws at one time in thinning algorithm
      look_ahead_time: 10
      patience_counter: 5 # the maximum iteration used in adaptive thinning
      over_sample_rate: 5
      num_samples_boundary: 5
      dtime_max: 5
```

--------------------------------

### Run Model Evaluation with EasyTPP Runner

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/notebooks/easytpp_3_train_eval.ipynb

Execute the evaluation using the EasyTPP Runner API. This script loads the configuration from 'eval_config.yaml', builds the model runner, and initiates the evaluation process.

```python
from easy_tpp.config_factory import Config
from easy_tpp.runner import Runner

config = Config.build_from_yaml_file('./eval_config.yaml', experiment_id='NHP_eval')

model_runner = Runner.build_from_config(config)

model_runner.run()
```

--------------------------------

### utils.create_folder

Source: https://github.com/ant-research/easytemporalpointprocess/blob/main/docs/source/ref/utils.md

Creates a directory path if it does not already exist.

```APIDOC
## utils.create_folder(*args)

### Description
Creates the specified directory path if it does not exist.

### Returns
The path of the created folder.
### Return type
str
```