### Mogptk Examples

Source: https://github.com/games-uchile/mogptk/blob/master/docs/examples.html

A collection of examples showcasing practical applications of the Mogptk library.

```APIDOC
## Mogptk Examples

### Description
This section provides a variety of practical examples demonstrating the use of the Mogptk library for different real-world scenarios and datasets.

### Example Datasets and Applications
- **Airline passengers**: Time series forecasting using airline passenger data.
- **Mauna Loa**: Analysis of CO2 concentration data from Mauna Loa.
- **Currencies**: Financial time series analysis, specifically currency exchange rates.
- **Financial**: Analysis of financial market data (e.g., gold, oil, NASDAQ, USD).
- **HAR**: Human Activity Recognition using sensor data.
- **Bramblemet**: Example using Bramblemet dataset.
- **EEG**: Analysis of Electroencephalogram (EEG) data.
```

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

### Mogptk Tutorials

Source: https://github.com/games-uchile/mogptk/blob/master/docs/examples.html

Provides a list of tutorials to guide users through various aspects of the Mogptk library.

```APIDOC
## Mogptk Tutorials

### Description
This section offers a series of tutorials designed to help users learn and effectively utilize the Mogptk library, starting from basic concepts to advanced features.

### Tutorials List
- **00 Quick Start**: An introductory guide to get started quickly.
- **01 Data Loading**: Learn how to load and prepare your data.
- **02 Data Preparation**: Covers essential data preprocessing steps.
- **03 Parameter Initialization**: Explains different methods for parameter initialization.
- **04 Model Training**: Guides through the process of training Mogptk models.
- **05 Error Metrics**: Details how to evaluate model performance using error metrics.
- **06 Custom Kernels and Mean Functions**: Demonstrates how to implement custom kernels and mean functions.
- **07 Sparse Multi Input**: Covers advanced techniques for sparse multi-input models.
- **08 Multi Likelihood Classification**: Explains multi-likelihood classification with Mogptk.
```

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

### GET /kernel/squared-exponential

Source: https://github.com/games-uchile/mogptk/blob/master/docs/examples/07_Sparse_Multi_Input.html

Retrieves the configuration and constraints for the Squared Exponential Kernel.

```APIDOC
## GET /kernel/squared-exponential

### Description
Returns the current magnitude and lengthscale parameters for the Squared Exponential Kernel.

### Method
GET

### Endpoint
/kernel/squared-exponential

### Parameters
None

### Response
#### Success Response (200)
- **magnitude** (float) - The amplitude of the kernel, constrained to [1e-08, ∞).
- **lengthscale** (array) - The lengthscale vector for the kernel, constrained to [1e-08, ∞).

#### Response Example
{
  "magnitude": 0.6950430635209098,
  "lengthscale": [0.25490734, 1.37001037, 0.4815968, 1.05024199, 0.54478095, 0.22171077, 0.88567226]
}
```

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

### GET /likelihood/gaussian

Source: https://github.com/games-uchile/mogptk/blob/master/docs/examples/07_Sparse_Multi_Input.html

Retrieves the configuration for the Gaussian Likelihood scale parameter.

```APIDOC
## GET /likelihood/gaussian

### Description
Returns the current scale parameter for the Gaussian Likelihood.

### Method
GET

### Endpoint
/likelihood/gaussian

### Parameters
None

### Response
#### Success Response (200)
- **scale** (float) - The noise scale of the likelihood, constrained to [1e-08, ∞).

#### Response Example
{
  "scale": 0.15417401196401354
}
```

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

### Install MOGPTK via pip

Source: https://github.com/games-uchile/mogptk/blob/master/docs/index.html

Command to install the MOGPTK library. Requires Python 3.6 or higher.

```bash
pip install mogptk
```

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

### Initialize and Train Multi-Output Spectral Mixture (MOSM) Model

Source: https://github.com/games-uchile/mogptk/blob/master/examples/05_Error_Metrics.ipynb

Demonstrates the setup of a MOSM model by initializing parameters with BNSE and training the model using specified optimization parameters.

```python
mosm = mogptk.MOSM(dataset, Q=4)
mosm.init_parameters('BNSE')
mosm.train(method=method, lr=lr, iters=iters, verbose=True, error='MAE', plot=True)
mosm.plot_prediction(title='MOSM on Air Quality Data');
```

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

### Get Training Data (Transformed) - Python

Source: https://github.com/games-uchile/mogptk/blob/master/docs/dataset.html

Retrieves the data specifically used for training across all channels, with an option to get transformed data. Returns X and Y data lists.

```python
return [channel.get_train_data(transformed=transformed)[0] for channel in self.channels], [channel.get_train_data(transformed=transformed)[1] for channel in self.channels]
```

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

### Initialize MOGPTK DataSet

Source: https://github.com/games-uchile/mogptk/blob/master/docs/dataset.html

Demonstrates various ways to instantiate a DataSet object, including passing individual Data objects, using lists, or providing raw X and Y arrays.

```python
import mogptk

# Initialize with Data objects
wind_velocity = mogptk.LoadDataFrame(df, x_col='Date', y_col='Wind Velocity', name='wind')
tidal_height = mogptk.LoadDataFrame(df, x_col='Date', y_col='Tidal Height', name='tidal')
dataset = mogptk.DataSet(wind_velocity, tidal_height)

# Initialize with raw arrays
dataset = mogptk.DataSet(x, [y1, y2, y3], names=['A', 'B', 'C'])

# Accessing channels
first_channel = dataset[0]
named_channel = dataset['wind']
```

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

### Iterate and Get Length of DataSet Channels

Source: https://github.com/games-uchile/mogptk/blob/master/docs/dataset.html

