# Iterates until obtaining the number of bins required so that the difference in the chosen measure (lambda, R0, life expectancy of a chosenBin) falls below a chosen tolerance level

### Description

Increases bin number by a specified `binIncrease`

until the difference in the chosen measure falls below a tolerance level

### Usage

1 2 3 4 | ```
convergeIPM(growObj, survObj, fecObj, nBigMatrix, minSize, maxSize,
discreteTrans = 1, integrateType = "midpoint",
correction = "none", preCensus = TRUE, tol=1e-4,
binIncrease=5, chosenBin=1, response="lambda")
``` |

### Arguments

`growObj` |
a growth object. |

`survObj` |
a survival object. |

`fecObj` |
a fecundity object. |

`nBigMatrix` |
numeric, initial number of bins of size used in the matrix - will be increased for the assessment |

`minSize` |
numeric, minimum size used for meshpoints |

`maxSize` |
numeric, maximum size used for meshpoints of the P matrix. |

`discreteTrans` |
matrix of discrete transitions; or 1 if there is none |

`integrateType` |
integration type. |

`correction` |
correction (see makeIPMPmatrix) |

`preCensus` |
boolean defining whether fecundity is pre or post census; defaults to pre |

`tol` |
desired tolerance level |

`binIncrease` |
increments in increase in the number of bins (should be an integer) |

`chosenBin` |
desired bin for which life expectancy should be assessed; default is 1st. |

`response` |
what variable is convergence to be tested for; options are "lambda", "R0", "lifeExpect"; for the latter, the desired bin should be considered |

### Details

Different choices for responses will yield different values. The pattern of change in lambda (or other response variables) can be complex, so it is advisable to start with large binIncrease and small tolerance, and then once one knows a general idea of how big the matrix needs to be, run the function again with a smaller binIncrease but start it closer to the goal.

For the life expectancy option, if discrete stages are included via discreteTrans then if chosenBin=1, this function will use the first discrete bin.

### Value

`binIncrease` |
the number of bins used to increase matrix size in assessing tolerance |

`Pmatrix` |
the final Pmatrix if only LE is being considered |

`IPM` |
the final IPM |

`R0` |
the final R0 |

`lambda` |
the final lambda |

`LE` |
the final vector of life expectancies |

### Note

This code was modified from original code by Melissa Eitzel.

### Author(s)

C. Jessica E. Metcalf, Sean M. McMahon, Roberto Salguero-Gomez, Eelke Jongejans & Cory Merow.

### See Also

`diagnosticsPmatrix`

### Examples

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 | ```
dff<-generateData()
gr1<-makeGrowthObj(dff)
sv1<-makeSurvObj(dff)
fv1<-makeFecObj(dff,Transform="log")
res <- convergeIPM(growObj=gr1,
survObj=sv1, fecObj=fv1,
nBigMatrix=10, minSize=-2,
maxSize=15,discreteTrans = 1,
integrateType = "midpoint",
correction = "none",
preCensus = TRUE, tol=1e-3,binIncrease=10)
res <- convergeIPM(growObj=gr1,
survObj=sv1, fecObj=fv1,
nBigMatrix=10, minSize=-2,
maxSize=15,discreteTrans = 1,
integrateType = "midpoint",
correction = "none",
preCensus = TRUE, tol=1e-3,
binIncrease=10, response="R0")
res <- convergeIPM(growObj=gr1, survObj=sv1, fecObj=fv1,
nBigMatrix=10, minSize=-2,
maxSize=15,discreteTrans = 1,
integrateType = "midpoint",
correction = "none",
preCensus = TRUE, tol=1e-3,binIncrease=10,
response="lifeExpect")
``` |

Want to suggest features or report bugs for rdrr.io? Use the GitHub issue tracker. Vote for new features on Trello.