# EcoNiche workflow

This vignette demonstrates the EcoNiche workflow using the built-in plant community example data.

## Input data

EcoNiche expects a taxon-by-sample abundance matrix and a sample-by-variable environmental table. The sample IDs in `colnames(plant_otu)` match `rownames(plant_env)` and `names(plant_group)`.

    data("plant_otu")
    data("plant_env")
    data("plant_group")

    dim(plant_otu)

    ## [1] 1038  290

    dim(plant_env)

    ## [1] 290  11

    table(plant_group)[1:5]

    ## plant_group
    ## BDGS_BDGS   BTM_BTM   BYS_BYS   DHY_DHY   DMS_DMS
    ##        10        10        10        10         4

For fast examples, we retain species observed in at least 15 samples.

    otu_ex <- plant_otu[rowSums(plant_otu > 0) >= 15, ]
    dim(otu_ex)

    ## [1] 200 290

## CCA / partial-CCA workflow

The CCA workflow uses multiple environmental variables to define the focal composite gradient and annual mean temperature as the covariate and plotting gradient.

    cca_res <- cca_workflow_gradient(
      otu = otu_ex,
      env = plant_env,
      sel = c("AMP", "Moisture", "AP", "pH"),
      covariates = "AMT",
      var = "AMT",
      method = "loess",
      galaxy_colnum = FALSE,
      make_plot = FALSE,
      top_node = 20
    )

    names(cca_res)

    ## [1] "step1" "step2" "step3" "step4"

    head(cca_res$step3$species)

    ##                          NichePosition NicheWidth
    ## Zanthoxylum.echinocarpum     0.1697882     4.7420
    ## Xanthophyllum.hainanense     1.7444806     5.3941
    ## Vitis.amurensis             -1.0263057     5.6119
    ## Viburnum.erosum             -0.5273252    10.2469
    ## Viburnum.dilatatum          -0.5462778     8.7614
    ## Viburnum.betulifolium       -0.3724929     5.2418

## Group-level workflow

    group_res <- cca_workflow_group(
      otu = otu_ex,
      env = plant_env,
      group = plant_group,
      sel = c("AMP", "Moisture", "AP", "pH"),
      covariates = "AMT",
      var = "AMT",
      choice = "all",
      method = "loess",
      plot_type = "sample",
      galaxy_colnum = FALSE,
      make_plot = FALSE
    )

    names(group_res)

    ## [1] "step1" "step2" "step5" "step6"

    head(group_res$step6$data)

    ##          ENV NicheWidth NicheWdithSD
    ## DQS_DQS1 1.5   5.815143     2.058778
    ## DQS_DQS2 1.5   5.657917     2.208762
    ## DQS_DQS3 1.5   5.657917     2.208762
    ## DQS_DQS4 1.5   5.307614     2.219123
    ## DQS_DQS5 1.5   6.118060     2.123746
    ## DQS_DQS6 1.5   5.620067     2.233015

## GAM response analysis

GAMs can be used to estimate taxon optima and response breadth along a single gradient.

    otu_gam <- plant_otu[rowSums(plant_otu > 0) >= 20, ]

    gam_res <- gam_fit_model(
      otu = otu_gam,
      env = plant_env,
      env_var = "AMT",
      data_type = "count",
      count_family = "nb",
      use_offset = TRUE,
      min_prev = 0.10,
      min_total = 20,
      k_spline = 5,
      n_grid = 100,
      verbose = FALSE
    )

    head(gam_res)

    ##                         OTU n_nonzero prevalence total_counts r2  dev_expl
    ## 7         Spiraea.pubescens        57  0.1965517          978 NA 0.8008558
    ## 12      Rhododendron.simsii        38  0.1310345          528 NA 0.7288264
    ## 14     Quercus.wutaishanica        64  0.2206897         1586 NA 0.8141505
    ## 18           Pinus.armandii        31  0.1068966          401 NA 0.8160050
    ## 30 Daphniphyllum.macropodum        41  0.1413793          184 NA 0.6504727
    ## 39         Carpinus.viminea        52  0.1793103          396 NA 0.6238261
    ##         edf   F_stat p_value optimum_env env50_min env50_max breadth50
    ## 7  2.876958 73.23198       0    1.500000  1.500000  2.663636 1.1636364
    ## 12 3.857311 51.25146       0   10.421212 10.033333 10.809091 0.7757576
    ## 14 2.842716 84.33932       0    5.572727  2.857576  6.930303 4.0727273
    ## 18 3.762329 76.05598       0    6.736364  6.348485  7.318182 0.9696970
    ## 30 2.638485 40.99768       0   11.778788 10.809091 12.748485 1.9393939
    ## 39 3.924044 41.33183       0   10.033333  9.645455 10.421212 0.7757576

## Levins breadth along a binned gradient

    levins_res <- levins_calc_binned(
      otu = otu_ex,
      env = plant_env,
      axis_var = "AMT",
      nbin = 8,
      bin_method = "equal_freq",
      min_occ = 3,
      min_abund = 5
    )

    head(levins_res)

    ##                       OTU axis n_states levins_B levins_Bstd n_samples
    ## 1       Spiraea.pubescens  AMT        8 1.600861  0.08583722        57
    ## 2    Quercus.wutaishanica  AMT        8 1.699995  0.09999926        64
    ## 3          Quercus.aliena  AMT        8 1.838842  0.11983455        25
    ## 4      Quercus.acutissima  AMT        8 1.748160  0.10688006        31
    ## 5       Lespedeza.bicolor  AMT        8 3.792412  0.39891596        42
    ## 6 Indosasa.shibataeaoides  AMT        8 1.246672  0.03523889        18
    ##   total_abund
    ## 1    8.128477
    ## 2   15.323397
    ## 3    5.140355
    ## 4    6.668544
    ## 5    5.226307
    ## 6   10.465862