Provides standard Python iteration and length checking for a DataSet. Allows looping through the channels and getting the total number of channels using `len()`.

```python
def __iter__(self):
    return self.channels.__iter__()

def __len__(self):
    return len(self.channels)
```

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

### Remove Observations in a Range (Python)

Source: https://github.com/games-uchile/mogptk/blob/master/docs/data.html

Removes observations that fall within a specified interval [start, end] for a given dimension. If no dimension is specified, it applies to all input dimensions. It handles date strings and numerical values for start and end points.

```python
def remove_range(self, start=None, end=None, dim=None):
            """
            Removes observations in the interval `[start,end]`.
            
            Args:
                start (float, str): Start of interval (inclusive). Defaults to the first value in observations.
                end (float, str): End of interval (inclusive). Defaults to the last value in observations.
                dim (int): Input dimension to apply to, if not specified applies to all input dimensions.
    
            Examples:
                >>> data = mogptk.LoadFunction(lambda x: np.sin(3*x[:,0]), 0, 10, n=200, var=0.1, name='Sine wave')
                >>> data.remove_range(3, 8)
            
                >>> data = mogptk.LoadCSV('gold.csv', 'Date', 'Price')
                >>> data.remove_range('2016-01-15', '2016-06-15')
            """
            if start is None:
                start = [np.min(self.X[:,i]) for i in range(self.get_input_dims())]
            if end is None:
                end = [np.max(self.X[:,i]) for i in range(self.get_input_dims())]
    
            start = self._normalize_x_val(start)
            end = self._normalize_x_val(end)
    
            if dim is not None:
                mask = np.logical_and(self.X[:,dim] >= start[dim], self.X[:,dim] <= end[dim])
                self._add_range(start[dim], end[dim], dim)
            else:
                mask = np.logical_and(self.X[:,0] >= start[0], self.X[:,0] <= end[0])
                for i in range(1,self.get_input_dims()):
                    mask = np.logical_or(mask, np.logical_and(self.X[:,i] >= start[i], self.X[:,i] <= end[i]))
                for i in range(self.get_input_dims()):
                    self._add_range(start[i], end[i], i)
            self.mask[mask] = False
```

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

### Initialize and Train a CONV Model

Source: https://github.com/games-uchile/mogptk/blob/master/docs/models/conv.html

Demonstrates how to instantiate a CONV model with a dataset, initialize its parameters using default settings, and perform training and prediction.

```python
import numpy as np
import mogptk

t = np.linspace(0, 10, 100)
y1 = np.sin(0.5 * t)
y2 = 2.0 * np.sin(0.2 * t)

dataset = mogptk.DataSet(t, [y1, y2])
model = mogptk.CONV(dataset, Q=2)
model.init_parameters()
model.train()
model.predict()
dataset.plot()
```

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

### GET /dataset/names

Source: https://github.com/games-uchile/mogptk/blob/master/docs/dataset.html

Retrieves the names of all channels in the dataset.

```APIDOC
## GET /dataset/names

### Description
Return the names of the channels.

### Method
GET

### Endpoint
/dataset/names

### Response
#### Success Response (200)
- **names** (list) - List of channel names.

#### Response Example
{
  "names": ["A", "B", "C"]
}
```

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

### MOSM Kernel Initialization and Usage (Python)

Source: https://github.com/games-uchile/mogptk/blob/master/docs/models/mosm.html

Example demonstrating the initialization, parameter initialization, training, and prediction using the Multi-Output Spectral Mixture (MOSM) kernel. This code snippet requires numpy and mogptk libraries. It sets up a dataset, creates an MOSM model, optimizes its parameters, and then performs predictions.

```python
import numpy as np
import mogptk

t = np.linspace(0, 10, 100)
y1 = np.sin(0.5 * t)
y2 = 2.0 * np.sin(0.2 * t)

dataset = mogptk.DataSet(t, [y1, y2])
model = mogptk.MOSM(dataset, Q=2)
model.init_parameters()
model.train()
model.predict()
dataset.plot()
```

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

### Apply Parameter Initialization and Train Model

Source: https://github.com/games-uchile/mogptk/blob/master/examples/03_Parameter_Initialization.ipynb

Demonstrates how to apply heuristic initialization (e.g., Lomb-Scargle) to a spectral mixture model and execute the training process. This improves the starting point for optimization compared to random parameter sampling.

```python
model.init_parameters(method='LS')
model.print_parameters()
model.train(iters=100, lr=0.2, verbose=True)
model.plot_prediction(title='Prediction with trained model')
```

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

### Filter DataSet by Range (Python)

Source: https://github.com/games-uchile/mogptk/blob/master/docs/dataset.html

Filters the data within each channel to include only the range between 'start' and 'end' on the X axis. The 'start' and 'end' arguments can be floats, strings (for dates), or lists. An optional 'dim' argument can specify the input dimension to apply the filter to.

```python
def filter(self, start, end, dim=None):
    """
    Filter the data range to be between `start` and `end` in the X axis.

    Args:
        start (float, str, list): Start of interval.
        end (float, str, list): End of interval.
        dim (int): Input dimension to apply to, if not specified applies to all input dimensions.

    Examples:
        >>> dataset.filter(3, 8)

        >>> dataset.filter('2016-01-15', '2016-06-15')
    """
    for channel in self.channels:
        channel.filter(start, end, dim=dim)
```

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

### GET /get_input_dims

Source: https://github.com/games-uchile/mogptk/blob/master/docs/data.html

Returns the number of input dimensions for the dataset.

