iRamat, un package R

WIAI - Webinaires de l’Informatique pour l’Archéométrie à l’IRAMAT

Thomas Huet

IRAMAT-CNRS

Introduction générale

La série WIAI

Webinaires dédiés aux technologies de l’information pour l’archéométrie:
GitHub , Python , R , API , IIIF , etc.

Note

📅 Le 2^e Mardi matin de chaque mois sur ZOOM entre 10h00 et 10h50 (50 minutes), lien sur le GitHub de l’IRAMAT

“A data structure is nothing without an algorithm, and an algorithm is nothing without a data structure.” – Jim Gray © Microsoft Research, CC BY-SA

Plan de la présentation

et les packages
Composition d’un package ( )
Du code à la $f$ , et de la $f$ au {pkg} ( )
Code as data
Discussion

R et les packages

est un langage de script orienté statistiques. C’est le langage préférés des archéologues¹ qui utilisent des packages génériques comme ggplot pour les graphiques (développé par Hadley Wickham), terra et sf pour l’analyse spatiale, etc., ou d’autres plus spécialisés: nexus , tidyspec , etc.

“Anything that can be automated, should be automated” – Hadley Wickham, 2023

Wikipedia

Les packages R

rassemblent du code, de la documentation et parfois des données.
conçus pour être facilement partagé, installé et réutilisé et ainsi garantir la reproductibilité des analyses.

Le Comprehensive R Archive Network (CRAN) https://cran.r-project.org/, l’archive officielle des packages R

Les packages R (suite)

En 2023, 19,000+ packages hebergés sur le CRAN.
En 2021, 25,000+ packages hebergés sur GitHub²

# install.packages("pkgsearch")
library(pkgsearch)
ps("raman")

- "raman" -------------------------------------- 13 packages in 0.049 seconds -
  #     package              version by                 @ title                
  1 100 serrsBayes           0.5.0   Matt Moores       4y Bayesian Modelling...
  2  92 RamanMP              1.0     Veronica Nava     4y Analysis and Ident...
  3  75 OpenSpecy            1.5.3   Win Cowger        5M Analyze, Process, ...
  4  36 readJDX              0.6.4   Bryan A. Hanson   2y Import Data in the...
  5  26 hyperSpec            0.100.2 Claudia Beleites  1y Work with Hyperspe...
  6  23 ChemoSpec            6.3.1   Bryan A. Hanson  28d Exploratory Chemom...
  7  22 PlackettLuce         0.4.4   Heather Turner    1M Plackett-Luce Mode...
  8  15 sabarsi              0.1.0   Li Jun            6y Background Removal...
  9  12 smdi                 0.3.1   Janick Weberpals  1y Perform Structural...
 10  11 FishProxCompAnalyzer 0.1.0   Tanuj Misra       1y Proximate Composit...

https://r-universe.dev/search?q=raman

https://github.com/search/advanced

⬇️

open-archaeo et le SIG-SSLA

https://open-archaeo.info/tags/x-ray-fluorescence/

Composition d’un package R

Description (fichiers sources)

DESCRIPTION
LICENSE
README.md
R/
inst/extdata/

Le fichier DESCRIPTION contient les métadonnées du package

Package: iRamat
Type: Package
Title: Statistical analysis on Archaeomaterial
Description: Statistical analysis on Archaeomaterial.
Version: 1.0.0
Authors@R: c(person("Thomas", "Huet", email = "thomas.huet@cnrs.fr", role = c("aut", "cre"), comment=c(ORCID="0000-0002-1112-6122")))
Depends:
    R (>= 4.0.1)
License: MIT + file LICENSE
Encoding: UTF-8
LazyData: true
Imports:
    dplyr,
    ggplot2,
    forcats,
    stringr,
    hash,
    jsonlite,
    httr,
    imager,
    spatstat.geom,
    spatstat.explore   
RoxygenNote: 7.3.2
Suggests: 
    testthat (>= 3.0.0),
    ggpubr
Config/testthat/edition: 3
URL: https://github.com/iramat/iRamat
BugsReport: https://github.com/iramat/iRamat/issues

Les fichiers LICENSE et LICENSE.md contiennent la licence du package

LICENSE

YEAR: 2025
COPYRIGHT HOLDER: IRAMAT-CNRS

LICENSE.md

# MIT License

Copyright (c) 2025 IRAMAT-CNRS

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

(...)

Le fichier README.md présente le package

Le dossier R/ contient les fonctions R

