Data

Tools

Indexes

Applications

Experiments

Open Source Science

rangr

Species range dynamics simulation toolset

https://github.com/ropensci/rangr

Science Score: 49.0%

This score indicates how likely this project is to be science-related based on various indicators:

  • ○
    CITATION.cff file
  • ✓
    codemeta.json file
    Found codemeta.json file
  • ✓
    .zenodo.json file
    Found .zenodo.json file
  • ✓
    DOI references
    Found 3 DOI reference(s) in README
  • ✓
    Academic publication links
    Links to: zenodo.org
  • ○
    Academic email domains
  • ○
    Institutional organization owner
  • ○
    JOSS paper metadata
  • ○
    Scientific vocabulary similarity
    Low similarity (19.2%) to scientific vocabulary
Last synced: 10 months ago · JSON representation

Repository

Species range dynamics simulation toolset

Basic Info
Statistics
  • Stars: 2
  • Watchers: 4
  • Forks: 1
  • Open Issues: 4
  • Releases: 2
Created about 3 years ago · Last pushed about 1 year ago
Metadata Files
Readme Changelog Contributing License Codemeta

README.Rmd 

---
output: github_document
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)

sapply(c("sim_data_01.rda", "sim_result_01.rda"), function(x) {
  load(file.path(system.file("extdata", package = "rangr"), x),
    envir = globalenv()
  )
})




library(rangr)
```

# rangr



[![CRAN release](https://www.r-pkg.org/badges/version/rangr?color=green)](https://cran.r-project.org/package=rangr) [![Status at rOpenSci Software Peer Review](https://badges.ropensci.org/595_status.svg)](https://github.com/ropensci/software-review/issues/595) [![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) [![R-CMD-check](https://github.com/ropensci/rangr/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/ropensci/rangr/actions/workflows/R-CMD-check.yaml) [![codecov](https://codecov.io/gh/ropensci/rangr/graph/badge.svg?token=noq7E0HSe2)](https://app.codecov.io/gh/ropensci/rangr) [![DOI](https://zenodo.org/badge/645848364.svg)](https://zenodo.org/doi/10.5281/zenodo.10569367) [![Static Badge](https://img.shields.io/badge/Publication-10.1111%2F2041--210X.14475-94ae63)](https://doi.org/10.1111/2041-210X.14475)



The **rangr** package is designed to simulate a species range dynamics. This new tool mimics the essential processes that shape population numbers and spatial distribution: local dynamics and dispersal. Simulations can be run in a spatially explicit and dynamic environment, facilitating population projections in response to climate or land-use changes. By using different sampling schemes and observational error distributions, the structure of the original survey data can be reproduced, or pure random sampling can be mimicked.

The study is supported by the National Science Centre, Poland, grant no. 2018/29/B/NZ8/00066 and the Poznań Supercomputing and Networking Centre (grant no. 403).

# Installation

## Released version

**rangr** is available from CRAN, so you can install it with:

```{r instalation_cran, eval=FALSE}
install.packages("rangr")
```

## Development version

You can install the development version from R-universe or GitHub with:

```{r instalation_dev, eval=FALSE}
install.packages("rangr", repos = "https://ropensci.r-universe.dev")
# or
devtools::install_github("ropensci/rangr")
```

# Basic simulation

Here's an example of how to use the `rangr` package.

## Input maps

Example maps available in rangr in the Cartesian coordinate system:

-   `n1_small.tif`
-   `n1_big.tif`
-   `K_small.tif`
-   `K_small_changing.tif`
-   `K_big.tif`

Example maps available in rangr in the longitude/latitude coordinate system:

-   `n1_small_lon_lat.tif`
-   `n1_big_lon_lat.tif`
-   `K_small_lon_lat.tif`
-   `K_small_changing_lon_lat.tif`
-   `K_big_lon_lat.tif`

```{r SP1.0, eval=FALSE, include=FALSE}
#' @srrstats {SP1.0} Specified domain of applicability
```

You can find additional information about these data sets in help files:

```{r help_input_maps, eval=FALSE}
library(rangr)