```APIDOC
## GET /get_input_dims

### Description
Returns the number of input dimensions.

### Method
GET

### Endpoint
/get_input_dims

### Response
#### Success Response (200)
- **input_dims** (int) - Number of input dimensions.

### Response Example
```json
{
  "input_dims": 2
}
```
```

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

### Initialize MOGPTK Environment

Source: https://github.com/games-uchile/mogptk/blob/master/examples/example_airquality_changepoint.ipynb

Imports necessary libraries and modules for Gaussian Process regression and data handling.

```python
import numpy as np
import pandas as pd
import matplotlib.pyplot as plt
from mogptk.gpr.kernel import MultiOutputKernel, ChangePointsKernel
from mogptk.gpr.singleoutput import SquaredExponentialKernel, LocallyPeriodicKernel, LinearKernel
from mogptk import Data, Model, Exact, Hensman, Titsias, LoadDataFrame, Model, TransformDetrend, TransformStandard
from mogptk.gpr.likelihood import LaplaceLikelihood, GaussianLikelihood, StudentTLikelihood
from mogptk.gpr import ConstantMean, LinearMean
np.random.seed(1410)
```

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

### GET /dataset/input_dims

Source: https://github.com/games-uchile/mogptk/blob/master/docs/dataset.html

Returns the input dimensions for each channel in the dataset.

```APIDOC
## GET /dataset/input_dims

### Description
Return the input dimensions per channel.

### Method
GET

### Endpoint
/dataset/input_dims

### Response
#### Success Response (200)
- **dimensions** (list) - List of the number of input dimensions per channel.

#### Response Example
{
  "dimensions": [2, 1]
}
```

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

### Initialize Mogptk Models

Source: https://github.com/games-uchile/mogptk/blob/master/examples/00_Quick_Start.ipynb

Demonstrates initializing different types of Mogptk models (CSM, SM_LMC, CONV) with a dataset and a specified number of components (Q). It also shows how to initialize the model parameters using the LombScargle method.

```python
model = mogptk.CSM(dataset, Q=2)
# model = mogptk.SM_LMC(dataset, Q=2)
# model = mogptk.CONV(dataset, Q=2)

# initialize parameters of kernel using LombScargle
model.init_parameters(method='LS', iters=500)
```

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

### GET /dataset/nyquist

Source: https://github.com/games-uchile/mogptk/blob/master/docs/dataset.html

Estimates the Nyquist frequency for each channel in the dataset.

```APIDOC
## GET /dataset/nyquist

### Description
Estimates the Nyquist frequency by taking 0.5/(minimum distance of points) per channel.

### Method
GET

### Endpoint
/dataset/nyquist

### Response
#### Success Response (200)
- **frequencies** (list) - Nyquist frequency array of shape (input_dims) per channel.

#### Response Example
{
  "frequencies": [[0.5, 0.5], [0.2, 0.2]]
}
```

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

### Initialize and Train Cross-Spectral Mixture (CSM) Model

Source: https://github.com/games-uchile/mogptk/blob/master/examples/05_Error_Metrics.ipynb

Demonstrates the setup of a CSM model by initializing parameters and training the model using specified optimization parameters.

```python
csm = mogptk.CSM(dataset, Q=4)
csm.init_parameters()
csm.train(method=method, lr=lr, iters=iters, verbose=True, error='MAE', plot=True)
csm.plot_prediction(title='CSM on Air Quality Data');
```

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

### Filter Data by X-axis Range - Python

Source: https://github.com/games-uchile/mogptk/blob/master/docs/data.html

Filters the dataset to include only data points where the X-axis values fall within a specified range [start, end). The `start` and `end` parameters can be numerical or datetime strings. Filtering can be applied to a specific input dimension or all dimensions.

```python
def filter(self, start, end, dim=None):
            """
            Filter the data range to be between `start` and `end` in the X axis.
    
            Args:
                start (float, str, list): Start of interval.
                end (float, str, list): End of interval (not included).
                dim (int): Input dimension to apply to, if not specified applies to all input dimensions.
    
            Examples:
                >>> data.filter(3, 8)
            
                >>> data.filter('2016-01-15', '2016-06-15')
            """
            start = self._normalize_x_val(start)
            end = self._normalize_x_val(end)
            
            if dim is not None:
                ind = np.logical_and(self.X[:,dim] >= start[dim], self.X[:,dim] < end[dim])
            else:
                ind = np.logical_and(self.X[:,0] >= start[0], self.X[:,0] < end[0])
                for i in range(1,self.get_input_dims()):
                    ind = np.logical_and(ind, np.logical_and(self.X[:,i] >= start[i], self.X[:,i] < end[i]))
    
            self.X = self.X[ind,:]
            self.Y = self.Y[ind]
            if self.Y_err is not None:
                self.Y_err = self.Y_err[ind]
            self.mask = self.mask[ind]
```

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

### Initialize and Populate MOGPTK DataSet

Source: https://github.com/games-uchile/mogptk/blob/master/docs/dataset.html

Demonstrates various ways to instantiate a DataSet object, including passing multiple Data objects, using LoadDataFrame, or providing raw numpy arrays for X and Y data.

```python
wind_velocity = mogptk.LoadDataFrame(df, x_col='Date', y_col='Wind Velocity', name='wind')
tidal_height = mogptk.LoadDataFrame(df, x_col='Date', y_col='Tidal Height', name='tidal')
dataset = mogptk.DataSet(wind_velocity, tidal_height)

# Alternative: Append after initialization
dataset = mogptk.DataSet()
dataset.append(wind_velocity)
dataset.append(tidal_height)

# Alternative: Using raw arrays
dataset = mogptk.DataSet(x, [y1, y2, y3], names=['A', 'B', 'C'])
```

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

### Initialize MOGPTK Data and Model