#' Connect the CHIPS DB API and return an R object (dataframe, etc.)
#'
#' @name db_api_connect
#' @description Connect the CHIPS DB API and return an R object (dataframe, etc.). The default dataset is dataset_adisser17, accessed at <http://157.136.252.188:3000/dataset_adisser17>
#'
#' @param d A hash object. If none is provided, a new one will be created.
#' @param api_url An URL landing to an API. Default: 'dataset_adisser17'.
#' @param output_format The selected output format. Default "dataframe".
#' @param verbose if TRUE (by default), verbose.
#'
#' @return An R object.
#'
#' @examples
#' df <- db_api_connect()
#' # Show the first rows of the dataframe
#' head(df$dataset_adisser17)
#' 
#' @export
db_api_connect <- function(d = NA,
                           api_url = "http://157.136.252.188:3000/dataset_adisser17",
                           output_format = "dataframe",
                           verbose = TRUE){
                           
                           (...)
                           
                           }

Le dossier inst/extdata/ contient les données externes

regular_distribution.png

clustered_distribution.png

random_distribution.png

Description (fichiers générés)

NAMESPACE
man/

Le fichier NAMESPACE décrit quelles fonctions du package sont exportées.

# Generated by roxygen2: do not edit by hand

export(chrono)
export(db_api_connect)
export(ppa)

Le dossier man/ contient la documentation des fonctions (générée depuis les fonctions elles-mêmes).

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ppa.R
\name{ppa}
\alias{ppa}
\title{Classify a Point Pattern Distribution}
\usage{
ppa(
  d = NA,
  root = "https://raw.githubusercontent.com/iramat/iRamat/master/inst/extdata/",
  img.paths = c("clustered_distribution.png", "random_distribution.png",
    "regular_distribution.png"),
  ppa_tests = c("quadrat", "ripley", "gfunction"),
  verbose = TRUE
)
}
(...)

Du code à la fonction, et de la fonction au package

Du `code` à la $f$ , et de la $f$ au `{pkg}`

Au Km
Fonctions
Package (private)
Package (public)

# Generate 100 random numbers from a normal distribution
x <- rnorm(100, mean = 10, sd = 2)

# Compute the mean
mean_x <- mean(x)

# Print the result
cat("The mean of x is:", mean_x, "\n")

#' Compute the mean of random normal numbers
#'
#' This function generates `n` random numbers from a normal distribution
#' with given `mean` and `sd`, then computes and prints their mean.
#'
#' @param n Integer, number of random values to generate.
#' @param mean Numeric, the mean of the normal distribution.
#' @param sd Numeric, the standard deviation of the normal distribution.
#'
#' @return The computed mean (numeric).
#' @export
#'
#' @examples
#' simulate_mean(100, mean = 10, sd = 2)
simulate_mean <- function(n = 100, mean = 0, sd = 1) {
  x <- rnorm(n, mean = mean, sd = sd)
  mean_x <- mean(x)
  cat("The mean of x is:", mean_x, "\n")
  return(mean_x)
}

https://github.com/iramat/iramat-private

https://github.com/iramat/iRamat

Code as data

Réutiliser

Citer
Publier sur Zenodo
Publier dans une revue

citation("iRamat")

To cite package 'iRamat' in publications use:

  Huet T (2025). _iRamat: Statistical analysis on Archaeomaterial_. R
  package version 1.0.0, commit
  2106b34129c6c9ab96d8e6302d807ab35f7ed13d,
  <https://github.com/iramat/iRamat>.

A BibTeX entry for LaTeX users is

  @Manual{,
    title = {iRamat: Statistical analysis on Archaeomaterial},
    author = {Thomas Huet},
    year = {2025},
    note = {R package version 1.0.0, commit 2106b34129c6c9ab96d8e6302d807ab35f7ed13d},
    url = {https://github.com/iramat/iRamat},
  }

https://docs.github.com/en/repositories/archiving-a-github-repository/referencing-and-citing-content

https://joss.theoj.org/papers/10.21105/joss.03191

Discussion

Footnotes

Batist, Z. and Roe, J. 2024 Open Archaeology, Open Source? Collaborative practices in an emerging community of archaeological software engineers, Internet Archaeology 67. https://doi.org/10.11141/ia.67.13
Bommarito, E., & Bommarito II, M. J. (2021). An empirical analysis of the R package ecosystem. arXiv preprint arXiv:2102.09904.

iRamat, un package R

Introduction générale

La série WIAI

Plan de la présentation

R et les packages

Les packages R

Les packages R (suite)

Trouver un package

Composition d’un package R

Description (fichiers sources)

Description (fichiers générés)

Du code à la fonction, et de la fonction au package

Du code à la f, et de la f au {pkg}

Code as data

Réutiliser

Discussion

Footnotes

Du `code` à la $f$ , et de la $f$ au `{pkg}`