---
title: "Introduction to circularNet"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to circularNet}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
library(circularNet)
```


# Overview

The circularNet package provides tools for estimating circular graphical models using node-wise regression approaches. Circular data arise naturally in many scientific fields, including chronobiology, directional statistics, environmental sciences, and gene-expression studies involving periodic or cyclic processes.

The package implements two complementary approaches for network estimation:

1. A likelihood-based node-wise regression framework using Maximum Likelihood Estimation (MLE).
2. A Circular Mean Squared Error (CMSE) based approach for network construction.

The package includes functions for:

- Model estimation
- Network construction
- Network evaluation
- Network visualization


# Circular Data

Circular variables are measured on a periodic scale where values wrap around after a full revolution. Typical examples include angles measured in radians within the interval

\[
[-\pi,\pi]
\]

Specialized statistical methods are required because standard Euclidean methods do not account for circular topology.

# Methodology

## Likelihood-Based Estimation

The likelihood-based method estimates conditional relationships between nodes using node-wise circular regression models. Parameters are estimated through numerical optimization using the `optim()` function.

Estimated regression coefficients are assembled into a coefficient matrix, which is subsequently thresholded to obtain an adjacency matrix representing the network structure.

## CMSE-Based Estimation

The package also supports network estimation based on Circular Mean Squared Error (CMSE). This approach measures discrepancies using circular distances and can be used for network construction, model fitting, and variable selection in circular data settings.

# Simulated Example

The following example illustrates a complete workflow using simulated circular data.

```{r}
# Simulated example data
set.seed(1)
data <- matrix(runif(200, -pi, pi), ncol = 5)

# Fit the model
fit <- fit_circular_model(data)

# Build adjacency matrix
network <- build_network(fit)

# Display network structure
network

```

The resulting adjacency matrix summarizes the estimated network structure obtained from the simulated circular data.

# Network Visualization

The estimated adjacency matrix can be visualized directly.

```{r}

# Plot the network
plot_network(network)

```

Nodes represent variables and edges represent estimated associations identified by the circular graphical model.

# Network Evaluation

When a reference network (ground-truth) is available, the estimated network can be evaluated using standard performance metrics.

```{r}
true_network <- matrix(
  sample(0:1, 25, replace = TRUE),
  ncol = 5
)

results <- evaluate_network(
  network,
  true_network
)

results

```

# Gene Expression Example

The package can also be applied to real biological datasets. The following example uses a small gene-expression dataset included with the package and demonstrates the complete workflow from data loading to network estimation and visualization.

```{r}
gene_file <- system.file(
  "extdata",
  "gene_expression_subset.csv",
  package = "circularNet"
)

gene_data <- read.csv(
  gene_file,
  check.names = FALSE
)

# Remove gene identifier column if present
if (!is.numeric(gene_data[[1]])) {
  gene_data <- gene_data[, -1]
}

gene_data <- as.matrix(gene_data)

# Convert from genes × samples to observations × variables
gene_data <- t(gene_data)

# Use a small subset of genes for faster vignette execution
gene_data_small <- gene_data[, 1:min(5, ncol(gene_data))]

# Fit circular graphical model
fit_gene <- fit_circular_model(gene_data_small)

# Display estimated coefficient matrix
round(fit_gene, 3)

# Build adjacency matrix
network_gene <- build_network(
  fit_gene,
  threshold = 0.2
)

# Display estimated network
network_gene

# Visualize estimated network
plot_network(network_gene)

```

The estimated adjacency matrix contains several non-zero entries, indicating potential associations among the selected genes. The network visualization represents genes as nodes and estimated associations as edges. In this example, connections are observed among multiple gene pairs, resulting in a sparse but non-empty network structure.
This example is intended to demonstrate the package workflow and should not be interpreted as a biological conclusion. The number of detected edges depends on the selected threshold value, with lower thresholds generally producing denser networks. generally producing denser networks.

# Applications

The package is suitable for both simulated and real-world circular datasets. Potential applications include:

- Circadian rhythm analysis
- Gene-expression network estimation
- Directional measurements
- Environmental cyclic processes
- Periodic biological systems

# Input Requirements

Input data should be provided as a matrix where:

- Rows correspond to observations.
- Columns correspond to variables (nodes).
- Circular measurements are expressed in radians.

# References

Dar, E. D. (2023). A Non-Parametric Circular Network Construction Via Simulations and a Hidden Markov Model for the HIV-1 Protease Cleavage Site Detection. Doctoral Dissertation, Middle East Technical University, Türkiye.

Available at: https://open.metu.edu.tr/handle/11511/102577

# Conclusion

The circularNet package provides a flexible framework for estimating and analyzing circular graphical models. By combining likelihood-based and CMSE-based methodologies, the package supports both methodological research and applied network analysis for circular data.