?n1_small.tif
?K_small.tif
```

Two of the available datasets, `n1_small.tif` and `K_small.tif`, represent the abundance of a virtual species at the starting point of a simulation and the carrying capacity of the environment, respectively. Both of these objects refer to the same relatively small area, so they are ideal for demonstrating the usage of the package. To view these maps and their dimensions, you can use the following commands:

```{r small_data, warning=FALSE}
library(terra)

n1_small <- rast(system.file("input_maps/n1_small.tif", package = "rangr"))
K_small <-  rast(system.file("input_maps/K_small.tif", package = "rangr"))
```

You can also use the `plot` function from the `terra` package to visualize these maps:

```{r vis_input_maps, fig.align='center', message=FALSE, out.width='70%'}
plot(c(n1_small, K_small))
```

## Initialise

To create a `sim_data` object containing the necessary information to run a simulation, use the `initialise()` function. For example:

```{r init}
sim_data_01 <- initialise(
  n1_map = n1_small,
  K_map = K_small,
  r = log(2),
  rate = 1 / 1e3
)
```

Here, we set the intrinsic population growth rate to `log(2)` and the rate parameter that is related to the kernel function describing dispersal to `1/1e3`.

To see the summary of the `sim_data` object:

```{r summary_sim_data}
summary(sim_data_01)
```

## Simulation

To run a simulation, use the `sim()` function, which takes a `sim_data` object and the specified number of time steps as input parameters. For example:

```{r sim, eval=FALSE}
sim_result_01 <- sim(obj = sim_data_01, time = 100)
```

To see the summary of the `sim_result_01` object:

```{r summary_sim_res, fig.align='center', message=FALSE, out.width='70%'}
summary(sim_result_01)
```

Note that this is a simple example and there are many more parameters that can be set for `initialise()` and `sim()`. See the documentation for the `rangr` package for more information.

## Visualisation

You can use `rangr` to visualise selected time steps from the simulation. The `plot()` method is used to generate the plot. Here's an example:

```{r vis_sim_res_01, warning=FALSE, fig.align='center', message=FALSE, out.width='70%'}
# generate visualisation
plot(sim_result_01,
  time_points = c(1, 10, 25, 50),
  template = sim_data_01$K_map
)
```

You can adjust the `breaks` parameter to get more breaks on the colorscale:

```{r vis_sim_res_02, warning=FALSE, fig.align='center', message=FALSE, out.width='70%'}
# generate visualisation with more breaks
plot(sim_result_01,
  time_points = c(1, 10, 25, 50),
  breaks = seq(0, max(sim_result_01$N_map + 5, na.rm = TRUE), by = 5),
  template = sim_data_01$K_map
)
```

If you prefer working on raster you can also transform any `sim_result` object into `SpatRaster` using `to_rast()` function:

```{r vis_sim_res_03, warning=FALSE, fig.align='center', message=FALSE, out.width='70%'}
# raster construction
my_rast <- to_rast(
  sim_result_01,
  time_points = 1:sim_result_01$simulated_time,
  template = sim_data_01$K_map
)