Source: https://github.com/games-uchile/mogptk/blob/master/examples/03_Parameter_Initialization.ipynb

Sets up the MOGPTK environment, generates synthetic signal data, and initializes a Spectral Mixture (SM) model. This provides the foundation for comparing random initialization versus heuristic-based initialization.

```python
import mogptk
import torch
import numpy as np

torch.manual_seed(1)
n_points = 500
frequencies = [0.2, 1.0, 2.0]
amplitudes = [1.0, 0.5, 0.5]
t = np.linspace(0.0, 20.0, n_points)
y = np.zeros(n_points)
for i in range(3):
    y += amplitudes[i] * np.sin(2.0*np.pi * frequencies[i] * t)
y += np.random.normal(scale=0.4, size=n_points)

data = mogptk.Data(t, y)
data.remove_range(start=10.0)
model = mogptk.SM(data, Q=3)
```

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

### GET /model/parameters

Source: https://github.com/games-uchile/mogptk/blob/master/docs/model.html

Prints the current parameters of the model in a formatted table.

```APIDOC
## GET /model/parameters

### Description
Displays the model's internal parameters in a table format for inspection.

### Method
GET

### Endpoint
/model/parameters

### Response
#### Success Response (200)
- **output** (string) - Table representation of model parameters.
```

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

### Initialize MOGPTK Environment

Source: https://github.com/games-uchile/mogptk/blob/master/examples/00_Quick_Start.ipynb

Sets up the necessary library imports and configures the random seed for reproducibility in MOGPTK workflows.

```python
import numpy as np
import torch
import mogptk

torch.manual_seed(1);
```

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

### GET /model/plot_gram

Source: https://github.com/games-uchile/mogptk/blob/master/docs/model.html

Generates a visualization of the gram matrix for the associated kernel.

```APIDOC
## GET /model/plot_gram

### Description
Plots the gram matrix of the associated kernel for the specified interval.

### Method
GET

### Parameters
#### Query Parameters
- **start** (float/list/array) - Optional - Interval minimum.
- **end** (float/list/array) - Optional - Interval maximum.
- **n** (int) - Optional - Number of points per channel.
- **title** (str) - Optional - Figure title.
- **figsize** (tuple) - Optional - Figure size.

### Response
#### Success Response (200)
- **figure** (matplotlib.figure.Figure) - The generated plot figure.
- **axis** (matplotlib.axes.Axes) - The axis object for the plot.
```

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

### Initialize MOGPTK Kernel Parameters

Source: https://github.com/games-uchile/mogptk/blob/master/docs/models/mohsm.html

This method initializes kernel parameters using BNSE, LS, or SM methods. It validates the chosen method, performs spectral estimation, and assigns the resulting weights, means, and variances to the Gaussian process kernel.

```python
def init_parameters(self, method='BNSE', iters=500):
    input_dims = self.dataset.get_input_dims()
    output_dims = self.dataset.get_output_dims()
    if not method.lower() in ['bnse', 'ls', 'sm']:
        raise ValueError("valid methods of estimation are BNSE, LS, and SM")
    for p in range(self.P):
        for q in range(self.Q):
            if self.P!=1:
                self.gpr.kernel[p*self.Q+q].center.assign((1000*p/(self.P-1))*np.ones(input_dims[0]))
                self.gpr.kernel[p*self.Q+q].lengthscale.assign(((self.P+1)/1000)*np.ones(output_dims))
        if method.lower() == 'bnse':
            amplitudes, means, variances = self.dataset.get_bnse_estimation(self.Q, iters=iters)
        elif method.lower() == 'ls':
            amplitudes, means, variances = self.dataset.get_ls_estimation(self.Q)
        else:
            amplitudes, means, variances = self.dataset.get_sm_estimation(self.Q, iters=iters)
        if len(amplitudes) == 0:
            logger.warning('{} could not find peaks for MOHSM'.format(method))
            return
        weight = np.zeros((output_dims, self.Q))
        for q in range(self.Q):
            mean = np.zeros((output_dims,input_dims[0]))
            variance = np.zeros((output_dims,input_dims[0]))
            for j in range(output_dims):
                if q < amplitudes[j].shape[0]:
                    weight[j,q] = amplitudes[j][q,:].mean()
                    mean[j,:] = means[j][q,:]
                    variance[j,:] = variances[j][q,:] * (4 + 20 * (max(input_dims) - 1))
            self.gpr.kernel[p*self.Q+q].mean.assign(mean)
            self.gpr.kernel[p*self.Q+q].variance.assign(variance)
```

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

### GET /model/plot_correlation

Source: https://github.com/games-uchile/mogptk/blob/master/docs/model.html

Generates a visualization of the correlation matrix between model channels.

```APIDOC
## GET /model/plot_correlation

### Description
Plots the correlation matrix between each channel in the dataset.

### Method
GET

### Parameters
#### Query Parameters
- **title** (str) - Optional - Figure title.
- **figsize** (tuple) - Optional - Figure size (default: (12, 12)).

### Response
#### Success Response (200)
- **figure** (matplotlib.figure.Figure) - The generated plot figure.
- **axis** (matplotlib.axes.Axes) - The axis object for the plot.
```

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

### Initialize Model and Kernels

Source: https://github.com/games-uchile/mogptk/blob/master/examples/06_Custom_Kernels_and_Mean_Functions.ipynb

Sets up the model with a custom mean function and an IndependentMultiOutputKernel.

```python
mean = Mean()
kernel = mogptk.gpr.PeriodicKernel(input_dims=1)
mo_kernel = mogptk.gpr.IndependentMultiOutputKernel(kernel)
model = mogptk.Model(data, mo_kernel, mean=mean, name="Periodic")

kernel.lengthscale.assign(1.0)
kernel.period.assign(1.0)
```

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

