README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

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

```{r, echo = F}
suppressPackageStartupMessages(library(phaseR))
```

# phaseR <img src='man/figures/phaseR.png' align="right" height="139" />

*Phase plane analysis of one- and two-dimensional autonomous ODE systems*

`r badger::badge_cran_release("phaseR", "green")`
`r badger::badge_cran_download("phaseR", "grand-total")`
`r badger::badge_cran_download("phaseR", "last-month")`
`r badger::badge_doi("10.32614/RJ-2014-023", "green")`
`r badger::badge_devel("mjg211/phaseR", "blue")`
`r badger::badge_code_size("mjg211/phaseR")`
`r badger::badge_custom("contributions", "welcome", "blue")`

## Description

__phaseR__ provides functions to perform a qualitative analysis of one- and two-dimensional autonomous ordinary differential equation (ODE) systems, using phase plane methods.
Programs are available to identify and classify equilibrium points, plot the direction field, and plot trajectories for multiple initial conditions.
In the one-dimensional case, a program is also available to plot the phase portrait.
Whilst in the two-dimensional case, programs are additionally available to plot nullclines and stable/unstable manifolds of saddle points.
Many example systems are provided for the user.

## Getting started

You can install the released version of __phaseR__ from [CRAN](https://CRAN.R-project.org) with:

``` r
install.packages("phaseR")
```

Alternatively, the latest development version available from [GitHub](https://github.com/) can be installed with:

``` r
devtools::install_github("mjg211/phaseR")
```

An introductory example of how to make use of the package's core functionality can be found below.
More detailed support is available in the package vignette, which can be accessed with `vignette("introduction", package = "phaseR")`.
For further help, please contact [Michael Grayling](https://www.newcastle-biostatistics.com/staff/michael_grayling/) at michael.grayling@newcastle.ac.uk.

## Example

As a basic example, we consider analysing the non-linear two-dimensional system of ODEs provided in __phaseR__ via `example12()`.
By hand, we typically first locate the nullclines and then identify the equilibrium points.
Following this, we produce a plot from which trajectories can be sketched.
This can all be seamlessly carried out in __phaseR__ with:
```{r}
example12_flowField   <- flowField(example12,
                                   xlim = c(-4, 4),
                                   ylim = c(-4, 4),
                                   add  = FALSE)
example12_nullclines  <- nullclines(example12,
                                    xlim   = c(-4, 4), 
                                    ylim   = c(-4, 4),
                                    points = 500)
y0                    <- matrix(c( 2,  2,
                                  -3,  0,
                                   0,  2,
                                   0, -3), 
                                nrow  = 4,
                                ncol  = 2,
                                byrow = TRUE)
example12_trajectory  <- trajectory(example12,
                                    y0   = y0,
                                    tlim = c(0, 10))
```
It appears that both of the equilibria are unstable. We could verify this by hand, but we can also perform this analysis in __phaseR__ using `stability()`:
```{r}
example12_stability_1 <- stability(example12,
                                   ystar = c(1, 1))
example12_stability_2 <- stability(example12,
                                   ystar = c(-1, -1),
                                   h     = 1e-8)
```

## References

Grayling MJ (2014) phaseR: An R package for phase plane analysis of autonomous ODE systems. *The R Journal* 6(2):43-51. DOI: [10.32614/RJ-2014-023](https://doi.org/10.32614/RJ-2014-023).