# print raster
print(my_rast)
```

And then visualise it using `plot()` function:

```{r vis_sim_res_04, warning=FALSE, fig.align='center', message=FALSE, out.width='70%'}
# plot selected time points
plot(my_rast, c(1, 10, 25, 50))
```

# Vignettes

-   [Workflow examples](https://docs.ropensci.org/rangr/articles/rangr.html)

# Citation

To cite `rangr` use `citation()` function:

```{r citation, eval=FALSE}
library(rangr)
citation("rangr")
```

# Code of Conduct

Please note that this package is released with a [Contributor Code of Conduct](https://ropensci.org/code-of-conduct/). By contributing to this project, you agree to abide by its terms.

Owner

  • Name: rOpenSci
  • Login: ropensci
  • Kind: organization
  • Email: info@ropensci.org
  • Location: Berkeley, CA

CodeMeta (codemeta.json) 

{
  "@context": "https://doi.org/10.5063/schema/codemeta-2.0",
  "@type": "SoftwareSourceCode",
  "identifier": "rangr",
  "description": "Integrates population dynamics and dispersal into a mechanistic virtual species simulator. The package can be used to study the effects of environmental change on population growth and range shifts. It allows for simple and straightforward definition of population dynamics (including positive density dependence), extensive possibilities for defining dispersal kernels, and the ability to generate virtual ecologist data. Learn more about the 'rangr' at <https://docs.ropensci.org/rangr/>.",
  "name": "rangr: Mechanistic Simulation of Species Range Dynamics",
  "relatedLink": [
    "https://docs.ropensci.org/rangr/",
    "https://doi.org/10.1111/2041-210X.14475"
  ],
  "codeRepository": "https://github.com/ropensci/rangr",
  "issueTracker": "https://github.com/ropensci/rangr/issues",
  "license": "https://spdx.org/licenses/MIT",
  "version": "1.0.7",
  "programmingLanguage": {
    "@type": "ComputerLanguage",
    "name": "R",
    "url": "https://r-project.org"
  },
  "runtimePlatform": "R version 4.3.0 (2023-04-21 ucrt)",
  "provider": {
    "@id": "https://cran.r-project.org",
    "@type": "Organization",
    "name": "Comprehensive R Archive Network (CRAN)",
    "url": "https://cran.r-project.org"
  },
  "author": [
    {
      "@type": "Person",
      "givenName": "Katarzyna",
      "familyName": "Markowska",
      "email": "katarzyna.markowska@amu.edu.pl"
    },
    {
      "@type": "Person",
      "givenName": "Lechosław",
      "familyName": "Kuczyński",
      "email": "lechu@amu.edu.pl"
    }
  ],
  "maintainer": [
    {
      "@type": "Person",
      "givenName": "Katarzyna",
      "familyName": "Markowska",
      "email": "katarzyna.markowska@amu.edu.pl"
    }
  ],
  "softwareSuggestions": [
    {
      "@type": "SoftwareApplication",
      "identifier": "knitr",
      "name": "knitr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=knitr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "rmarkdown",
      "name": "rmarkdown",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=rmarkdown"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "testthat",
      "name": "testthat",
      "version": ">= 3.0.0",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=testthat"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "covr",
      "name": "covr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=covr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "bookdown",
      "name": "bookdown",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=bookdown"
    }
  ],
  "softwareRequirements": {
    "1": {
      "@type": "SoftwareApplication",
      "identifier": "methods",
      "name": "methods"
    },
    "2": {
      "@type": "SoftwareApplication",
      "identifier": "parallel",
      "name": "parallel"
    },
    "3": {
      "@type": "SoftwareApplication",
      "identifier": "pbapply",
      "name": "pbapply",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=pbapply"
    },
    "4": {
      "@type": "SoftwareApplication",
      "identifier": "grDevices",
      "name": "grDevices"
    },
    "5": {
      "@type": "SoftwareApplication",
      "identifier": "graphics",
      "name": "graphics"
    },
    "6": {
      "@type": "SoftwareApplication",
      "identifier": "stats",
      "name": "stats"
    },
    "7": {
      "@type": "SoftwareApplication",
      "identifier": "utils",
      "name": "utils"
    },
    "8": {
      "@type": "SoftwareApplication",
      "identifier": "zoo",
      "name": "zoo",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=zoo"
    },
    "9": {
      "@type": "SoftwareApplication",
      "identifier": "terra",
      "name": "terra",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=terra"
    },
    "10": {
      "@type": "SoftwareApplication",
      "identifier": "assertthat",
      "name": "assertthat",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=assertthat"
    },
    "11": {
      "@type": "SoftwareApplication",
      "identifier": "R",
      "name": "R",
      "version": ">= 3.5.0"
    },
    "SystemRequirements": null
  },
  "fileSize": "4696.766KB",
  "citation": [
    {
      "@type": "ScholarlyArticle",
      "datePublished": "2025",
      "author": [
        {
          "@type": "Person",
          "givenName": "Katarzyna",
          "familyName": "Markowska"
        },
        {
          "@type": "Person",
          "givenName": "Katarzyna",
          "familyName": "Malinowska"
        },
        {
          "@type": "Person",
          "givenName": "Lechosław",
          "familyName": "Kuczyński"
        }
      ],
      "name": "rangr: An R package for mechanistic, spatially explicit simulation of species range dynamics",
      "identifier": "10.1111/2041-210X.14475",
      "pagination": "468-476",
      "@id": "https://doi.org/10.1111/2041-210X.14475",
      "sameAs": "https://doi.org/10.1111/2041-210X.14475",
      "isPartOf": {
        "@type": "PublicationIssue",
        "issueNumber": "3",
        "datePublished": "2025",
        "isPartOf": {
          "@type": [
            "PublicationVolume",
            "Periodical"
          ],
          "volumeNumber": "16",
          "name": "Methods in Ecology and Evolution"
        }
      }
    }
  ],
  "releaseNotes": "https://github.com/ropensci/rangr/blob/master/NEWS.md",
  "readme": "https://github.com/ropensci/rangr/blob/main/README.md",
  "contIntegration": [
    "https://github.com/ropensci/rangr/actions/workflows/R-CMD-check.yaml",
    "https://app.codecov.io/gh/ropensci/rangr"
  ],
  "developmentStatus": "https://www.repostatus.org/#active",
  "review": {
    "@type": "Review",
    "url": "https://github.com/ropensci/software-review/issues/595",
    "provider": "https://ropensci.org"
  }
}

GitHub Events

Total
  • Issues event: 2
  • Watch event: 1
  • Push event: 16
Last Year
  • Issues event: 2
  • Watch event: 1
  • Push event: 16

Packages

  • Total packages: 1
  • Total downloads:
    • cran 553 last-month
  • Total dependent packages: 0
  • Total dependent repositories: 0
  • Total versions: 3
  • Total maintainers: 1
cran.r-project.org: rangr

Mechanistic Simulation of Species Range Dynamics

  • Versions: 3
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Downloads: 553 Last month
Rankings
Dependent packages count: 27.2%
Dependent repos count: 33.5%
Average: 49.2%
Downloads: 86.9%
Maintainers (1)
katarzyna.markowska@amu.edu.pl
Last synced: 10 months ago

Dependencies

.github/workflows/R-CMD-check.yaml actions
  • actions/checkout v3 composite
  • r-lib/actions/check-r-package v2 composite
  • r-lib/actions/setup-pandoc v2 composite
  • r-lib/actions/setup-r v2 composite
  • r-lib/actions/setup-r-dependencies v2 composite
.github/workflows/pkgcheck.yaml actions
  • ropensci-review-tools/pkgcheck-action main composite
.github/workflows/pkgdown.yaml actions
  • JamesIves/github-pages-deploy-action v4.4.1 composite
  • actions/checkout v3 composite
  • r-lib/actions/setup-pandoc v2 composite
  • r-lib/actions/setup-r v2 composite
  • r-lib/actions/setup-r-dependencies v2 composite
.github/workflows/test-coverage.yaml actions
  • actions/checkout v3 composite
  • actions/upload-artifact v3 composite
  • r-lib/actions/setup-r v2 composite
  • r-lib/actions/setup-r-dependencies v2 composite
DESCRIPTION cran
  • R >= 3.5.0 depends
  • assertthat * imports
  • grDevices * imports
  • graphics * imports
  • methods * imports
  • parallel * imports
  • pbapply * imports
  • stats * imports
  • terra * imports
  • utils * imports
  • zoo * imports
  • bookdown * suggests
  • covr * suggests
  • knitr * suggests
  • rmarkdown * suggests
  • testthat >= 3.0.0 suggests