### GET /model/parameters

Source: https://github.com/games-uchile/mogptk/blob/master/docs/model.html

Retrieves all parameters associated with the model's kernel.

```APIDOC
## GET /model/parameters

### Description
Returns a list of all parameters of the kernel currently used by the model.

### Method
GET

### Endpoint
/model/parameters

### Response
#### Success Response (200)
- **parameters** (list) - A list of mogptk.gpr.parameter.Parameter objects.

#### Response Example
{
  "parameters": ["param1", "param2"]
}
```

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

### Initialize MultiOutputSpectralKernel

Source: https://github.com/games-uchile/mogptk/blob/master/docs/gpr/multioutput.html

This snippet demonstrates how to define the MultiOutputSpectralKernel class and integrate it into a MixtureKernel for multi-output Gaussian process modeling.

```python
from mogptk.gpr import MultiOutputSpectralKernel, MixtureKernel

# Initialize the spectral kernel
mosm = MultiOutputSpectralKernel(output_dims=2, input_dims=1)

# Wrap in a MixtureKernel
mixture = MixtureKernel(mosm, Q=3)
```

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

### GET /data/train

Source: https://github.com/games-uchile/mogptk/blob/master/examples/01_Data_Loading.ipynb

Retrieves the training dataset, optionally applying transformations.

```APIDOC
## GET /data/train

### Description
Retrieves the X and Y training data. Can return raw or transformed data.

### Method
GET

### Endpoint
data.get_train_data(transformed=False)

### Parameters
#### Query Parameters
- **transformed** (boolean) - Optional - If true, returns data with transformations applied for improved training results.

### Response
#### Success Response (200)
- **data** (tuple) - A tuple containing arrays of X and Y training data.

#### Response Example
([array([[12487.]]), array([[12487.]])], [array([2.6, 2.0]), array([1360., 1292.])])
```

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

### GET /data/names

Source: https://github.com/games-uchile/mogptk/blob/master/examples/01_Data_Loading.ipynb

Retrieves the list of available channel names in the dataset.

```APIDOC
## GET /data/names

### Description
Returns a list of strings representing the names of all channels available in the data object.

### Method
GET

### Endpoint
data.get_names()

### Response
#### Success Response (200)
- **names** (array) - List of channel name strings.

#### Response Example
["CO(GT)", "PT08.S1(CO)", "NMHC(GT)"]
```

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

### PeriodicKernel Initialization and Kernel Computation (Python)

Source: https://github.com/games-uchile/mogptk/blob/master/docs/gpr/singleoutput.html

This snippet shows the Python implementation of the PeriodicKernel class. It includes the constructor (__init__) which initializes the kernel's parameters (magnitude, period, lengthscale, cross_lengthscale) based on the provided order, input dimensions, and active dimensions. It also includes the K method, which computes the kernel matrix between two input sets X1 and X2, incorporating the periodic nature and different lengthscale configurations.

```Python
class PeriodicKernel(Kernel):
    """
    A periodic kernel given by

    $$ K(x,x') = \sigma^2 \exp\left(-\frac{2\sin^2(\pi \tau / p)}{l^2}\right) $$

    with \(\tau = |x-x'|\), \(M = LL^T + \mathrm{diag}(l)^{-2}\), \(\sigma^2\) the magnitude, \(p\) the period parameter, \(l\) the lengthscale, and \(LL^T\) the cross lengthscales. When `order` equals zero this reverts to one lengthscale per input dimension (ie. ARD with \(M = \mathrm{diag}(l)^{-2}\)). When `order` equals `-1` we revert to a single lengthscale for all input dimensions (ie. \(M = l^{-2}I\)).

    Args:
        order (int): Order of cross lengthscales.
        input_dims (int): Number of input dimensions.
        active_dims (list of int): Indices of active dimensions of shape (input_dims,).

    Attributes:
        magnitude (mogptk.gpr.parameter.Parameter): Magnitude \(\sigma^2\) a scalar.
        period (mogptk.gpr.parameter.Parameter): Period \(p\) of shape (input_dims,).
        lengthscale (mogptk.gpr.parameter.Parameter): Lengthscale \(l\) of shape (input_dims,) or scalar.
        cross_lengthscale (mogptk.gpr.parameter.Parameter): Cross lengthscale \(L\) of shape (input_dims,order) if `0 < order`.
    """
    def __init__(self, order=0, input_dims=1, active_dims=None):
        super().__init__(input_dims, active_dims)

        magnitude = 1.0
        period = torch.ones(input_dims)
        lengthscale = 1.0
        if -1 < order:
            lengthscale = torch.ones(input_dims)
        if 0 < order:
            cross_lengthscale = torch.ones(input_dims,order)

        self.order = order
        self.magnitude = Parameter(magnitude, lower=config.positive_minimum)
        self.period = Parameter(period, lower=config.positive_minimum)
        self.lengthscale = Parameter(lengthscale, lower=config.positive_minimum)
        if 0 < order:
            self.cross_lengthscale = Parameter(cross_lengthscale, lower=config.positive_minimum)

    def K(self, X1, X2=None):
        # X has shape (data_points,input_dims)
        X1, X2 = self._active_input(X1, X2)
        tau = self.distance(X1,X2)
        sin = torch.sin(np.pi * tau / self.period())  # NxMxD
        if self.order == -1:
            lengthscale = (1.0/self.lengthscale()**2).repeat(self.input_dims).diag()  # DxD
        elif self.order == 0:
            lengthscale = (1.0/self.lengthscale()**2).diag()  # DxD
        else:
            lengthscale = self.cross_lengthscale().mm(self.cross_lengthscale().T) + (1.0/self.lengthscale()**2).diag()  # DxD

```

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

