<commit_before># Brief Description

Octave code to find the evolutionarily singular breeding-time strategy for a strict, discrete-flocking resident bird species (e.g. marsh tit) in a phenologically heterogenous landscape.

# Reference

<NAME>., <NAME>., <NAME>., <NAME>. Paper in preparation.

# Quick Start

If you have git:

    $ git clone https://github.com/nadiahpk/phenology-discrete-flocking-paridae
    $ cd phenology-two-trait-migratory-bird

If you don't have git, just download and unpack the latest zip file:

[https://github.com/nadiahpk/phenology-discrete-flocking-paridae/archive/master.zip](https://github.com/nadiahpk/phenology-discrete-flocking-paridae/archive/master.zip)

## Find an evolutionarily singular strategy

In Octave,

```> default_parameter_values```

will load the parameter dictionary p into the workspace. 

The default parameters have both habitats with the same
plant phenology

```> p.x_opt
171   171```

Let's change it so that the first habitat has a phenology
five days earlier than the second habitat

```> p.x_opt(1) = 171-5;
p.x_opt
ans =

   166   171 ```

You can then define a good initial guess for the system's
evolutionarily singular state. Let's say our first guess for the
hatching dates in each habitat type is about 8 days earlier
than the optimal hatching date

```> x0 = [159 164];```

and our first guess for the population size we'll set equal
to the number of available territories in each habitat type

```> n0 = p.K
n0 =

  50   50 ```

The solver can then be run,

```> x=calc_x(p,x0,n0)

x = 158.81   163.11

> n=calc_n(p,x,n0)

n = 46.764   46.692

and this is our singular strategy hatching dates and
population size respectively.

## Issues

The solver needs a fairly good initial guess in order to succeed at finding the singular strategy. Some helpful tips:

* Prior residence means that the hatching date will always be earlier than synchrony, so make sure that ```x0``` is lower than ```p.x_opt```. The solver can get "lost" if you start at the wrong end.
* The biologically reasonable system will be close to saturated, so you can often use ```K``` as a good initial guess for ```n```.
* Do you already know the singular strategy nearby in the parameter space? Perhaps start there and work your way slowly to the area of interest. If you are sweeping the parameter space, it's a good idea to go through incrementally, using the mismatch of the singular strategy at the previous step as the initial guess for the next step.

# Taking it further

## Check the evolutionary stability of a singular strategy

Let's check the evolutionary stability of the singular
strategy above. In the same workspace

```> [eigH,eigJ,eigJs,Hess,Jac] = check_stab(p,x,n)
eigH = -0.0012491
eigJ = -0.0018242
eigJs = -0.0016523
Hess =

-3.6961e-03   1.6310e-05
2.1677e-05  -1.2492e-03

Jac =

-4.3088e-03   2.5307e-04
-1.0704e-03  -1.7152e-03 ```

The dominant eigenvalue of the Hessian matrix ```eigH``` is
negative, so this singular strategy is a fitness maximum.
The dominant eigenvalue of Leimar's (2009) Jacobian
matrix is negative, so the singular strategy is also
an evolutionary attractor. Therefore we have found a singular
strategy that is a continuously stable strategy (CSS).

## Reproduce Figure 2a

First we'll read in the default parameter values supplied in
```default_parameter_values.m```

```
default_parameter_values
```

We want to vary the landscape-composition parameter ```K```.
It is stored in the parameter values dictionary ```p``` as a
vector of two values. We'd like to vary it between 20 and 80
percent early habitat, so we create a matrix with each row
corresponding to a point at which we'd like to solve the
system, and the columns being early- and late-K
```
parV = [linspace(20,80,13)',linspace(80,20,13)'];
```<commit_msg>lol markup<commit_after># Brief Description

Octave code to find the evolutionarily singular breeding-time strategy for a strict, discrete-flocking resident bird species (e.g. marsh tit) in a phenologically heterogenous landscape.

# Reference

<NAME>., <NAME>., <NAME>., <NAME>. Paper in preparation.

# Quick Start

If you have git:

    $ git clone https://github.com/nadiahpk/phenology-discrete-flocking-paridae
    $ cd phenology-two-trait-migratory-bird

If you don't have git, just download and unpack the latest zip file:

[https://github.com/nadiahpk/phenology-discrete-flocking-paridae/archive/master.zip](https://github.com/nadiahpk/phenology-discrete-flocking-paridae/archive/master.zip)

## Find an evolutionarily singular strategy

In Octave,

```> default_parameter_values```

will load the parameter dictionary p into the workspace. 

The default parameters have both habitats with the same
plant phenology

```
> p.x_opt
171   171
```

Let's change it so that the first habitat has a phenology
five days earlier than the second habitat

```
> p.x_opt(1) = 171-5;
p.x_opt
ans =

   166   171 
```

You can then define a good initial guess for the system's
evolutionarily singular state. Let's say our first guess for the
hatching dates in each habitat type is about 8 days earlier
than the optimal hatching date

```
> x0 = [159 164];
```

and our first guess for the population size we'll set equal
to the number of available territories in each habitat type

```
> n0 = p.K
n0 =

  50   50 
```

The solver can then be run,

```
> x=calc_x(p,x0,n0)

x = 158.81   163.11

> n=calc_n(p,x,n0)

n = 46.764   46.692
```

and this is our singular strategy hatching dates and
population size respectively.

## Issues

The solver needs a fairly good initial guess in order to succeed at finding the singular strategy. Some helpful tips:

* Prior residence means that the hatching date will always be earlier than synchrony, so make sure that ```x0``` is lower than ```p.x_opt```. The solver can get "lost" if you start at the wrong end.
* The biologically reasonable system will be close to saturated, so you can often use ```K``` as a good initial guess for ```n```.
* Do you already know the singular strategy nearby in the parameter space? Perhaps start there and work your way slowly to the area of interest. If you are sweeping the parameter space, it's a good idea to go through incrementally, using the mismatch of the singular strategy at the previous step as the initial guess for the next step.

# Taking it further

## Check the evolutionary stability of a singular strategy

Let's check the evolutionary stability of the singular
strategy above. In the same workspace

```
> [eigH,eigJ,eigJs,Hess,Jac] = check_stab(p,x,n)
eigH = -0.0012491
eigJ = -0.0018242
eigJs = -0.0016523
Hess =

-3.6961e-03   1.6310e-05
2.1677e-05  -1.2492e-03

Jac =

-4.3088e-03   2.5307e-04
-1.0704e-03  -1.7152e-03 
```

The dominant eigenvalue of the Hessian matrix ```eigH``` is
negative, so this singular strategy is a fitness maximum.
The dominant eigenvalue of Leimar's (2009) Jacobian
matrix is negative, so the singular strategy is also
an evolutionary attractor. Therefore we have found a singular
strategy that is a continuously stable strategy (CSS).

## Reproduce Figure 2a

First we'll read in the default parameter values supplied in
```default_parameter_values.m```

```
default_parameter_values
```

We want to vary the landscape-composition parameter ```K```.
It is stored in the parameter values dictionary ```p``` as a
vector of two values. We'd like to vary it between 20 and 80
percent early habitat, so we create a matrix with each row
corresponding to a point at which we'd like to solve the
system, and the columns being early- and late-K
```
parV = [linspace(20,80,13)',linspace(80,20,13)'];
```
{'fraction_non_alphanumeric': 0.08801154249737671, 'fraction_numerical': 0.040923399790136414, 'mean_word_length': 4.180027173913044, 'pattern_counts': {'":': 0, '<': 11, '<?xml version=': 0, '>': 27, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3122069', 'n_tokens_mistral': 2570, 'n_tokens_neox': 2267, 'n_words': 1033}