### Clone and Setup pyvinecopulib Environment

Source: https://github.com/vinecopulib/pyvinecopulib/blob/main/README.md

This snippet shows how to clone the pyvinecopulib repository and set up a conda environment for development. It includes commands for cloning, activating the environment, and installing development dependencies.

```bash
git clone --recursive https://github.com/vinecopulib/pyvinecopulib.git
cd pyvinecopulib
make env-conda                    # Create conda environment
conda activate pyvinecopulib      # Activate environment
make dev-setup                    # Install dependencies and pre-commit hooks
```

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

### Setup and Data Preparation for Vine Copulas

Source: https://github.com/vinecopulib/pyvinecopulib/blob/main/examples/04_discrete_variables.ipynb

Initializes the environment by importing necessary libraries and generating dummy data. It demonstrates how to convert raw data into pseudo-observations required for copula modeling.

```python
import math
import numpy as np
import pyvinecopulib as pv

np.random.seed(1234)
n = 30
d = 5
x = np.random.normal(size=n).reshape(n, 1) * np.ones((n, d)) + 0.5 * np.random.normal(size=(n, d))
u = pv.to_pseudo_obs(x)
```

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

### pyvinecopulib Pre-commit Hook Installation and Execution

Source: https://github.com/vinecopulib/pyvinecopulib/blob/main/README.md

Instructions for installing and manually running pre-commit hooks in the pyvinecopulib project. These hooks automate code quality checks before commits.

```bash
make pre-commit-install
make pre-commit
```

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

### pyvinecopulib Release and Troubleshooting Commands

Source: https://github.com/vinecopulib/pyvinecopulib/blob/main/README.md

Commands for preparing a release by running comprehensive checks, and for troubleshooting build or installation issues. Includes commands for debugging and cleaning the project.

```bash
make release-check
make debug-build
make debug-install
make status
make git-clean
```

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

### pyvinecopulib Development Commands

Source: https://github.com/vinecopulib/pyvinecopulib/blob/main/README.md

A list of key development commands available via the Makefile for pyvinecopulib. These commands cover installation, testing, documentation, cleaning, and metadata generation.

```bash
make install-dev
make test
make test-fast
make test-examples
make lint
make format
make type-check
make docs
make docs-serve
make clean
make stubs
make docstrings
make metadata
make examples
make clear-cache
```

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

### pyvinecopulib Testing Commands

Source: https://github.com/vinecopulib/pyvinecopulib/blob/main/README.md

Commands for running various test suites in pyvinecopulib, including all tests, fast tests, and example notebooks. Also includes command for performance benchmarks.

```bash
make test
make test-fast
make test-examples
make benchmark
```

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

### Define and Build pyvinecopulib Python Extension

Source: https://github.com/vinecopulib/pyvinecopulib/blob/main/CMakeLists.txt

Sets up include directories, defines the Python extension module 'pyvinecopulib_ext' using nanobind, and configures build options such as stable ABI, link-time optimization, and static nanobind linking. It also sets version information and installs the target.

```cmake
include(lib/vinecopulib/cmake/printInfo.cmake REQUIRED)

include_directories(SYSTEM ${external_includes})
include_directories(${vinecopulib_INCLUDE_DIRS} ${kde1d_INCLUDE_DIRS}
                    ${pyvinecopulib_INCLUDE_DIRS})

nanobind_add_module(
  pyvinecopulib_ext
  # Target the stable ABI for Python 3.12+, which reduces the number of binary
  # wheels that must be built. This does nothing on older Python versions
  STABLE_ABI
  # Enable link-time optimization for the extension
  LTO
  # Don’t perform optimizations to minimize binary size.
  NOMINSIZE
  # Build libnanobind statically and merge it into the extension (which itself
  # remains a shared library)
  #
  # If your project builds multiple extensions, you can replace this flag by
  # NB_SHARED to conserve space by reusing a shared libnanobind across libraries
  NB_STATIC
  src/pyvinecopulib_ext.cpp)

target_compile_definitions(pyvinecopulib_ext
                           PRIVATE VERSION_INFO=\"${PROJECT_VERSION}\")

# Install directive for scikit-build-core
install(TARGETS pyvinecopulib_ext LIBRARY DESTINATION pyvinecopulib)
```

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

### Initialize and Visualize a Vine Copula

Source: https://github.com/vinecopulib/pyvinecopulib/blob/main/examples/02_vine_copulas.ipynb

Demonstrates how to define pair-copulas, specify an R-vine matrix, and construct a Vinecop model. It also shows how to visualize the model structure.

```python
import pyvinecopulib as pv
import numpy as np

# Specify pair-copulas
bicop = pv.Bicop(pv.bb1, 90, parameters=np.array([[1.0], [2.0]]))
pcs = [[bicop, bicop], [bicop]]

# Specify R-vine matrix
mat = np.array([[1, 1, 1], [2, 2, 0], [3, 0, 0]])

# Set-up a vine copula
cop = pv.Vinecop.from_structure(matrix=mat, pair_copulas=pcs)
print(cop)
cop.plot()
```

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

### Fit Vinecop Model from Data

Source: https://github.com/vinecopulib/pyvinecopulib/blob/main/examples/02_vine_copulas.ipynb

Demonstrates how to initialize a Vinecop model and select structure, family, and parameters automatically from input data. It also shows the alternative method of creating a model directly from data using the from_data factory method.