### Get Channel Names

Source: https://github.com/games-uchile/mogptk/blob/master/docs/dataset.html

Retrieves the names of all channels within the dataset.

```APIDOC
## GET /api/dataset/get_names

### Description
Retrieves the names of all channels within the dataset.

### Method
GET

### Endpoint
/api/dataset/get_names

### Response
#### Success Response (200)
- **names** (list) - List of channel names.

#### Response Example
```json
{
  "names": ["A", "B", "C"]
}
```
```

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

### Initialize Mogptk DataSet with X and Y

Source: https://github.com/games-uchile/mogptk/blob/master/docs/dataset.html

Shows different ways to initialize a DataSet using separate X and Y data. Supports single X/Y pairs, multiple Y channels with a single X, and multiple X/Y pairs with corresponding names.

```python
>>> dataset = mogptk.DataSet(x, y)

>>> dataset = mogptk.DataSet(x, [y1, y2, y3], names=['A', 'B', 'C'])
            
>>> dataset = mogptk.DataSet([x1, x2, x3], [y1, y2, y3])
```

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

### Example Usage of CSM Model in MOGPTK

Source: https://github.com/games-uchile/mogptk/blob/master/docs/models/csm.html

Demonstrates how to create a dataset, instantiate the CSM model, initialize its parameters, train the model, make predictions, and plot the results using MOGPTK.

```python
import numpy as np
import mogptk

t = np.linspace(0, 10, 100)
y1 = np.sin(0.5 * t)
y2 = 2.0 * np.sin(0.2 * t)

dataset = mogptk.DataSet(t, [y1, y2])
model = mogptk.CSM(dataset, Q=2)
model.init_parameters()
model.train()
model.predict()
dataset.plot()
```

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

### GET /parameter/numpy

Source: https://github.com/games-uchile/mogptk/blob/master/docs/gpr/parameter.html

Retrieves the current value of the parameter as a NumPy array.

```APIDOC
## GET /parameter/numpy

### Description
Returns the constrained value of the parameter as a numpy.ndarray.

### Method
GET

### Endpoint
/parameter/numpy

### Response
#### Success Response (200)
- **value** (numpy.ndarray) - The parameter value.

#### Response Example
{
  "value": [0.5, 0.2]
}
```

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

### MultiOutputKernel Initialization and Methods (Python)

Source: https://github.com/games-uchile/mogptk/blob/master/docs/gpr/multioutput.html

Implements a base class for multi-output kernels where each output channel is handled independently. It provides methods for kernel computation and naming, utilizing a list of subkernels.

```Python
class MultiOutputKernel(Kernel):
    """
    Kernel with subkernels for each channels independently. Only the subkernels as block matrices on the diagonal are calculated, there is no correlation between channels.

    Args:
        kernels (list of Kernel): Kernels of shape (output_dims,).
        output_dims (int): Number of output dimensions.
    """
    def __init__(self, *kernels, output_dims=None):
        if output_dims is None:
            output_dims = len(kernels)
        super().__init__(output_dims)
        self.kernels = torch.nn.ModuleList(self._check_kernels(kernels, output_dims))

    def __getitem__(self, key):
        return self.kernels[key]

    def name(self):
        names = [kernel.name() for kernel in self.kernels]
        return '%s[%s]' % (self.__class__.__name__, ','.join(names))
    
    def Ksub(self, i, j, X1, X2=None):
        # X has shape (data_points,input_dims)
        X1, X2 = self._active_input(X1, X2)
        if i == j:
            return self.kernels[i].K(X1, X2)
        else:
            if X2 is None:
                X2 = X1
            return torch.zeros(X1.shape[0], X2.shape[0], device=config.device, dtype=config.dtype)

    def Ksub_diag(self, i, X1):
        # X has shape (data_points,input_dims)
        X1, _ = self._active_input(X1)
        return self.kernels[i].K_diag(X1)
```

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

### SincKernel Initialization and Parameters

Source: https://github.com/games-uchile/mogptk/blob/master/docs/gpr/singleoutput.html

Initializes the SincKernel with specified input dimensions and active dimensions. It sets up the learnable parameters: magnitude, frequency, and bandwidth, with constraints for positive values.

```python
class SincKernel(Kernel):
    """
    A sinc kernel given by

    $$ K(x,x') = \sigma^2 \frac{\sin(\Delta \tau)}{\Delta \tau} \cos(2\pi \xi_0 \tau) $$

    with \(\tau = |x-x'|\), \(\sigma^2\) the magnitude, \(\Delta\) the bandwidth, and \(\xi_0\) the frequency.

    Args:
        input_dims (int): Number of input dimensions.
        active_dims (list of int): Indices of active dimensions of shape (input_dims,).

    Attributes:
        magnitude (mogptk.gpr.parameter.Parameter): Magnitude \(\sigma^2\) a scalar.
        frequency (mogptk.gpr.parameter.Parameter): Frequency \(\xi_0\) of shape (input_dims,).
        bandwidth (mogptk.gpr.parameter.Parameter): Bandwidth \(\Delta\) of shape (input_dims,).
    """
    def __init__(self, input_dims=1, active_dims=None):
        super().__init__(input_dims, active_dims)

        magnitude = 1.0
        frequency = torch.ones(input_dims)
        bandwidth = torch.ones(input_dims)

        self.magnitude = Parameter(magnitude, lower=config.positive_minimum)
        self.frequency = Parameter(frequency, lower=config.positive_minimum)
        self.bandwidth = Parameter(bandwidth, lower=config.positive_minimum)
```

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

