Data

Tools

Indexes

Applications

Experiments

Open Source Science

blvim

Boltzmann–Lotka–Volterra Interaction Model

https://github.com/fabrice-rossi/blvim

Science Score: 39.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
  • ○
    Academic email domains
  • ○
    Institutional organization owner
  • ○
    JOSS paper metadata
  • ○
    Scientific vocabulary similarity
    Low similarity (16.7%) to scientific vocabulary

Keywords

boltzmann-lotka-volterra r r-package r-stats spatial-analysis spatial-interaction-modeling

Scientific Fields

Psychology Social Sciences - 40% confidence
Last synced: 4 months ago · JSON representation

Repository

Boltzmann–Lotka–Volterra Interaction Model

Basic Info
Statistics
  • Stars: 2
  • Watchers: 1
  • Forks: 0
  • Open Issues: 2
  • Releases: 0
Topics
boltzmann-lotka-volterra r r-package r-stats spatial-analysis spatial-interaction-modeling
Created 11 months ago · Last pushed 4 months ago
Metadata Files
Readme License Codemeta

README.Rmd 

---
output: 
  github_document
---



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

# Boltzmann–Lotka–Volterra Interaction Model



[![R-CMD-check](https://github.com/fabrice-rossi/blvim/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/fabrice-rossi/blvim/actions/workflows/R-CMD-check.yaml) [![Codecov test coverage](https://codecov.io/gh/fabrice-rossi/blvim/graph/badge.svg)](https://app.codecov.io/gh/fabrice-rossi/blvim)



`blvim` implements A. Wilson's Boltzmann–Lotka–Volterra (BLV) interaction model. The model is described in [Wilson, A. (2008), "Boltzmann, Lotka and Volterra and spatial structural evolution: an integrated methodology for some dynamical systems", J. R. Soc. Interface, 5:865–871](http://dx.doi.org/10.1098/rsif.2007.1288). The first goal of the
package is to provide a fast implementation of the BLV model with a collection of
tools designed to explore the results via statistical summaries and graphical
representations. The second goal of the package is to facilitate systematic assessment 
of the impact of the model parameters on the results, again through summaries and 
graphical representations. 

## Installation

You can install the development version of `blvim` from [GitHub](https://github.com/) with:

``` r
# install.packages("pak")
pak::pak("fabrice-rossi/blvim")
```

## Spatial interaction models

Spatial interaction models aim to estimate flows between locations, for instance, 
workers commuting from residential zones to employment zones. The focus of the 
`blvim` package is on maximum entropy models developed by Alan Wilson. See
`vignette("theory")` for a theoretical background. 

In practice, if we have $n$ origin locations and $p$ destination locations, the
aim is to compute a matrix of flows $(Y_{ij})_{1\leq i\leq n, 1\leq j\leq p}$, where
$Y_{ij}$ is the flow from origin $i$ to destination $j$. This is done using
characteristics of the origin and destination locations, together with a matrix
of exchange difficulties, a *cost matrix*, $(c_{ij})_{1\leq i\leq n, 1\leq j\leq p}$. 
For instance, $c_{ij}$ can be the distance between origin $i$ and destination $j$.

## Usage

The package is loaded in a standard way.
```{r}
library(blvim)
```

### Input data
To compute a spatial interaction model with `blvim`, one needs at least a cost 
matrix. In this example, we use the distance between some random locations.
```{r}
set.seed(42)
## random origin locations
origins <- matrix(runif(2 * 30), ncol = 2)
## random destination locations
destinations <- matrix(runif(2 * 10), ncol = 2)
## cost matrix
full_costs <- as.matrix(dist(rbind(origins, destinations)))
cost_matrix <- full_costs[1:nrow(origins), (nrow(origins) + 1):(nrow(origins) + nrow(destinations))]
```

In addition, we focus on production-constrained models, which means that we need to
specify the production of each origin location (a vector of positive values 
$(X_i)_{1\leq i\leq n}$). In this example, we assume a common unitary production.
```{r}
X <- rep(1, nrow(origins))
```

Finally, the simple *static* model needs an attractiveness value of each destination
location, a vector of positive values $(Z_j)_{1\leq j\leq p}$. We again assume
a common unitary attractiveness.
```{r}
Z <- rep(1, nrow(destinations))
```

### Static models
In Wilson's production-constrained maximum entropy model, the flows are given
by

$$
Y_{ij} = \frac{X_iZ_j^{\alpha}\exp(-\beta c_{ij})}{\sum_{k=1}^pZ_k^{\alpha}\exp(-\beta c_{ik})},
$$

where $\alpha$ is a return-to-scale parameter and $\beta$ is the inverse of a
cost scale parameter. Notice that the flow matrix is *production-constrained*, 
which means that the total outgoing flow from any origin location is equal to 
the production of this location, i.e.,

$$
\forall i,\quad X_i=\sum_{j=1}^{p}Y_{ij}.
$$

The model is obtained using the `static_blvim()` function as follows:
```{r}
a_model <- static_blvim(cost_matrix, X, alpha = 1.1, beta = 2, Z)
a_model
```

Several functions are provided to extract parts of the result. In particular
`flows()` returns the flow matrix $Y$. 
```{r}
a_model_flows <- flows(a_model)
```
which can be displayed using, e.g., the `image()` function.
```{r a_flow}
#| fig.height: 9
#| fig.width: 3
#| out.width: 25%
#| fig.align: center
par(mar = rep(0.1, 4))
image(t(a_model_flows),
  col = gray.colors(20, start = 1, end = 0),
  axes = FALSE,
  frame = TRUE
)
```

In this representation, each row gives the flows from one origin location to
all the destination location. The package provides a `ggplot2::autoplot()` function
that can be used as follows:
```{r a_flow_ggplot2}
#| fig.height: 9
#| fig.width: 4
#| out.width: 40%
#| fig.align: center
library(ggplot2)
autoplot(a_model, "full") +
  scale_fill_viridis_c() +
  coord_fixed()
```



```{r}
b_model <- static_blvim(cost_matrix, X, alpha = 1.1, beta = 15, Z)
b_model
```

```{r b_flow}
#| fig.height: 9
#| fig.width: 4
#| out.width: 40%
#| fig.align: center
autoplot(b_model) +
  scale_fill_viridis_c() +
  coord_fixed()
```

Different values of the parameters $\alpha$ and $\beta$ lead to more or less 
concentrated flows, as exemplified by the two figures above. 

### Dynamic models

A. Wilson's Boltzmann–Lotka–Volterra (BLV) interaction model is based on the 
production-constrained maximum entropy model. The main idea consists in updating
the attractiveness of the destination locations based on their incoming flows.
In the limit, we want to have

$$
Z_j =\sum_{i=1}^{n}Y_{ij}, 
$$

where the flows are given by the equations above. The model is estimated using
the `blvim()` function as follows.

```{r}
a_blv_model <- blvim(cost_matrix, X, alpha = 1.1, beta = 2, Z)
a_blv_model
```

Notice that we start with some initial values of the attractiveness, but the 
final values are different. They can be obtained using the `attractiveness()` 
function as follows (we show the values using a bar plot).

```{r a_blv_Z}
#| fig.height: 4
#| fig.width: 8
#| out.width: 80%
#| fig.align: center
par(mar = c(0.1, 4, 1, 0))
a_final_Z <- attractiveness(a_blv_model)
barplot(a_final_Z)
```
In this example, one destination location acts as a global attractor of all
the flows. This can be seen also on the final flow matrix.

```{r a_blv_flow}
#| fig.height: 9
#| fig.width: 4
#| out.width: 40%
#| fig.align: center
autoplot(a_blv_model) +
  scale_fill_viridis_c()
```

The `autoplot()` function can also be used to show the destination flows or the
attractivenesses as follows. 
```{r a_blv_Z_ggplot2}
#| fig.height: 4
#| fig.width: 8
autoplot(a_blv_model, "attractiveness")
```


Results are, of course, strongly influenced by the parameters, as shown by this 
second example.


```{r}
b_blv_model <- blvim(cost_matrix, X, alpha = 1.1, beta = 15, Z)
b_blv_model
```

```{r b_blv_Z}
#| fig.height: 4
#| fig.width: 8
autoplot(b_blv_model, "attractiveness")
```

```{r b_blv_flow}
#| fig.height: 9
#| fig.width: 4
#| out.width: 40%
#| fig.align: center
autoplot(b_blv_model) +
  scale_fill_viridis_c()
```

Owner

  • Name: Fabrice Rossi
  • Login: fabrice-rossi
  • Kind: user

CodeMeta (codemeta.json) 

{
  "@context": "https://doi.org/10.5063/schema/codemeta-2.0",
  "@type": "SoftwareSourceCode",
  "identifier": "blvim",
  "description": "Estimates Boltzmann–Lotka–Volterra (BLV) interaction model efficiently. See Wilson, A. (2008) <dx.doi.org/10.1098/rsif.2007.1288>.",
  "name": "blvim: Boltzmann–Lotka–Volterra Interaction Model",
  "codeRepository": "https://github.com/fabrice-rossi/blvim",
  "issueTracker": "https://github.com/fabrice-rossi/blvim/issues",
  "license": "https://spdx.org/licenses/GPL-3.0",
  "version": "0.0.0.9000",
  "programmingLanguage": {
    "@type": "ComputerLanguage",
    "name": "R",
    "url": "https://r-project.org"
  },
  "runtimePlatform": "R version 4.5.1 (2025-06-13)",
  "author": [
    {
      "@type": "Person",
      "givenName": "Fabrice",
      "familyName": "Rossi",
      "email": "Fabrice.Rossi@apiacoa.org",
      "@id": "https://orcid.org/0000-0003-4638-1286"
    }
  ],
  "maintainer": [
    {
      "@type": "Person",
      "givenName": "Fabrice",
      "familyName": "Rossi",
      "email": "Fabrice.Rossi@apiacoa.org",
      "@id": "https://orcid.org/0000-0003-4638-1286"
    }
  ],
  "softwareSuggestions": [
    {
      "@type": "SoftwareApplication",
      "identifier": "callr",
      "name": "callr",
      "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=callr"
    },
    {
      "@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": "dplyr",
      "name": "dplyr",
      "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=dplyr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "ggplot2",
      "name": "ggplot2",
      "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=ggplot2"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "ggrepel",
      "name": "ggrepel",
      "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=ggrepel"
    },
    {
      "@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": "pkgload",
      "name": "pkgload",
      "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=pkgload"
    },
    {
      "@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": "sf",
      "name": "sf",
      "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=sf"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "sloop",
      "name": "sloop",
      "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=sloop"
    },
    {
      "@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": "vctrs",
      "name": "vctrs",
      "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=vctrs"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "vdiffr",
      "name": "vdiffr",
      "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=vdiffr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "withr",
      "name": "withr",
      "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=withr"
    }
  ],
  "softwareRequirements": {
    "1": {
      "@type": "SoftwareApplication",
      "identifier": "cli",
      "name": "cli",
      "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=cli"
    },
    "2": {
      "@type": "SoftwareApplication",
      "identifier": "collapse",
      "name": "collapse",
      "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=collapse"
    },
    "3": {
      "@type": "SoftwareApplication",
      "identifier": "Rcpp",
      "name": "Rcpp",
      "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=Rcpp"
    },
    "4": {
      "@type": "SoftwareApplication",
      "identifier": "rlang",
      "name": "rlang",
      "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=rlang"
    },
    "5": {
      "@type": "SoftwareApplication",
      "identifier": "stats",
      "name": "stats"
    },
    "SystemRequirements": null
  },
  "fileSize": "31753.296KB",
  "relatedLink": "https://fabrice-rossi.github.io/blvim/",
  "readme": "https://github.com/fabrice-rossi/blvim/blob/main/README.md",
  "contIntegration": [
    "https://github.com/fabrice-rossi/blvim/actions/workflows/R-CMD-check.yaml",
    "https://app.codecov.io/gh/fabrice-rossi/blvim"
  ],
  "keywords": [
    "r",
    "r-package",
    "r-stats",
    "spatial-analysis",
    "spatial-interaction-modeling",
    "boltzmann-lotka-volterra"
  ]
}

GitHub Events

Total
  • Issues event: 15
  • Watch event: 2
  • Public event: 1
  • Push event: 32
  • Create event: 1
Last Year
  • Issues event: 15
  • Watch event: 2
  • Public event: 1
  • Push event: 32
  • Create event: 1

Issues and Pull Requests

Last synced: 4 months ago

All Time
  • Total issues: 9
  • Total pull requests: 0
  • Average time to close issues: 23 days
  • Average time to close pull requests: N/A
  • Total issue authors: 1
  • Total pull request authors: 0
  • Average comments per issue: 0.0
  • Average comments per pull request: 0
  • Merged pull requests: 0
  • Bot issues: 0
  • Bot pull requests: 0
Past Year
  • Issues: 9
  • Pull requests: 0
  • Average time to close issues: 23 days
  • Average time to close pull requests: N/A
  • Issue authors: 1
  • Pull request authors: 0
  • Average comments per issue: 0.0
  • Average comments per pull request: 0
  • Merged pull requests: 0
  • Bot issues: 0
  • Bot pull requests: 0
View more stats
Top Authors
Issue Authors
  • fabrice-rossi (9)
Pull Request Authors
Top Labels
Issue Labels
feature (5) documentation (2) Breaking change (1) cleanup (1)
Pull Request Labels

Dependencies

.github/workflows/pkgdown.yaml actions
  • JamesIves/github-pages-deploy-action v4.5.0 composite
  • actions/checkout v4 composite
  • r-lib/actions/setup-pandoc v2 composite
  • r-lib/actions/setup-r v2 composite
  • r-lib/actions/setup-r-dependencies v2 composite
DESCRIPTION cran
  • Rcpp * imports
  • cli * imports
  • rlang * imports
  • testthat >= 3.0.0 suggests
  • withr * suggests