```python
# Create a new object and select strucutre, family, and parameters
cop3 = pv.Vinecop(d=3)
cop3.select(data=u)
print(cop3)

# Otherwise, create directly from data
cop3 = pv.Vinecop.from_data(data=u)
print(cop3)
cop3.plot()
```

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

### Initialize Bivariate Copulas

Source: https://github.com/vinecopulib/pyvinecopulib/blob/main/examples/01_bivariate_copulas.ipynb

Demonstrates how to initialize an independence copula using the default constructor and how to create specific parametric copulas like Gaussian, Clayton, and Student by providing family and parameters.

```python
import pyvinecopulib as pv
import numpy as np

# Independence copula
indep_cop = pv.Bicop()

# Gaussian copula
gaussian_cop = pv.Bicop(family=pv.gaussian, parameters=np.array([[0.5]]))

# Rotated Clayton and Student copula
clayton_cop = pv.Bicop(family=pv.clayton, rotation=90, parameters=np.array([[3.0]]))
student_cop = pv.Bicop(family=pv.student, parameters=np.array([[0.5], [4]]))
```

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

### Initialize pyvinecopulib Environment

Source: https://github.com/vinecopulib/pyvinecopulib/blob/main/examples/07_kde1d.ipynb

Imports necessary libraries and configures the environment for plotting and reproducibility.

```python
import numpy as np
import matplotlib.pyplot as plt
import scipy.stats as stats
import pyvinecopulib as pv

np.random.seed(42)
plt.style.use("default")
plt.rcParams["figure.figsize"] = (12, 6)
plt.rcParams["font.size"] = 11

print(f"pyvinecopulib version: {pv.__version__}")
```

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

### Vine Copula Construction and Simulation with pyvinecopulib

Source: https://context7.com/vinecopulib/pyvinecopulib/llms.txt

Illustrates the manual construction of a 3-dimensional vine copula by defining bivariate pair-copulas and an R-vine structure matrix. It shows how to create a `Vinecop` object from this structure, simulate data from it, and evaluate its probability density function (PDF) and cumulative distribution function (CDF). Includes Rosenblatt transform for converting to uniforms and inverse Rosenblatt for simulation.

```python
import pyvinecopulib as pv
import numpy as np

bicop = pv.Bicop(pv.bb1, rotation=90, parameters=np.array([[1.0], [2.0]]))
pair_copulas = [
    [bicop, bicop],
    [bicop]
]

mat = np.array([
    [1, 1, 1],
    [2, 2, 0],
    [3, 0, 0]
])

cop = pv.Vinecop.from_structure(matrix=mat, pair_copulas=pair_copulas)
print(cop)

u = cop.simulate(n=1000, seeds=[1, 2, 3])
print(u.shape)

pdf_vals = cop.pdf(u[:10])
cdf_vals = cop.cdf(u[:10], N=10000)
loglik = cop.loglik(u)

v = cop.rosenblatt(u)
u_new = cop.inverse_rosenblatt(v)

print(f"Dimension: {cop.dim}")
print(f"Truncation level: {cop.trunc_lvl}")
print(f"Structure matrix:\n{cop.matrix}")

cop.plot(tree=[0, 1])
```

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

### Fit and Select Copula Models

Source: https://github.com/vinecopulib/pyvinecopulib/blob/main/examples/01_bivariate_copulas.ipynb

Explains how to fit a copula to data using predefined parameters or by performing automated model selection to determine the best family and parameters.

```python
# Fitting to existing object
cop2 = pv.Bicop(pv.student)
cop2.fit(data=u)

# Using FitControls for specific selection
controls = pv.FitControlsBicop(family_set=[pv.student])
cop3 = pv.Bicop.from_data(data=u, controls=controls)

# Automated selection
cop4 = pv.Bicop()
cop4.select(data=u)
cop5 = pv.Bicop.from_data(data=u)
```

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

### Estimate Density for Bounded Continuous Data

Source: https://github.com/vinecopulib/pyvinecopulib/blob/main/examples/07_kde1d.ipynb

Shows how to handle bounded data by specifying xmin and xmax parameters during Kde1d initialization.

```python
x_gamma = np.random.gamma(shape=1, scale=1, size=500)
kde_gamma = pv.Kde1d(xmin=0)
kde_gamma.fit(x_gamma)

x_beta = np.random.beta(a=2, b=5, size=500)
kde_beta = pv.Kde1d(xmin=0, xmax=1)
kde_beta.fit(x_beta)
```

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

### Bivariate Copula Selection and Fitting with pyvinecopulib

Source: https://context7.com/vinecopulib/pyvinecopulib/llms.txt

Demonstrates how to select the best bivariate copula family and parameters for given data using the `Bicop.select()` method. It also shows how to customize the fitting process with `FitControlsBicop` for family selection, parameter estimation methods, and rotation considerations. Accesses properties like Kendall's tau, number of parameters, and observations.

```python
import pyvinecopulib as pv

data = pv.load_data("data.csv") # Load your data here
u = pv.to_pseudo_obs(data)

cop2 = pv.Bicop()
cop2.select(data=u)
print(f"Selected family: {cop2.family}, parameters: {cop2.parameters}")

controls = pv.FitControlsBicop(
    family_set=pv.parametric, 
    parametric_method="itau", 
    preselect_families=True, 
    allow_rotations=True
)
cop3 = pv.Bicop()
cop3.select(data=u, controls=controls)

print(f"Kendall's tau: {cop3.tau:.3f}")
print(f"Number of parameters: {cop3.npars}")
print(f"Number of observations: {cop3.nobs}")
```

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