### MultiOutputHarmonizableSpectralKernel Initialization (Python)

Source: https://github.com/games-uchile/mogptk/blob/master/docs/gpr/multioutput.html

Initializes the MultiOutputHarmonizableSpectralKernel, a multi-output kernel for Gaussian Processes. It models each channel and cross-channel with spectral kernels, incorporating parameters like weight, mean, variance, lengthscale, center, delay, and phase. This class inherits from MultiOutputKernel.

```python
class MultiOutputHarmonizableSpectralKernel(MultiOutputKernel):
    """
    Multi-output harmonizable spectral kernel (MOHSM) where each channel and cross-channel is modelled with a spectral kernel as proposed by [1]. You can add the mixture kernel with `MixtureKernel(MultiOutputHarmonizableSpectralKernel(...), Q=3)`.

    $$ K_{ij}(x,x') = \alpha_{ij} \exp\left(-\frac{1}{2}(\tau+\theta_{ij})^T\Sigma_{ij}(\tau+\theta_{ij})\right) \cos((\tau+\theta_{ij})^T\mu_{ij} + \phi) \exp\left(-\frac{l_{ij}}{2}|\bar{x}-c|\right) $$

    $$ \alpha_{ij} = w_{ij}(2\pi)^n\sqrt{\left(|\Sigma_{ij}|\right)} $$

    Args
    ----

    **`output_dims`** :\ `int`

    Number of output dimensions.

    **`input_dims`** :\ `int`

    Number of input dimensions.

    **`active_dims`** :\ `list` of `int`

    Indices of active dimensions of shape (input_dims,).

    Attributes
    ----------

    **`weight`** :\ `[Parameter](parameter.html#mogptk.gpr.parameter.Parameter "mogptk.gpr.parameter.Parameter")`

    Weight ww of shape (output_dims,).

    **`mean`** :\ `[Parameter](parameter.html#mogptk.gpr.parameter.Parameter "mogptk.gpr.parameter.Parameter")`

    Mean \mu\mu of shape (output_dims,input_dims).

    **`variance`** :\ `[Parameter](parameter.html#mogptk.gpr.parameter.Parameter "mogptk.gpr.parameter.Parameter")`

    Variance \Sigma\Sigma of shape (output_dims,input_dims).

    **`lengthscale`** :\ `[Parameter](parameter.html#mogptk.gpr.parameter.Parameter "mogptk.gpr.parameter.Parameter")`

    Lengthscale ll of shape (output_dims,).

    **`center`** :\ `[Parameter](parameter.html#mogptk.gpr.parameter.Parameter "mogptk.gpr.parameter.Parameter")`

    Center cc of shape (input_dims,).

    **`delay`** :\ `[Parameter](parameter.html#mogptk.gpr.parameter.Parameter "mogptk.gpr.parameter.Parameter")`

    Delay \theta\theta of shape (output_dims,input_dims).

    **`phase`** :\ `[Parameter](parameter.html#mogptk.gpr.parameter.Parameter "mogptk.gpr.parameter.Parameter")`

    Phase \phi\phi in hertz of shape (output_dims,).

    [1] M. Altamirano, "Nonstationary Multi-Output Gaussian Processes via Harmonizable Spectral Mixtures, 2021

    Initializes internal Module state, shared by both nn.Module and ScriptModule.
    """
    pass
```

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

### Get Prediction Data

Source: https://github.com/games-uchile/mogptk/blob/master/docs/dataset.html

Retrieves the prediction X range for all channels in the dataset.

```python
def get_prediction_data(self):
    x = []
    for channel in self.channels:
        x.append(channel.get_prediction_data())
    return x
```

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

### Get Input Dimensions

Source: https://github.com/games-uchile/mogptk/blob/master/docs/dataset.html

Retrieves the number of input dimensions for each channel in the dataset.

```APIDOC
## GET /api/dataset/get_input_dims

### Description
Retrieves the number of input dimensions for each channel in the dataset.

### Method
GET

### Endpoint
/api/dataset/get_input_dims

### Response
#### Success Response (200)
- **input_dims** (list) - List of the number of input dimensions per channel.

#### Response Example
```json
{
  "input_dims": [2, 1]
}
```
```

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

### POST /model/sm/initialize

Source: https://github.com/games-uchile/mogptk/blob/master/docs/models/sm.html

Initializes a Spectral Mixture model with a given dataset and number of components.

```APIDOC
## POST /model/sm/initialize

### Description
Creates an instance of the Spectral Mixture (SM) model. The SM kernel is used for pattern discovery and extrapolation in multi-output Gaussian processes.

### Method
POST

### Request Body
- **dataset** (DataSet) - Required - The dataset object containing data for all channels.
- **Q** (int) - Required - Number of spectral components.
- **inference** (object) - Optional - The inference model to use (e.g., mogptk.Exact).
- **mean** (Mean) - Optional - The mean function class.
- **name** (str) - Optional - Identifier for the model.
```

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

### GET /model/log_marginal_likelihood

Source: https://github.com/games-uchile/mogptk/blob/master/docs/gpr/model.html

Calculates the log marginal likelihood for the Exact Gaussian process model.

```APIDOC
## GET /model/log_marginal_likelihood

### Description
Computes the log marginal likelihood for the Exact Gaussian process, accounting for kernel, likelihood variance, and optional data variance.

### Method
GET

### Endpoint
/model/log_marginal_likelihood

### Parameters
None

### Response
#### Success Response (200)
- **log_likelihood** (float) - The calculated log marginal likelihood value.

#### Response Example
{
  "log_likelihood": -12.45
}
```

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

### MultiOutputKernel Initialization and Input Checking (Python)

Source: https://github.com/games-uchile/mogptk/blob/master/docs/gpr/kernel.html

This snippet shows the initialization of the MultiOutputKernel class and its input validation logic. It ensures that the input data contains valid channel IDs and checks for consistency with the specified output dimensions. Dependencies include the `torch` library.

```python
class MultiOutputKernel(Kernel):
    """
    The `MultiOutputKernel` is a base class for multi-output kernels. It assumes that the first dimension of `X` contains channel IDs (integers) and calculates the final kernel matrix accordingly. Concretely, it will call the `Ksub` method for derived kernels from this class, which should return the kernel matrix between channel `i` and `j`, given inputs `X1` and `X2`. This class will automatically split and recombine the input vectors and kernel matrices respectively, in order to create the final kernel matrix of the multi-output kernel.

    Be aware that for implementation of `Ksub`, `i==j` is true for the diagonal matrices. `X2==None` is true when calculating the Gram matrix (i.e. `X1==X2`) and when `i==j`. It is thus a subset of the case `i==j`, and if `X2==None` than `i` is always equal to `j`.

    Args:
        output_dims (int): Number of output dimensions.
        input_dims (int): Number of input dimensions.
        active_dims (list of int): Indices of active dimensions of shape (input_dims,).
    """
    # TODO: seems to accumulate a lot of memory in the loops to call Ksub, perhaps it's keeping the computational graph while indexing?

    def __init__(self, output_dims, input_dims=None, active_dims=None):
        super().__init__(input_dims, active_dims)
        self.output_dims = output_dims

    def _check_input(self, X1, X2=None):
        X1, X2 = super()._check_input(X1, X2)
        if not torch.all(X1[:,0] == X1[:,0].long()) or not torch.all(X1[:,0] < self.output_dims):
            raise ValueError("X must have integers for the channel IDs in the first input dimension")
        if X2 is not None and not torch.all(X2[:,0] == X2[:,0].long()) or not torch.all(X1[:,0] < self.output_dims):
            raise ValueError("X must have integers for the channel IDs in the first input dimension")
        return X1, X2

```

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

### Configure Inference Methods

Source: https://context7.com/games-uchile/mogptk/llms.txt

Demonstrates selecting different inference algorithms including Exact, Snelson, Titsias, and Hensman for Gaussian Process models.

```python
import mogptk
model = mogptk.MOSM(dataset, Q=2, inference=mogptk.Exact())
model = mogptk.MOSM(dataset, Q=2, inference=mogptk.Snelson(inducing_points=50, init_inducing_points='density'))
model = mogptk.MOSM(dataset, Q=2, inference=mogptk.Titsias(inducing_points=50))
model = mogptk.MOSM(dataset, Q=2, inference=mogptk.Hensman(inducing_points=100, likelihood=mogptk.gpr.GaussianLikelihood(1.0)))
```

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

### GET /dataset/ls_estimation

Source: https://github.com/games-uchile/mogptk/blob/master/docs/dataset.html

Performs peak estimation of the spectrum using Lomb-Scargle per channel.

```APIDOC
## GET /dataset/ls_estimation

### Description
Peak estimation of the spectrum using Lomb-Scargle per channel.

### Method
GET

### Endpoint
/dataset/ls_estimation

### Parameters
#### Query Parameters
- **Q** (int) - Optional - Number of peaks to find (default: 1).
- **n** (int) - Optional - Number of points of the grid to evaluate frequencies (default: 10000).

### Response
#### Success Response (200)
- **amplitudes** (list) - Amplitude array per channel.
- **means** (list) - Frequency array per channel.
- **variances** (list) - Variance array per channel.

#### Response Example
{
  "amplitudes": [[0.5]],
  "means": [[1.2]],
  "variances": [[0.01]]
}
```

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

### Configure and Run Model Optimizer

Source: https://github.com/games-uchile/mogptk/blob/master/docs/model.html

This snippet demonstrates how to initialize an optimizer based on user input, manage training iterations, and track progress using a callback function. It supports PyTorch-based optimization routines and handles both iterative and closure-based update steps.

```python
if method.lower() in ('l-bfgs', 'lbfgs', 'l-bfgs-b', 'lbfgsb'):
    method = 'LBFGS'
elif method.lower() == 'adam':
    method = 'Adam'
elif method.lower() == 'sgd':
    method = 'SGD'
elif method.lower() == 'adagrad':
    method = 'AdaGrad'
else:
    raise ValueError('optimizer must be LBFGS, Adam, SGD, or AdaGrad')

if method == 'LBFGS':
    optimizer = torch.optim.LBFGS(self.gpr.parameters(), **kwargs)
    def loss():
        i = int(optimizer.state_dict()['state'][0]['func_evals'])
        loss = self.loss()
        progress(i, loss)
        return loss
    optimizer.step(loss)
else:
    # Logic for Adam, SGD, AdaGrad
    optimizer = torch.optim.Adam(self.gpr.parameters(), **kwargs)
    for i in range(iters):
        progress(i, self.loss())
        optimizer.step()
```

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

### GET /dataset/index

Source: https://github.com/games-uchile/mogptk/blob/master/docs/dataset.html

Retrieves the numeric index of a channel based on its name or existing index.

```APIDOC
## GET /dataset/index

### Description
Return the channel's numeric index given its name or current index.

### Method
GET

### Endpoint
/dataset/index

### Parameters
#### Query Parameters
- **index** (int, str) - Required - Index or name of the channel.

### Response
#### Success Response (200)
- **index** (int) - The numeric index of the channel.

#### Response Example
{
  "index": 0
}
```