---
title: "PFWIM Workflow"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{PFWIM Workflow}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

# Introduction

This vignette demonstrates how to use the PFWIM package to infer
consumer–resource interactions from trait data, and generate
hypothetical realized food webs using a power-law link distribution.

This workflow demonstrates:

1. Inferring feasible interactions with `infer_edgelist()`.
2. Downsampling interactions into hypothetical realized webs with `powerlaw_prey()`.
3. Customizing link distributions via the `func` argument.

Users can now use these realised webs for **network analyses**,  
simulation studies, or **comparisons to fossil and modern food webs**.

```{r setup, message=FALSE, warning=FALSE}
library(dplyr)
library(tidyr)
library(pfwim)

# Load example data included in the package
data("traits", package = "pfwim")
data("feeding_rules", package = "pfwim")
```

## Data Structure Requirements

Before running the inference model, ensure your data is formatted correctly. The `infer_edgelist()` function requires two specific data.frame objects.

### Taxon Trait Data (`data`)

This table contains the taxa along with their physical or ecological characteristics. Each row is a unique taxon, and columns represent specific traits.

Taxon Column: A unique identifier for each species or group (*e.g.,* "species").

Trait Columns: Categorical traits (*e.g.,* habitat, tiering, motility) or numerical traits (*e.g.,* body size).

```{r trait-preview}
# Preview the input structure
head(traits)
```

### Feeding Rules (`cat_combo_list`)

This table acts as the logic engine. It defines which consumer traits are compatible with which resource traits. It needs to contain both the broader trait category (column names in the trait data frame) as well as the specific trait class (the row entries for each trait column)

```{r rules-preview}
# Preview the input structure
head(feeding_rules)
```

## Infer Edgelist

Infer interactions using categorical trait rules

```{r infer-edgelist}

edgelist <- infer_edgelist(
  data = traits,
  cat_combo_list = feeding_rules,
  col_taxon = "species",
  certainty_req = "all",
  hide_printout = TRUE
)

head(edgelist)
```

## Generate Realised Webs with Power-Law

Generate 5 hypothetical realised webs

```{r powerlaw-webs}
realised_webs <- powerlaw_prey(
  el = edgelist,
  n_samp = 5,
  y = 2.5
)

# Inspect first realised web
realised_webs[[1]]
```

## Customizing the Power-Law Distribution

```{r custom-func}
# Define a custom in-degree distribution function
custom_func <- function(r, M, y) (M - r + 1)^(-y)

realised_webs_custom <- powerlaw_prey(
  el = edgelist,
  n_samp = 5,
  y = 2,
  func = custom_func
)

# First custom web
realised_webs_custom[[1]]
```