### Fitting Continuous Vine Copula Models

Source: https://github.com/vinecopulib/pyvinecopulib/blob/main/examples/04_discrete_variables.ipynb

Demonstrates how to configure fit controls and instantiate a Vinecop model from continuous pseudo-observations. The model captures dependencies between variables using specified families.

```python
controls = pv.FitControlsVinecop(family_set=[pv.gaussian])
fit_cont = pv.Vinecop.from_data(u, controls=controls)
print(str(fit_cont))
```

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

### Import Libraries and Helper Function for Benchmarking

Source: https://github.com/vinecopulib/pyvinecopulib/blob/main/examples/05_benchmark.ipynb

Imports necessary libraries like timeit, numpy, and pyvinecopulib. Defines a helper function `print_results` to display benchmark outcomes, calculating min, mean, and max execution times in milliseconds.

```python
import timeit

import numpy as np

import pyvinecopulib as pv

from collections import defaultdict


def print_results(results, name):
  print(
    f"{name}: min={min(results) * 1000:.6f}, mean={np.mean(results) * 1000:.6f}, max={max(results) * 1000:.6f}"
  )
```

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

### Simulate Data and Evaluate Model Metrics

Source: https://github.com/vinecopulib/pyvinecopulib/blob/main/examples/02_vine_copulas.ipynb

Shows how to generate synthetic data from a fitted Vinecop model and evaluate various statistical functions such as PDF, Rosenblatt transforms, and information criteria.

```python
u = cop.simulate(n=1000, seeds=[1, 2, 3])
u = u[:10, :]
fcts = [cop.pdf, cop.rosenblatt, cop.inverse_rosenblatt, cop.loglik, cop.aic, cop.bic]
[f(u) for f in fcts]
```

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

### Prepare Data and Fit Vine Copula Model

Source: https://github.com/vinecopulib/pyvinecopulib/blob/main/examples/03_vine_copulas_fit_sample.ipynb

This snippet demonstrates generating multivariate normal data, transforming it into pseudo-observations, and fitting a Gaussian vine copula model using pyvinecopulib.

```python
import numpy as np
import pyvinecopulib as pv

np.random.seed(1234)
n = 1000
d = 5
mean = 1 + np.random.normal(size=d)
cov = np.random.normal(size=(d, d))
cov = np.dot(cov.transpose(), cov)
x = np.random.multivariate_normal(mean, cov, n)

u = pv.to_pseudo_obs(x)
pv.pairs_copula_data(u, scatter_size=0.5)

controls = pv.FitControlsVinecop(family_set=[pv.gaussian])
cop = pv.Vinecop.from_data(u, controls=controls)
print(cop)
```

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

### Fit Bivariate Copula from Data (Bicop.from_data) in Python

Source: https://context7.com/vinecopulib/pyvinecopulib/llms.txt

Shows how to use the `Bicop.from_data` factory method to automatically select the best-fitting bivariate copula family and estimate its parameters from observed data. It covers automatic selection using AIC/BIC, restricting families with `FitControlsBicop`, and fitting with discrete variables.

```python
import pyvinecopulib as pv
import numpy as np

# Generate sample data from a known copula
true_cop = pv.Bicop(family=pv.student, parameters=np.array([[0.5], [4]]))
u = true_cop.simulate(n=1000, seeds=[1, 2, 3])

# Automatic family selection and parameter estimation
fitted_cop = pv.Bicop.from_data(data=u)
print(fitted_cop)
# Output: family = Student, parameters = 0.48, 3.7

# Restrict to specific families using FitControlsBicop
controls = pv.FitControlsBicop(
    family_set=[pv.gaussian, pv.student, pv.clayton],
    parametric_method="mle",           # Maximum likelihood estimation
    selection_criterion="bic",          # Use BIC for model selection
    num_threads=4                       # Parallel computation
)
fitted_cop2 = pv.Bicop.from_data(data=u, controls=controls)

# Fit with discrete variables
# var_types: "c" for continuous, "d" for discrete
fitted_discrete = pv.Bicop.from_data(
    data=u,
    var_types=["c", "d"],
    controls=pv.FitControlsBicop(family_set=[pv.gaussian])
)
```

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

### Evaluate Zero-Inflated Density

Source: https://github.com/vinecopulib/pyvinecopulib/blob/main/examples/07_kde1d.ipynb

Demonstrates how to evaluate the probability density function for a zero-inflated KDE model. It includes logic to handle the point mass at zero and compares estimated values against theoretical continuous distributions.

```python
eval_points_zi = np.array([0.0, 0.5, 1.0, 2.0, 4.0, 6.0])
density_zi = kde_zi.pdf(eval_points_zi)

print("\nDensity evaluation for zero-inflated data:")
for point, density in zip(eval_points_zi, density_zi):
  if point == 0:
    print(f"x = {point:4.1f}: estimated = {density:.4f} (includes point mass)")
  else:
    true_continuous = 0.6 * stats.expon.pdf(point, scale=2)
    print(f"x = {point:4.1f}: estimated = {density:.4f}, true continuous = {true_continuous:.4f}")
```

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

### Fitting a Vinecop Model

Source: https://github.com/vinecopulib/pyvinecopulib/blob/main/examples/02_vine_copulas.ipynb

