Ml distance

[karan3242]

Machine learning approach functions for Pb-iso-otope provence studies

Functions

This pull request adds 6 new functions.

The first is the pb_iso_emdmembers functions, which can identify PC-iso-EMD members forming a group using principal component analysis and geocrone-age lines using Stacey & Kramers, 1975. This creates a list object with the class "pbisoendmebers", which can be used with the S3 method of Summary.

The next main function in the as.ref_data function, which takes in any PB-iso-ate database and converts it into a ref.data object which can be used for Euclidean and machine-learing provenance studies.

The next function is the pb_iso_prov_dist function, which enables the traditional Euclidean distance with and without mass fractionation corrections applied. The mass fractionation correction is following the method laid out by Albarede et al., 2024.

The final two functions deal with creating an xgboost distance probability model which is trained on the ref.data object and then using the model to create predicted distance probabilities of individual sample points or "pbisoendmebers" class objects. This process is outlined by Shnyr et al., 2026.

Vignettes

The current pull request includes 2 new vignettes.

1. Pb_Iso_endmembers. Rmd, which explains how lia end members work.
2. Mass-Dependent Fractionation. Rmd, which explains the math behind the mass fractionation corrections.

TODO

Currently a Vignet expelling the machine learning process is in the process of drafting and will push at a later date.

Imports

These sets of functions import the following:

• xgboost
• dbscan
• smotefamily

References

Albarede, F., Davis, G., Blichert-Toft, J., Gentelli, L., Gitler, H., Pinto, M., & Telouk, P. (2024). A new algorithm for using Pb isotopes to determine the provenance of bullion in ancient Greek coinage. Journal of Archaeological Science, 163, 105919. https://doi.org/10.1016/j.jas.2023.105919

Shnyr, E., Kuflik, T., Desai, K., & Eshel, T. (2026). Determining the origins of Phoenician silver: Exploring the potential of machine learning for lead isotope analysis. Journal of Archaeological Science, 188, 106–499. https://doi.org/10.1016/j.jas.2026.106499

Stacey, J. S., & Kramers, J. D. (1975). Approximation of Terrestrial Lead Isotope Evolution by a Two-Stage Model. Earth and Planetary Science Letters, 26, 207–221.

[karan3242]

• Provenance functions have been merged into one file and the same is true for the endmember function.
• All functions exclusively use ASTR objects, and the input and output schema follow the same; we add new columns attributed as 'ASTR_context'.
• Documentation of the endmembers and the provenance functions, with each having their own vignette.
• A new file in draw-raw/ will fetch the Globalid database and process only 4 variables (Plitical province/region, and the 3 Pb isotopes) as an ASTR object and a pre-trained ML model.
• The ML training functions use the \dontrun{} function to prevent the example from running.
• The lead isotope data from the Tel Dor silver hoard is also added as sample data. A real-world dataset is useful for reproducibility.
• Because the GlobaLID data is large, a LazyDataCompression tag is also added to the DESCRIPTION. The current version follows the xz compression.

[archaeothommy]

Awesome work, thank you! Some of your helper functions will be very helpful for other functions in the package, too.

I edited documentation and vignettes directly there. Most edits are related to grammar and wording but please have a look. Additional questions and suggestions are inline.

I have no idea why testing your code fails since Mathias' commit. I did not check the statistics of your tests but will do so as soon as your code is running again.

[archaeothommy]

If "errors" here refer to the analytical uncertainties, please replace them with the proper term for them.