{"id":14066344,"url":"https://github.com/GlobalEcologyLab/poems","last_synced_at":"2025-07-29T23:30:39.980Z","repository":{"id":56934215,"uuid":"315204459","full_name":"GlobalEcologyLab/poems","owner":"GlobalEcologyLab","description":"Pattern-oriented ensemble modelling and simulation (with spatially explicit populations)","archived":false,"fork":false,"pushed_at":"2025-05-07T18:45:25.000Z","size":16334,"stargazers_count":10,"open_issues_count":1,"forks_count":2,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-07-12T17:44:28.700Z","etag":null,"topics":["biogeography","population-model","process-based","r","r-package","rstats"],"latest_commit_sha":null,"homepage":"https://globalecologylab.github.io/poems/","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GlobalEcologyLab.png","metadata":{"files":{"readme":"README.Rmd","changelog":"NEWS.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":"codemeta.json","zenodo":null}},"created_at":"2020-11-23T04:56:52.000Z","updated_at":"2025-05-07T18:42:14.000Z","dependencies_parsed_at":"2024-02-19T18:22:04.284Z","dependency_job_id":"814c5023-16f7-4a7b-a396-1221e364cf9f","html_url":"https://github.com/GlobalEcologyLab/poems","commit_stats":{"total_commits":114,"total_committers":7,"mean_commits":"16.285714285714285","dds":0.4035087719298246,"last_synced_commit":"49fd07fcd354628ba8093cc91841fc4e66cd161d"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/GlobalEcologyLab/poems","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GlobalEcologyLab%2Fpoems","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GlobalEcologyLab%2Fpoems/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GlobalEcologyLab%2Fpoems/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GlobalEcologyLab%2Fpoems/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GlobalEcologyLab","download_url":"https://codeload.github.com/GlobalEcologyLab/poems/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GlobalEcologyLab%2Fpoems/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267779921,"owners_count":24143198,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-29T02:00:12.549Z","response_time":2574,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["biogeography","population-model","process-based","r","r-package","rstats"],"created_at":"2024-08-13T07:05:03.229Z","updated_at":"2025-07-29T23:30:39.401Z","avatar_url":"https://github.com/GlobalEcologyLab.png","language":"R","funding_links":[],"categories":["R"],"sub_categories":[],"readme":"---\noutput: github_document\n---\n\n\u003c!-- README.md is generated from README.Rmd. Please edit that file --\u003e\n\n```{r, include = FALSE}\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\u003e\",\n  fig.path = \"man/figures/README-\",\n  out.width = \"100%\"\n)\n```\n\n# poems: Pattern-oriented ensemble modeling system (for spatially explicit populations) \u003cimg src='man/figures/logo.svg' align=\"right\" height=\"125\" /\u003e\n\n\u003c!-- badges: start --\u003e\n[![Paper_doi](https://img.shields.io/badge/doi-10.1111/2041--210X.13720-orange.svg)](https://doi.org/10.1111/2041-210X.13720)\n[![CRAN_version](https://www.r-pkg.org/badges/version/poems)](https://cran.r-project.org/package=poems)\n[![Codecov test coverage](https://codecov.io/gh/GlobalEcologyLab/poems/branch/main/graph/badge.svg)](https://app.codecov.io/gh/GlobalEcologyLab/poems?branch=main)\n[![Last commit](https://img.shields.io/github/last-commit/GlobalEcologyLab/poems.svg)](https://github.com/GlobalEcologyLab/poems/commits/main)\n[![R-CMD-check](https://github.com/GlobalEcologyLab/poems/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/GlobalEcologyLab/poems/actions/workflows/R-CMD-check.yaml)\n[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)\n\u003c!-- badges: end --\u003e\n\nThe poems package provides a framework of interoperable *R6* (Chang, 2020) classes\nfor building ensembles of viable models via the pattern-oriented modeling (POM)\napproach (Grimm et al., 2005). Pattern-oriented modeling is a vigorous form of \nstatistical validation in which simulations and their parameter settings are\nsummarized using key metrics and converged toward multiple observed patterns,\nor targets.\n\nThe package provides a process-based population model related to the \nfunctionality of RAMAS or Vortex, but in a free and open source \nformat, with high customizability. The package includes classes for encapsulating and \ngenerating model parameters, and managing the POM workflow. The workflow includes:\n\n1. Model setup including generated spatial layers and demographic population \n   model parameters.\n1. Generating model parameters via Latin hypercube sampling (Iman \u0026 Conover, 1980).\n1. Running multiple sampled model simulations.\n1. Collating summary results metrics via user-defined functions.\n1. Validating and selecting an ensemble of models that best match known patterns.\n\nBy default, model validation and selection utilizes an approximate Bayesian computation \n(ABC) approach (Beaumont et al., 2002) using the *abc* package (Csillery et al., 2015). \nHowever, alternative user-defined functionality could be employed. \n\nThe package includes a spatially explicit demographic population model simulation\nengine, which incorporates default functionality for density dependence, correlated \nenvironmental stochasticity, stage-based transitions, and distance-based dispersal. \nThe user may customize the simulator by defining functionality for translocations, \nharvesting, mortality, and other processes, as well as defining the sequence order \nfor the simulator processes. The framework could also be adapted for use with other \nmodel simulators by utilizing its extendable (inheritable) base classes.\n\n## Installation\n\nYou can install poems from the CRAN repository:\n\n``` r\ninstall.packages(\"poems\")\n```\n\nOr you can install the development version of poems from [GitHub](https://github.com/) using:\n\n``` r\n# install.packages(\"devtools\")\nremotes::install_github(\"GlobalEcologyLab/poems\")\n```\n\n## The poemsverse\n\n`poems` can do spatial population models on its own, but it also provides the engine behind two extension packages: [paleopop](https://github.com/GlobalEcologyLab/paleopop) and [epizootic](https://github.com/viralemergence/epizootic). `paleopop` is an extension for simulating populations over very long timescales, and `epizootic` is an extension for simulating disease dynamics in wild populations.\n\n## Example\n\nThe following simple example demonstrates how to run a single spatially explicit \ndemographic population model using *poems*:\n\n```{r example, message = FALSE, fig.align = \"center\"}\nlibrary(poems)\n\n# Demonstration example region (U Island) and initial abundance\ncoordinates \u003c- data.frame(\n  x = rep(seq(177.01, 177.05, 0.01), 5),\n  y = rep(seq(-18.01, -18.05, -0.01), each = 5)\n)\ntemplate_raster \u003c- Region$new(coordinates = coordinates)$region_raster # full extent\ntemplate_raster[][-c(7, 9, 12, 14, 17:19)] \u003c- NA # make U Island\nregion \u003c- Region$new(template_raster = template_raster)\ninitial_abundance \u003c- seq(0, 300, 50)\nraster::plot(region$raster_from_values(initial_abundance),\n  main = \"Initial abundance\", xlab = \"Longitude (degrees)\",\n  ylab = \"Latitude (degrees)\", zlim = c(0, 300), colNA = \"blue\"\n)\n\n# Set population model\npop_model \u003c- PopulationModel$new(\n  region = region,\n  time_steps = 5,\n  populations = 7,\n  initial_abundance = initial_abundance,\n  stage_matrix = matrix(c(\n    0, 2.5, # Leslie/Lefkovitch matrix\n    0.8, 0.5\n  ), nrow = 2, ncol = 2, byrow = TRUE),\n  carrying_capacity = rep(200, 7),\n  density_dependence = \"logistic\",\n  dispersal = (!diag(nrow = 7, ncol = 7)) * 0.05,\n  result_stages = c(1, 2)\n)\n\n# Run single simulation\nresults \u003c- population_simulator(pop_model)\nresults # examine\nraster::plot(region$raster_from_values(results$abundance[, 5]),\n  main = \"Final abundance\", xlab = \"Longitude (degrees)\",\n  ylab = \"Latitude (degrees)\", zlim = c(0, 300), colNA = \"blue\"\n)\n```\n\nFurther examples utilizing the POM workflow and more advanced features of *poems*\ncan be found in the accompanying vignettes.\n\n## Citation\n\nYou may cite poems in publications using our software paper in *Methods in Ecology and Evolution*:\n\nFordham, D. A., Haythorne, S., Brown, S. C., Buettel, J. C., \u0026 Brook, B. W. (2021). poems: R package for simulating species' range dynamics using pattern‐oriented validation. *Methods in Ecology and Evolution*, *12*(12), 2364-2371.\n\n## References\n\nBeaumont, M. A., Zhang, W., \u0026 Balding, D. J. (2002). 'Approximate Bayesian computation\nin population genetics'. *Genetics*, vol. 162, no. 4, pp, 2025–2035.\n\u003cdoi:10.1093/genetics/162.4.2025\u003e\n\nChang, W. (2020). 'R6: Encapsulated Classes with Reference Semantics'. *R package version 2.5.0*. \nRetrieved from  \u003chttps://CRAN.R-project.org/package=R6\u003e\n\nCsillery, K., Lemaire L., Francois O., \u0026 Blum M. (2015). 'abc: Tools for Approximate \nBayesian Computation (ABC)'. *R package version 2.1*. Retrieved from \n\u003chttps://CRAN.R-project.org/package=abc\u003e\n\nGrimm, V., Revilla, E., Berger, U., Jeltsch, F., Mooij, W. M., Railsback, S. F.,\nThulke, H. H., Weiner, J., Wiegand, T., DeAngelis, D. L., (2005). 'Pattern-Oriented\nModeling of Agent-Based Complex Systems: Lessons from Ecology'. *Science*\nvol. 310, no. 5750, pp. 987–991. \u003cdoi:10.1126/science.1116681\u003e\n\nIman R. L., Conover W. J. (1980). 'Small sample sensitivity analysis techniques for computer \nmodels, with an application to risk assessment'. *Commun Stat Theor Methods* A9, pp. 1749–1842.\n\u003cdoi:10.1080/03610928008827996\u003e\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGlobalEcologyLab%2Fpoems","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FGlobalEcologyLab%2Fpoems","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGlobalEcologyLab%2Fpoems/lists"}