Demonstrates how to automatically select and fit a Vinecop model to data, and how to create a Vinecop model directly from data and visualize it.

```APIDOC
## Fitting a Vinecop Model

### Description
This section shows two ways to fit a copula model when no prior information is known. The first method involves creating a `Vinecop` object and then using the `select` method to automatically determine the structure, families, and parameters. The second method directly instantiates a `Vinecop` object from the provided data using `from_data`. Both methods allow for visualization of the fitted copula.

### Method
`select()` and `from_data()` methods of the `Vinecop` class.

### Endpoint
N/A (This is a library usage example, not a web API endpoint)

### Parameters
- `data` (numpy.ndarray or pandas.DataFrame): The input data for fitting the copula.

### Request Example
```python
# Create a new object and select structure, family, and parameters
cop3 = pv.Vinecop(d=3)
cop3.select(data=u)
print(cop3)

# Otherwise, create directly from data
cop3 = pv.Vinecop.from_data(data=u)
print(cop3)
cop3.plot()
```

### Response
#### Success Response
The `print(cop3)` command outputs a representation of the fitted Vinecop model, including details about each tree, edge, conditioned variables, conditioning variables, variable types, family, rotation, parameters, degrees of freedom (df), and Kendall's tau (tau).

#### Response Example
```
<pyvinecopulib.Vinecop> Vinecop model with 3 variables
tree edge conditioned variables conditioning variables var_types family rotation parameters  df   tau 
   1    1                  2, 1                             c, c    BB1       90 0.90, 2.00 2.0 -0.66 
   1    2                  1, 3                             c, c    BB1       90 0.36, 2.54 2.0 -0.67 
   2    1                  2, 3                      1      c, c    BB1      270 1.03, 2.03 2.0 -0.68 

<pyvinecopulib.Vinecop> Vinecop model with 3 variables
tree edge conditioned variables conditioning variables var_types family rotation parameters  df   tau 
   1    1                  2, 1                             c, c    BB1       90 0.90, 2.00 2.0 -0.66 
   1    2                  1, 3                             c, c    BB1       90 0.36, 2.54 2.0 -0.67 
   2    1                  2, 3                      1      c, c    BB1      270 1.03, 2.03 2.0 -0.68 
```

### Visualization
- `cop3.plot()` generates a graphical representation of the fitted Vinecop model.
```

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

### Defining a C-vine Structure and Instantiating a Vinecop Model

Source: https://github.com/vinecopulib/pyvinecopulib/blob/main/examples/02_vine_copulas.ipynb

Illustrates how to manually define a C-vine structure and then instantiate a Vinecop model by specifying the pair-copulas for each tree.

```APIDOC
## Defining a C-vine Structure and Instantiating a Vinecop Model

### Description
This section demonstrates how to construct a C-vine copula model manually. It involves first defining the structure of the C-vine using `CVineStructure`, specifying the root node for each tree. Subsequently, the `Vinecop.from_structure` method is used to instantiate the model, where `pair_copulas` are provided as a list of lists, with each inner list containing `Bicop` objects for the corresponding tree.

### Method
`CVineStructure` class and `Vinecop.from_structure()` method.

### Endpoint
N/A (This is a library usage example, not a web API endpoint)

### Parameters
- `structure` (CVineStructure): An object defining the C-vine structure.
- `pair_copulas` (list of lists of Bicop objects): A list where each element is a list of `Bicop` objects representing the pair-copulas for each tree in the vine structure.

### Request Example
```python
# create a C-vine structure with root node 1 in first tree, 2 in second, ...
cvine = pv.CVineStructure([4, 3, 2, 1])
# specify pair-copulas in every tree
tree1 = [
  pv.Bicop(pv.gaussian, 0, np.array([[0.5]])),
  pv.Bicop(pv.clayton, 0, np.array([[3.0]])),
  pv.Bicop(pv.student, 0, np.array([[0.4], [4]])),
]
tree2 = [
  pv.Bicop(pv.indep),
  pv.Bicop(pv.gaussian, 0, np.array([[0.5]])),
]
tree3 = [pv.Bicop(pv.gaussian)]

# instantiate C-vine copula model
cop = pv.Vinecop.from_structure(
  structure=cvine, pair_copulas=[tree1, tree2, tree3]
)
print(cop)
cop.plot()
```

### Response
#### Success Response
The `print(cop)` command outputs a detailed representation of the constructed Vinecop model, including information about each tree, edge, conditioned variables, conditioning variables, variable types, family, rotation, parameters, degrees of freedom (df), and Kendall's tau (tau).

#### Response Example
```
<pyvinecopulib.Vinecop> Vinecop model with 4 variables
tree edge conditioned variables conditioning variables var_types       family rotation parameters  df  tau 
   1    1                  4, 1                             c, c     Gaussian        0       0.50 1.0 0.33 
   1    2                  3, 1                             c, c      Clayton        0       3.00 1.0 0.60 
   1    3                  2, 1                             c, c      Student        0 0.40, 4.00 2.0 0.26 
   2    1                  4, 2                      1      c, c Independence                         0.00 
   2    2                  3, 2                      1      c, c     Gaussian        0       0.50 1.0 0.33 
   3    1                  4, 3                   2, 1      c, c     Gaussian        0       0.00 1.0 0.00 
```

### Visualization
- `cop.plot()` generates a graphical representation of the defined C-vine copula model.
```

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

