| Title: | Utility Functions for 'CDMetaPOP' |
| Version: | 1.0.0 |
| Description: | Provides a set of helper functions to launch, analyze, and visualize the output files of 'CDMetaPOP' https://computationalecologylab.github.io/cdmetapop_web/. |
| Imports: | ggplot2, tidyr, tidyselect, dplyr, adegenet, gdistance, graph4lg, poppr, shiny, shinyBS, terra |
| License: | GPL-2 | GPL-3 [expanded from: GPL (≥ 2)] |
| Encoding: | UTF-8 |
| RoxygenNote: | 7.3.3 |
| Suggests: | knitr, pkgload, rmarkdown, tidyverse, testthat (≥ 3.0.0) |
| Config/testthat/edition: | 3 |
| VignetteBuilder: | knitr |
| Language: | en-US |
| NeedsCompilation: | no |
| Packaged: | 2026-07-02 08:54:19 UTC; domi |
| Author: | Dominique Alò |
| Maintainer: | Dominique Alò <dominiquealo@gmail.com> |
| Repository: | CRAN |
| Date/Publication: | 2026-07-09 09:10:14 UTC |
Determine the proportions of the age structure of the population
Description
This function summarizes the proportions of the age structure in the simulated population. It is calculated counting the values in the column 'age' of the chosen 'ind' generation.
Usage
age_structure_proportions(
path = system.file("extdata", "Example_dat", package = "cdmetapopR"),
runs = 1,
gen = 49,
species = 0
)
Arguments
path |
path to the simulation folder |
runs |
integer referring to the number of montecarlo simulations output files to examine. It refers to the mcruns option in the RunVars CDMetaPOP input file. Right now it defaults to 1, which would be only one montecarlo run. |
gen |
Simulation run time (generation or year). Refers to runtime in the RunVars of CDMetaPOP input file. Currently defaults to 49. |
species |
If the simulation includes more species... The code for this needs to be adjusted |
Value
a dataframe with a column for each montecarlo run (MC) with the proportion of the population for each given age (in rows) and the last column with the average value across all montecarlo runs at any given age.
Examples
mypath <- system.file("extdata", "Example_dat", package = "cdmetapopR")
age_structure_proportions(path = paste0(mypath, "/"), runs = 1, gen = 9)
Plot Individual-Level Allele Frequencies
Description
Calculates allele frequencies from L#A# genotype columns in CDMetaPOP
ind##.csv or ind##_Sample.csv files.
Usage
allele_frequencies_ind(
path,
year = 0,
run = 0,
batch = 0,
mc = 0,
species = 0,
file_type = "ind",
patches = "all",
loci = NULL,
group_col = "PatchID",
jitter = TRUE
)
Arguments
path |
A dataframe, file path, vector of file paths, run directory, or top-level output directory containing individual files. |
year |
Integer. Year/generation to plot for one-year plots. Defaults to
|
run |
Integer. Run index used when |
batch |
Integer. Batch index used when |
mc |
Integer. Monte Carlo index used when |
species |
Integer. Species index used when |
file_type |
Character. Which individual file type to read. Use
|
patches |
Patch IDs to include. Use |
loci |
Optional vector of loci to include, such as |
group_col |
Column used for grouping frequencies. Defaults to
|
jitter |
Logical. If |
Value
A ggplot object with frequency data in plot$data.
Examples
ex_dir <- system.file("extdata", "Example_dat", package = "cdmetapopR")
allele_frequencies_ind(ex_dir, year = 9)
allele_frequencies_ind(ex_dir, year = 9, jitter = FALSE)
Convert CDMetaPOP data to GENEPOP or GENALEX format
Description
This function reads a CDMetaPOP CSV file, processes the genetic loci,
and converts the data into GENEPOP or GENALEX formats.
Usage
cdmetapop_to_gene(path, format = "genepop", output_dir = tempdir())
Arguments
path |
Character string; the file path to the |
format |
A character string indicating the desired output format: "genepop" or "genalex". Genepop is default. |
output_dir |
Character string; the directory where output files will be written. Defaults to tempdir(). |
Value
The function writes the GENEPOP or GENALEX formatted data to the specified output directory.
Examples
path <- system.file("extdata", "Example_dat",
"run0batch0mc0species0", "ind9.csv",
package = "cdmetapopR")
cdmetapop_to_gene(path = path, format = "genepop")
cdmetapop_to_gene(path = path, format = "genalex")
Create cost distance matrix for CDMetaPOP simulation
Description
Takes input coordinates and produces a symmetrical cost distance matrix with options for Euclidean distance, equal distance, or least cost paths based on a provided resistance surface
Usage
create_cdmat(
coords,
method = c("euclidean", "equal", "lcp"),
resistance = NULL
)
Arguments
coords |
A set of spatial coordinates in the form of a 2-column data frame or matrix |
method |
Method for creating the cost distance matrix, must be "euclidean", "equal", or "lcp" |
resistance |
Raster object representing resistance surface for generating cost distance matrix |
Details
Hello
Value
An NxN matrix of cost distances among patch locations
Examples
x <- c(1,2,3,4,5,6)
y <- c(1,2,3,4,5,6)
test <- data.frame(x=x, y=y)
create_cdmat(coords=test)
x <- runif(6, min=0, max=10)
y <- runif(6, min=0, max=10)
coords <- data.frame(x=x, y=y)
r <- terra::rast(nrows=10, ncols=10, xmin = 0, xmax = 10, ymin = 0, ymax = 10)
terra::values(r) <- 1
create_cdmat(coords=coords, method="lcp", resistance=r)
Plot Individual-Level Heterozygosity
Description
Calculates observed and expected heterozygosity from L#A# genotype columns
in CDMetaPOP ind##.csv files.
Usage
heterozygosity_ind(
path,
year = 0,
run = 0,
batch = 0,
mc = 0,
species = 0,
file_type = "ind",
patches = "all",
loci = NULL,
group_col = "PatchID",
jitter = TRUE
)
Arguments
path |
A dataframe, file path, vector of file paths, run directory, or top-level output directory containing individual files. |
year |
Integer. Year/generation to plot for one-year plots. Defaults to
|
run |
Integer. Run index used when |
batch |
Integer. Batch index used when |
mc |
Integer. Monte Carlo index used when |
species |
Integer. Species index used when |
file_type |
Character. Which individual file type to read. Use
|
patches |
Patch IDs to include. Use |
loci |
Optional vector of loci to include, such as |
group_col |
Column used for grouping frequencies. Defaults to
|
jitter |
Logical. If |
Value
A ggplot object with heterozygosity data in plot$data.
Examples
ex_dir <- system.file("extdata", "Example_dat", package = "cdmetapopR")
heterozygosity_ind(ex_dir, year = 9)
heterozygosity_ind(ex_dir, year = 9, jitter = FALSE)
Package import directives for NAMESPACE generation.
Description
Package import directives for NAMESPACE generation.
Function to facilitate the running of CDMetaPOP software from R
Description
Function to run CDMetaPOP from R
Usage
launch_cdmetapop(
pythonFilepath = "python",
CDMetaPOPFilepath = "CDMetaPOP.py",
runvarsDirectory = NULL,
runvarsFilename = "RunVars.csv",
outputDirectory = "test_"
)
Arguments
pythonFilepath |
Location of Python executable, or just 'python' if the environment is already established |
CDMetaPOPFilepath |
Location of the CDMetaPOP.py file, if already in the working directory then this can just be 'CDMetaPOP.py' |
runvarsDirectory |
Location of the directory where the RunVars.csv file is stored for the run |
runvarsFilename |
Name of the RunVars file to run |
outputDirectory |
Name of output directory to be stored in the same location as runvarsDirectory |
Details
This function will launch a command prompt (Windows) or terminal (Linux/Mac) that will call Python and supply the 5 arguments needed to launch CDMetaPOP simulations
Value
No return value. This function is called for its side effect of launching a CDMetaPOP simulation in a terminal window.
Examples
# Example: This function launches a system command to initiate CDMetaPOP.
pythonFilepath="C:/Users/User1/anaconda3/python.exe"
CDMetaPOPFilepath="C:/Users/User1/CDMetaPOP_v3.03/src/CDMetaPOP.py"
runvarsDirectory = "C:/Users/User1/CDMetaPOP_v3.03/example_files/"
runvarsFilename = "RunVars.csv"
outputDirectory = "test_"
mymodel <- launch_cdmetapop(pythonFilepath,
CDMetaPOPFilepath,
runvarsDirectory,
runvarsFilename,
outputDirectory = "test_")
Build ClassVars File from Template
Description
This function loads a provided ClassVars template, allows the user to edit selected areas, and saves the modified version as a new file.
Usage
make_classvars(output_file = "my_new_classvars.csv")
Arguments
output_file |
The name of the output file. Defaults to 'my_new_classvars.csv'. |
Value
A Shiny app instance.
Build PatchVars File from Template
Description
This function loads a provided PatchVars template, allows the user to edit selected areas, and saves the modified version as a new file.
Usage
make_patchvars(output_file = "my_new_patchvars.csv")
Arguments
output_file |
The name of the output file. Defaults to 'my_new_patchvars.csv'. |
Value
A Shiny app instance.
Build PopVars File from Template
Description
This function loads a provided PopVars template, allows the user to edit selected areas, and saves the modified version as a new file.
Usage
make_popvars(output_file = "my_new_popvars.csv")
Arguments
output_file |
The name of the output file. Defaults to 'my_new_popvars.csv'. |
Value
A Shiny app instance.
Build RunVars File from Template
Description
This function loads a provided runVars template, allows the user to edit selected areas, and saves the modified version as a new file.
Usage
make_runvars(output_file = "my_new_runvars.csv")
Arguments
output_file |
The name of the output file. Defaults to 'my_new_runvars.csv'. |
Value
A Shiny app instance.
Plot Pairwise FST Between Individual Groups
Description
Calculates pairwise FST between groups, usually patches, from L#A#
genotype columns in CDMetaPOP ind##.csv files. FST is calculated per locus
and then averaged across loci for each pair.
Usage
pairwise_fst_ind(
path,
year = 0,
run = 0,
batch = 0,
mc = 0,
species = 0,
file_type = "ind",
patches = "all",
loci = NULL,
group_col = "PatchID"
)
Arguments
path |
A dataframe, file path, vector of file paths, run directory, or top-level output directory containing individual files. |
year |
Integer. Year/generation to plot for one-year plots. Defaults to
|
run |
Integer. Run index used when |
batch |
Integer. Batch index used when |
mc |
Integer. Monte Carlo index used when |
species |
Integer. Species index used when |
file_type |
Character. Which individual file type to read. Use
|
patches |
Patch IDs to include. Use |
loci |
Optional vector of loci to include, such as |
group_col |
Column used for grouping frequencies. Defaults to
|
Value
A ggplot heatmap with pairwise FST data in plot$data.
Examples
ex_dir <- system.file("extdata", "Example_dat", package = "cdmetapopR")
pairwise_fst_ind(ex_dir, year = 9)
Plot CDMetaPOP Class Summary Dynamics
Description
Summarizes and plots data from summary_classAllTime.csv files. Inputs can
be a data frame, one file path, multiple file paths, or a CDMetaPOP output
directory containing summary_classAllTime.csv files.
Usage
summary_class(
data,
type = "age_class",
batch_labels = NULL,
show_mc = TRUE,
show_ci = TRUE,
run = 0,
batch = 0,
mc = 0,
species = 0,
...
)
Arguments
data |
A dataframe, file path ( |
type |
String specifying the plot type: |
batch_labels |
Optional named character vector used to relabel faceted
source groups. Names should match folder names such as |
show_mc |
Logical. If |
show_ci |
Logical. If |
run |
Integer run index used when |
batch |
Integer batch index used when |
mc |
Integer Monte Carlo index used when |
species |
Integer species index used when |
... |
Additional arguments passed to specific plot types. Use |
Value
A ggplot object.
Examples
ex_dir <- system.file("extdata", "Example_dat", package = "cdmetapopR")
summary_class(ex_dir, type = "age_class", n = 10)
summary_class(ex_dir, type = "age_plus_one")
Return CDMetaPOP Output Data as Data Frames
Description
Reads CDMetaPOP population, class, disease-state, or individual output files and returns data frames for custom plotting or downstream summaries.
Usage
summary_dataframe(
data,
type = c("pop", "class", "disease", "ind"),
run = 0,
batch = 0,
mc = 0,
species = 0,
years = NULL,
file_type = "ind",
patches = "all",
state_names = NULL,
cumulative_states = NULL,
state_column = "States_SecondUpdate",
disease_format = c("long", "wide"),
summary_format = c("long", "wide")
)
Arguments
data |
A data frame, file path, vector of file paths, run directory, or top-level CDMetaPOP output directory. |
type |
Character. Which file type to read: |
run |
Integer run index used when |
batch |
Integer batch index used when |
mc |
Integer Monte Carlo index used when |
species |
Integer species index used when |
years |
Optional integer vector of years/generations to include for
|
file_type |
Character. Which individual file type to read for
|
patches |
Patch IDs to include for |
state_names |
Character vector used to name disease states for
|
cumulative_states |
Character vector of disease state names to
calculate as running totals for |
state_column |
Character. Disease-state column to parse for
|
disease_format |
Character. Use |
summary_format |
Character. Use |
Value
A data frame with source metadata columns. For type = "pop" and
type = "class", the default long format includes PatchID or ClassID
indexing values split from pipe-delimited metric columns. For
type = "disease", the default long format includes State and Count
columns.
Examples
ex_dir <- system.file("extdata", "Example_dat", package = "cdmetapopR")
pop_df <- summary_dataframe(ex_dir, type = "pop")
class_df <- summary_dataframe(ex_dir, type = "class")
disease_df <- summary_dataframe(ex_dir, type = "disease")
ind_df <- summary_dataframe(ex_dir, type = "ind", years = 9)
all_mc_pop_df <- summary_dataframe(ex_dir, type = "pop", mc = "all")
Summarize CDMetaPOP Disease States
Description
Scans CDMetaPOP output directories, pulls state totals from
summary_popAllTime_DiseaseStates.csv files, and returns a faceted ggplot
comparing disease states across batches.
Usage
summary_disease(
base_path,
state_names = NULL,
scenario_names = NULL,
cumulative_states = NULL,
state_column = "States_SecondUpdate"
)
Arguments
base_path |
Character. Path to a CDMetaPOP output directory containing
|
state_names |
Character vector. Optional labels for disease states. If
|
scenario_names |
Character vector. Optional labels for batches. The first value labels batch 0, the second labels batch 1, and so on. |
cumulative_states |
Character vector. Names of states to calculate as running totals within each Monte Carlo replicate. |
state_column |
Character. Disease-state column to summarize. Defaults
to |
Value
A ggplot object.
Examples
ex_dir <- system.file(
"extdata",
"Example_dat",
package = "cdmetapopR"
)
summary_disease(ex_dir)
summary_disease(
ex_dir,
state_names = c("Susceptible", "Infected", "Recovered"),
scenario_names = c("Batch 0", "Batch 1"),
cumulative_states = "Recovered"
)
Plot CDMetaPOP Individual File Summaries
Description
Plots simple summaries from CDMetaPOP ind##.csv or
ind##_Sample.csv files. Inputs can be a data frame, one individual file,
multiple individual files, a single run folder, or a top-level CDMetaPOP
output directory containing run folders.
Usage
summary_ind(
path,
type = "age",
year = 0,
years = NULL,
run = 0,
batch = 0,
mc = 0,
species = 0,
file_type = "ind",
patches = "all",
bins = 30
)
Arguments
path |
A dataframe, file path, vector of file paths, run directory, or top-level output directory containing individual files. |
type |
String specifying the plot type: |
year |
Integer. Year/generation to plot for one-year plots. Defaults to
|
years |
Integer vector. Years/generations to include for movement
plots. If |
run |
Integer. Run index used when |
batch |
Integer. Batch index used when |
mc |
Integer. Monte Carlo index used when |
species |
Integer. Species index used when |
file_type |
Character. Which individual file type to read. Use
|
patches |
Patch IDs to include. Use |
bins |
Integer. Number of bins for continuous histograms. Defaults to
|
Value
A ggplot object.
Examples
ex_dir <- system.file("extdata", "Example_dat", package = "cdmetapopR")
summary_ind(ex_dir, type = "age", year = 9)
summary_ind(ex_dir, type = "age_size", year = 9)
summary_ind(ex_dir, type = "movement", years = 0:9, batch = 1, mc = 1)
Map CDMetaPOP Patch Abundance
Description
Creates a faceted patch map from CDMetaPOP ind##.csv or
ind##_Sample.csv files. Points are drawn at patch coordinates and scaled
by the number of individuals in each patch.
Usage
summary_patch_map(
path,
type = "abundance",
years = 0,
run = 0,
batch = 0,
mc = 0,
species = 0,
file_type = "ind",
patches = "all",
states = NULL,
facet_by_state = FALSE,
locus = NULL,
allele = NULL,
metric = "Ho",
labels = FALSE,
log_scale = FALSE,
crs = NULL
)
Arguments
path |
A dataframe, file path, vector of file paths, run directory, or top-level output directory containing individual files. |
type |
Character. What to map: |
years |
Integer vector. Years/generations to map. Defaults to |
run |
Integer. Run index used when |
batch |
Integer. Batch index used when |
mc |
Integer. Monte Carlo index used when |
species |
Integer. Species index used when |
file_type |
Character. Which individual file type to read. Use
|
patches |
Patch IDs to include. Use |
states |
Optional vector of disease states to include. If |
facet_by_state |
Logical. If |
locus |
Locus to map for genetic summaries, such as |
allele |
Allele to map for |
metric |
Heterozygosity metric to map for |
labels |
Logical. If |
log_scale |
Logical. If |
crs |
Optional coordinate reference system label. For example, use
|
Value
A ggplot object with patch-level summary data in plot$data.
Examples
ex_dir <- system.file("extdata", "Example_dat", package = "cdmetapopR")
summary_patch_map(ex_dir, years = c(0, 5, 9), crs = 5070)
summary_patch_map(ex_dir, years = c(0, 5, 9), states = 1, crs = 5070)
summary_patch_map(ex_dir, years = c(0, 9), states = c(0, 1), facet_by_state = TRUE, crs = 5070)
summary_patch_map(ex_dir, type = "allele_frequency", years = 9, locus = "L0", allele = "A1")
summary_patch_map(ex_dir, type = "heterozygosity", years = 9, locus = "L0", metric = "Ho")
Plot CDMetaPOP Population Summary Dynamics
Description
Summarizes and plots data from summary_popAllTime.csv files. Inputs can be
a data frame, one file path, multiple file paths, or a CDMetaPOP output
directory containing summary_popAllTime.csv files.
Usage
summary_pop(
data,
type = "N_initial",
batch_labels = NULL,
show_mc = TRUE,
show_ci = TRUE,
run = 0,
batch = 0,
mc = 0,
species = 0,
...
)
Arguments
data |
A dataframe, file path ( |
type |
String specifying the plot type: |
batch_labels |
Optional named character vector used to relabel faceted
source groups. Names should match folder names such as |
show_mc |
Logical. If |
show_ci |
Logical. If |
run |
Integer run index used when |
batch |
Integer batch index used when |
mc |
Integer Monte Carlo index used when |
species |
Integer species index used when |
... |
Additional arguments passed to specific plot types. Use
|
Value
A ggplot object.
Examples
ex_dir <- system.file("extdata", "Example_dat", package = "cdmetapopR")
summary_pop(ex_dir, type = "N_initial")
summary_pop(ex_dir, type = "sex")
summary_pop(ex_dir, type = "mature", include_yys = TRUE)
summary_pop(ex_dir, type = "allelic_richness")
summary_pop(ex_dir, type = "het")