
# KARDL <img src="man/figures/KARDL.png" align="right"/>

[![R-CMD-check](https://github.com/karamelikli/kardl/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/karamelikli/kardl/actions/workflows/R-CMD-check.yaml) 
[![GitHub version](https://img.shields.io/github/v/release/karamelikli/kardl)](https://github.com/karamelikli/kardl/releases) 
[![License: GPL-3](https://img.shields.io/badge/license-GPL--3-blue.svg)](https://opensource.org/licenses/GPL-3.0) 
[![CRAN downloads](https://cranlogs.r-pkg.org/badges/kardl)](https://cran.r-project.org/package=kardl) 
[![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable)

## Introduction

The `kardl` package is an R tool for estimating symmetric and asymmetric Autoregressive Distributed Lag (ARDL) and Nonlinear ARDL (NARDL) models, designed for econometricians and researchers analyzing cointegration and dynamic relationships in time series data. It offers flexible model specifications, allowing users to include deterministic variables, asymmetric effects for short- and long-run dynamics, and trend components. The package supports customizable lag structures, model selection criteria (AIC, BIC, AICc, HQ), and parallel processing for computational efficiency. Key features include:

- **Flexible Formula Specification**: Use `Asymmetric()`, `Lasymmetric()`, and `Sasymmetric()` to model asymmetric effects in short- and long-run dynamics, and `deterministic()` for dummy variables.
- **Lag Optimization**: Choose between automatic lag selection (`"quick"`, `"grid"`, `"grid_custom"`) or user-defined lags.
- **Dynamic Analysis**: Compute long-run coefficients, perform cointegration tests (PSS F, PSS t, Narayan), and ECM estimation.

This vignette demonstrates how to use the `kardl()` function to estimate an asymmetric ARDL model, perform diagnostic tests, and visualize results, using economic data from Turkey. 

## Installation

`kardl` in R can easily be installed from its CRAN repository:

``` r

install.packages("kardl")
library(kardl)
```

Alternatively, you can use the `devtools` package to load directly from GitHub:

``` r

# Install required packages
install.packages(c("stats", "msm", "lmtest", "nlWaldTest", "car", "strucchange", "utils"))
# Install kardl from GitHub
install.packages("devtools")
devtools::install_github("karamelikli/kardl")
```

Load the package:

``` r

library(kardl)
```

## Unique Features and Methodological Contributions

The `kardl` package implements several methodological extensions and improvements for ARDL/NARDL modelling that go beyond standard implementations available in R and other software:

- **different_asym_lag** option: Enables different lag orders for the positive and negative partial sum decompositions in NARDL models. This provides greater flexibility than the common symmetric lag restriction used in most existing packages.
- **Narayan cointegration test** (`narayan()`): A dedicated small-sample bounds test (Narayan, 2005) with automatic handling of critical values for cases II–V. While the test exists in the literature, its seamless integration into a full ARDL/NARDL workflow is unique in R.
- **Symmetry tests** (`symmetrytest()`): Comprehensive Wald tests for both short-run and long-run symmetry in NARDL models.
- **Bootstrap confidence intervals for dynamic multipliers**: Robust uncertainty quantification around short-run, long-run, and impact multipliers through resampling methods, fully integrated with asymmetric multiplier estimation.
- Additional advanced capabilities include highly flexible formula parsing for mixed symmetric/asymmetric regressors, multiple model selection criteria (AIC, BIC, AICc, HQ), parallel processing support, and extensive post-estimation tools tailored for asymmetric analysis.

These features make `kardl` particularly suitable for researchers needing fine-grained control over asymmetric dynamics and small-sample inference.


## Estimating an asymmetric ARDL Model

This example estimates an asymmetric ARDL model to analyze the impact of petrol prices and driving patterns on road fatalities in the UK, using the built-in `Seatbelts` dataset with variables for DriversKilled, PetrolPrice, drivers, kms, and a seatbelt law dummy variable.

### Step 1: Data Preparation

The `Seatbelts` dataset contains monthly data on road casualties in Great Britain from 1969 to 1984. It is a built-in R time series dataset that can be used directly.

Note: The `Seatbelts` dataset is a built-in R dataset included in the `datasets` package.
The data can be accessed directly without any conversion.


### Step 2: Define the Model Formula

We define the model formula using R's formula syntax, incorporating asymmetric effects and deterministic variables. We use `asymmetric()` for variables with both short- and long-run asymmetry, `lasymmetric()` for long-run asymmetry, `sasymmetric()` for short-run asymmetry, and `deterministic()` for fixed dummy variables. The `trend` term includes a linear time trend in the model.

``` r
# Define the model formula
my_formula <- DriversKilled ~ PetrolPrice + drivers + asymmetric(PetrolPrice + drivers) + deterministic(law) +
  trend
```
Indeed, the formula syntax is flexible, allowing for various combinations of asymmetric and deterministic variables. The following variations of the formula are equivalent and will yield the same model specification:

``` r
same_formula <- y ~ asymmetric(x1) +
  sasymmetric(x2 + x3) +
  lasymmetric(x4 + x5) +
  deterministic(dummy1) + trend
same_formula <- y ~ asymmetric(x1) +
  sasymmetric(x2 + x3) +
  lasymmetric(x4 + x5) +
  deterministic(dummy1) + trend
same_formula <- y ~ asym(x1) + sasym(x2 + x3) + lasym(x4 + x5) +
  det(dummy1) + trend
same_formula <- y ~ a(x1) + s(x2 + x3) + l(x4 + x5) + d(dummy1) + trend
```




### Step 3: Model Estimation

We estimate the ARDL model using different `mode` settings to demonstrate flexibility in lag selection. The `kardl()` function supports various modes: `"grid"`, `"grid_custom"`, `"quick"`, or a user-defined lag vector.

#### Using `mode = "grid"`
The `"grid"` mode evaluates all lag combinations up to `maxlag` and provides console feedback.

``` r
# Set model options
kardl_set(criterion = "BIC", different_asym_lag = TRUE, data = Seatbelts)
# Estimate model with grid mode
kardl_model <- kardl(
  data = Seatbelts, formula = my_formula,
  maxlag = 4, mode = "grid"
)
# View results
kardl_model
```
Summary of the model provides detailed information about the estimated coefficients, standard errors, t-values, and significance levels.

``` r
# Display model summary
summary(kardl_model)
```


#### Using User-Defined Lags

Specify custom lags to bypass automatic lag selection:

``` r
kardl_model2 <- kardl(
  data = Seatbelts, my_formula,
  mode = c(2, 1, 1, 3, 0)
)
# View results
kardl_extract(kardl_model2,"opt_lag")

```
``` r
# Display model summary
summary(kardl_model2)
```



#### Using All Variables
Use the `.` operator to include all variables except the dependent variable:

``` r
kardl_set(data = Seatbelts)
kardl(formula = DriversKilled ~ . + deterministic(law), mode = "grid")
```

#### Visualizing Lag Criteria

The `lag_criteria` component contains lag combinations and their criterion values. We visualize these to compare model selection criteria (AIC, BIC, HQ).

``` r
library(dplyr)
library(tidyr)
library(ggplot2)
# Convert lag_criteria to a data frame
lag_criteria <- as.data.frame(kardl_extract(kardl_model, "lag_criteria"))
colnames(lag_criteria) <- c("lag", "AIC", "BIC", "AICc", "HQ")
lag_criteria <- lag_criteria |> mutate(across(c(AIC, BIC, HQ), as.numeric))

# Pivot to long format
lag_criteria_long <- lag_criteria |>
  select(-AICc) |>
  pivot_longer(
    cols = c(AIC, BIC, HQ),
    names_to = "Criteria",
    values_to = "Value"
  )

# Find minimum values
min_values <- lag_criteria_long |>
  group_by(Criteria) |>
  slice_min(order_by = Value) |>
  ungroup()

# Plot
ggplot(
  lag_criteria_long,
  aes(x = lag, y = Value, color = Criteria, group = Criteria)
) +
  geom_line() +
  geom_point(
    data = min_values, aes(x = lag, y = Value),
    color = "red", size = 3, shape = 8
  ) +
  geom_text(
    data = min_values, aes(x = lag, y = Value, label = lag),
    vjust = 1.5, color = "black", size = 3.5
  ) +
  labs(
    title = "Lag Criteria Comparison",
    x = "Lag Configuration",
    y = "Criteria Value"
  ) +
  theme_minimal() +
  theme(axis.text.x = element_text(angle = 45, hjust = 1))
```

#### Error Correction Model (ECM) Estimation

The `ecm()` function estimates a Restricted ECM for cointegration testing. We specify the same formula and lag structure as in the ARDL model.
``` r
ecm_model <- ecm(
  data = Seatbelts, formula = my_formula,
  maxlag = 4, mode = "grid_custom"
)
# View results
summary(ecm_model)
```


### Step 4: Long-Run Coefficients

We calculate long-run coefficients using `kardl_longrun()`, which standardizes coefficients by dividing them by the negative of the dependent variable’s long-run parameter.

``` r
# Long-run coefficients
my_long <- kardl_longrun(kardl_model)
my_long
```

The `summary()` function provides detailed information about the long-run coefficients, including standard errors, t-values, and significance levels.

``` r
# Summary of long-run coefficients
summary(my_long)
```


### Step 5: Symmetry Test

The `symmetrytest()` function performs Wald tests to assess short- and long-run asymmetry in the model.

``` r
ast <- Seatbelts |>
  kardl(
    DriversKilled ~ PetrolPrice + drivers + asymmetric(PetrolPrice + drivers) +
      deterministic(law) + trend,
    mode = c(1, 2, 3, 0, 1),
    data = _
  ) |>
  symmetrytest()
ast
```

Summary of the symmetry test provides detailed results for both long-run and short-run asymmetry tests, including F-values, p-values, hypotheses, and test decisions.

``` r
# Summary of symmetry test
summary(ast)
```



### Step 6: Cointegration Tests

We perform cointegration tests to assess long-term relationships using `pssf()`, `psst()`, and `narayan()`.

#### PSS F Bound Test

The `pssf()` function tests for cointegration using the Pesaran, Shin, and Smith F Bound test.

``` r
test_result <- kardl_model |> pssf(case = 3, signif_level = "0.05")
test_result
```

Summary of the PSS F Bound test provides detailed information about the test statistic, critical values, hypotheses, and decision regarding cointegration.

``` r
summary(test_result)
```

#### PSS t Bound Test

The `psst()` function tests the significance of the lagged dependent variable’s coefficient.

``` r
test_result <- kardl_model |> psst(case = 3, signif_level = "0.05")
test_result
```
Summary of the PSS t Bound test provides detailed information about the test statistic, critical values, hypotheses, and decision regarding cointegration.
``` r
summary(test_result)
```

#### Narayan Test

The `narayan()` function is tailored for small sample sizes. It tests for cointegration using critical values optimized for small samples.

``` r
test_result <- kardl_model |> narayan(case = 3, signif_level = "0.05")
test_result
```
Summary of the Narayan test provides detailed information about the test statistic, critical values, hypotheses, and decision regarding cointegration.

``` r
summary(test_result)
```



### Step 7: Dynamic Multipliers

The `mplier()` function calculates dynamic multipliers for the model, showing how changes in independent variables affect the dependent variable over time.
``` r
multipliers <- kardl_model |> mplier()
# View multipliers of the model
head(kardl_extract(multipliers, "multipliers"))
# View long-run multipliers
kardl_extract(multipliers, "omega")
# View short-run multipliers
head(kardl_extract(multipliers, "lambda"))
```

Plotting dynamic multipliers for specific variables can be done using the `plot()` function, which visualizes the response of the dependent variable to changes in independent variables over time.
``` r
plot(multipliers, variables = c("PetrolPrice", "drivers"))
```

 
 To handle a large number of variables, you can specify a subset of variables to plot or use `variables = "all"` to visualize all dynamic multipliers.
 
 Bootstrap confidence intervals for dynamic multipliers can be calculated using the `bootstrap()` function, which provides robust estimates of uncertainty around the multipliers.
``` r
bootstrap_results <- kardl_model |>
  bootstrap(horizon = 12, replications = 10)
# View bootstrap summary
summary(bootstrap_results)
```

Visualize bootstrap results for specific variables to understand the variability and confidence intervals of the dynamic multipliers.

``` r
plot(bootstrap_results, variables = "PetrolPrice")
```
 


### Step 8: Customizing asymmetric Variables

We demonstrate how to customize prefixes and suffixes for asymmetric variables using `kardl_set()`.

``` r
# Set custom prefixes and suffixes
kardl_reset()
kardl_set(asym_prefix = c("asyP_", "asyN_"), asym_suffix = c("_PP", "_NN"))
kardl_custom <- kardl(data = Seatbelts, my_formula)
kardl_custom
```

## Key Functions and Parameters

- **`kardl(data, model, maxlag, mode, ...)`**:
  - `data`: A time series dataset (e.g., a data frame with DriversKilled, PetrolPrice, drivers).
  - `formula`: A formula specifying the long-run equation, e.g., `y ~ x + z + asymmetric(z) + lasymmetric(x2 + x3) + sasymmetric(x3 + x4) + deterministic(dummy1 + dummy2) + trend`. Supports:
    - `asymmetric()`: asymmetric effects for both short- and long-run dynamics.
    - `lasymmetric()`: Long-run asymmetric variables.
    - `sasymmetric()`: Short-run asymmetric variables.
    - `deterministic()`: Fixed dummy variables.
    - `trend`: Linear time trend.
  - `maxlag`: Maximum number of lags (default: 4). Use smaller values (e.g., 2) for small datasets, larger values (e.g., 8) for long-term dependencies.
  - `mode`: Estimation mode:
    - `"quick"`: Verbose output for interactive use.
    - `"grid"`: Verbose output with lag optimization.
    - `"grid_custom"`: Silent, efficient execution.
    - User-defined vector (e.g., `c(1, 2, 4, 5)` or `c(DriversKilled = 2, PetrolPrice_POS = 3, PetrolPrice_NEG = 1, drivers = 3)`).
  - Returns a list with components: `inputs`, `finalModel`, `start_time`, `end_time`, `properLag`, `time_span`, `opt_lag`, `lag_criteria`, `type` ("kardlmodel").

- **`kardl_set(...)`**: Configures options like `criterion` (AIC, BIC, AICc, HQ), `different_asym_lag`, `asym_prefix`, `Sasymuffix`, `short_coef`, and `long_coef`. Use `kardl_get()` to retrieve settings and `kardl_reset()` to restore defaults.

- **`kardl_longrun(model)`**: Calculates standardized long-run coefficients, returning `type` ("kardl_longrun"), `coef`, `delta_se`, `results`, and `starsDesc`.

- **`symmetrytest(model)`**: Performs Wald tests for short- and long-run asymmetry, returning `Lhypotheses`, `Lwald`, `Shypotheses`, `Swald`, and `type` ("symmetrytest").

- **`pssf(model, case, signif_level)`**: Performs the Pesaran, Shin, and Smith F Bound test for cointegration, supporting cases 1–5 and significance levels ("auto", 0.01, 0.025, 0.05, 0.1, 0.10).

- **`psst(model, case, signif_level)`**: Performs the PSS t Bound test, focusing on the lagged dependent variable’s coefficient.

- **`narayan(model, case, signif_level)`**: Conducts the Narayan test for cointegration, optimized for small samples (cases 2–5).

- **`ecm(data, model, maxlag, mode,  ...)`**: Conducts the Restricted ECM test for cointegration, with similar parameters to `kardl()` and case/significance level options.

For detailed documentation, use `?kardl`, `?kardl_set`, `?kardl_longrun`, `?symmetrytest`, `?pssf`, `?psst`, `?narayan`, or `?ecm`.

# Options

The options for the KARDL package are set by the `kardl_set()` function in R. The default values are set in the `kardl_set` list. You can change the options by using the `kardl_set()` function with the desired parameters. The following options are available:

| Option Name | Default | Description |
|------------------------|------------------------|------------------------|
| formula | NULL | The formula to be used for the model estimation |
| data | NULL | The data to be used for the model estimation |
| maxlag | 4 | The maximum number of lags to be considered for the model estimation |
| mode | "quick" | The mode of the model estimation, can be "quick", "grid", "grid_custom" or a user-defined vector |
| criterion | "AIC" | The criterion for model selection, can be "AIC", "BIC", "HQ" or a user-defined function |
| different_asym_lag | FALSE | If TRUE, the asymmetry lags will be different for positive and negative shocks |
| asym_prefix | c() | Prefix for asymmetry variables, default is empty |
| asym_suffix | c("\_POS", "\_NEG") | Suffix for asymmetry variables, default is "\_POS" and "\_NEG" |
| long_coef | "L{lag}.{varName}" | Prefix for long-run coefficients, default is "L1." |
| short_coef | "L{lag}.d.{varName}" | Prefix for short-run coefficients, default is "L1.d." |
| batch | "1/1" | Batch size for parallel processing, default is "1/1" |
| print_wrap | NULL | If not NULL, the output will be wrapped to the specified number of characters |

The details of the options are as follows:

### 1. model

`formula` is a formula object specifying the model to be estimated. The default value is `NULL`, which means that the user must provide a model formula when calling the `kardl()` function.

#### Details

The `model` parameter defines the structure of the ARDL or NARDL model to be estimated. It should include the dependent variable on the left side of the formula and the independent variables, asymmetric components, deterministic variables, and trend (if applicable) on the right side. The formula can include: - `Asymmetric()`: To specify variables with asymmetric effects in both short- and long -run dynamics. - `Lasymmetric()`: To specify variables with asymmetric effects only in the long-run -dynamics. - `Sasymmetric()`: To specify variables with asymmetric effects only in the short-run -dynamics. - `Deterministic()`: To include fixed dummy variables (e.g., seasonal d -ummies, event dummies). - `trend`: To include a linear time trend in the model. When constructing the `model` formula, ensure that: - All variables used in the formula are present in the `data` provided. - The formula is syntactically correct and follows R's formula conventions. - The use of asymmetric and deterministic functions is appropriate for the research question and data characteristics.

### 2. data

`data` is a data frame or time series object containing the variables to be used in the model estimation. The default value is `NULL`, which means that the user must provide a dataset when calling the `kardl()` function.

#### Details

The `data` parameter is essential for the `kardl()` function to perform model estimation. It should contain all the variables specified in the model formula, including the dependent variable and any independent variables, asymmetric components, and deterministic variables defined in the formula. The trend will be generated automatically if specified in the formula. Input data can be in the form of a data frame, tibble, or time series object (e.g., `ts`, `xts`, `zoo`).

When providing the `data`, ensure that: - The dataset is clean and free of missing values for the variables used in the model. - The variables are appropriately formatted (e.g., numeric for continuous variables). - The time series data is ordered correctly, especially if the analysis involves lagged variables.

### 3. maxlag

`maxlag` is an integer value specifying the maximum number of lags to be considered for the model estimation. The default value is `4`.

#### Details

The `maxlag` parameter sets the upper limit for the number of lags that the `kardl()` function will evaluate when optimizing the lag structure of the model. This is particularly important when using modes like `"grid"` or `"grid_custom"`, where the function systematically tests different lag combinations up to the specified maximum. When choosing a value for `maxlag`, consider the following: - **Data Frequency**: For monthly data, a `maxlag` of 4 is often sufficient to capture short-term dynamics. For quarterly data, a lower `maxlag` ( e.g., 2) may be appropriate, while for daily data, a higher `maxlag` (e.g., 8 or more) might be necessary. - **Sample Size**: A larger `maxlag` increases the number of parameters to estimate, which can be problematic with small sample sizes. Ensure that the sample size is adequate to support the number of lags being considered. - **Model Complexity**: Higher `maxlag` values lead to more complex models, which may overfit the data. Balance the need for capturing dynamics with the risk of overfitting. - **Computational Resources**: Evaluating a large number of lag combinations can be computationally intensive. Consider the available resources and time constraints when setting `maxlag`.

### 4. mode

`mode` is a character string or numeric vector specifying the mode of the model estimation. The default value is `"quick"`. The available options are:\
- **"quick"**: This mode provides a fast estimation of the model without optimizing the lags. It is suitable for initial explorations or when the user has a predefined lag structure. - **"grid"**: This mode performs a grid search over all possible lag combinations up to the specified `maxlag`. It provides verbose output, including the lag criteria for each combination, and is useful for thorough lag optimization. - **"grid_custom"**: Similar to `"grid"`, but with silent execution. It is more efficient for large datasets or when the user wants to avoid console output during the lag optimization process. - **User-defined vector**: The user can specify a custom lag structure by providing a numeric vector (e.g., `c(1, 2, 4, 5)`) or a named vector (e.g., `c(DriversKilled = 2, PetrolPrice_POS = 3, PetrolPrice_NEG = 1, drivers = 3)`). This allows for complete control over the lag selection process.

#### Details

The `mode` parameter determines how the `kardl()` function approaches the estimation of the ARDL or NARDL model. Each mode has its advantages and is suited to different scenarios: - Use `"quick"` for rapid assessments when the lag structure is already known or when computational speed is a priority. - Use `"grid"` for comprehensive lag optimization, especially when the optimal lag structure is unknown. This mode is ideal for exploratory analysis and model selection. - Use `"grid_custom"` for efficient lag optimization without console output, particularly for large datasets or when running multiple models in batch mode. - Use a user-defined vector when the user has specific knowledge about the appropriate lags for each variable, allowing for tailored model specifications. When using `"grid"` or `"grid_custom"`, ensure that the `maxlag` parameter is set appropriately to balance the thoroughness of the search with computational feasibility.

### 5. criterion

`criterion` is a character string specifying the criterion to be used for selecting the optimal lags. The default value is `"AIC"`. The available options are:

- **User defined function**: For detailed information on the model selection criteria used in the methods, see the documentation for the `model_criterion` function.
- **AIC**: Akaike Information Criterion (AIC). This criterion balances model fit and complexity, favoring models with a lower AIC value. It is widely used in time series analysis and model selection.
- **BIC**: Schwarz Criterion (SC), also known as the Bayesian Information Criterion (BIC). This criterion imposes a stricter penalty for model complexity compared to AIC, often leading to simpler models when data size is large.
- **AICc**: Corrected Akaike Information Criterion. This is a modification of AIC that accounts for small sample sizes. It is more reliable than AIC when the number of observations is limited.
- **HQ**: Hannan-Quinn Criterion. This criterion is similar to AIC and BIC but uses a logarithmic penalty term that grows more slowly than BIC. It is often used in econometric applications.


#### Details

For detailed information on the model selection criteria used in the methods, see the documentation for the `model_criterion` function.

The choice of the criterion can significantly impact the selected lag length and, consequently, the performance of the model. Each criterion has its strengths and is suited to specific scenarios:

- Use `"AIC"` for general purposes, especially when prioritizing a good fit over simplicity.
- Use `"BIC"` when you prefer a more parsimonious model, particularly with large datasets.
- Use `"AICc"` when working with small sample sizes to avoid overfitting.
- Use `"HQ"` for a balance between AIC and BIC, often in econometrics or time series models.

Ensure that the selected criterion aligns with the goals of your analysis and the characteristics of your data.

#### Examples

##### Default criterion (AIC)

``` r

kardl_set(criterion = "AIC")
kardl(data, my_formula)
```

##### Using BIC for lag selection

``` r

kardl_set(criterion = "BIC")
kardl(data, my_formula)
```

##### Using AICc for small sample sizes

``` r

kardl_set(criterion = "AICc")
data %>% kardl(my_formula, data=.)
```

##### Using HQ criterion

``` r

kardl_set(criterion = "HQ")
kardl(data, my_formula)
```

### 6. different_asym_lag

`different_asym_lag` is a logical value (`TRUE` or `FALSE`) indicating whether positive and negative asymmetric variables should be assigned different lags during the estimation process. The default value is `FALSE`, meaning that both positive and negative components will use the same lag.

#### Details

Asymmetric decomposition separates a variable into its positive and negative changes. In some models, it may be desirable to assign different lags to these components to capture distinct dynamic behaviors. Setting `different_asym_lag = TRUE` allows the function to optimize lags for positive and negative components independently. When `different_asym_lag = FALSE`, both components will share the same lag.

This parameter is particularly useful when:

- Positive and negative changes in a variable are expected to have different impacts over time.
- The user wants more flexibility in modeling asymmetric responses.

**Attention!**

- When `different_asym_lag = TRUE`, ensure that the model has sufficient data to estimate separate lags reliably.
- For models with limited observations or a high number of variables, `different_asym_lag = FALSE` may be more robust and computationally efficient.

#### Examples

##### Using the same lag for positive and negative components (default)

``` r

kadrl_set(different_asym_lag = FALSE)
kardl(data, my_formula)
```

##### Assigning different lags for positive and negative components

``` r

kardl_set(different_asym_lag = TRUE)
kardl(data, my_formula)
```

### 7. asym_prefix

`asym_prefix` is a character vector specifying the prefixes used for naming asymmetric variables created during positive and negative decomposition. The default value is an empty vector `c()`, indicating that no prefixes are added by default.

When specified, the prefixes are added to the beginning of variable names to represent the positive and negative decomposition:

- The first element in the vector corresponds to the positive decomposition.
- The second element in the vector corresponds to the negative decomposition.

#### Details

Asymmetric decomposition is used to analyze the separate effects of positive and negative changes in a variable. For example, given a variable `X`, prefixes can be used to generate `POS_X` and `NEG_X` for the positive and negative components, respectively.

By default, no prefixes are applied (`asym_prefix = c()`). However, users can define custom prefixes by providing a vector with two elements. For example:

- `kardl_set(asym_prefix = c("POS_", "NEG_"))` results in variable names such as `POS_X` and `NEG_X`.
- `kardl_set(asym_prefix = c("Increase_", "Decrease_"))` results in variable names such as `Increase_X` and `Decrease_X`.

**Attention!**

- The vector must contain exactly two elements: the first for the positive decomposition and the second for the negative decomposition.
- If prefixes are used in combination with suffixes (via `asym_suffix`), ensure that the resulting variable names are meaningful and do not conflict.

### Examples

#### Using default (no prefixes)

``` r

kardl_set( asym_prefix = c())
```

#### Custom prefixes for positive and negative decomposition

``` r

kardl_set(asym_prefix = c("POS_", "NEG_"))
```

#### Combining prefixes with suffixes

``` r

kardl_set( asym_prefix = c("Change_", "Fall_"), asym_suffix = c("_High", "_Low"))
```

### 8. asym_suffix

`asym_suffix` is a character vector specifying the suffixes used for naming asymmetric variables created during positive and negative decomposition. The default value is `c("_POS", "_NEG")`, where:

- `"_POS"` is the suffix appended to variables representing the positive decomposition.
- `"_NEG"` is the suffix appended to variables representing the negative decomposition.

##### Details

The order of the suffixes is important:

- The first element in the vector corresponds to the positive decomposition.
- The second element in the vector corresponds to the negative decomposition.

Asymmetric decomposition is commonly used in models to separate the effects of positive and negative changes in a variable. For example, given a variable `X`, the decomposition may result in `X_POS` and `X_NEG` to represent its positive and negative components, respectively.

By default, the suffixes `"_POS"` and `"_NEG"` are used, but users can customize them as needed by providing a custom vector. For example:

- `asym_suffix = c("_Increase", "_Decrease")` results in variable names such as `X_Increase` and `X_Decrease`.
- `asym_suffix = c("_Up", "_Down")` results in variable names such as `X_Up` and `X_Down`.

**Attention!**

- Ensure that the custom suffix vector has exactly two elements:
  - The first element must always represent the positive decomposition.
  - The second element must always represent the negative decomposition.
- Providing more or fewer elements or incorrect ordering may cause errors in variable naming.

### 9. long_coef

`long_coef` is a character string specifying the prefix format for naming long-run coefficients in the model output. The default value is `"L{lag}.{varName}"`, where:

- `{lag}` is a placeholder for the lag number.
- `{varName}` is a placeholder for the variable name.

This format generates names like `L1.X` for the first lag of variable `X`.

#### Details

Long-run coefficients represent the long-term relationships between the dependent variable and independent variables in an ARDL or NARDL model. The `long_coef` parameter allows users to customize how these coefficients are named in the output, making it easier to identify and interpret them. The default format `"L{lag}.{varName}"` is widely used and provides clear information about the lag and variable associated with each coefficient. Users can modify the format by changing the `long_coef` string. For example:

- `long_coef = "LongRun_{varName}_Lag{lag}"` results in names like `LongRun_X_Lag1`.
- `long_coef = "LR_{varName}_L{lag}"` results in names like `LR_X_L1`.

**Attention!**

- Ensure that the placeholders `{lag}` and `{varName}` are included in the custom format to maintain clarity in the coefficient names.
- Avoid using special characters or spaces in the format that may cause issues in R variable naming conventions.

### 10. short_coef

`short_coef` is a character string specifying the prefix format for naming short-run coefficients in the model output. The default value is `"L{lag}.d.{varName}"`, where:

- `{lag}` is a placeholder for the lag number.
- `{varName}` is a placeholder for the variable name.

This format generates names like `L1.d.X` for the first lag of the differenced variable `X`.

#### Details

Short-run coefficients capture the immediate effects of changes in independent variables on the dependent variable in an ARDL or NARDL model. The `short_coef` parameter allows users to customize how these coefficients are named in the output, facilitating easier identification and interpretation. The default format `"L{lag}.d.{varName}"` is commonly used and provides clear information about the lag, differencing, and variable associated with each coefficient. Users can modify the format by changing the `short_coef` string. For example:

- `short_coef = "ShortRun_{varName}_Lag{lag}"` results in names like `ShortRun_X_Lag1`.
- `short_coef = "SR_{varName}_L{lag}"` results in names like `SR_X_L1`.

**Attention!**

- Ensure that the placeholders `{lag}` and `{varName}` are included in the custom format to maintain clarity in the coefficient names.
- Avoid using special characters or spaces in the format that may cause issues in R variable naming conventions.

### 11. batch

`batch` is a character string specifying the batch size for parallel processing during model estimation. The default value is `"1/1"`, indicating that the model estimation will be executed as a single job without batching.

#### Details

The `batch` parameter is particularly useful when dealing with large datasets or complex models that require significant computational resources. By specifying a batch size, users can divide the model estimation process into smaller, more manageable segments, which can be processed in parallel. The format for the `batch` parameter is `"m/n"`, where:

- `m` is the number of batches to be processed in parallel.
- `n` is the total number of batches.

For example, setting `batch = "2/4"` would divide the estimation into 4 batches, with 2 batches being processed simultaneously. This can significantly reduce computation time, especially for models with extensive lag structures or large numbers of variables.

**Attention!**

- Ensure that the specified batch size is appropriate for the available computational resources (e.g., CPU cores, memory).
- Overloading the system with too many parallel processes may lead to performance degradation or failures.
- The effectiveness of batching may vary depending on the specific model and dataset characteristics.

#### Examples

##### Default batch size (no batching)

``` r
kardl_set(batch = "1/1")
kardl(data, my_formula)
```

##### Using a batch size of 2 out of 4

``` r
kardl_set(batch = "2/4")
kardl(data, my_formula)
```

##### Using a batch size of 3 out of 6

``` r
kardl_set(batch = "3/6")
kardl(data, my_formula)
```

### 12. print_wrap

`print_wrap` is an optional parameter that specifies the maximum number of characters per line for console output. The default value is `NULL`, which means that the output will not be wrapped and will be displayed in its entirety.
 
#### Examples

##### Default (no wrapping)

``` r
kardl_set(print_wrap = NULL)
```

##### Custom wrapping (e.g., 80 characters per line)
``` r
kardl_set(print_wrap = 80L)
```




## Contributing to kardl

Thank you for considering contributing to the `kardl` package!

### Life Cycle Statement

This package is **in a stable state of development, with active subsequent development primarily in response to user feedback.**

The core functionality for linear and nonlinear ARDL/NARDL estimation, dynamic multipliers, symmetry tests, Narayan cointegration test, and bootstrap methods is considered stable and reliable.

Future development will mainly focus on: 
- Fixing bugs reported by users 
- Addressing feature requests (e.g., additional post-estimation tools, new test options, or performance improvements) 
- Maintaining compatibility with newer R versions and dependencies 
- Minor enhancements based on community needs

Major new methodological features will only be added if they align with clear user demand or important advancements in the econometric literature.

### How to Contribute

- Report bugs or suggest features by opening an issue on GitHub.
- Submit pull requests for bug fixes or improvements.
- All contributions are welcome and will be properly acknowledged.

For questions or discussions, please open an issue.

## Conclusion

The `kardl` package is a versatile tool for econometric analysis, offering robust support for symmetric and asymmetric ARDL/NARDL modeling, cointegration tests. Its flexible formula specification, lag optimization, and support for parallel processing make it ideal for studying complex economic relationships. For more information, visit <https://github.com/karamelikli/kardl> or contact the authors at [hakperest\@gmail.com](mailto:hakperest@gmail.com).

## Disclosures

- The logo created by **canva.com** free account.