### Plotting, Simulation, and Evaluation with Kde1d in Python

Source: https://github.com/vinecopulib/pyvinecopulib/blob/main/examples/07_kde1d.ipynb

This Python snippet shows how to use the Kde1d class for plotting, simulating data, and evaluating CDF and quantile functions. It includes comparisons between simulated and original data statistics, as well as visual comparisons using histograms and Q-Q plots.

```python
kde_normal.plot()

# Simulate from fitted density
simulated_data = kde_normal.simulate(n=1000, seeds=[123])

print("Simulation from fitted normal density:")
print(f"Original data: mean={x_normal.mean():.3f}, std={x_normal.std():.3f}")
print(
  f"Simulated data: mean={simulated_data.mean():.3f}, std={simulated_data.std():.3f}"
)

# CDF and quantile functions
print("\nCDF and quantile evaluation for normal kde:")
test_points = np.array([-1, 0, 1])
cdf_values = kde_normal.cdf(test_points)
print(f"CDF at [-1, 0, 1]: {cdf_values}")

quantiles = np.array([0.25, 0.5, 0.75])
quantile_values = kde_normal.quantile(quantiles)
print(f"Quantiles at [0.25, 0.5, 0.75]: {quantile_values}")

# True values for comparison
true_cdf = stats.norm.cdf(test_points)
true_quantiles = stats.norm.ppf(quantiles)
print(f"True CDF values: {true_cdf}")
print(f"True quantiles: {true_quantiles}")

# Plot histogram of simulated data vs. original
plt.figure(figsize=(12, 6))
plt.subplot(1, 2, 1)
plt.hist(x_normal, bins=20, density=True, alpha=0.7, label="Original data")
plt.hist(
  simulated_data, bins=30, density=True, alpha=0.7, label="Simulated data"
)
plt.title("Histogram Comparison")
plt.xlabel("x")
plt.ylabel("Density")
plt.legend()
plt.grid(True, alpha=0.3)

plt.subplot(1, 2, 2)

# Q-Q plot
stats.probplot(simulated_data, dist=stats.norm, plot=plt)
plt.title("Q-Q Plot: Simulated vs. Normal")
plt.grid(True, alpha=0.3)

plt.tight_layout()
plt.show()
```

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

### Manage Vine Copula Structures

Source: https://context7.com/vinecopulib/pyvinecopulib/llms.txt

Demonstrates how to truncate vine structures, simulate random vine structures, and construct a VineCopula object from a specific structure and pair copulas.

```python
import pyvinecopulib as pv
import numpy as np

# Truncate structure
rvine_trunc = pv.RVineStructure.from_matrix(mat)
rvine_trunc.truncate(trunc_lvl=2)

# Randomly sample a vine structure
random_struct = pv.RVineStructure.simulate(d=5, seeds=[42])

# Create vine copula with C-vine structure
tree1 = [pv.Bicop(pv.gaussian, 0, np.array([[0.5]])), pv.Bicop(pv.clayton, 0, np.array([[3.0]])), pv.Bicop(pv.student, 0, np.array([[0.4], [4]]))]
tree2 = [pv.Bicop(pv.indep), pv.Bicop(pv.gaussian, 0, np.array([[0.5]]))]
tree3 = [pv.Bicop(pv.gaussian)]

cop = pv.Vinecop.from_structure(structure=cvine, pair_copulas=[tree1, tree2, tree3])
print(cop)
cop.plot()
```

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

### Estimate Parameters and Select Models (Bicop.fit, Bicop.select) in Python

Source: https://context7.com/vinecopulib/pyvinecopulib/llms.txt

Explains how to use the `fit` and `select` methods of the `Bicop` class in pyvinecopulib. `fit` estimates parameters for a pre-defined copula family, while `select` performs both family selection and parameter estimation. Both methods modify the copula object in-place.

```python
import pyvinecopulib as pv
import numpy as np

# Generate data
true_cop = pv.Bicop(family=pv.clayton, rotation=0, parameters=np.array([[2.0]]))
u = true_cop.simulate(n=500, seeds=[42])

# Method 1: fit() - Estimate parameters for a fixed family
cop = pv.Bicop(pv.clayton)  # Create copula with known family
cop.fit(data=u)
print(f"Fitted Clayton parameter: {cop.parameters}")

```

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

### Univariate Kernel Density Estimation with Kde1d

Source: https://context7.com/vinecopulib/pyvinecopulib/llms.txt

Illustrates the usage of the `Kde1d` class for univariate kernel density estimation. It covers fitting, evaluating PDF, CDF, quantiles, simulating data, plotting, and handling continuous, bounded, discrete, and zero-inflated data with custom parameters.

