Author: Aurélie Mercadié, Nathalie Vialaneix

# NiLeDAM

#### Aurélie Mercadié, Nathalie Vialaneix

#### 18 septembre, 2023

# Preliminary steps

    library(NiLeDAM)
    #>
    #> ***********************************************************
    #>
    #>       Welcome to the NiLeDAM package
    #>       An online graphical interface is available at:
    #>         http://shiny.nathalievilla.org/niledam
    #>         or run: liveNILEDAM()
    #>       Citation details with citation('NiLeDAM')
    #>
    #>       For questions/remarks, please contact the maintainer:
    #>         nathalie.vialaneix@inrae.fr
    #>
    #> ***********************************************************

The package `NiLeDAM` will be tested on a data set called srilanka, provided by Anne-Magali Seydoux-Guillaume and published in Seydoux-Guillaume et al. (2012). For more information about this dataset, refer to the help page:

    ?srilanka

    data("srilanka")

    dim(srilanka)
    #> [1] 32  6

    summary(srilanka)
    #>        U             errU             Th             ErrTh            Pb
    #>  Min.   : 495   Min.   :229.0   Min.   : 41275   Min.   : 856   Min.   :1000
    #>  1st Qu.:1816   1st Qu.:239.0   1st Qu.: 62489   1st Qu.:1006   1st Qu.:1548
    #>  Median :6275   Median :271.0   Median :187783   Median :1711   Median :4562
    #>  Mean   :4276   Mean   :256.8   Mean   :139063   Mean   :1433   Mean   :3457
    #>  3rd Qu.:6760   3rd Qu.:274.0   3rd Qu.:199075   3rd Qu.:1768   3rd Qu.:4871
    #>  Max.   :7359   Max.   :277.0   Max.   :215401   Max.   :1852   Max.   :5365
    #>      ErrPb
    #>  Min.   :314.0
    #>  1st Qu.:318.0
    #>  Median :338.0
    #>  Mean   :331.3
    #>  3rd Qu.:341.0
    #>  Max.   :345.0

# Using all analyses

## `calculateAges()`

As a first step, ages are calculated with the help of the function `calculateAges()`.

    ?calculateAges

- For a reliable estimation, one must fix the number of bootstrap samples `nloops` to at least 1000. The larger the number of bootstraps, the more time-consuming the function gets.
- The option `seed` is used to make results reproducible. Any integer can be used.
- By default, `level = 0.05` (statistical risk for the tests) and `verbose = TRUE`.

Remark: the data frame used in this function must have exactly 6 columns as the srilanka data set has (in that order). If not, then the function will generate an error.

    calculated.ages <- calculateAges(srilanka, nloops = 10, seed = 12, verbose = TRUE)
    #> Age estimation...
    #> MC simulations...
    #>  (it might take a while if 'nloops' is large...)
    #>
    #> 32 ages and confidence intervals estimated from 10 bootstrap samples.
    #>  Summary:
    #>    Min. 1st Qu.  Median    Mean 3rd Qu.    Max.
    #>   447.0   491.2   505.5   515.3   546.5   598.0

What contains this `ages` object ?

- The estimated age for each sample

    calculated.ages@ages
    #>   1   2   3   4   5   6   7   8   9  10  11  12  13  14  15  16  17  18  19  20
    #> 569 447 598 515 543 567 557 567 458 497 481 497 520 519 477 559 515 525 493 581
    #>  21  22  23  24  25  26  27  28  29  30  31  32
    #> 561 501 479 500 482 505 486 468 506 501 521 494

- The age confidence interval for each sample

    calculated.ages@ci
    #>             1       2       3       4      5       6       7      8       9
    #> 2.5%  530.200 384.375 534.600 443.800 487.35 541.900 478.350 521.35 448.225
    #> 97.5% 660.325 542.125 662.425 569.725 586.55 612.475 603.175 599.50 486.775
    #>            10      11      12     13      14      15      16      17      18
    #> 2.5%  447.825 457.925 475.575 496.35 496.025 438.675 434.725 336.075 390.625
    #> 97.5% 508.775 508.500 512.975 543.65 539.325 549.275 744.650 572.775 596.475
    #>            19      20      21      22      23      24      25     26      27
    #> 2.5%  421.175 500.125 497.175 480.675 439.575 475.925 441.925 473.90 473.575
    #> 97.5% 535.400 680.450 692.750 533.625 485.775 522.200 510.000 530.05 505.600
    #>           28     29      30     31      32
    #> 2.5%  453.90 485.95 489.125 488.60 468.725
    #> 97.5% 488.75 531.30 518.975 540.65 507.875

## `tests()`

Then, one can estimate the number of age populations using the previously generated object. This is done with the function `tests`, which help page is accessible with:

    ?tests

One can either test a unique number or a sequence of numbers to find the most likely number of different populations of ages (or common ages).

Here, 1 to 3 populations are tested:

    res.tests <- tests(calculated.ages, nbmin = 1, nbmax = 3, verbose = TRUE)
    #> Test if the 32 estimated ages are coming from
    #>  1 2 3
    #> population(s).
    #>
    #>     The ages are found to be likely coming from 2 population(s) at level 5 %.
    #>     Chi2 test statistic: 26.52015  ~ df: 30
    #>
    #>     Estimated ages: 566 494
    #>
    #>     Population numbers:
    #>  1 2 1 2 1 1 1 1 2 2 2 2 2 2 2 1 2 2 2 1 1 2 2 2 2 2 2 2 2 2 2 2

It appears that the samples come from 2 different populations of ages.

## Plotting methods

Finally, the results can be visualized thanks to the following methods:

- `plot` to plot the sample age densities as well as the common age densities
- `popline` to plot samples with Th* (calculated from estimated ages and from U) on x-axis and with Pb on y-axis

    plot(res.tests)

    popline(res.tests)

# Removing the first 8 analyses (control group)

    srilanka2 <- srilanka[-(1:8), ]

## `calculateAges()`

    calculated.ages <- calculateAges(srilanka2, nloops = 10, seed = 12)
    #> Age estimation...
    #> MC simulations...
    #>  (it might take a while if 'nloops' is large...)
    #>
    #> 24 ages and confidence intervals estimated from 10 bootstrap samples.
    #>  Summary:
    #>    Min. 1st Qu.  Median    Mean 3rd Qu.    Max.
    #>   458.0   485.0   500.5   505.2   519.2   581.0

## `tests()`

    res.tests <- tests(calculated.ages, nbmax = 3)
    #> Test if the 24 estimated ages are coming from
    #>  1 2 3
    #> population(s).
    #>
    #>     The ages are found to be likely coming from 1 population(s) at level 5 %.
    #>     Chi2 test statistic: 28.15801  ~ df: 23
    #>
    #>     Estimated ages: 493
    #>
    #>     Population numbers:
    #>  1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1

This time, only one population is identified (as expected).

## Plotting methods

    plot(res.tests)

    popline(res.tests)

# Graphical user interface

NiLeDAM also contains a shiny graphical interface that can be used to perform the actions described above. This interface in launched using:

    liveNiLeDAM()

# References

Seydoux-Guillaume A.M., Montel J.M., Bingen B., Bosse V., de Parseval P., Paquette J.L., Janots E., Wirth R. (2012) Low-temperature alteration of monazite: fluid mediated coupled dissolution-precipitation, irradiation damage and disturbance of the U-Pb and Th-Pb chronometers. Chemical Geology, 330–331, 140–158.