```python
import pyvinecopulib as pv
import numpy as np

# Continuous unbounded data
np.random.seed(42)
x = np.random.normal(0, 1, 500)
kde = pv.Kde1d()
kde.fit(x)

# Evaluate density functions
x_eval = np.linspace(-3, 3, 100)
pdf_vals = kde.pdf(x_eval)          # Probability density
cdf_vals = kde.cdf(x_eval)          # Cumulative distribution
quantiles = kde.quantile(np.array([0.25, 0.5, 0.75]))  # Quantile function

# Simulate from the fitted density
x_sim = kde.simulate(n=1000, seeds=[42])

# Plot the density
kde.plot()

# Bounded data (e.g., positive values)
x_pos = np.random.gamma(2, 2, 500)
kde_bounded = pv.Kde1d(xmin=0.0, degree=1)
kde_bounded.fit(x_pos)
kde_bounded.plot()

# Discrete data
x_discrete = np.random.binomial(10, 0.3, 500)
kde_discrete = pv.Kde1d(xmin=0, xmax=10, type="discrete")
kde_discrete.fit(x_discrete)
kde_discrete.plot()

# Zero-inflated data
x_zi = np.random.exponential(2, 500)
x_zi[np.random.choice(500, 100, replace=False)] = 0
kde_zi = pv.Kde1d(xmin=0, type="zero_inflated")
kde_zi.fit(x_zi)
print(f"Point mass at zero: {kde_zi.prob0:.3f}")
kde_zi.plot()

# Custom bandwidth and parameters
kde_custom = pv.Kde1d(
    multiplier=1.5,        # Scale automatic bandwidth by 1.5
    degree=2,              # Log-quadratic local polynomial
    grid_size=500          # Interpolation grid points
)
kde_custom.fit(x)
```

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

### Construct C-Vine Copula Manually

Source: https://github.com/vinecopulib/pyvinecopulib/blob/main/examples/02_vine_copulas.ipynb

Shows how to manually define a C-vine structure and specify pair-copulas for each tree. This approach allows for full control over the copula model architecture and individual pair-copula parameters.

```python
# create a C-vine structure with root node 1 in first tree, 2 in second, ...
cvine = pv.CVineStructure([4, 3, 2, 1])
# specify pair-copulas in every tree
tree1 = [
  pv.Bicop(pv.gaussian, 0, np.array([[0.5]])),
  pv.Bicop(pv.clayton, 0, np.array([[3.0]])),
  pv.Bicop(pv.student, 0, np.array([[0.4], [4]])),
]
tree2 = [
  pv.Bicop(pv.indep),
  pv.Bicop(pv.gaussian, 0, np.array([[0.5]])),
]
tree3 = [pv.Bicop(pv.gaussian)]

# instantiate C-vine copula model
cop = pv.Vinecop.from_structure(
  structure=cvine, pair_copulas=[tree1, tree2, tree3]
)
print(cop)
cop.plot()
```

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

### Automatic Vine Copula Fitting with pyvinecopulib

Source: https://context7.com/vinecopulib/pyvinecopulib/llms.txt

Explains the `Vinecop.from_data` factory method for automatic vine copula fitting, including structure selection, family selection, and parameter estimation based on Dissmann et al. (2013). Demonstrates customized fitting using `FitControlsVinecop` to specify family sets, estimation methods, tree selection criteria, truncation levels, and parallel computation. Also shows fitting with a pre-specified structure like D-vines and evaluating model quality using log-likelihood, AIC, and BIC.

```python
import pyvinecopulib as pv
import numpy as np

np.random.seed(42)
n, d = 500, 5
data = np.random.normal(size=(n, d))
u = pv.to_pseudo_obs(data)

cop = pv.Vinecop.from_data(data=u)
print(cop)

controls = pv.FitControlsVinecop(
    family_set=[pv.gaussian, pv.clayton, pv.gumbel],
    parametric_method="mle",
    tree_criterion="tau",
    tree_algorithm="mst_prim",
    trunc_lvl=3,
    selection_criterion="bic",
    select_trunc_lvl=True,
    num_threads=4,
    show_trace=True
)
cop2 = pv.Vinecop.from_data(data=u, controls=controls)

structure = pv.DVineStructure([1, 2, 3, 4, 5])
cop3 = pv.Vinecop.from_data(
    data=u,
    structure=structure,
    controls=pv.FitControlsVinecop(family_set=pv.parametric)
)

print(f"Log-likelihood: {cop.loglik(u):.2f}")
print(f"AIC: {cop.aic(u):.2f}")
print(f"BIC: {cop.bic(u):.2f}")
print(f"Number of parameters: {cop.npars}")
```

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

### Simulation Functions for Uniform Random and Quasi-Random Numbers

Source: https://context7.com/vinecopulib/pyvinecopulib/llms.txt

Explains how to generate uniform random numbers using `simulate_uniform`, `ghalton`, and `sobol` for Monte Carlo integration. It covers pseudo-random, quasi-random (Halton, Sobol), and their application in copula simulation and CDF estimation.

```python
import pyvinecopulib as pv
import numpy as np

# Standard uniform random numbers
u_random = pv.simulate_uniform(n=1000, d=5, qrng=False, seeds=[42])
print(f"Random uniforms shape: {u_random.shape}")

# Quasi-random numbers (better space coverage)
u_quasi = pv.simulate_uniform(n=1000, d=5, qrng=True, seeds=[42])

# Generalized Halton sequence (d <= 300)
u_halton = pv.ghalton(n=1000, d=5, seeds=[1, 2, 3])

# Sobol sequence (for higher dimensions)
u_sobol = pv.sobol(n=1000, d=500, seeds=[42])

# Use quasi-random numbers for vine copula simulation
cop = pv.Vinecop.from_data(pv.to_pseudo_obs(np.random.randn(500, 4)))
u_vine = cop.simulate(n=1000, qrng=True, seeds=[1, 2, 3])

# Compare random vs quasi-random for CDF estimation
np.random.seed(42)
u_test = np.random.uniform(0, 1, (10, 4))
cdf_random = cop.cdf(u_test, N=10000)  # Uses quasi-random internally
```

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

### Create and Use Bivariate Copulas (Bicop) in Python

Source: https://context7.com/vinecopulib/pyvinecopulib/llms.txt

Demonstrates how to create bivariate copula (Bicop) objects in pyvinecopulib. It shows instantiation with different families (Gaussian, Clayton, Student-t), rotations, parameter settings, data simulation, and evaluation of copula functions like PDF, CDF, and conditional distributions. It also includes model evaluation metrics (log-likelihood, AIC, BIC) and visualization.

```python
import pyvinecopulib as pv
import numpy as np

# Create a Gaussian copula with correlation parameter 0.5
cop = pv.Bicop(family=pv.gaussian, parameters=np.array([[0.5]]))
print(cop)
# Output: family = Gaussian, rotation = 0, var_types = c,c, parameters = 0.5

# Create a rotated Clayton copula (captures negative dependence)
cop_clayton = pv.Bicop(family=pv.clayton, rotation=90, parameters=np.array([[3.0]]))

# Create a Student-t copula with correlation 0.5 and 4 degrees of freedom
cop_t = pv.Bicop(family=pv.student, parameters=np.array([[0.5], [4]]))

# Simulate data from the copula
u = cop_t.simulate(n=1000, seeds=[1, 2, 3])
print(u.shape)  # (1000, 2)

# Evaluate copula functions
pdf_vals = cop_t.pdf(u[:10])           # Copula density
cdf_vals = cop_t.cdf(u[:10])           # Copula distribution
h1_vals = cop_t.hfunc1(u[:10])         # Conditional distribution h1
h2_vals = cop_t.hfunc2(u[:10])         # Conditional distribution h2

# Model evaluation metrics
loglik = cop_t.loglik(u)               # Log-likelihood
aic = cop_t.aic(u)                     # Akaike Information Criterion
bic = cop_t.bic(u)                     # Bayesian Information Criterion
print(f"Log-likelihood: {loglik:.2f}, AIC: {aic:.2f}, BIC: {bic:.2f}")

# Visualize the copula density
cop.plot()                              # 3D surface plot
cop.plot(type="contour", margin_type="norm")  # Contour plot with normal margins
```

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

### wdm API - Weighted Dependence Measures

Source: https://github.com/vinecopulib/pyvinecopulib/blob/main/examples/06_weighted_dependence_measures.ipynb

Illustrates how to use the `wdm` function with observation weights, including uniform, linear, and half-zero weighting schemes.

```APIDOC
## `wdm` API - Weighted Dependence Measures

### Description
This section demonstrates the use of the `wdm` function with observation weights. It shows how different weighting schemes (uniform, linear, half-zero) can influence the calculated dependence measures.

### Method
`pv.wdm(x, y, method, weights)`

### Endpoint
N/A (This is a function call within a Python library)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```python
import numpy as np
import pyvinecopulib as pv

n = 200
x = np.random.normal(0, 1, n)
y = 0.7 * x + np.random.normal(0, 0.5, n)

# Example 1: Uniform weights (should give same result as unweighted)
weights_uniform = np.ones(n)
print("Uniform Weights vs Unweighted:")
print("=" * 35)
for method in ["pearson", "spearman", "kendall"]:
  unweighted = pv.wdm(x, y, method)
  weighted = pv.wdm(x, y, method, weights_uniform)
  print(f"{method.capitalize():12}: {unweighted:.6f} vs {weighted:.6f}")

# Example 2: Linear weights (more weight on later observations)
weights_linear = np.linspace(0.1, 2.0, n)
print("\nLinear Weights (0.1 to 2.0):")
print("=" * 35)
for method in ["pearson", "spearman", "kendall"]:
  unweighted = pv.wdm(x, y, method)
  weighted = pv.wdm(x, y, method, weights_linear)
  print(f"{method.capitalize():12}: {unweighted:.4f} -> {weighted:.4f}")

# Example 3: Half-zero weights (focus on second half of data)
weights_half_zero = np.zeros(n)
weights_half_zero[n // 2 :] = 1.0
print("\nHalf-Zero Weights (second half only):")
print("=" * 45)
for method in ["pearson", "spearman", "kendall"]:
  weighted_result = pv.wdm(x, y, method, weights_half_zero)
  second_half_result = pv.wdm(x[n // 2 :], y[n // 2 :], method)
  print(
    f"{method.capitalize():12}: {weighted_result:.6f} (weighted) vs {second_half_result:.6f} (second half)"
  )
  print(
    f"              Difference: {abs(weighted_result - second_half_result):.2e}"
  )
```

### Response
#### Success Response (200)
Prints the comparison of weighted and unweighted dependence measures to the console.

#### Response Example
```
Uniform Weights vs Unweighted:
===================================
Pearson     : 0.818019 vs 0.818019
Spearman    : 0.805694 vs 0.805694
Kendall     : 0.609749 vs 0.609749

Linear Weights (0.1 to 2.0):
===================================
Pearson     : 0.8180 -> 0.8138
Spearman    : 0.8057 -> 0.7929
Kendall     : 0.6097 -> 0.5965

Half-Zero Weights (second half only):
=============================================
Pearson     : 0.830812 (weighted) vs 0.830812 (second half)
              Difference: 0.00e+00
Spearman    : 0.809241 (weighted) vs 0.809241 (second half)
              Difference: 0.00e+00
Kendall     : 0.615354 (weighted) vs 0.615354 (second half)
              Difference: 0.00e+00
```
```

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

### Sample from Fitted Vine Copula Model

Source: https://github.com/vinecopulib/pyvinecopulib/blob/main/examples/03_vine_copulas_fit_sample.ipynb

This snippet shows how to simulate new data from a fitted vine copula model and transform the simulated pseudo-observations back to the original scale.

```python
n_sim = 1000
u_sim = cop.simulate(n_sim, seeds=[1, 2, 3, 4])
pv.pairs_copula_data(u_sim, scatter_size=0.5)

x_sim = np.asarray([np.quantile(x[:, i], u_sim[:, i]) for i in range(0, d)])
print(np.mean(x_sim, 1))
print(np.cov(x_sim))
```

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

### Fit Mixed Vine Copula Model with pyvinecopulib

Source: https://github.com/vinecopulib/pyvinecopulib/blob/main/examples/04_discrete_variables.ipynb

This snippet shows how to initialize and fit a Vinecop model from data containing mixed variable types (discrete and continuous). It uses the `from_data` method and specifies variable types. The resulting model is then printed.

```python
import pyvinecopulib as pv

# Assuming u_disc_mixed, var_types, and controls are defined
fit_mixed = pv.Vinecop.from_data(
  u_disc_mixed, var_types=["d"] + ["c"] * 4, controls=controls
)
print(str(fit_mixed))
```

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

### Visualize and Analyze Copulas

Source: https://github.com/vinecopulib/pyvinecopulib/blob/main/examples/01_bivariate_copulas.ipynb

Shows how to generate surface and contour plots for copula density and how to perform statistical operations like simulation and evaluation of PDF, CDF, and h-functions.

```python
cop = pv.Bicop(family=pv.gaussian, parameters=np.array([[0.5]]))
cop.plot()
cop.plot(type="contour", margin_type="norm")

# Simulation and evaluation
u = cop.simulate(n=10, seeds=[1, 2, 3])
pdf_vals = cop.pdf(u)
cdf_vals = cop.cdf(u)
loglik = cop.loglik(u)
```

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

### Visualize Zero-Inflated KDE

Source: https://github.com/vinecopulib/pyvinecopulib/blob/main/examples/07_kde1d.ipynb

Plots the density estimate of a zero-inflated model compared to the true distribution, highlighting the point mass at zero.

```python
x_range = np.linspace(0.1, 10, 200)
kde_density_zi = kde_zi.pdf(x_range)
true_density_zi = 0.6 * stats.expon.pdf(x_range, scale=1)

plt.figure(figsize=(12, 6))
plt.plot(x_range, kde_density_zi, "b-", label="KDE (continuous part)", linewidth=2)
plt.plot(x_range, true_density_zi, "r--", label="True (continuous part)", linewidth=2)
plt.plot(0, kde_zi.prob0, "bo", markersize=10, label=f"Estimated point mass at zero ({kde_zi.prob0:.2f})", markerfacecolor="blue")
plt.plot(0, 0.4, "ro", markersize=10, label="True point mass at zero (0.4)", markerfacecolor="red")
plt.title("Zero-Inflated Data: Exponential with 40% Zeros")
plt.xlabel("x")
plt.ylabel("Density")
plt.legend()
plt.grid(True, alpha=0.3)
plt.xlim(-0.5, 10)
plt.show()
```

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

### KDE for Discrete Data (Python)

Source: https://github.com/vinecopulib/pyvinecopulib/blob/main/examples/07_kde1d.ipynb

This snippet demonstrates fitting a Kernel Density Estimator (KDE) to discrete data, specifically using a binomial distribution. It shows how to set the `type` to 'discrete' and specify bounds. The code evaluates the KDE at integer points and compares the estimated density with the true binomial probability mass function and empirical frequencies. Dependencies include numpy, scipy.stats, and pyvinecopulib.

```python
# Generate discrete data (binomial distribution)
x_binomial = np.random.binomial(n=5, p=0.5, size=500)

# Create Kde1d for discrete data
# Set type="discrete" and specify bounds [0, 5] since binomial(n=5) has support on {0,1,2,3,4,5}
kde_discrete = pv.Kde1d(xmin=0, xmax=5, type="discrete")
kde_discrete.fit(x_binomial)

print(f"Kde1d fitted to discrete data (binomial): {kde_discrete}")
print(f"Log-likelihood: {kde_discrete.loglik:.4f}")
print(f"Effective degrees of freedom: {kde_discrete.edf:.2f}")

# Evaluate density at integer points (the support of binomial distribution)
eval_points_discrete = np.array([0, 1, 2, 3, 4, 5])
density_discrete = kde_discrete.pdf(eval_points_discrete.astype(float))

print("\nDensity evaluation for discrete data:")
print("Point | Estimated | True (Binom) | Empirical Frequency")
print("------|-----------|--------------|---------------")
frequency_counts = np.bincount(x_binomial, minlength=6)
empirical_frequencies = frequency_counts / len(x_binomial)
for point in eval_points_discrete:
  estimated = kde_discrete.pdf(np.array([float(point)]))[0]
  true_density = stats.binom.pmf(point, n=5, p=0.5)
  count = np.sum(x_binomial == point)
  print(
    f"  {point}   |   {estimated:.4f}  |    {true_density:.4f}    |      {empirical_frequencies[point]:.4f}"
  )
```