├── .Rapp.history ├── .Rbuildignore ├── .github ├── .gitignore └── workflows │ └── R-CMD-check.yaml ├── .gitignore ├── DESCRIPTION ├── NAMESPACE ├── NEWS.md ├── R ├── aggregation.R ├── calibration-helpers.R ├── calibration.R ├── data.R ├── package-rcarbon.R ├── plots.R ├── rcarbon-deprecated.R ├── tests.R └── utilities.R ├── README.md ├── cran-comments.md ├── data ├── emedyd.rda ├── euroevol.rda ├── ewdates.rda └── ewowin.rda ├── inst ├── CITATION └── extdata │ ├── intcal13.14c │ ├── intcal13nhpine16.14c │ ├── intcal20.14c │ ├── marine13.14c │ ├── marine20.14c │ ├── normal.14c │ ├── shcal13.14c │ ├── shcal13shkauri16.14c │ └── shcal20.14c ├── logo └── rcarbon_logo.png ├── man ├── BCADtoBP.Rd ├── BPtoBCAD.Rd ├── as.CalDates.Rd ├── as.CalGrid.Rd ├── as.UncalGrid.Rd ├── barCodes.Rd ├── binMed.Rd ├── binPrep.Rd ├── binsense.Rd ├── calibrate.Rd ├── ckde.Rd ├── combine.Rd ├── emedyd.Rd ├── euroevol.Rd ├── ewdates.Rd ├── ewowin.Rd ├── gaussW.Rd ├── hpdi.Rd ├── medCal.Rd ├── mixCurves.Rd ├── modelTest.Rd ├── multiplot.Rd ├── p2pTest.Rd ├── permTest.Rd ├── plot.CalDates.Rd ├── plot.CalGrid.Rd ├── plot.CalSPD.Rd ├── plot.SpdModelTest.Rd ├── plot.SpdPermTest.Rd ├── plot.compositeKDE.Rd ├── plot.spatialTest.Rd ├── plot.spdRC.Rd ├── plot.stKde.Rd ├── plot.stackCalSPD.Rd ├── poolDates.Rd ├── qCal.Rd ├── rcarbon-deprecated.Rd ├── rcarbon.Rd ├── reScale.Rd ├── runMean.Rd ├── sampleDates.Rd ├── smoothGauss.Rd ├── spd.Rd ├── spd2rc.Rd ├── spkde.Rd ├── sptest.Rd ├── stackspd.Rd ├── stkde.Rd ├── subset.CalDates.Rd ├── summary.CalDates.Rd ├── summary.SpdModelTest.Rd ├── summary.SpdPermTest.Rd ├── thinDates.Rd ├── transformSPD.Rd ├── uncalibrate.Rd └── which.CalDates.Rd └── vignettes ├── rcarbon.Rmd └── rcarbon.html /.Rapp.history: -------------------------------------------------------------------------------- 1 | 0.603/14 2 | 0.23/16.1 3 | 0.250/13.25 4 | 0.28/12.1 5 | 0.998/18.15 6 | 0.230/16.1 7 | (0.998/18.15) / (0.230/16.1) 8 | (0.603/14) / (0.250/13.25) 9 | (0.380/8) / (0.280/12.1) 10 | quit("no") 11 | library(rcarbon) 12 | plot(calibrate(2020,70), calendar="BCAD") 13 | plot(calibrate(2070,70), calendar="BCAD") 14 | quit("no") 15 | library(rcarbon) 16 | plot(calibrate(5130,80), calendar="BCAD") 17 | quit("no") 18 | library(rcarbon) 19 | plot(calibrate(4390,60)) 20 | plot(calibrate(4390,60), calendar="BCAD") 21 | plot(calibrate(4520,60), calendar="BCAD") 22 | quit("no") 23 | library(rcarbon) 24 | plot(calibrate(6605,45), calendar="BCAD") 25 | plot(calibrate(6640,95), calendar="BCAD") 26 | plot(calibrate(6200,95), calendar="BCAD") 27 | plot(calibrate(6501,37), calendar="BCAD") 28 | plot(calibrate(6200,95), calendar="BCAD") 29 | quit("no") 30 | library(devtools)# 31 | install_github("ahb108/rcarbon")# 32 | library(rcarbon) 33 | plot(calibrate(4500,34)) 34 | ?calibrate 35 | citation("rcarbon") 36 | ?modelTest 37 | quit("no") 38 | library(spatstat) 39 | ?owin() 40 | w <- owin(xrange=c(0,1000), yrange=c(0,1000) 41 | ) 42 | plot(w) 43 | ?image 44 | ?as.im 45 | wim <- as.im(w, eps=1000) 46 | plot(wim) 47 | wim 48 | wim <- as.im(w, nx=1000, ny=1000) 49 | plot(wim) 50 | wim 51 | ?as.im 52 | wim <- as.im(w, dimxy=1000) 53 | wim 54 | plot(w,axes=T) 55 | ?as.im 56 | wim <- as.im(w, eps=1) 57 | wim 58 | ?dist 59 | ?distmap 60 | A <- ppp(0,1000,w) 61 | plot(A) 62 | A <- ppp(0,1000,w)# 63 | B <- ppp(0,0,w)# 64 | C <- ppp(1000,1000,w)# 65 | D <- ppp(1000,0,w) 66 | plot(D) 67 | dA <- distmap(A,wim) 68 | ?distmap 69 | dA <- distmap(A,1) 70 | plot(dA) 71 | dA 72 | ?distmap 73 | ?rpoiss 74 | ?rpois 75 | ?rmh 76 | sA1 <- rpoiss(1000, f=dA) 77 | sA1 <- rmpoint(1000, f=dA) 78 | sA1 <- rmpoint(1000, f=dA, types="A") 79 | plot(sA1) 80 | ?rpoint 81 | sA1 <- rpoint(1000, f=dA) 82 | plot(sA1) 83 | dA <- 1 / distmap(A,wim) 84 | dA <- 1 / distmap(A,1) 85 | plot(dA) 86 | ?im.calc 87 | ?imcalc 88 | ?im 89 | ?im.eval 90 | dA <- distmap(A,1)# 91 | idA <- eval.im(1/dA) 92 | plot(idA) 93 | dA 94 | plot(dA) 95 | flot(dA) 96 | float(dA) 97 | idA <- eval.im(1000/dA) 98 | plot(idA) 99 | ?eval.im 100 | idA <- eval.im(dA+1000) 101 | plot(idA) 102 | idA <- eval.im(dA*4) 103 | plot(idA) 104 | idA <- eval.im(1/(dA+1)) 105 | plot(idA) 106 | idA <- eval.im(1000000/(dA+1)) 107 | plot(idA) 108 | idA <- 1000000/(dA+1) 109 | plot(idA) 110 | hist(idA) 111 | as.array(dA) 112 | 1/as.array(dA) 113 | plot(as.im(1/as.array(dA))) 114 | plot(as.im((1/as.array(dA)))) 115 | idA <- eval.im(1.0/dA) 116 | plot(idA) 117 | idA <- 1 / dA 118 | plot(idA) 119 | idA 120 | max(idA) 121 | max(dA) 122 | min(dA) 123 | 1/min(dA) 124 | idA <- 1 / (dA+1) 125 | min(idA) 126 | max(idA) 127 | idA <- max(dA)-dA 128 | plot(idA) 129 | idA <- max(dA)-dA# 130 | idB <- max(dB)-dB# 131 | idC <- max(dC)-dC# 132 | idD <- max(dD)-dD 133 | dA <- distmap(A,1)# 134 | dB <- distmap(B,1)# 135 | dC <- distmap(C,1)# 136 | dD <- distmap(D,1)# 137 | idA <- max(dA)-dA# 138 | idB <- max(dB)-dB# 139 | idC <- max(dC)-dC# 140 | idD <- max(dD)-dD 141 | sA1 <- rpoint(1000, f=idA) 142 | plot(sA1) 143 | sA1 <- rpoint(1000, f=idA) 144 | plot(sA1) 145 | sA1 146 | sA1 <- as.ppp(sA1,w) 147 | plot(sA1) 148 | sA1 149 | Window(sA1) <- w 150 | plot(sA1) 151 | sA1 152 | sA1 <- rpoint(1000, f=idA)# 153 | Window(sA1) <- w# 154 | sB1 <- rpoint(1000, f=idB)# 155 | Window(sB1) <- w# 156 | sC1 <- rpoint(1000, f=idC)# 157 | Window(sC1) <- w# 158 | sD1 <- rpoint(1000, f=idD)# 159 | Window(sD1) <- w 160 | plot(sD1) 161 | Adens <- density(sA1, eps=1) 162 | plot(Ades) 163 | plot(Adens) 164 | Adens 165 | ?density 166 | Adens <- density(sA1, eps=1, give.Rkern=TRUE) 167 | Adens 168 | ?density 169 | bw(Adens) 170 | Adens$bw 171 | Adens@bw 172 | Adens <- density(sA1, eps=1) 173 | Adens$bw 174 | Adens <- density(sA1, give.Rkern=TRUE) 175 | Adens 176 | summary(Adens) 177 | Adens <- density(sA1, eps=1, sigma=25) 178 | plot(Adens) 179 | Adens <- density(sA1, eps=1, sigma=100) 180 | plot(Adens) 181 | Adens <- density(sA1, eps=1, sigma=100)# 182 | Bdens <- density(sB1, eps=1, sigma=100)# 183 | Cdens <- density(sC1, eps=1, sigma=100)# 184 | Ddens <- density(sD1, eps=1, sigma=100) 185 | plot(Ddens) 186 | sAll <- superimpose(sA1,sB1,sC1,sD1) 187 | plot(sAll) 188 | alldens <- density(sAll, eps=1, sigma=100) 189 | plot(alldens) 190 | Aprop <- Adens / alldens 191 | plot(Aprop) 192 | Aprop <- Adens / alldens# 193 | Bprop <- Bdens / alldens# 194 | Cprop <- Cdens / alldens# 195 | Dprop <- Ddens / alldens 196 | plot(Dprop) 197 | library(raster) 198 | library(randomForest) 199 | library(cluster) 200 | install.packages("randomForest") 201 | library(randomForest) 202 | r <- raster(Aprop) 203 | plot(r) 204 | allims <- stack(raster(Aprop),raster(Bprop),raster(Cprop),raster(Dprop)) 205 | plot(allims) 206 | v <- getValues(allims)# 207 | i <- which(!is.na(v))# 208 | v <- na.omit(v) 209 | ?kmeans 210 | E <- kmeans(v, 4, iter.max=100, nstart=10) 211 | allclassed <- raster(allims)# 212 | allclassed[i] <- E$cluster# 213 | plot(allclassed) 214 | sum(Adens) 215 | plot(dA) 216 | b100_200 <- dA >100 & dA <=200 217 | plot(b100_200) 218 | b1000_200_A <- Adens * b100_200 219 | plot(b1000_200_A) 220 | b1000_200_A <- Adens / b100_200 221 | plot(b1000_200_A) 222 | sum(b1000_200_A) 223 | sum(b1000_200_A, na.omit=TRUE) 224 | as.vector(b1000_200_A,) 225 | as.array(b1000_200_A,) 226 | as.numeric(b1000_200_A,) 227 | as.numeric(b1000_200_A) 228 | ## Summary of point density# 229 | ptDensRaster <- function(pts, r, cellVals=NULL, cellQuants=NULL, areaRescale=1){# 230 | #Simple summary of possible correlation between points and a raster dataset# 231 | if ((is.null(cellVals)&is.null(cellQuants))|(!is.null(cellVals)&!is.null(cellQuants))){# 232 | stop("Need to define only one of either cellVals or cellQuants")# 233 | }# 234 | cellarea <- xres(r) * yres(r) #Assumes projected raster# 235 | pts$vals <- extract(r,pts)# 236 | if (!is.null(cellQuants)){# 237 | brk<- data.frame(quantile(r, probs = seq(0, 1, cellQuants)))[,1]# 238 | h <- hist(r, breaks=brk, plot = FALSE)# 239 | binned <- data.frame(MidBin=length(brk)-1)# 240 | for (i in 1:length(brk)-1){# 241 | binned[i,] <- (brk[i] + brk[i + 1]) / 2# 242 | }# 243 | binned$Cells <- h$counts# 244 | binned$Area <- binned$Cells * cellarea * areaRescale# 245 | binned$PointCount <- hist(pts$vals, brk, plot = FALSE)$counts# 246 | } else {# 247 | x<-as.matrix(na.omit(getValues(r)))# 248 | binned <- data.frame(table(x))# 249 | binned[,1] <- cellVals# 250 | names(binned)<-c("MidBin","Cells")# 251 | binned$Area <- binned$Cells * cellarea * areaRescale# 252 | ptvals <- data.frame(table(pts$vals))# 253 | ptvals[,1] <- cellVals# 254 | names(ptvals) <- c("MidBin", "PointCount")# 255 | binned <- merge(binned,ptvals,by="MidBin", all=TRUE)# 256 | binned[is.na(binned$PointCount),4] <- 0# 257 | }# 258 | binned$Intensity <- binned$PointCount / binned$Area# 259 | return(binned)# 260 | } 261 | brk <- data.frame(quantile(raster(dA), probs=seq(0, 1, 0.05)))[,1] 262 | brk 263 | bin <- ptDensRaster(dA, bdistr, cellBreaks=brk) 264 | bin <- ptDensRaster(dA, cellBreaks=brk) 265 | bin <- ptDensRaster(dA, brk) 266 | bin <- ptDensRaster(dA) 267 | bin <- ptDensRaster(dA, cellVals=brk) 268 | bin <- ptDensRaster(dA, r=100, cellVals=brk) 269 | bin <- ptDensRaster(dA, r=100) 270 | Asp <- as(sA1,"SpatialPoints") 271 | plot(Asp) 272 | extract(as(sA1,"SpatialPoints")) 273 | ?extract 274 | extract(dA,as(sA1,"SpatialPoints")) 275 | extract(dA,as(sA1,"SpatialPointsDataFrame")) 276 | ?extract 277 | extract(raster(dA),as(sA1,"SpatialPointsDataFrame")) 278 | extract(raster(dA),as(sA1,"SpatialPoints")) 279 | Adists <- extract(raster(dA),as(sA1,"SpatialPoints")) 280 | hist(Adists) 281 | quit("no") 282 | library(rcarbon) 283 | plot(calibrate(2190,40), calendar="BCAD") 284 | plot(calibrate(2410,40), calendar="BCAD") 285 | 19/146 286 | quit("no") 287 | chisq() 288 | ?chi.sq 289 | library(MASS) 290 | x <- matrix(c(12, 5, 7, 7), ncol = 2) 291 | x 292 | chisq.test(8,4) 293 | chisq.test(c(8,4)) 294 | chisq.test(c(10,0)) 295 | quit("no") 296 | library(rcarbon) 297 | plot(calibrate,3912,30),calendar="BCAD") 298 | plot(calibrate(3912,30),calendar="BCAD") 299 | quit("no") 300 | library(rcarbon) 301 | plot(calibrate(2110,70), calendar="BCAD") 302 | quit("no") 303 | library(rcarbon) 304 | citation(rcarbon) 305 | citation("rcarbon") 306 | quit("no") 307 | setwd("/Users/abevan/Projects/github/rcarbon") 308 | document() 309 | library(roxygen) 310 | library(roxygen2) 311 | document() 312 | library(devtools) 313 | document() 314 | cd ~/Projects/github/rcarbon/ 315 | quit("no") 316 | -------------------------------------------------------------------------------- /.Rbuildignore: -------------------------------------------------------------------------------- 1 | ^.*\.Rproj$ 2 | ^\.Rproj\.user$ 3 | ^\.DS_Store$ 4 | ^logo/rcarbon_logo\.png$ 5 | ^cran-comments\.md$ 6 | ^README\.md$ 7 | ^NEWS\.md$ 8 | ^\.github$ 9 | -------------------------------------------------------------------------------- /.github/.gitignore: -------------------------------------------------------------------------------- 1 | *.html 2 | -------------------------------------------------------------------------------- /.github/workflows/R-CMD-check.yaml: -------------------------------------------------------------------------------- 1 | # For help debugging build failures open an issue on the RStudio community with the 'github-actions' tag. 2 | # https://community.rstudio.com/new-topic?category=Package%20development&tags=github-actions 3 | on: 4 | push: 5 | branches: 6 | - main 7 | - master 8 | pull_request: 9 | branches: 10 | - main 11 | - master 12 | 13 | name: R-CMD-check 14 | 15 | jobs: 16 | R-CMD-check: 17 | runs-on: ${{ matrix.config.os }} 18 | 19 | name: ${{ matrix.config.os }} (${{ matrix.config.r }}) 20 | 21 | strategy: 22 | fail-fast: false 23 | matrix: 24 | config: 25 | - {os: windows-latest, r: 'release'} 26 | - {os: macOS-latest, r: 'release'} 27 | - {os: ubuntu-20.04, r: 'release', rspm: "https://packagemanager.rstudio.com/cran/__linux__/focal/latest"} 28 | 29 | env: 30 | R_REMOTES_NO_ERRORS_FROM_WARNINGS: true 31 | RSPM: ${{ matrix.config.rspm }} 32 | GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} 33 | 34 | steps: 35 | - uses: actions/checkout@v2 36 | 37 | - uses: r-lib/actions/setup-r@v1 38 | with: 39 | r-version: ${{ matrix.config.r }} 40 | 41 | - uses: r-lib/actions/setup-pandoc@v1 42 | 43 | - name: Query dependencies 44 | run: | 45 | install.packages('remotes') 46 | saveRDS(remotes::dev_package_deps(dependencies = TRUE), ".github/depends.Rds", version = 2) 47 | writeLines(sprintf("R-%i.%i", getRversion()$major, getRversion()$minor), ".github/R-version") 48 | shell: Rscript {0} 49 | 50 | - name: Restore R package cache 51 | if: runner.os != 'Windows' 52 | uses: actions/cache@v2 53 | with: 54 | path: ${{ env.R_LIBS_USER }} 55 | key: ${{ runner.os }}-${{ hashFiles('.github/R-version') }}-1-${{ hashFiles('.github/depends.Rds') }} 56 | restore-keys: ${{ runner.os }}-${{ hashFiles('.github/R-version') }}-1- 57 | 58 | - name: Install system dependencies 59 | if: runner.os == 'Linux' 60 | run: | 61 | while read -r cmd 62 | do 63 | eval sudo $cmd 64 | done < <(Rscript -e 'writeLines(remotes::system_requirements("ubuntu", "20.04"))') 65 | 66 | - name: Install dependencies 67 | run: | 68 | remotes::install_deps(dependencies = TRUE) 69 | remotes::install_cran("rcmdcheck") 70 | shell: Rscript {0} 71 | 72 | - name: Check 73 | env: 74 | _R_CHECK_CRAN_INCOMING_REMOTE_: false 75 | run: | 76 | options(crayon.enabled = TRUE) 77 | rcmdcheck::rcmdcheck(args = c("--no-manual", "--ignore-vignettes", "--no-build-vignettes"), build_args = c("--no-manual", "--ignore-vignettes", "--no-build-vignettes"), error_on = "error") 78 | shell: Rscript {0} 79 | 80 | - name: Upload check results 81 | if: failure() 82 | uses: actions/upload-artifact@main 83 | with: 84 | name: ${{ runner.os }}-r${{ matrix.config.r }}-results 85 | path: check 86 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .Rproj.user 2 | .Rhistory 3 | .RData 4 | -------------------------------------------------------------------------------- /DESCRIPTION: -------------------------------------------------------------------------------- 1 | Package: rcarbon 2 | Title: Calibration and Analysis of Radiocarbon Dates 3 | Version: 1.5.1 4 | Authors@R: c(person("Andrew","Bevan", role=c("aut"),email=c("andrew.bevan@gmail.com"),comment=c(ORCID="0000-0001-7967-3117")), 5 | person("Enrico","Crema", role=c("aut","cre"),email=c("enrico.crema@gmail.com"),comment=c(ORCID="0000-0001-6727-5138")), 6 | person("R. Kyle","Bocinsky",role=c("ctb"),email="bocinsky@gmail.com"), 7 | person("Martin","Hinz", role=c("ctb"),email="martin.hinz@iaw.unibe.ch"), 8 | person("Philip","Riris", role=c("ctb"),email="priris@bournemouth.ac.uk"), 9 | person("Fabio","Silva", role=c("ctb"),email="fabio.silva@ucl.ac.uk")) 10 | URL: https://github.com/ahb108/rcarbon/ 11 | BugReports: https://github.com/ahb108/rcarbon/issues 12 | Description: Enables the calibration and analysis of radiocarbon dates, often but not exclusively for the purposes of archaeological research. It includes functions not only for basic calibration, uncalibration, and plotting of one or more dates, but also a statistical framework for building demographic and related longitudinal inferences from aggregate radiocarbon date lists, including: Monte-Carlo simulation test (Timpson et al 2014 ), random mark permutation test (Crema et al 2016 ) and spatial permutation tests (Crema, Bevan, and Shennan 2017 ). 13 | Depends: R (>= 3.3.0) 14 | Imports: sf,stats,spatstat.geom, spatstat.model,spatstat.explore, spatstat.linnet, spatstat (>= 2.0-0),graphics,grDevices,utils,snow,doSNOW,foreach,iterators,knitr 15 | Suggests: 16 | rmarkdown, 17 | testthat (>= 2.1.0) 18 | License: GPL (>= 2) 19 | Encoding: UTF-8 20 | LazyData: true 21 | VignetteBuilder: knitr 22 | RoxygenNote: 7.2.3 23 | Language: en-GB 24 | -------------------------------------------------------------------------------- /NAMESPACE: -------------------------------------------------------------------------------- 1 | # Generated by roxygen2: do not edit by hand 2 | 3 | S3method("[",CalDates) 4 | S3method(calibrate,UncalGrid) 5 | S3method(calibrate,default) 6 | S3method(length,CalDates) 7 | S3method(plot,CalDates) 8 | S3method(plot,CalGrid) 9 | S3method(plot,CalSPD) 10 | S3method(plot,SpdModelTest) 11 | S3method(plot,SpdPermTest) 12 | S3method(plot,compositeKDE) 13 | S3method(plot,spatialTest) 14 | S3method(plot,spdRC) 15 | S3method(plot,stKde) 16 | S3method(plot,stackCalSPD) 17 | S3method(subset,CalDates) 18 | S3method(summary,CalDates) 19 | S3method(summary,SpdModelTest) 20 | S3method(summary,SpdPermTest) 21 | S3method(uncalibrate,CalGrid) 22 | S3method(uncalibrate,default) 23 | export(BCADtoBP) 24 | export(BPtoBCAD) 25 | export(as.CalDates) 26 | export(as.CalGrid) 27 | export(as.UncalGrid) 28 | export(barCodes) 29 | export(binMed) 30 | export(binPrep) 31 | export(binsense) 32 | export(calibrate) 33 | export(ckde) 34 | export(combine) 35 | export(gaussW) 36 | export(hpdi) 37 | export(medCal) 38 | export(mixCurves) 39 | export(modelTest) 40 | export(multiplot) 41 | export(p2pTest) 42 | export(permTest) 43 | export(poolDates) 44 | export(qCal) 45 | export(reScale) 46 | export(runMean) 47 | export(sampleDates) 48 | export(smoothGauss) 49 | export(spd) 50 | export(spd2rc) 51 | export(spkde) 52 | export(sptest) 53 | export(stackspd) 54 | export(stkde) 55 | export(thinDates) 56 | export(transformSPD) 57 | export(uncalibrate) 58 | export(which.CalDates) 59 | import(doSNOW) 60 | import(foreach) 61 | import(grDevices) 62 | import(graphics) 63 | import(iterators) 64 | import(sf) 65 | import(snow) 66 | import(spatstat.geom,spatstat.explore,spatstat.model,spatstat.linnet,spatstat) 67 | import(stats) 68 | import(utils) 69 | import(knitr) 70 | -------------------------------------------------------------------------------- /NEWS.md: -------------------------------------------------------------------------------- 1 | # Version 1.5.1 (in development) 2 | * Bug Fix: Removed non-relevant warning messages from `calibrate()` within `modelTest()`. 3 | * NEW: `qCal()` function computes quantiles of calibrated dates. 4 | * UPDATE: `multiplot()` now enables relative positioning of labels based on quantiles of calibrated dates and/or a user-defined offset. 5 | 6 | # Version 1.5.0 (21 November 2022) 7 | * UPDATE: Functions related to spatial permutation test (`spweights()`,`sptest()`, and `plot.spatialTest()`) now depend on `sf` instead of `sp` package. 8 | * UPDATE: `modelTest()` now issues a warning message when `model` is set to `"exponential"` or `"uniform"` (i.e. when the SPD is tested against exponential and uniform curves fitted on observed SPD values.) 9 | * UPDATE: Updated vignette with minor changes reflecting the workflow for `sptest()` and the warning in `modelTest()`. 10 | * Bug Fix: Fixed a problem with `plot.stackCalSPD()` function when attempting to display proportion SPD plots including intervals with no dates. 11 | * Updated spatstat dependencies. 12 | 13 | # Version 1.4.4 (21 July 2022) 14 | * Bug Fix: Fixed a bug in `spd()` reducing the `timeRange` when `datenormalised` was set to TRUE. 15 | * UPDATE: `calibrate()` now issues a warning in case dates have calibrated probabilities outside the user defined `timeRange` value. 16 | * UPDATE: `stackspd()` now requires the `group` argument to be factors. Factor levels will be condition the plot order in `plot.stackCalSPD()`. 17 | * UPDATE: when setting the `rescale=TRUE` and `type='multipanel'`, `plot.stackCalSPD()` will now display the true y-axis range of individual SPDs (instead of a rescaled 0-1 range). 18 | 19 | # Version 1.4.3 (17 February 2022) 20 | * UPDATE: Reversed legend item order in `plot.stackCalSPD()` to match display 21 | * UPDATE: `hpdi()` now has the option to return a character vector with HPDI ranges in either BP or BCAD. 22 | 23 | # Version 1.4.2 (15 March 2021) 24 | * Bug fix: Fixed a number of minor bugs and errors caused when the summed probability vector contains zero. Functions affected by this bugs were: 25 | * proportion plots in `plot.stackCalSPD()` 26 | * `summary()` and `plot()` functions for `SpdModelTest` class objects 27 | * Bug Fix: Fixed issues with `summary()` function on `CalDates` class object with multiple dates (thanks to [nferebau](https://github.com/nfrerebeau) for the bug report and fix) 28 | `plot.stackCalSPD()` proportion plot to handle instances with 0 summed probability in the time Range of analysis. 29 | * UPDATE: `binMed()` function can now handle larger `caldates` objects. 30 | * NEW: `poolDates()` function allows combination of 14C ages associated with the same event using Ward and Wilson 1978 method. 31 | * Minor bug fixes. 32 | * Minor typos and errors in the help documentation. 33 | * Updated dependencies for `spatstat(>= 2.0-0)`. 34 | 35 | 36 | # Version 1.4.1 (6 October 2020) 37 | * UPDATE: Improved performance of the `calibrate()` function (c.a 400% faster) 38 | * UPDATE: `multiplot` allows for rescaled calibrated probability distribution (new argument `rescale`) for improved readability. 39 | * UPDATE: The package vignette now includes examples from new functions such as `multiplot()` and `stackspd()`. 40 | * UPDATE: `hdmi()` now computes the probability mass of each age bracket (thanks to [hanecakr](https://github.com/hanecakr) for the suggestion and sample code) 41 | * NEW: `transformSPD()` allows for taphonomic (and other user-defined) corrections to SPDs. 42 | * Bug fix: Fixed color matching and improved label placing in the `multiplot` function. 43 | * Bug fix: calCurve='normal' no longer causing error in `calibrate()` 44 | 45 | # Version 1.4.0 (15 August 2020) 46 | * IntCal20, ShCal20, and Marine20 curves added, with IntCal20 as default calibration curve for `calibrate()`. 47 | 48 | # Version 1.3.3 (4 August 2020) 49 | * Minor changes on NAMESPACE and test environment to ensure workable CRAN checks for all operating systems. 50 | 51 | # Verson 1.3.2 (25 July 2020) 52 | * Bug fix : `F14C=TRUE` was producting an error message in `calibrate()` after refactoring in version 1.3.1. 53 | * Bug fix : fixed error in the handling of `resErrors` (Delta R error) for marine reservoir effect. 54 | * NEW: `stackspd()` creates a set of multiple SPDs as an object of class `stackCalSPD` with a dedicated plot function. 55 | * NEW: `multiplot()` function for displaying multiple calibrated dates. 56 | * NEW: `hpdi()` function for computing highest probability density intervals of calibrated dates. 57 | * NEW: `combine()` function for concatenating multiple `calDates` class objects. 58 | * UPDATE: `calibrate()`, `modelTest()`, and `sptest()` are now parallelised using the *doSNOW* package, enabling progress bar when running over multiple cores. 59 | 60 | # Version 1.3.1 (18 March 2020) 61 | * `binPrep()` now accepts alternative clustering algorithms 62 | * Refactoring of calibration related functions to increase readability 63 | * Minor bug fixes 64 | 65 | # Version 1.3.0 (12 December 2019) 66 | * UPDATEs in `modelTest()`: 67 | * Added an error message and a note in the help documentation warning users to not use calibration curves not supported by `uncalibrate()`. 68 | * NEW argument `gridclip` to add range constrain in the simulation envelope. When set to TRUE the sampling is executed within the observed range of dates. 69 | * UPDATE `timeRange` can now be left undefined, in which case the range of median calibrated observed dates is used. 70 | * NEW argument `normalised` handles whether simulated dates should be normalised or not. 71 | * NEW arguments `backsight` and `changexpr` enabling the comparison of expected and observed rates of changes. 72 | * UPDATE: improved performance of `calsample` and `uncalsample` methods (update in `uncalibrate()`) ` 73 | * Bug fix: users no longer need to specify `nsim` when `fitonly` is set to TRUE. 74 | * UPDATE in `permTest()` 75 | * NEW arguments `backsight` and `changexpr` enabling the comparison of expected and observed rates of changes. 76 | * UPDATE in `spd()`: aggregation matrix now spans beyond `timeRange` to avoid edge effects. 77 | * UPDATE in `calibrate()`: the new argument `F14C` enables calibration in F14C space. 78 | * UPDATE in `SPpermTest()`: 79 | * function is deprecated and renamed `sptest()` 80 | * function now allows user defined expression for computing the rate of change 81 | * UPDATE in `spd2gg()`: 82 | * function is deprecated and renamed `spd2rc()` 83 | * function now allows user defined expression for computing the rate of change 84 | * rates of changes can now be based on abutting time-blocks (e.g. 5600-5501 to 5500-5401) or a fixed interval across all years. 85 | * NEW: `thinDates()` function to randomly select a maximum number of dates per site, bin or phase. 86 | * NEW: `as.CalDates()` function converts dates in `BchronCalibratedDates` class ([Bchron](https://cran.r-project.org/package=Bchron)) and `oxcAARCalibratedDatesList`class ([oxAAR](https://cran.r-project.org/package=oxcAAR)) into CalDates` class (rcarbon). 87 | * NEW: `sampleDates()` function for sampling random dates from calibrated dates or bins. 88 | * NEW: `ckde()` function for generating composite kernel density estimates. 89 | * NEW: Suite of functions for mapping the spatial intensity of a set of radiocarbon dates via Kernel Density Estimates. 90 | * `stkde()` Map the spatio-temporal intensity of a set of radiocarbon dates across multiple years 91 | * `spkde()` Map the spatial intensity of a set of radiocarbon dates for a given focal year. 92 | * Associated `plot()` function. 93 | * NEW: `subset()` and `which.CalDates()` for subsetting and extracting indices of calibrated dates based on temporal intervals described by logical conditions (e.g. between 5500 and 4500 cal BP) and user defined probability mass. 94 | * Bug fix: fixed display error in some `plot()` functions when calendar is set to `BC/AD' 95 | * Bug fix: fixed error in the computation of the combined uncertainties in `mixCurves()`. 96 | * Further minor bug fixes for R 4.0.0 97 | 98 | # Version 1.2.0 (1 October 2018) 99 | * Bug fix in `SPpermTest()`: Functions was not working when not running when `raw=FALSE` and `ncores=1`. 100 | * Bug fix in `summary()` for the output of `modelTest()`: The number of bins reported was incorrect. 101 | * UPDATE: `binsense()` requires a smaller number of non-optional arguments and allows for binning based on median calibrated dates. 102 | * UPDATE: `plot()` function for geometric growth rates now allows for BC/AD calendar display. 103 | * UPDATE: `binPrep()` can now group dates based on median calibrated dates. 104 | * UPDATE: `modelTest()`can now test SPD generated from multiple calibration curves. 105 | * UPDATE: `modelTest()` now uses randomised back-calibration for the 'calsample' method. 106 | * UPDATE: `uncalibrate()`'s random back-calibration now utilises both the user supplied lab error and the error of the calibration curve. 107 | * NEW: `mixCurves()` function generates mixed terrestrial/marine calibration curves. 108 | * Further minor updates in plot labels, help documentation, and vignette. 109 | 110 | # Version 1.1.3 (26 June 2018) 111 | * Bug fix in `permTest()`: p-values calculation algorithm was yielding p-values of 0. 112 | * NEW: `summary()` functions for the outputs of `permTest()` and `modelTest()`. 113 | 114 | # Version 1.1.2 (22 May 2018) 115 | * Bug Fix in `calibrate()`: calibration of multiple dates with different calibration curves was based on the calibration curve of the first sample. 116 | * Bug Fix in `modelTest()`: back-calibration routine was ignoring user-supplied calibration curve and was solely using "intcal13". 117 | * UPDATE: `modelTest()` now allows for two distinct procedures for generating random dates from fitted models. 118 | * Minor corrections (e.g. typos) in the help documentation. 119 | 120 | # Version 1.1.1 (28 April 2018) 121 | * Added a Vignette. 122 | * Added normally-distributed (non-14C) age in `calibrate()`. 123 | * Fixed a bug in `SPpermTest()` generating opposite results (positive deviations were recorded as negative deviations) when `ncores` was larger than 1. 124 | * Fixed a minor bug in the implementation of the [North el al 2002] formula 125 | * Several changes in the`plot.SpatialTest()`. 126 | * NEW function: `spd2gg()` to convert SPD curves into geometric growth rates for given temporal blocks and an associated plot function. 127 | * Minor updates in the documentation. 128 | 129 | # Version 1.1.0 (12 March 2018) 130 | * Improved performance of `modelTest()` function when running with multiple cores. 131 | * NEW function: `p2pTest()` for comparing point to point differences in SPD. 132 | * p-values of Monte-Carlo simulations are now all calculated using a different formula. 133 | * minor bug fixes 134 | 135 | 136 | # Version 1.0.0 (9 October 2017) 137 | First official CRAN release. 138 | -------------------------------------------------------------------------------- /R/calibration-helpers.R: -------------------------------------------------------------------------------- 1 | # normalise densities to 1 2 | normalise_densities <- function(dens,eps) { 3 | dens <- dens/sum(dens) 4 | dens[dens < eps] <- 0 5 | dens <- dens/sum(dens) 6 | return(dens) 7 | } 8 | 9 | # calibrates in F14C space 10 | F14C_calibration <- function(age, error, calf14,calf14error, eps) { 11 | # F14 <- exp(calcurve[,2]/-8033) 12 | # F14Error <- F14*calcurve[,3]/8033 13 | # calf14 <- approx(calcurve[,1], F14, xout=calBP)$y 14 | # calf14error <- approx(calcurve[,1], F14Error, xout=calBP)$y 15 | f14age <- exp(age/-8033) 16 | f14err <- f14age*error/8033 17 | p1 <- (f14age - calf14)^2 18 | p2 <- 2 * (f14err^2 + calf14error^2) 19 | p3 <- sqrt(f14err^2 + calf14error^2) 20 | dens <- exp(-p1/p2)/p3 21 | dens[dens < eps] <- 0 22 | return(dens) 23 | } 24 | 25 | # calibrates in 14C BP space 26 | BP14C_calibration <- function(age, error, mu, tau2, eps) { 27 | tau <- error^2 + tau2 28 | dens <- dnorm(age, mean=mu, sd=sqrt(tau)) 29 | dens[dens < eps] <- 0 30 | return(dens) 31 | } 32 | 33 | # reads a cal curve file from extdata 34 | read_cal_curve_from_file <- function(calCurves) { 35 | calCurveFile <- paste(system.file("extdata", package="rcarbon"), "/", calCurves,".14c", sep="") 36 | options(warn=-1) 37 | calcurve <- readLines(calCurveFile, encoding="UTF-8") 38 | calcurve <- calcurve[!grepl("[#]",calcurve)] 39 | calcurve.con <- textConnection(calcurve) 40 | calcurve <- as.matrix(read.csv(calcurve.con, header=FALSE, stringsAsFactors=FALSE))[,1:3] 41 | close(calcurve.con) 42 | options(warn=0) 43 | colnames(calcurve) <- c("CALBP","C14BP","Error") 44 | return(calcurve) 45 | } 46 | -------------------------------------------------------------------------------- /R/data.R: -------------------------------------------------------------------------------- 1 | #' @title Radiocarbon dates from the EUROEVOL database 2 | #' @description Radiocarbon dates (n=14,053) and site coordinates (n=4,213) from the EUROEVOL project database. Sites without radiocarbon dates (n=544), phase-codes, and other data have been omitted. 3 | 4 | #' @format A data.frame with the following variables: 5 | #' \describe{ 6 | #' \item{\code{C14ID}}{ID of each radiocarbon date} 7 | #' \item{\code{C14Age}}{Radiocarbon age in 14C years BP} 8 | #' \item{\code{C14SD}}{Radiocarbon age error} 9 | #' \item{\code{LabCode}}{Labcode of the radiocarbon date} 10 | #' \item{\code{Material}}{Material of the dated sample} 11 | #' \item{\code{SiteID}}{ID of the site from which the sample has been recovered} 12 | #' \item{\code{Latitude}}{Latitude of the sampling site in decimal degrees} 13 | #' \item{\code{Longitude}}{Longitude of the sampling site in decimal degrees} 14 | #' \item{\code{Country}}{Country where the sampling site is located} 15 | #'} 16 | #' @source Manning, K., Colledge, S., Crema, E., Shennan, S., Timpson, A., 2016. The Cultural Evolution of Neolithic Europe. EUROEVOL Dataset 1: Sites, Phases and Radiocarbon Data. Journal of Open Archaeology Data 5. doi:10.5334/joad.40 17 | #' @references 18 | #' Shennan, S., Downey, S.S., Timpson, A., Edinborough, K., Colledge, S., Kerig, T., Manning, K., Thomas, M.G., 2013. Regional population collapse followed initial agriculture booms in mid-Holocene Europe. Nature Communications 4, ncomms3486. doi:10.1038/ncomms3486 19 | #' 20 | #' Timpson, A., Colledge, S., Crema, E., Edinborough, K., Kerig, T., Manning, K., Thomas, M.G., Shennan, S., 2014. Reconstructing regional population fluctuations in the European Neolithic using radiocarbon dates: a new case-study using an improved method. Journal of Archaeological Science 52, 549-557. doi:10.1016/j.jas.2014.08.011 21 | #' 22 | #' @examples 23 | #' \dontrun{ 24 | #' data(euroevol) 25 | #' Ireland <- subset(euroevol,Country=="Ireland") 26 | #' bins <- binPrep(Ireland$SiteID,Ireland$C14Age,h=200) 27 | #' x <- calibrate(Ireland$C14Age,Ireland$C14SD) 28 | #' spd.ireland <- spd(x,bins=bins,runm=200,timeRange=c(8000,4000)) 29 | #' plot(spd.ireland) 30 | #'} 31 | "euroevol" 32 | 33 | #' @title Radiocarbon dates for the Eastern Mediterranean around the Younger Dryas 34 | #' @description Radiocarbon dates (n=1915) and site coordinates (n=201) from a paper considering the relationship between human activity in the eastern Mediterranean/Middle East and early Holocene climate change, including the Younger Dryas. 35 | 36 | #' @format A data.frame with the following variables: 37 | #' \describe{ 38 | #' \item{\code{LabID}}{Laboratory ID assigned to each radiocarbon date (where known)} 39 | #' \item{\code{CRA}}{Radiocarbon age in 14C years BP} 40 | #' \item{\code{Error}}{Radiocarbon age error} 41 | #' \item{\code{Material}}{Material of the dated sample} 42 | #' \item{\code{Species}}{Species of the dated sample (where identified)} 43 | #' \item{\code{SiteName}}{Name of the site from which the sample has been recovered} 44 | #' \item{\code{Country}}{Country where the sampling site is located} 45 | #' \item{\code{Longitude}}{Longitude of the sampling site in decimal degrees} 46 | #' \item{\code{Latitude}}{Latitude of the sampling site in decimal degrees} 47 | #' \item{\code{Region}}{One of three analytical regions (1=southern Levant, 2=Northern Levant, 3= South-central Anatolia} 48 | #'} 49 | #' @source Palmisano, A., Bevan, A. and S. Shennan 2017. Data and code for demographic trends in the paper "Human responses and non-responses to climatic variations during the Last Glacial-Interglacial transition in the eastern Mediterranean", UCL Discovery Archive 1570274. doi:10.14324/000.ds.1570274. 50 | #' @references 51 | #' Roberts, N., Woodbridge, J., Bevan, A., Palmisano, A., Shennan, S. and E. Asouti 2017. Human responses and non-responses to climatic variations during the Last Glacial-Interglacial transition in the eastern Mediterranean. Quaternary Science Reviews, 184, 47-67. doi:10.1016/j.quascirev.2017.09.011. 52 | #' 53 | #' @examples 54 | #' \dontrun{ 55 | #' data(emedyd) 56 | #' northernlevant <- emedyd[emedyd$Region=="2",] 57 | #' bins <- binPrep(northernlevant$SiteName, northernlevant$CRA, h=50) 58 | #' x <- calibrate(northernlevant$CRA, northernlevant$Error, normalised=FALSE) 59 | #' spd.northernlevant <- spd(x, bins=bins, runm=50, timeRange=c(17000,8000)) 60 | #' plot(spd.northernlevant) 61 | #'} 62 | "emedyd" 63 | 64 | 65 | #' @title Subset of EUROEVOL radiocarbon dates from Great Britain 66 | #' @description Radiocarbon dates (n=2,324) and site coordinates (n=652) from England and Wales collected from the EUROEVOL project database. See \cite{\link{euroevol}} for more details regarding the source data. 67 | #' 68 | #' @format A data.frame with the following variables: 69 | #' \describe{ 70 | #' \item{\code{C14ID}}{ID of each radiocarbon date} 71 | #' \item{\code{C14Age}}{Radiocarbon age in 14C years BP} 72 | #' \item{\code{C14SD}}{Radiocarbon age error} 73 | #' \item{\code{LabCode}}{Labcode of the radiocarbon date} 74 | #' \item{\code{Material}}{Material of the dated sample} 75 | #' \item{\code{SiteID}}{ID of the site from which the sample has been recovered} 76 | #' \item{\code{Eastings}}{Easting coordinates of the sampling site in meters (OSGB 1936 epsg:27700) } 77 | #' \item{\code{Northings}}{Northing coordinates of the sampling site in meters (OSGB 1936 epsg:27700)} 78 | #'} 79 | #' @source Manning, K., Colledge, S., Crema, E., Shennan, S., Timpson, A., 2016. The Cultural Evolution of Neolithic Europe. EUROEVOL Dataset 1: Sites, Phases and Radiocarbon Data. Journal of Open Archaeology Data 5. doi:10.5334/joad.40 80 | #' 81 | "ewdates" 82 | 83 | 84 | #' @title Polygonal window of England and Wales 85 | #' @description An \code{\link{owin}} class polygonal window of England and Wales. 86 | #' @format An \code{owin} class object. 87 | #' @examples 88 | #' \dontrun{ 89 | #' data(ewowin) 90 | #' # Obtained from rworldmap: 91 | #' library(maptools) 92 | #' library(rgeos) 93 | #' library(rworldmap) 94 | #' bng <- CRS("+init=epsg:27700") 95 | #' sbrit <- getMap(resolution="high") 96 | #' sbrit <- spTransform(sbrit[sbrit$GEOUNIT =="United Kingdom",], bng) 97 | #' tmp <- SpatialPolygons(list(Polygons(list(Polygon(cbind(c(130000,130000,310000, 98 | #' 425000,700000,700000,130000), c(0,300000,560000,598000,300000,0,0)))), 99 | #' "1")), 1:1, proj4string=bng) 100 | #' sbrit <- gIntersection(sbrit,tmp) 101 | #' ewowin <- as.owin(sbrit) 102 | #' } 103 | #' @source South,A.2011.rworldmap: A New R package for Mapping Global Data. The R Journal Vol. 3/1 : 35-43. 104 | "ewowin" 105 | 106 | -------------------------------------------------------------------------------- /R/package-rcarbon.R: -------------------------------------------------------------------------------- 1 | #' @title rcarbon:Calibration and analysis of radiocarbon dates 2 | #' 3 | #' @description The \pkg{rcarbon} package handles the calibration and analysis of radiocarbon, often but not exclusively for the purposes of archaeological research. It includes functions not only for basic calibration, uncalibration and plotting of one or more dates, but also a statistical framework for building demographic and related longitudinal inferences from aggregate radiocarbon date lists. 4 | 5 | #' @details 6 | #' 7 | #' Core functions in the \pkg{rcarbon} package can be grouped as follows: 8 | #' \describe{ 9 | #' \item{\strong{Calibration Functions}}{\code{\link{calibrate}} and \code{\link{uncalibrate}} enable the calibration and back-calibration for a variety of curves.} 10 | #' \item{\strong{Aggregation Functions}}{\code{\link{spd}} generates a summed probability distribution (SPD) of radiocarbon dates; \code{\link{binPrep}} can be used to define clusters of radiocarbon dates associated with the same context/phase} 11 | #' \item{\strong{Statistical Test Functions}}{\code{\link{modelTest}} compares the observed SPD against a variety of theoretical models (most typically an exponential curve) using the Monte-Carlo approach; \code{\link{p2pTest}} compares observed differences in SPD between two user-specified points in time against differences expected from a theoretical model; \code{\link{permTest}} compares two or more SPDs and test for the null hypothesis that all sets are derived from the same population; \code{\link{sptest}} identifies, for defined intervals, locations with significantly higher or lower growth rate in the SPD compared to the pan-regional trend in the data} 12 | #' } 13 | #' @note 14 | #' Up-to-date development version, bug-reports, and further information concerning the \pkg{rcarbon} package can be found on GitHub (\url{https://github.com/ahb108/rcarbon}). 15 | #' To see the preferred citation for the package, type citation("rcarbon"). 16 | #' 17 | #'@references See individual functions for references. 18 | #' 19 | #' @author The \pkg{rcarbon} is developed and maintained by Andrew Bevan and Enrico Crema 20 | #' @docType package 21 | #' @name rcarbon 22 | #' @aliases rcarbon-package 23 | NULL 24 | -------------------------------------------------------------------------------- /R/rcarbon-deprecated.R: -------------------------------------------------------------------------------- 1 | #' @title Deprecated functions. 2 | #' @description The functions listed below are deprecated and will be defunct in 3 | #' the near future. When possible, alternative functions with similar 4 | #' functionality are also mentioned. Help pages for deprecated functions are 5 | #' available at \code{help("-deprecated")}. 6 | #' @name rcarbon-deprecated 7 | #' @keywords internal 8 | NULL 9 | -------------------------------------------------------------------------------- /R/utilities.R: -------------------------------------------------------------------------------- 1 | #' @title Rescale a numeric vector to a specified minimum and maximum 2 | #' @description Rescale a numeric vector to a specified minimum and maximum. 3 | #' @param x numeric vector to smooth. 4 | #' @param type what kind of rescaling to perform. Current options are 'simple' (default) and 'normal' which produces a z-score and 'custom' for which the 'to' argument must be specified. 5 | #' @param to numeric vector of length 2 specifying the minimum and maximum value to perform a linear rescale between (default is 0 and 1) 6 | #' @param na.rm Set to TRUE,this removes NAs before rescaling. 7 | #' @return A numeric vector of rescaled values. 8 | #' @examples 9 | #' reScale(15:200) 10 | #' @import stats 11 | #' @export 12 | 13 | reScale <- function(x, type="simple", to=c(0,1), na.rm=TRUE){ 14 | 15 | types <- c("simple","normal") 16 | if (!type %in% types){ 17 | stop("The rescale type you have chosen is not currently an option.") 18 | } 19 | if (max(x)-min(x)==0){ 20 | warning("All the values in x are the same, and will just be recentred on 0 if type='normal' or max(to) if type='simple'.") 21 | if (type=="normal"){ res <- rep(0,length(x)) } else { res <- rep(max(to), length(x)) } 22 | return(res) 23 | } 24 | if (na.rm){ x <- na.omit(x) } 25 | if (type=="normal"){ 26 | res <- (x-mean(x))/sd(x) 27 | } else { 28 | xrange <- range(x) 29 | mfac <- (to[2] - to[1])/(xrange[2] - xrange[1]) 30 | res <- to[1] + (x - xrange[1]) * mfac 31 | } 32 | return(res) 33 | } 34 | 35 | #' @title Calculate a running mean from a numeric vector. 36 | #' @description Calculate a running mean from a numeric vector. 37 | #' @param x numeric vector to smooth. 38 | #' @param n the size of the window in which to smooth. 39 | #' @param edge How to treat edge cases where a full window is unavailable. Current options are 'NA' to fill with NAs or 'fill' to fill with original values 40 | #' @return A numeric vector of smoothed values. 41 | #' @examples 42 | #' x <- rnorm(1000) 43 | #' y <- c(1:1000) 44 | #' plot(y,x, type="l") 45 | #' lines(runMean(x,50), col="red") 46 | #' @import stats 47 | #' @export 48 | 49 | runMean <- function(x, n, edge="NA"){ 50 | res <- x 51 | tmp <- filter(res,rep(1/n,n), sides=2) 52 | if (edge == "fill"){ 53 | res[!is.na(tmp)] <- tmp[!is.na(tmp)] 54 | } else { 55 | res <- tmp 56 | } 57 | return(res) 58 | } 59 | 60 | #' Smooth a numeric vector using a Gaussian window 61 | #' 62 | #' @description Smooth a numeric vector using a Gaussian window 63 | #' @param x numeric vector of values to smooth. 64 | #' @param alpha numeric value controlling the size of the gaussian smoothing window. Proportional to the standard deviation of the Gaussian smoothing kernel where sd=(N-1)/(2*alpha) with N being the length of the input vector. 65 | #' @param window a fraction between 0 and 1 representing the proportion of the input vector to include in the moving window. 66 | #' @details Adapted from \code{smth.gaussian} in the \code{smoother} package. 67 | #' @references 68 | #' Hamilton, N. (2015). smoother: Functions Relating to the Smoothing of Numerical Data, R package version 1.1, https://CRAN.R-project.org/package=smoother 69 | #' @examples 70 | #' smoothGauss(runif(200),alpha=5) 71 | #' @import stats 72 | #' @export 73 | 74 | smoothGauss <- function(x, alpha, window=0.1){ 75 | 76 | windowLength <- as.integer(max(abs(window*length(x)),1)) 77 | hw <- abs(windowLength / 2.0) 78 | w <- sapply(c(0:(windowLength-1)), function(x){ 79 | n <- x - as.integer(hw) 80 | k <- -0.5 * (abs(alpha) * n / hw) ^2 81 | exp(1)^k 82 | }) 83 | sizeW <- length(w) 84 | sizeD <- length(x) 85 | w <- w/sum(w) 86 | hkwL <- as.integer(sizeW/2) 87 | hkwR <- sizeW - hkwL 88 | smthfun <- function(i){ 89 | ix.d <- c((i-hkwL):(i+hkwR-1)) 90 | ix.w <- which(ix.d %in% 1:sizeD) 91 | ix.d <- ix.d[ix.w] 92 | if (length(ix.w) != sizeW){ 93 | W.nm <- w[ix.w] / sum(w[ix.w]) 94 | } else { 95 | W.nm <- w 96 | } 97 | D.nm <- x[ix.d] 98 | as.numeric(D.nm %*% W.nm) 99 | } 100 | res <- sapply(c(1:sizeD), FUN=smthfun) 101 | res[c(1:hkwL,(sizeD - hkwR + 1):sizeD)] <- NA # remove tails 102 | return(res) 103 | } 104 | 105 | #' @import utils 106 | #' @keywords internal 107 | 108 | rangecheck <- function(x, bins, timeRange, datenormalised=FALSE){ 109 | binNames <- unique(bins) 110 | calyears <- data.frame(calBP=seq(timeRange[1], timeRange[2],-1)) 111 | caldateTR <- as.numeric(x$metadata[1,c("StartBP","EndBP")]) 112 | caldateyears <- seq(caldateTR[1],caldateTR[2],-1) 113 | binnedMatrix <- matrix(NA, nrow=nrow(calyears), ncol=length(binNames)) 114 | for (b in 1:length(binNames)){ 115 | index <- which(bins==binNames[b]) 116 | if (length(x$calmatrix)>1){ 117 | tmp <- x$calmatrix[,index, drop=FALSE] 118 | if (datenormalised){ 119 | tmp <- apply(tmp,2,FUN=function(x) x/sum(x)) 120 | } 121 | spdtmp <- rowSums(tmp) 122 | if (length(binNames)>1){ 123 | spdtmp <- spdtmp / length(index) 124 | } 125 | binnedMatrix[,b] <- spdtmp[caldateyears<=timeRange[1] & caldateyears>=timeRange[2]] 126 | 127 | } else { 128 | slist <- x$grids[index] 129 | slist <- lapply(slist,FUN=function(x) merge(calyears,x, all.x=TRUE)) 130 | slist <- rapply(slist, f=function(x) ifelse(is.na(x),0,x), how="replace") 131 | slist <- lapply(slist, FUN=function(x) x[with(x, order(-calBP)), ]) 132 | tmp <- lapply(slist,`[`,2) 133 | if (datenormalised){ 134 | outofTR <- lapply(tmp,sum)==0 # date out of range 135 | tmpc <- tmp[!outofTR] 136 | if (length(tmpc)>0){ 137 | tmp <- lapply(tmpc,FUN=function(x) x/sum(x)) 138 | } 139 | } 140 | if (length(binNames)>1){ 141 | spdtmp <- Reduce("+", tmp) / length(index) 142 | } else { 143 | spdtmp <- Reduce("+", tmp) 144 | } 145 | binnedMatrix[,b] <- spdtmp[,1] 146 | } 147 | } 148 | return(sum(apply(binnedMatrix,2,sum)==0)/ncol(binnedMatrix)*100) 149 | } 150 | 151 | #' @title Convert BP dates to BC/AD format 152 | #' @description Converts calibrated BP dates to BC/AD dates, omitting `year 0' 153 | #' @param x A numerical vector (currently only basic checks that these numbers are in a sensible range). 154 | #' @return A vector with BC/BCE dates expressed as negative numbers and AD/CE dates as positive ones. 155 | #' @examples 156 | #' BPtoBCAD(4200) 157 | #' @export 158 | 159 | BPtoBCAD <- function(x){ 160 | index <- !is.na(x) 161 | if (any(x[index] < 0)){ stop("Post-bomb dates (<0 BP) are not currently supported.") } 162 | res <- matrix(c(x, rep(NA,length(x))), ncol=2) 163 | res[index & x < 1950,2] <- 1950-res[index & x < 1950,1] 164 | res[index & x >= 1950,2] <- 1949-res[index & x >= 1950,1] 165 | return(res[,2]) 166 | } 167 | 168 | #' @title Convert BC/AD dates to BP format 169 | #' @description Converts BC/AD dates to BP format while handling the absence of 'year 0' 170 | #' @param x A numerical vector (currently only basic checks that these numbers are in a sensible range). 171 | #' @return A vector with BP dates. 172 | #' @examples 173 | #' BCADtoBP(-1268) 174 | #' @export 175 | 176 | BCADtoBP <- function(x){ 177 | index <- !is.na(x) 178 | if (any(x[index] == 0)){ stop("0 BC/AD is not a valid year.") } 179 | if (any(x[index] > 1950)){ stop("Post-bomb dates (> AD 1950) are not currently supported.") } 180 | res <- matrix(c(x, rep(NA,length(x))), ncol=2) 181 | res[index & x > 0,2] <- abs(res[index & x > 0,1] - 1950) 182 | res[index & x < 0,2] <- abs(res[index & x < 0,1] - 1949) 183 | return(res[,2]) 184 | } 185 | 186 | 187 | #' @title Computes the median date of each bin 188 | #' 189 | #' @description Function for generating a vector of median calibrated dates for each each bin. 190 | #' 191 | #' @param x A \code{CalDates} class object. 192 | #' @param bins vector containing the bin names associated with each radiocarbon date. Can be generated using \code{\link{binPrep}}. 193 | #' @param verbose A logical variable indicating whether extra information on progress should be reported. Default is TRUE. 194 | #' 195 | #' @return A vector of median dates in cal BP 196 | #' @examples 197 | #' \dontrun{ 198 | #' #Load EUROEVOL Data 199 | #' data(euroevol) 200 | #' #Subset Danish Dates 201 | #' denmark <- subset(euroevol,Country=="Denmark") 202 | #' #Calibrate and Bin 203 | #' denmarkDates <- calibrate(x=denmark$C14Age,errors=denmark$C14SD) 204 | #' denmarkBins <- binPrep(sites=denmark$SiteID,ages=denmark$C14Age,h=200) #200 years bin size 205 | #' #Compute median date for each bin 206 | #' binMed(x=denmarkDates,bins=denmarkBins) 207 | #' } 208 | #' @seealso \code{\link{binPrep}},\code{\link{barCodes}} 209 | #' @import utils 210 | #' @import stats 211 | #' @export 212 | 213 | binMed <- function(x,bins,verbose=TRUE){ 214 | if (!"CalDates" %in% class(x)){ 215 | stop("x must be an object of class 'CalDates'.") 216 | } 217 | if (length(bins)>1){ 218 | nbins <- length(unique(bins)) 219 | if (any(is.na(bins))){ 220 | stop("Cannot have NA values in bins.") 221 | } 222 | if (length(bins)!=nrow(x$metadata)){ 223 | stop("bins (if provided) must be the same length as x.") 224 | } 225 | } else { 226 | bins <- rep("0_0",nrow(x$metadata)) 227 | } 228 | binNames <- unique(bins) 229 | medbins = numeric(length=nbins) 230 | caltimeRange =c(55000,0) 231 | if (any(x$metadata$CalCurve %in% c("intcal13","shcal13","marine13","intcal13nhpine16","shcal13shkauri16"))) 232 | { 233 | caltimeRange =c(50000,0) 234 | } 235 | calyears <- data.frame(calBP=seq(caltimeRange[1], 0,-1)) 236 | 237 | if (verbose){ 238 | if (length(x$calmatrix)>1){ 239 | print("Aggregating...") 240 | } else { 241 | print("Extracting and aggregating...") 242 | } 243 | } 244 | 245 | caldateTR <- as.numeric(x$metadata[1,c("StartBP","EndBP")]) 246 | caldateyears <- seq(caldateTR[1],caldateTR[2],-1) 247 | 248 | if (verbose & length(binNames)>1){ 249 | flush.console() 250 | pb <- txtProgressBar(min=1, max=length(binNames), style=3) 251 | } 252 | 253 | for (b in 1:length(binNames)){ 254 | 255 | if (verbose & length(binNames)>1){ setTxtProgressBar(pb, b) } 256 | index <- which(bins==binNames[b]) 257 | 258 | if (length(x$calmatrix)>1){ 259 | tmp <- x$calmatrix[,index, drop=FALSE] 260 | spdtmp <- rowSums(tmp) 261 | if (length(binNames)>1){ 262 | spdtmp <- spdtmp / length(index) 263 | } 264 | spdtmp=spdtmp[caldateyears<=caltimeRange[1] & caldateyears>=0] 265 | } else { 266 | 267 | slist <- x$grids[index] 268 | slist <- lapply(slist,FUN=function(x) merge(calyears,x, all.x=TRUE)) 269 | slist <- rapply(slist, f=function(x) ifelse(is.na(x),0,x), how="replace") 270 | slist <- lapply(slist, FUN=function(x) x[with(x, order(-calBP)), ]) 271 | tmp <- lapply(slist,`[`,2) 272 | if (length(binNames)>1){ 273 | spdtmp <- Reduce("+", tmp) / length(index) 274 | } else { 275 | spdtmp <- Reduce("+", tmp) 276 | } 277 | spdtmp = spdtmp[,1] 278 | } 279 | cumcal=cumsum(spdtmp) 280 | medbins[b]=caldateyears[which.min(abs(cumcal-max(cumcal)/2))] 281 | } 282 | if (verbose & length(binNames)>1){close(pb);print("Done")} 283 | 284 | return(medbins) 285 | } 286 | 287 | #' @title Computes rates of change from SPDs 288 | #' 289 | #' @description Function for computing rates of change between abutting user-defined time-blocks. 290 | #' 291 | #' @param spd Summed Probability Distribution obtained using the \code{\link{spd}} function. 292 | #' @param breaks A vector giving the breakpoints between the time-blocks. 293 | #' @param backsight A single numeric value defining the distance in time between the focal year and the backsight year for computing the rate of change. 294 | #' @param changexpr An expression defining how the rate of change is calculated, where \code{t1} is the summed probability for a focal block or year, \code{t0} is the summed probability for previous block or backsight year, and \code{d} is the duration of the block or the length of the backsight. Default is a geometric growth rate (i.e \code{expression((t1/t0)^(1/d)-1)}). 295 | #' @details When the argument \code{breaks} is supplied the function aggregates the summed probability within each time-block and compared them across abutting blocks using the expression defined by \code{changexpr}. When the argument \code{backsight} is provided he expression is based on the comparison between the summed probability of each year and the associated backsight year. 296 | #' 297 | #' @return An object of class \code{spdRC}. 298 | #' 299 | #' @examples 300 | #' \dontrun{ 301 | #' data(emedyd) 302 | #' caldates <- calibrate(x=emedyd$CRA, errors=emedyd$Error, normalised=FALSE, calMatrix=TRUE) 303 | #' bins <- binPrep(sites=emedyd$SiteName, ages=emedyd$CRA, h=50) 304 | #' emedyd.spd <- spd(caldates,bins,timeRange=c(16000,9000),runm=100) 305 | #' emedyd.gg <- spd2rc(emedyd.spd,breaks=seq(16000,9000,-1000)) 306 | #' emedyd.gg2 <- spd2rc(emedyd.spd,backsight=10) 307 | #' plot(emedyd.gg) 308 | #' plot(emedyd.gg2) 309 | #' } 310 | 311 | #' @import stats 312 | #' @export 313 | 314 | spd2rc <- function(spd,breaks=NULL,backsight=NULL,changexpr=expression((t1/t0)^(1/d)-1)) 315 | { 316 | if (is.null(breaks)&is.null(backsight)) 317 | { 318 | stop('Either breaks or backsight should be provided') 319 | } 320 | 321 | if (!is.null(breaks)&!is.null(backsight)) 322 | { 323 | stop('Both breaks and backsight cannot be provided') 324 | } 325 | 326 | if (is.null(backsight)) 327 | { 328 | if (length(unique(round(abs(diff(breaks)))))!=1) 329 | { 330 | stop("Unequal break intervals is not supported") 331 | } 332 | nBreaks = length(breaks)-1 333 | } 334 | 335 | timeRange = eval(parse(text=spd$metadata[2])) 336 | timeSequence = timeRange[1]:timeRange[2] 337 | 338 | # if block based: 339 | if(!is.null(breaks)) 340 | { 341 | type='blocks' 342 | obs=numeric(length=nBreaks) 343 | for (x in 1:nBreaks) 344 | { 345 | index=which(timeSequence<=breaks[x]&timeSequence>breaks[x+1]) 346 | obs[x]=sum(spd$grid[index,2]) 347 | } 348 | 349 | res=numeric(length=nBreaks-1) 350 | for (i in 1:(nBreaks-1)) 351 | { 352 | d=abs(breaks[i+1]-breaks[i]) 353 | t0 = obs[i] 354 | t1 = obs[i+1] 355 | res[i] = eval(changexpr) 356 | if (t1==0|t0==0){res[i]=NA} 357 | # res[i]=(obs[i+1]/obs[i])^(1/d)-1 358 | } 359 | } 360 | 361 | # if backsight based: 362 | if (!is.null(backsight)) 363 | { 364 | type ='backsight' 365 | breaks = NA 366 | res=rep(NA,length(timeSequence)) 367 | obs=NA 368 | 369 | for (i in 1:c(length(timeSequence)-backsight)) 370 | { 371 | d=backsight 372 | t0 = spd$grid$PrDens[i] 373 | t1 = spd$grid$PrDens[i+backsight] 374 | res[i+backsight] = eval(changexpr) 375 | if (t1==0|t0==0){res[i+backsight]=NA} 376 | } 377 | } 378 | 379 | res=list(sumblock=obs,roca=res,breaks=breaks,timeSequence=timeSequence,type=type) 380 | class(res) <- append(class(res),"spdRC") 381 | return(res) 382 | } 383 | 384 | 385 | #' @import stats 386 | #' @import grDevices 387 | #' @import graphics 388 | #' @import utils 389 | 390 | curveSamples <- function(bins,calCurves,nsim) 391 | { 392 | x = table(bins,calCurves) 393 | x = prop.table(x,1) 394 | x = replicate(nsim,table(factor(apply(x,1,function(x,y){sample(x=y,size=1,prob=x)},y=colnames(x)),levels=unique(calCurves)))) 395 | return(t(x)) 396 | } 397 | 398 | 399 | #' @title Sample random calendar dates 400 | #' 401 | #' @description Randomly samples calendar dates from each calibrated date or bin. 402 | #' @param x A 'CalDates' class object. 403 | #' @param bins A vector containing the bin names associated with each radiocarbon date. If set to NA, binning is not carried out. 404 | #' @param nsim Number of sampling repetitions. 405 | #' @param boot A logical value indicating whether bootstrapping is carried out (see details below). Default is FALSE. 406 | #' @param verbose A logical variable indicating whether extra information on progress should be reported. Default is TRUE. 407 | #' @details The function randomly samples calendar dates based from calibrated probability distributions. When the \code{bins} argument is supplied a single calendar date is sampled from each bin. When \code{boot=TRUE}, dates (or bins) are randomly sampled with replacement before calendar dates are sampled. 408 | #' 409 | #' @return An object of class \code{simdates} with the following elements 410 | #' \itemize{ 411 | #' \item{\code{sdates}} {A matrix containing the randomly sampled calendar dates, with rows containing each of the \code{nsim} repetitions.} 412 | #' \item{\code{weight}} {A vector (or matrix in when \code{boot=TRUE}) containing the total area under the curve of each date, normalised to sum to unity. Notice this will be identical for all dates if the calibration is carried out with the argument \code{normalised} set to TRUE.} 413 | #'} 414 | #' 415 | #' @import stats 416 | #' @import utils 417 | #' @export 418 | 419 | 420 | sampleDates <- function(x,bins=NA,nsim,boot=FALSE,verbose=TRUE) 421 | { 422 | # initial checks #### 423 | if (!"CalDates" %in% class(x)){ 424 | stop("x must be an object of class 'CalDates'.") 425 | } 426 | if (length(bins)>1){ 427 | if (any(is.na(bins))){ 428 | stop("Cannot have NA values in bins.") 429 | } 430 | if (length(bins)!=nrow(x$metadata)){ 431 | stop("bins (if provided) must be the same length as x.") 432 | } 433 | } 434 | else { 435 | bins <- 1:(length(x)) 436 | } 437 | uni.bins = unique(bins) 438 | nbins = length(uni.bins) 439 | binList = vector('list',length=nbins) 440 | binLength=numeric() 441 | calmatrix=FALSE 442 | if (anyNA(x$grids)){calmatrix=TRUE} 443 | if (calmatrix) 444 | { 445 | warning("Processing time is slower when dates are calibrated using calMatrix=TRUE",immediate.=TRUE) 446 | } 447 | # Aggregate Bins #### 448 | if (verbose){ 449 | flush.console() 450 | print("Aggregating...") 451 | pb <- txtProgressBar(min = 1, max = nbins,style = 3) 452 | } 453 | for (b in 1:nbins) 454 | { 455 | if (verbose){setTxtProgressBar(pb, b)} 456 | tmp.dates=x[which(bins==uni.bins[b])] 457 | if (calmatrix) 458 | { 459 | tmp.prob=tmp.dates$calmatrix 460 | binLength[b]=1 461 | if (length(tmp.dates)>1) 462 | { 463 | tmp.prob=apply(tmp.dates$calmatrix,1,sum) 464 | binLength[b]=ncol(tmp.dates$calmatrix) 465 | } 466 | tmp.prob=tmp.prob[which(tmp.prob>0)] 467 | binList[[b]]=data.frame(calBP=as.numeric(names(tmp.prob)),PrDens=tmp.prob) 468 | } else { 469 | if (length(tmp.dates)==1) 470 | { 471 | binList[[b]]=tmp.dates$grids[[1]] 472 | binLength[b]=1 473 | } else { 474 | binLength[b]=length(tmp.dates) 475 | st.date = max(unlist(lapply(tmp.dates$grids,function(x){max(x$calBP)}))) 476 | end.date = min(unlist(lapply(tmp.dates$grids,function(x){min(x$calBP)}))) 477 | tmp.prob = data.frame(calBP=st.date:end.date,PrDens=0) 478 | tmp.prob$PrDens=apply(sapply(tmp.dates$grids,function(x,r){ 479 | res = rep(0,length(r)) 480 | res[which(r%in%x$calBP)]=x$PrDens 481 | return(res)},r=tmp.prob$calBP),1,sum) 482 | binList[[b]]=tmp.prob 483 | } 484 | } 485 | } 486 | if (verbose) {close(pb)} 487 | # Sample random dates #### 488 | if (!boot) 489 | { 490 | if (verbose){print("Simulating dates ...")} 491 | res=sapply(binList,function(x,nsim){sample(x$calBP,size=nsim,prob=x$PrDens,replace=TRUE)},nsim=nsim) 492 | weight=sapply(binList,function(x){return(sum(x$PrDens))})/binLength 493 | weight=weight/sum(weight) 494 | } 495 | if (boot) 496 | { 497 | res = matrix(NA,nrow=nsim,ncol=nbins) 498 | weight = matrix(NA,nrow=nsim,ncol=nbins) 499 | if (verbose){ 500 | print("Bootstrapping...") 501 | pb <- txtProgressBar(min = 1, max = nsim,style = 3) 502 | } 503 | for (i in 1:nsim) 504 | { 505 | if (verbose){setTxtProgressBar(pb, i)} 506 | index=sample(nbins,replace=TRUE) 507 | res[i,]=sapply(binList[index],function(x,nsim){sample(x$calBP,size=1,prob=x$PrDens)}) 508 | weight[i,]=sapply(binList[index],function(x){sum(x$PrDens)})/binLength[index] 509 | weight[i,]=weight[i,]/sum(weight[i,]) 510 | } 511 | if (verbose) {close(pb)} 512 | } 513 | if (verbose){print("Done")} 514 | result=list(sdates=res,weight=weight) 515 | class(result) = c('simdates',class(result)) 516 | return(result) 517 | } 518 | 519 | #' @title Gaussian weighting of dates relative to 520 | #' @description Rescale a numeric vector to a specified minimum and maximum. 521 | #' @param x A numeric vector or an object of class CalDates. 522 | #' @param mean A single numeric value indicating the value to centre the Gaussian kernel on. 523 | #' @param sd A single numeric value indicating the standard deviation of the Gaussian kernel to be used. 524 | #' @param type The type of output to produce: currently either "weighted" (for a simple total weight value for each date) or "raw" (a list of reweighted calibrated radiocarbon probabilities for each calibrated date). 525 | #' @return A numeric vector of weights (or optionally a list of reweighted calibrated radiocarbon probabilities). 526 | #' @examples 527 | #' ## Example weighting fo a set of dates versus a focal date of 5950 calBP 528 | #' years <- seq(6500, 5500, -10) 529 | #' plot(cbind(years, gaussW(years, 5950, 50))) 530 | #' ## Example weighting of three calibrated dates versus a focal date of 5950 calBP 531 | #' dates <- calibrate(c(5280, 5180, 5080), c(30,30,30), normalised=FALSE) 532 | #' gaussW(dates, 5950, 50) 533 | #' ## Or the same with raw output 534 | #' dateswt <- gaussW(dates, 5950, 50, type="raw") 535 | #' head(dateswt[[1]]) 536 | #' @export 537 | #' 538 | gaussW <- function(x, mean, sd, type="weights"){ 539 | if (!class(x)[1] %in% c("numeric", "CalDates")){ 540 | stop("Input must be a numeric vector of calibrated years BP or an object of class CalDates.") 541 | } 542 | if (!type %in% c("weights","raw")){ stop("type must be either weights or raw.") } 543 | base <- (dnorm(x=mean, mean=mean, sd=sd)) 544 | if (class(x)[1]=="numeric"){ 545 | res <- dnorm(x=x, mean=mean, sd=sd) / base 546 | return(res) 547 | } else { 548 | res <- vector(mode="list", length=length(x)) 549 | wts <- vector(mode="numeric", length=length(x)) 550 | for (a in 1: length(x)){ 551 | wt <- dnorm(x=x$grids[[a]]$calBP, mean=mean, sd=sd) / base 552 | res[[a]] <- cbind(x$grids[[a]]$calBP, x$grids[[a]]$PrDens * wt) 553 | wts[a] <- sum(x$grids[[a]]$PrDens * wt) 554 | } 555 | } 556 | if (type=="raw"){ 557 | return(res) 558 | } else if (type=="weights"){ 559 | return(wts) 560 | } 561 | } 562 | 563 | rybcolourmap <- function(range, ...) { 564 | ## slightly modified from beachcolourmap() in the spatstat package 565 | col <- rybcolours(range, ...) 566 | z <- colourmap(col, range=range) 567 | return(z) 568 | } 569 | 570 | rybcolours <- function(range, sealevel=0, ncolours=100, nbeach=0){ 571 | ## modified from beachcolours() in the spatstat package 572 | stopifnot(is.numeric(range) && length(range)==2) 573 | stopifnot(all(is.finite(range))) 574 | yr <- colorRampPalette(c("yellow","orangered","darkred"), space="rgb") 575 | cb <- colorRampPalette(c("blue","cyan","yellow"), space="rgb") 576 | depths <- range[1] 577 | peaks <- range[2] 578 | dv <- diff(range)/(ncolours - 1) 579 | epsilon <- nbeach * dv/2 580 | lowtide <- max(sealevel - epsilon, depths) 581 | hightide <- min(sealevel + epsilon, peaks) 582 | countbetween <- function(a, b, delta) { max(0, round((b-a)/delta)) } 583 | nsea <- countbetween(depths, lowtide, dv) 584 | nbeach <- countbetween(lowtide, hightide, dv) 585 | nland <- countbetween(hightide, peaks, dv) 586 | colours <- character(0) 587 | if(nsea > 0) colours <- cb(nsea) # cyan/blue 588 | if(nbeach > 0) colours <- c(colours,rep("yellow",nbeach)) # yellow 589 | if(nland > 0) colours <- c(colours, yr(nland)) # darkred/yellow 590 | return(colours) 591 | } 592 | 593 | #' @title Subsetting calibrated dates 594 | #' @description Subsets calibrated dates (\code{CalDates} class object) based on Logical expressions of time intervals. 595 | #' @param x A CalDates class object 596 | #' @param s Logical expression indicating dates to keep. The expression should include the term \code{BP} which refers to specific dates. 597 | #' @param p Probability mass meeting the condition defined by \code{ss}. 598 | #' @param ... Further arguments to be passed to or from other methods (ignored). 599 | #' @details The function subsets \code{CalDates} class objects by identifying all dates that have a probability mass larger than \code{p} for a user defined logical expression of temporal interval containing the term \code{BP}, where \code{BP} refers to radiocarbon date. See examples for further detailes 600 | #' @return A CalDates class object. 601 | #' @examples 602 | #' ## Generate some calibrated dates 603 | #' x = calibrate(c(12100,5410,5320,3320),errors=c(20,20,30,30)) 604 | #' ## Subsets all dates that have a probability mass above 0.8 before 10000 BP 605 | #' x2 = subset(x,BP>10000,p=0.8) 606 | #' ## Subsets all dates that have a probability mass above 0.5 between 6000 and 6300 BP 607 | #' x3 = subset(x,BP>6000&BP<6300,p=0.5) 608 | #' @import stats 609 | #' @export 610 | 611 | subset.CalDates=function(x,s,p,...) 612 | { 613 | index=rep(NA,length(x)) 614 | s=substitute(s) 615 | calmat=anyNA(x$calmatrix) 616 | if (calmat) 617 | { 618 | for (i in 1:length(x)) 619 | { 620 | tmp=x$grids[[i]] 621 | BP=tmp$calBP 622 | prdens=tmp$PrDens/sum(tmp$PrDens) 623 | sumprob=sum(prdens[eval(s)]) 624 | index[i]=sumprob>p 625 | } 626 | } else { 627 | BP=as.numeric(row.names(x$calmatrix)) 628 | tmp=apply(x$calmatrix,2,function(x){x/sum(x)}) 629 | index=apply(tmp[eval(s),],2,sum)>p 630 | } 631 | return(x[which(index)]) 632 | } 633 | 634 | 635 | 636 | 637 | #' @title Which indices for calibrated dates 638 | #' @description Gives the TRUE indices of calibrated dates (\code{CalDates} class object) based on Logical expressions of time intervals. 639 | #' @param x A CalDates class object 640 | #' @param s Logical expression indicating dates to keep. The expression should include the term \code{BP} which refers to specific dates. 641 | #' @param p Probability mass meeting the condition defined by \code{ss}. 642 | #' @details The function subsets \code{CalDates} class objects by identifying all dates that have a probability mass larger than \code{p} for a user defined logical expression of temporal interval containing the term \code{BP}, where \code{BP} refers to radiocarbon date. See examples for further detailes 643 | #' @return A CalDates class object. 644 | #' @examples 645 | #' ## Generate some calibrated dates 646 | #' x = calibrate(c(12100,5410,5320,3320),errors=c(20,20,30,30)) 647 | #' ## Subsets all dates that have a probability mass above 0.8 before 10000 BP 648 | #' x2 = which.CalDates(x,BP>10000,p=0.8) 649 | #' ## Subsets all dates that have a probability mass above 0.5 between 6000 and 6300 BP 650 | #' x3 = which.CalDates(x,BP>6000&BP<6300,p=0.5) 651 | #' @import stats 652 | #' @export 653 | 654 | which.CalDates=function(x,s,p) 655 | { 656 | index=rep(NA,length(x)) 657 | s=substitute(s) 658 | calmat=anyNA(x$calmatrix) 659 | if (calmat) 660 | { 661 | for (i in 1:length(x)) 662 | { 663 | tmp=x$grids[[i]] 664 | BP=tmp$calBP 665 | prdens=tmp$PrDens/sum(tmp$PrDens) 666 | sumprob=sum(prdens[eval(s)]) 667 | index[i]=sumprob>p 668 | } 669 | } else { 670 | BP=as.numeric(row.names(x$calmatrix)) 671 | tmp=apply(x$calmatrix,2,function(x){x/sum(x)}) 672 | index=apply(tmp[eval(s),],2,sum)>p 673 | } 674 | return(which(index)) 675 | } 676 | 677 | #' @title Combine multiple CalDates Class Objects into one. 678 | #' 679 | #' @param ... \code{CalDates} class objects to be concatenated. 680 | #' @param fixIDs logical. If set to TRUE, each date is given a new ID based on sequential integer. Default is FALSE 681 | #' @return An object of class CalDates 682 | #' @examples 683 | #' x1 = calibrate(c(2000,3400),c(20,20),ids=1:2) 684 | #' x2 = calibrate(c(4000,3000),c(30,30),calCurves=c('intcal20','marine20'), 685 | #' resOffsets=c(0,30),resErrors=c(0,20),ids=3:4) 686 | #' mcurve <- mixCurves('intcal20','marine20',p=0.7,resOffsets=300,resErrors=20) 687 | #' x3 = calibrate(5300,20,calCurves=mcurve,ids=5) 688 | #' x = combine(x1,x2,x3) 689 | #' ## x$metadata 690 | #' @seealso \code{\link{calibrate}} 691 | #' @export 692 | combine = function(...,fixIDs=FALSE) 693 | { 694 | x=c(...) 695 | n = length(x)/3 696 | metadata.index=seq(from=1,length.out=n,by=3) 697 | grids.index = seq(from=2,length.out=n,by=3) 698 | calmatrices.index = seq(from=3,length.out=n,by=3) 699 | 700 | if (sum(is.na(x[calmatrices.index]))!=n&(sum(is.na(x[grids.index]))!=n)) 701 | { 702 | stop('CalDates class object can be combined only if all elements were created with calMatrix=TRUE or calMatrix=FALSE') 703 | } 704 | 705 | if (all(!is.na(x[calmatrices.index]))) 706 | { 707 | cmat=TRUE 708 | } else {cmat=FALSE} 709 | 710 | metadata=x[[metadata.index[1]]] 711 | grids=x[[grids.index[1]]] 712 | calmatrix=x[[calmatrices.index[1]]] 713 | 714 | for (i in 2:n) 715 | { 716 | metadata = rbind.data.frame(metadata,x[[metadata.index[i]]]) 717 | if (cmat) 718 | { 719 | grids=NA 720 | calmatrix=cbind(calmatrix,x[[calmatrices.index[i]]]) 721 | } 722 | 723 | if (!cmat) 724 | { 725 | calmatrix=NA 726 | grids = c(grids,x[[grids.index[i]]]) 727 | } 728 | } 729 | 730 | res=list(metadata=metadata,grids=grids,calmatrix=calmatrix) 731 | class(res)=c('CalDates','list') 732 | if (fixIDs){metadata$DateID=1:nrow(metadata)} 733 | if (any(duplicated(metadata$DateID))) 734 | { 735 | stop('Date IDs must be unique. Consider setting ids explicitly when using calibrate() or set fixIDs to TRUE') 736 | } 737 | return(res) 738 | } 739 | 740 | 741 | 742 | #' @title Apply taphonomic corrections or other transformations to an SPD. 743 | #' 744 | #' @param x An object of class \code{CalSPD}, \code{compositeKDE} or \code{stackCalSPD}. 745 | #' @param correction An expression for transforming the SPD. Available input terms include: CalBP, the vector of \code{calBP} year within the time range; and \code{PrDens}, a matching vector of summed probability. The default expression is the taphonomic correction formula proposed by Surovell et al 2009. 746 | #' 747 | #' @return An object of the same class as x 748 | #' @examples 749 | #' \dontrun{ 750 | #'data(emedyd) 751 | #'region1 = subset(emedyd,Region==1) 752 | #'x = calibrate(x=region1$CRA, errors=region1$Error,normalised=FALSE) 753 | #'bins = binPrep(sites=region1$SiteName, ages=region1$CRA,h=50) 754 | #'region1.spd = spd(x=x,bins=bins,timeRange=c(16000,8000)) 755 | #'region1.spd.corrected = transformSPD(region1.spd) 756 | #'} 757 | #' @references 758 | #' Surovell, T.A., Finley, J.B., Smith, G.M., Brantingham, P.J., Kelly, R., 2009. Correcting temporal frequency distributions for taphonomic bias. Journal of Archaeological Science 36, 1715–1724. 759 | #' @export 760 | 761 | transformSPD = function(x,correction=expression(PrDens / (5.726442 * 10^6 * (CalBP+2176.4)^-1.3925309))) 762 | { 763 | if (!any(class(x)%in%c('compositeKDE','CalSPD','stackCalSPD'))) 764 | { 765 | stop("x must be of class 'CalSPD', 'compositeKDE', or 'stackCalSPD'") 766 | } 767 | 768 | if (any(class(x)%in%c('compositeKDE'))) 769 | { 770 | x$res.matrix=apply(x$res.matrix,2,function(x,CalBP,expr){PrDens=x;return(eval(expr))},CalBP=x$timeRange[1]:x$timeRange[2],expr=correction) 771 | } 772 | 773 | if (any(class(x)%in%c('CalSPD'))) 774 | { 775 | CalBP = x$grid$calBP 776 | PrDens=x$grid$PrDens 777 | x$grid$PrDens=eval(correction) 778 | } 779 | 780 | if (any(class(x)%in%c('stackCalSPD'))) 781 | { 782 | for (i in 1:length(x$spds)) 783 | { 784 | CalBP = x$spds[[i]]$grid$calBP 785 | PrDens= x$spds[[i]]$grid$PrDens 786 | x$spds[[i]]$grid$PrDens=eval(correction) 787 | } 788 | } 789 | 790 | return(x) 791 | } 792 | 793 | 794 | 795 | 796 | 797 | 798 | -------------------------------------------------------------------------------- /cran-comments.md: -------------------------------------------------------------------------------- 1 | ## Test environments 2 | * Local Manjaro Linux 21.3.3 install, R 4.2.1 3 | * Ubuntu Linux 20.04.1 LTS, R-release, GCC (via rhub) 4 | * Fedora Linux, R-devel, clang, gfortran (via rhub) 5 | * Windows Server 2022, R-devel, 64 bit (via rhub) 6 | 7 | 8 | ## R CMD check results 9 | 10 | There were no ERRORs or WARNINGs. 11 | 12 | There were 2 NOTEs: 13 | 14 | * checking CRAN incoming feasibility ... NOTE 15 | 16 | Uses the superseded packages: ‘doSNOW’, ‘snow’ 17 | 18 | *Use of the 'doSNOW' package as opposed to the 'doParallel' package is required due to the support of the printed txtProgressBar in the 'doSNOW' package.* 19 | 20 | * checking for detritus in the temp directory ... NOTE 21 | 22 | Found the following files/directories: 23 | 'lastMiKTeXException' 24 | 25 | * As noted in R-hub issue #503[https://github.com/r-hub/rhub/issues/503], this could be due to a bug/crash in MiKTeX and can likely be ignored. 26 | -------------------------------------------------------------------------------- /data/emedyd.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ahb108/rcarbon/5ed402b629d92d32a26bd0584c789877a831069f/data/emedyd.rda -------------------------------------------------------------------------------- /data/euroevol.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ahb108/rcarbon/5ed402b629d92d32a26bd0584c789877a831069f/data/euroevol.rda -------------------------------------------------------------------------------- /data/ewdates.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ahb108/rcarbon/5ed402b629d92d32a26bd0584c789877a831069f/data/ewdates.rda -------------------------------------------------------------------------------- /data/ewowin.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ahb108/rcarbon/5ed402b629d92d32a26bd0584c789877a831069f/data/ewowin.rda -------------------------------------------------------------------------------- /inst/CITATION: -------------------------------------------------------------------------------- 1 | bibentry( 2 | bibtype = "Article", 3 | title = "Inference from large sets of radiocarbon dates: software and methods", 4 | author = c(person(given="Enrico R.", family= "Crema"), 5 | person(given="Andrew",family="Bevan")), 6 | journal = "Radiocarbon", 7 | year = "2021", 8 | volume = "63", 9 | issue = "1", 10 | pages = "23-39", 11 | doi = "10.1017/RDC.2020.95", 12 | url = "https://dx.doi.org/10.1017/RDC.2020.95", 13 | textVersion = 14 | paste("Crema, E.R. and Bevan, A. (2021)", 15 | "Inference from large sets of radiocarbon dates: software and methods", 16 | "Radiocarbon, 63(1), 23-39", 17 | "URL https://dx.doi.org/10.1017/RDC.2020.95") 18 | encoding = "UTF-8", 19 | header("To cite rcarbon in publications use:") 20 | ) 21 | -------------------------------------------------------------------------------- /inst/extdata/normal.14c: -------------------------------------------------------------------------------- 1 | # Adapted from Andrew Parnell (2016). Bchron: Radiocarbon Dating, Age-Depth Modelling,Relative Sea Level Rate Estimation, and Non-Parametric Phase Modelling. Rpackage version 4.2.6. https://CRAN.R-project.org/package=Bchron 2 | 5e+05,5e+05,0,NA,NA 3 | -500,-500,0,NA,NA 4 | -------------------------------------------------------------------------------- /logo/rcarbon_logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ahb108/rcarbon/5ed402b629d92d32a26bd0584c789877a831069f/logo/rcarbon_logo.png -------------------------------------------------------------------------------- /man/BCADtoBP.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/utilities.R 3 | \name{BCADtoBP} 4 | \alias{BCADtoBP} 5 | \title{Convert BC/AD dates to BP format} 6 | \usage{ 7 | BCADtoBP(x) 8 | } 9 | \arguments{ 10 | \item{x}{A numerical vector (currently only basic checks that these numbers are in a sensible range).} 11 | } 12 | \value{ 13 | A vector with BP dates. 14 | } 15 | \description{ 16 | Converts BC/AD dates to BP format while handling the absence of 'year 0' 17 | } 18 | \examples{ 19 | BCADtoBP(-1268) 20 | } 21 | -------------------------------------------------------------------------------- /man/BPtoBCAD.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/utilities.R 3 | \name{BPtoBCAD} 4 | \alias{BPtoBCAD} 5 | \title{Convert BP dates to BC/AD format} 6 | \usage{ 7 | BPtoBCAD(x) 8 | } 9 | \arguments{ 10 | \item{x}{A numerical vector (currently only basic checks that these numbers are in a sensible range).} 11 | } 12 | \value{ 13 | A vector with BC/BCE dates expressed as negative numbers and AD/CE dates as positive ones. 14 | } 15 | \description{ 16 | Converts calibrated BP dates to BC/AD dates, omitting `year 0' 17 | } 18 | \examples{ 19 | BPtoBCAD(4200) 20 | } 21 | -------------------------------------------------------------------------------- /man/as.CalDates.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/calibration.R 3 | \name{as.CalDates} 4 | \alias{as.CalDates} 5 | \title{Convert to a CalDates object} 6 | \usage{ 7 | as.CalDates(x) 8 | } 9 | \arguments{ 10 | \item{x}{One or more calibrated dated to convert (currently only BchronCalibratedDates and oxcAARCalibratedDatesList objects are supported)} 11 | } 12 | \value{ 13 | A CalDates object 14 | } 15 | \description{ 16 | Convert other calibrated date formats to an rcarbon CalDates object. 17 | } 18 | \examples{ 19 | \dontrun{ 20 | library(Bchron) 21 | library(oxcAAR) 22 | quickSetupOxcal() 23 | dates <- data.frame(CRA=c(3200,2100,1900), Error=c(35,40,50)) 24 | bcaldates <- BchronCalibrate(ages=dates$CRA, ageSds=dates$Error, 25 | calCurves=rep("intcal13", nrow(dates))) 26 | rcaldates <- rcarbon::calibrate(dates$CRA, dates$Error, calCurves=rep("intcal13")) 27 | ocaldates <- oxcalCalibrate(c(3200,2100,1900),c(35,40,50),c("a","b","c")) 28 | ## Convert to rcarbon format 29 | caldates.b <- as.CalDates(bcaldates) 30 | caldates.o <- as.CalDates(ocaldates) 31 | ## Comparison plot 32 | plot(rcaldates$grids[[2]]$calBP,rcaldates$grids[[2]]$PrDens, 33 | type="l", col="green", xlim=c(2300,1900)) 34 | lines(caldates.b$grids[[2]]$calBP,caldates.b$grids[[2]]$PrDens, col="red") 35 | lines(caldates.o$grids[[2]]$calBP,caldates.o$grids[[2]]$PrDens, col="blue") 36 | legend("topright", legend=c("rcarbon","Bchron","OxCal"), col=c("green","red","blue"), lwd=2) 37 | } 38 | } 39 | -------------------------------------------------------------------------------- /man/as.CalGrid.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/calibration.R 3 | \name{as.CalGrid} 4 | \alias{as.CalGrid} 5 | \title{Convert data to class CalGrid.} 6 | \usage{ 7 | as.CalGrid(x) 8 | } 9 | \arguments{ 10 | \item{x}{A two-column \code{matrix} or \code{data.frame} class object.} 11 | } 12 | \value{ 13 | A CalGrid class object of probabilities or summed probabilities per calendar year BP. 14 | } 15 | \description{ 16 | Tries to coerce any two-column matrix or data.frame to a calibrated probability distribution (an object of class "CalGrid") for use by the rcarbon package. 17 | } 18 | \examples{ 19 | df <- data.frame(calBP=5000:2000,PrDens=runif(length(5000:2000))) 20 | mycalgrid <- as.CalGrid(df) 21 | plot(mycalgrid) 22 | } 23 | -------------------------------------------------------------------------------- /man/as.UncalGrid.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/calibration.R 3 | \name{as.UncalGrid} 4 | \alias{as.UncalGrid} 5 | \title{Convert data to class UncalGrid.} 6 | \usage{ 7 | as.UncalGrid(x) 8 | } 9 | \arguments{ 10 | \item{x}{A two-column \code{matrix} or \code{data.frame} class object.} 11 | } 12 | \value{ 13 | A CalGrid class object of probabilities or summed probabilities per CRA. 14 | } 15 | \description{ 16 | Tries to coerce any two-column matrix or data.frame to a uncalibrated probability distribution (an object of class "UncalGrid") for use by the rcarbon package. 17 | } 18 | \examples{ 19 | df <- data.frame(CRA=5000:2000,PrDens=runif(length(5000:2000))) 20 | mycalgrid <- as.UncalGrid(df) 21 | } 22 | -------------------------------------------------------------------------------- /man/barCodes.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/plots.R 3 | \name{barCodes} 4 | \alias{barCodes} 5 | \title{Plot the median values of calibrated radiocarbon dates or bins} 6 | \usage{ 7 | barCodes( 8 | x, 9 | yrng = c(0, 0.03), 10 | width = 20, 11 | col = rgb(0, 0, 0, 25, maxColorValue = 255), 12 | border = NA, 13 | ... 14 | ) 15 | } 16 | \arguments{ 17 | \item{x}{A vector containing median values obtained from \code{\link{medCal}} or \code{\link{binMed}}} 18 | 19 | \item{yrng}{y-axis range of the bars.} 20 | 21 | \item{width}{width of the bars (optional)} 22 | 23 | \item{col}{color of the bars} 24 | 25 | \item{border}{the color to draw the border. Use border = NA to omit borders.} 26 | 27 | \item{...}{Additional arguments affecting the plot} 28 | } 29 | \description{ 30 | Plot the median values of multiple calibrated radiocarbon dates or bins in a barcode-like strip. 31 | } 32 | \examples{ 33 | \dontrun{ 34 | #Load EUROEVOL Data 35 | data(euroevol) 36 | 37 | #Subset Danish Dates 38 | denmark <- subset(euroevol,Country=="Denmark") 39 | 40 | #Calibrate and Bin 41 | denmarkDates <- calibrate(x=denmark$C14Age,errors=denmark$C14SD) 42 | denmarkBins <- binPrep(sites=denmark$SiteID,ages=denmark$C14Age,h=200) #200 years bin size 43 | 44 | #Compute median date for each bin 45 | bm <- binMed(x=denmarkDates,bins=denmarkBins) 46 | 47 | #Compute median date for each date 48 | dm <- medCal(denmarkDates) 49 | 50 | #Compute SPD 51 | denmarkSPD <- spd(x=denmarkDates,bins=denmarkBins,timeRange=c(10000,4000)) 52 | 53 | #Plot SPD and barCodes of median dates 54 | plot(denmarkSPD,runm=200) 55 | barCodes(dm,yrng=c(0,0.01)) 56 | 57 | #Plot SPD and barCodes of median bins in BC/AD 58 | plot(denmarkSPD,runm=200,calendar="BCAD") 59 | barCodes(BPtoBCAD(bm),yrng=c(0,0.01)) 60 | } 61 | } 62 | \seealso{ 63 | \code{\link{medCal}}; \code{\link{binMed}} 64 | } 65 | -------------------------------------------------------------------------------- /man/binMed.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/utilities.R 3 | \name{binMed} 4 | \alias{binMed} 5 | \title{Computes the median date of each bin} 6 | \usage{ 7 | binMed(x, bins, verbose = TRUE) 8 | } 9 | \arguments{ 10 | \item{x}{A \code{CalDates} class object.} 11 | 12 | \item{bins}{vector containing the bin names associated with each radiocarbon date. Can be generated using \code{\link{binPrep}}.} 13 | 14 | \item{verbose}{A logical variable indicating whether extra information on progress should be reported. Default is TRUE.} 15 | } 16 | \value{ 17 | A vector of median dates in cal BP 18 | } 19 | \description{ 20 | Function for generating a vector of median calibrated dates for each each bin. 21 | } 22 | \examples{ 23 | \dontrun{ 24 | #Load EUROEVOL Data 25 | data(euroevol) 26 | #Subset Danish Dates 27 | denmark <- subset(euroevol,Country=="Denmark") 28 | #Calibrate and Bin 29 | denmarkDates <- calibrate(x=denmark$C14Age,errors=denmark$C14SD) 30 | denmarkBins <- binPrep(sites=denmark$SiteID,ages=denmark$C14Age,h=200) #200 years bin size 31 | #Compute median date for each bin 32 | binMed(x=denmarkDates,bins=denmarkBins) 33 | } 34 | } 35 | \seealso{ 36 | \code{\link{binPrep}},\code{\link{barCodes}} 37 | } 38 | -------------------------------------------------------------------------------- /man/binPrep.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/aggregation.R 3 | \name{binPrep} 4 | \alias{binPrep} 5 | \title{Binning function of radiocarbon dates.} 6 | \usage{ 7 | binPrep(sites, ages, h, method = "complete") 8 | } 9 | \arguments{ 10 | \item{sites}{a vector of character strings (or number to coerce to character) of all sites or site phases. If character strings are used these should not contain underscores (see also below)} 11 | 12 | \item{ages}{a vector of uncalibrated conventional radiocarbon ages or a \code{CalDates} class object obtained using the \code{\link{calibrate}} function.} 13 | 14 | \item{h}{a single numeric value passed to \code{\link{cutree}} control degree of grouping of similar ages in a phase site.} 15 | 16 | \item{method}{the agglomeration method to be used, passed on to \code{\link{hclust}}. Defaults to "complete" as in \code{\link{hclust}}.} 17 | } 18 | \value{ 19 | A vector of character strings with the same length of the object supplied for the argument \code{ages} identifying intra-site or intra-phase grouping, for use with \code{\link{spd}}.The character strings effectively provide a "name" for each "phase" within a "site", using sequential integers after an underscore. For example if a site named "S001" had four dates grouped into two bins with two dates each, the resulting vector would be "S001_1", "S001_1", "S001_2", and "S001_2". 20 | } 21 | \description{ 22 | Prepare a set of bins for controlling the aggregation of radiocarbon dates 23 | known to be from the same phase of same archaeological site (for use with \code{\link{spd}}). Used in cases where there is a concern that unusually high levels of sampling for radiocarbon at a given site or in a given site phase will impede comparison between sites or phases. 24 | } 25 | \details{ 26 | If \code{ages} is a \code{CalDates} class object, median dates are used for the clustering. 27 | } 28 | \seealso{ 29 | \code{\link{spd}} for generating SPD; \code{\link{binsense}} for sensitivity analysis pertaining the choice of the parameter \code{h}. 30 | } 31 | -------------------------------------------------------------------------------- /man/binsense.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/plots.R 3 | \name{binsense} 4 | \alias{binsense} 5 | \title{Bin sensitivity Plot} 6 | \usage{ 7 | binsense( 8 | x, 9 | y, 10 | h, 11 | timeRange, 12 | calendar = "BP", 13 | binning = "CRA", 14 | raw = F, 15 | verbose = T, 16 | legend = T, 17 | ... 18 | ) 19 | } 20 | \arguments{ 21 | \item{x}{A \code{CalDates} class object containing calibrated radiocarbon dates.} 22 | 23 | \item{y}{A vector containing the locations ID (e.g. site ID) of each calibrated date to be used for the binning process.} 24 | 25 | \item{h}{A vector of numbers containing values for the \code{h} parameter to be used in the \code{\link{binPrep}} function.} 26 | 27 | \item{timeRange}{A vector of length 2 indicating the start and end date of the analysis in cal BP.} 28 | 29 | \item{calendar}{Either \code{'BP'} or \code{'BCAD'}. Indicate whether the calibrated date should be displayed in BP or BC/AD. Default is \code{'BP'}.} 30 | 31 | \item{binning}{Either \code{'CRA'} or \code{'calibrated'}. Indicate whether the binning should be carried using the 14C age or using the median calibrated date. Default is \code{'CRA'}.} 32 | 33 | \item{raw}{A logical variable indicating whether all SPDs should be returned or not. Default is FALSE.} 34 | 35 | \item{verbose}{A logical variable indicating whether extra information on progress should be reported. Default is TRUE.} 36 | 37 | \item{legend}{A logical variable indicating whether the legend should be displayed. Default is TRUE} 38 | 39 | \item{...}{Additional arguments to be passed to the \code{\link{spd}} function.} 40 | } 41 | \description{ 42 | Visually explores how choosing different values for \code{h} in the \code{\link{binPrep}} function affects the shape of the SPD. 43 | } 44 | \examples{ 45 | \dontrun{ 46 | data(euroevol) 47 | #subset Danish dates 48 | denmark=subset(euroevol,Country=="Denmark") 49 | denmarkDates=calibrate(x=denmark$C14Age,errors=denmark$C14SD) 50 | binsense(x=denmarkDates,y=denmark$SiteID,h=seq(0,200,20),timeRange=c(10000,4000),runm=200) 51 | } 52 | } 53 | \seealso{ 54 | \code{\link{binPrep}}; \code{\link{spd}} 55 | } 56 | -------------------------------------------------------------------------------- /man/calibrate.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/calibration.R 3 | \name{calibrate} 4 | \alias{calibrate} 5 | \alias{calibrate.default} 6 | \alias{calibrate.UncalGrid} 7 | \title{Calibrate radiocarbon dates} 8 | \usage{ 9 | calibrate(x, ...) 10 | 11 | \method{calibrate}{default}( 12 | x, 13 | errors, 14 | ids = NA, 15 | dateDetails = NA, 16 | calCurves = "intcal20", 17 | resOffsets = 0, 18 | resErrors = 0, 19 | timeRange = c(55000, 0), 20 | normalised = TRUE, 21 | F14C = FALSE, 22 | calMatrix = FALSE, 23 | eps = 1e-05, 24 | ncores = 1, 25 | verbose = TRUE, 26 | ... 27 | ) 28 | 29 | \method{calibrate}{UncalGrid}( 30 | x, 31 | errors = 0, 32 | calCurves = "intcal20", 33 | timeRange = c(55000, 0), 34 | eps = 1e-05, 35 | type = "fast", 36 | datenormalised = FALSE, 37 | spdnormalised = FALSE, 38 | verbose = TRUE, 39 | ... 40 | ) 41 | } 42 | \arguments{ 43 | \item{x}{A vector of uncalibrated radiocarbon ages or a UncalGrid class object.} 44 | 45 | \item{...}{ignored} 46 | 47 | \item{errors}{A vector of standard deviations corresponding to each estimated radiocarbon age.} 48 | 49 | \item{ids}{An optional vector of IDs for each date.} 50 | 51 | \item{dateDetails}{An optional vector of details for each date which will be returned in the output metadata.} 52 | 53 | \item{calCurves}{Either a character string naming a calibration curve already provided with the rcarbon package (currently 'intcal20','intcal13','intcal13nhpine16','shcal20','shcal13','shcal13shkauri16',''marine13','marine20' and 'normal'(i.e. no calibration) are possible; default is 'intcal20') or a custom calibration curve as three-column matrix or data.frame (calibrated year BP, uncalibrated age bp, standard deviation). Different existing curves can be specified per dated sample, but only one custom curve can be provided for all dates.} 54 | 55 | \item{resOffsets}{A vector of offset values for any marine reservoir effect (default is no offset).} 56 | 57 | \item{resErrors}{A vector of offset value errors for any marine reservoir effect (default is no offset).} 58 | 59 | \item{timeRange}{Earliest and latest data to calibrate for, in calendar years. Posterior probabilities beyond this range will be excluded (the default is sensible in most cases).} 60 | 61 | \item{normalised}{A logical variable indicating whether the calibration should be normalised or not. Default is TRUE.} 62 | 63 | \item{F14C}{A logical variable indicating whether calibration should be carried out in F14C space or not. Default is FALSE.} 64 | 65 | \item{calMatrix}{a logical variable indicating whether the age grid should be limited to probabilities higher than \code{eps}} 66 | 67 | \item{eps}{Cut-off value for density calculation. Default is 1e-5.} 68 | 69 | \item{ncores}{Number of cores/workers used for parallel execution. Default is 1 (>1 requires doSnow package).} 70 | 71 | \item{verbose}{A logical variable indicating whether extra information on progress should be reported. Default is TRUE.} 72 | 73 | \item{type}{Currently, two options are available. With "fast", a look-up is conducted for each calendar year that picks up the amplitude of the nearest CRA age. With "full", each CRA is calibrated individually and then summed (much slower).} 74 | 75 | \item{datenormalised}{Controls for calibrated dates with probability mass outside the timerange of analysis. If set to TRUE the total probability mass within the time-span of analysis is normalised to sum to unity. Should be set to FALSE when the parameter \code{normalised} in \code{\link{calibrate}} is set to FALSE. Default is FALSE.} 76 | 77 | \item{spdnormalised}{A logical variable indicating whether the total probability mass of the SPD is normalised to sum to unity.} 78 | } 79 | \value{ 80 | An object of class CalDates with the following elements: 81 | \itemize{ 82 | \item{\code{metadata}} {A data.frame containing relevant information regarding each radiocarbon date and the parameter used in the calibration process.} 83 | \item{\code{grids}} {A list of calGrid class objects, containing the posterior probabilities for each calendar year. The most memory-efficient way to store calibrated dates, as only years with non-zero probability are stored, but aggregation methods such as \code{spd()} may then take longer to extract and combine multiple dates. NA when the parameter calMatrix is set to TRUE.} 84 | \item{\code{calMatrix}} {A matrix of probability values, one row per calendar year in timeRange and one column per date. By storing all possible years, not just those with non-zero probability, this approach takes more memory, but speeds up spd() and is suggested whenever the latter is to be used. NA when the parameter calMatrix is set to FALSE.} 85 | } 86 | } 87 | \description{ 88 | Function for calibrating radiocarbon dates or uncalibrated SPDs. 89 | 90 | Function for calibrating a SPD generated by summing uncalibrated dates. 91 | } 92 | \details{ 93 | This function computes one or more calibrated radiocarbon ages using the method described in Bronk Ramsey 2008 (see also Parnell 2017). It is possible to specify different calibration curves or reservoir offsets individually for each date, and control whether the resulting calibrated distribution is normalised to 1 under-the-curve or not. Calculations can also be executed in parallel to reduce computing time. The function was modified from the \code{BchronCalibrate} function in the \code{Bchron} package developed by A.Parnell (see references below). 94 | } 95 | \examples{ 96 | x1 <- calibrate(x=4000, errors=30) 97 | plot(x1) 98 | summary(x1) 99 | # Example with a Marine Date, using a DeltaR of 300 and a DeltaR error of 30 100 | x2 <- calibrate(x=4000, errors=30, calCurves='marine20', resOffsets=300, resErrors=30) 101 | plot(x2) 102 | } 103 | \references{ 104 | Bronk Ramsey, C. 2008. Radiocarbon dating: revolutions in understanding, \emph{Archaeometry} 50.2: 249-75. DOI: https://doi.org/10.1111/j.1475-4754.2008.00394.x \cr 105 | Parnell, A. 2017. Bchron: Radiocarbon Dating, Age-Depth Modelling, Relative Sea Level Rate Estimation, and Non-Parametric Phase Modelling, R package: https://CRAN.R-project.org/package=Bchron 106 | } 107 | -------------------------------------------------------------------------------- /man/ckde.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/aggregation.R 3 | \name{ckde} 4 | \alias{ckde} 5 | \title{Composite Kernel Density Estimates of Radiocarbon Dates} 6 | \usage{ 7 | ckde(x, timeRange, bw, normalised = FALSE) 8 | } 9 | \arguments{ 10 | \item{x}{A \code{simdates} class object, generated using \code{\link{sampleDates}}.} 11 | 12 | \item{timeRange}{A vector of length 2 indicating the start and end date of the analysis in cal BP.} 13 | 14 | \item{bw}{Kernel bandwidth to be used.} 15 | 16 | \item{normalised}{A logical variable indicating whether the contribution of individual dates should be equal (TRUE), or weighted based on the area under the curve of non-normalised calibration (FALSE). Default is TRUE.} 17 | } 18 | \value{ 19 | An object of class \code{ckdeSPD} with the following elements 20 | \itemize{ 21 | \item{\code{timeRange}} {The \code{timeRange} setting used.} 22 | \item{\code{res.matrix}} {A matrix containing the KDE values with rows representing calendar dates.} 23 | } 24 | } 25 | \description{ 26 | Computes a Composite Kernel Density Estimate (CKDE) from multiple sets of randomly sampled calendar dates. 27 | } 28 | \details{ 29 | The function computes Kernel Density Estimates using randomly sampled calendar dates contained in a \code{simdates} class object (generated using the \code{sampledates()} function). The output contains \code{nsim} KDEs, where \code{nsim} is the argument used in \code{simulate.dates()}. The resulting object can be plotted to visualise a CKDE (cf Brown 2017), and if \code{boot} was set to \code{TRUE} in \code{sampleDates} its bootstrapped variant (cf McLaughlin 2018 for a similar analysis). The shape of the CKDE is comparable to an SPD generated from non-normalised dates when the argument \code{normalised} is set to FALSE. 30 | } 31 | \examples{ 32 | \dontrun{ 33 | data(emedyd) 34 | x = calibrate(x=emedyd$CRA, errors=emedyd$Error,normalised=FALSE) 35 | bins = binPrep(sites=emedyd$SiteName, ages=emedyd$CRA,h=50) 36 | s = sampleDates(x,bins=bins,nsim=100,boot=FALSE) 37 | ckdeNorm = ckde(s,timeRange=c(16000,9000),bw=100,normalised=TRUE) 38 | plot(ckdeNorm,type='multiline',calendar='BCAD') 39 | } 40 | 41 | } 42 | \references{ 43 | Brown, W. A. 2017. The past and future of growth rate estimation in demographic temporal frequency analysis: Biodemographic interpretability and the ascendance of dynamic growth models. \emph{Journal of Archaeological Science}, 80: 96–108. DOI: https://doi.org/10.1016/j.jas.2017.02.003 \cr 44 | McLaughlin, T. R. 2018. On Applications of Space–Time Modelling with Open-Source 14C Age Calibration. \emph{Journal of Archaeological Method and Theory}. DOI https://doi.org/10.1007/s10816-018-9381-3 45 | } 46 | \seealso{ 47 | \code{\link{sampleDates}} 48 | } 49 | -------------------------------------------------------------------------------- /man/combine.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/utilities.R 3 | \name{combine} 4 | \alias{combine} 5 | \title{Combine multiple CalDates Class Objects into one.} 6 | \usage{ 7 | combine(..., fixIDs = FALSE) 8 | } 9 | \arguments{ 10 | \item{...}{\code{CalDates} class objects to be concatenated.} 11 | 12 | \item{fixIDs}{logical. If set to TRUE, each date is given a new ID based on sequential integer. Default is FALSE} 13 | } 14 | \value{ 15 | An object of class CalDates 16 | } 17 | \description{ 18 | Combine multiple CalDates Class Objects into one. 19 | } 20 | \examples{ 21 | 22 | x1 = calibrate(c(2000,3400),c(20,20),ids=1:2) 23 | x2 = calibrate(c(4000,3000),c(30,30),calCurves=c('intcal20','marine20'), 24 | resOffsets=c(0,30),resErrors=c(0,20),ids=3:4) 25 | mcurve <- mixCurves('intcal20','marine20',p=0.7,resOffsets=300,resErrors=20) 26 | x3 = calibrate(5300,20,calCurves=mcurve,ids=5) 27 | x = combine(x1,x2,x3) 28 | ## x$metadata 29 | } 30 | \seealso{ 31 | \code{\link{calibrate}} 32 | } 33 | -------------------------------------------------------------------------------- /man/emedyd.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/data.R 3 | \docType{data} 4 | \name{emedyd} 5 | \alias{emedyd} 6 | \title{Radiocarbon dates for the Eastern Mediterranean around the Younger Dryas} 7 | \format{ 8 | A data.frame with the following variables: 9 | \describe{ 10 | \item{\code{LabID}}{Laboratory ID assigned to each radiocarbon date (where known)} 11 | \item{\code{CRA}}{Radiocarbon age in 14C years BP} 12 | \item{\code{Error}}{Radiocarbon age error} 13 | \item{\code{Material}}{Material of the dated sample} 14 | \item{\code{Species}}{Species of the dated sample (where identified)} 15 | \item{\code{SiteName}}{Name of the site from which the sample has been recovered} 16 | \item{\code{Country}}{Country where the sampling site is located} 17 | \item{\code{Longitude}}{Longitude of the sampling site in decimal degrees} 18 | \item{\code{Latitude}}{Latitude of the sampling site in decimal degrees} 19 | \item{\code{Region}}{One of three analytical regions (1=southern Levant, 2=Northern Levant, 3= South-central Anatolia} 20 | } 21 | } 22 | \source{ 23 | Palmisano, A., Bevan, A. and S. Shennan 2017. Data and code for demographic trends in the paper "Human responses and non-responses to climatic variations during the Last Glacial-Interglacial transition in the eastern Mediterranean", UCL Discovery Archive 1570274. doi:10.14324/000.ds.1570274. 24 | } 25 | \usage{ 26 | emedyd 27 | } 28 | \description{ 29 | Radiocarbon dates (n=1915) and site coordinates (n=201) from a paper considering the relationship between human activity in the eastern Mediterranean/Middle East and early Holocene climate change, including the Younger Dryas. 30 | } 31 | \examples{ 32 | \dontrun{ 33 | data(emedyd) 34 | northernlevant <- emedyd[emedyd$Region=="2",] 35 | bins <- binPrep(northernlevant$SiteName, northernlevant$CRA, h=50) 36 | x <- calibrate(northernlevant$CRA, northernlevant$Error, normalised=FALSE) 37 | spd.northernlevant <- spd(x, bins=bins, runm=50, timeRange=c(17000,8000)) 38 | plot(spd.northernlevant) 39 | } 40 | } 41 | \references{ 42 | Roberts, N., Woodbridge, J., Bevan, A., Palmisano, A., Shennan, S. and E. Asouti 2017. Human responses and non-responses to climatic variations during the Last Glacial-Interglacial transition in the eastern Mediterranean. Quaternary Science Reviews, 184, 47-67. doi:10.1016/j.quascirev.2017.09.011. 43 | } 44 | \keyword{datasets} 45 | -------------------------------------------------------------------------------- /man/euroevol.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/data.R 3 | \docType{data} 4 | \name{euroevol} 5 | \alias{euroevol} 6 | \title{Radiocarbon dates from the EUROEVOL database} 7 | \format{ 8 | A data.frame with the following variables: 9 | \describe{ 10 | \item{\code{C14ID}}{ID of each radiocarbon date} 11 | \item{\code{C14Age}}{Radiocarbon age in 14C years BP} 12 | \item{\code{C14SD}}{Radiocarbon age error} 13 | \item{\code{LabCode}}{Labcode of the radiocarbon date} 14 | \item{\code{Material}}{Material of the dated sample} 15 | \item{\code{SiteID}}{ID of the site from which the sample has been recovered} 16 | \item{\code{Latitude}}{Latitude of the sampling site in decimal degrees} 17 | \item{\code{Longitude}}{Longitude of the sampling site in decimal degrees} 18 | \item{\code{Country}}{Country where the sampling site is located} 19 | } 20 | } 21 | \source{ 22 | Manning, K., Colledge, S., Crema, E., Shennan, S., Timpson, A., 2016. The Cultural Evolution of Neolithic Europe. EUROEVOL Dataset 1: Sites, Phases and Radiocarbon Data. Journal of Open Archaeology Data 5. doi:10.5334/joad.40 23 | } 24 | \usage{ 25 | euroevol 26 | } 27 | \description{ 28 | Radiocarbon dates (n=14,053) and site coordinates (n=4,213) from the EUROEVOL project database. Sites without radiocarbon dates (n=544), phase-codes, and other data have been omitted. 29 | } 30 | \examples{ 31 | \dontrun{ 32 | data(euroevol) 33 | Ireland <- subset(euroevol,Country=="Ireland") 34 | bins <- binPrep(Ireland$SiteID,Ireland$C14Age,h=200) 35 | x <- calibrate(Ireland$C14Age,Ireland$C14SD) 36 | spd.ireland <- spd(x,bins=bins,runm=200,timeRange=c(8000,4000)) 37 | plot(spd.ireland) 38 | } 39 | } 40 | \references{ 41 | Shennan, S., Downey, S.S., Timpson, A., Edinborough, K., Colledge, S., Kerig, T., Manning, K., Thomas, M.G., 2013. Regional population collapse followed initial agriculture booms in mid-Holocene Europe. Nature Communications 4, ncomms3486. doi:10.1038/ncomms3486 42 | 43 | Timpson, A., Colledge, S., Crema, E., Edinborough, K., Kerig, T., Manning, K., Thomas, M.G., Shennan, S., 2014. Reconstructing regional population fluctuations in the European Neolithic using radiocarbon dates: a new case-study using an improved method. Journal of Archaeological Science 52, 549-557. doi:10.1016/j.jas.2014.08.011 44 | } 45 | \keyword{datasets} 46 | -------------------------------------------------------------------------------- /man/ewdates.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/data.R 3 | \docType{data} 4 | \name{ewdates} 5 | \alias{ewdates} 6 | \title{Subset of EUROEVOL radiocarbon dates from Great Britain} 7 | \format{ 8 | A data.frame with the following variables: 9 | \describe{ 10 | \item{\code{C14ID}}{ID of each radiocarbon date} 11 | \item{\code{C14Age}}{Radiocarbon age in 14C years BP} 12 | \item{\code{C14SD}}{Radiocarbon age error} 13 | \item{\code{LabCode}}{Labcode of the radiocarbon date} 14 | \item{\code{Material}}{Material of the dated sample} 15 | \item{\code{SiteID}}{ID of the site from which the sample has been recovered} 16 | \item{\code{Eastings}}{Easting coordinates of the sampling site in meters (OSGB 1936 epsg:27700) } 17 | \item{\code{Northings}}{Northing coordinates of the sampling site in meters (OSGB 1936 epsg:27700)} 18 | } 19 | } 20 | \source{ 21 | Manning, K., Colledge, S., Crema, E., Shennan, S., Timpson, A., 2016. The Cultural Evolution of Neolithic Europe. EUROEVOL Dataset 1: Sites, Phases and Radiocarbon Data. Journal of Open Archaeology Data 5. doi:10.5334/joad.40 22 | } 23 | \usage{ 24 | ewdates 25 | } 26 | \description{ 27 | Radiocarbon dates (n=2,324) and site coordinates (n=652) from England and Wales collected from the EUROEVOL project database. See \cite{\link{euroevol}} for more details regarding the source data. 28 | } 29 | \keyword{datasets} 30 | -------------------------------------------------------------------------------- /man/ewowin.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/data.R 3 | \docType{data} 4 | \name{ewowin} 5 | \alias{ewowin} 6 | \title{Polygonal window of England and Wales} 7 | \format{ 8 | An \code{owin} class object. 9 | } 10 | \source{ 11 | South,A.2011.rworldmap: A New R package for Mapping Global Data. The R Journal Vol. 3/1 : 35-43. 12 | } 13 | \usage{ 14 | ewowin 15 | } 16 | \description{ 17 | An \code{\link{owin}} class polygonal window of England and Wales. 18 | } 19 | \examples{ 20 | \dontrun{ 21 | data(ewowin) 22 | # Obtained from rworldmap: 23 | library(maptools) 24 | library(rgeos) 25 | library(rworldmap) 26 | bng <- CRS("+init=epsg:27700") 27 | sbrit <- getMap(resolution="high") 28 | sbrit <- spTransform(sbrit[sbrit$GEOUNIT =="United Kingdom",], bng) 29 | tmp <- SpatialPolygons(list(Polygons(list(Polygon(cbind(c(130000,130000,310000, 30 | 425000,700000,700000,130000), c(0,300000,560000,598000,300000,0,0)))), 31 | "1")), 1:1, proj4string=bng) 32 | sbrit <- gIntersection(sbrit,tmp) 33 | ewowin <- as.owin(sbrit) 34 | } 35 | } 36 | \keyword{datasets} 37 | -------------------------------------------------------------------------------- /man/gaussW.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/utilities.R 3 | \name{gaussW} 4 | \alias{gaussW} 5 | \title{Gaussian weighting of dates relative to} 6 | \usage{ 7 | gaussW(x, mean, sd, type = "weights") 8 | } 9 | \arguments{ 10 | \item{x}{A numeric vector or an object of class CalDates.} 11 | 12 | \item{mean}{A single numeric value indicating the value to centre the Gaussian kernel on.} 13 | 14 | \item{sd}{A single numeric value indicating the standard deviation of the Gaussian kernel to be used.} 15 | 16 | \item{type}{The type of output to produce: currently either "weighted" (for a simple total weight value for each date) or "raw" (a list of reweighted calibrated radiocarbon probabilities for each calibrated date).} 17 | } 18 | \value{ 19 | A numeric vector of weights (or optionally a list of reweighted calibrated radiocarbon probabilities). 20 | } 21 | \description{ 22 | Rescale a numeric vector to a specified minimum and maximum. 23 | } 24 | \examples{ 25 | ## Example weighting fo a set of dates versus a focal date of 5950 calBP 26 | years <- seq(6500, 5500, -10) 27 | plot(cbind(years, gaussW(years, 5950, 50))) 28 | ## Example weighting of three calibrated dates versus a focal date of 5950 calBP 29 | dates <- calibrate(c(5280, 5180, 5080), c(30,30,30), normalised=FALSE) 30 | gaussW(dates, 5950, 50) 31 | ## Or the same with raw output 32 | dateswt <- gaussW(dates, 5950, 50, type="raw") 33 | head(dateswt[[1]]) 34 | } 35 | -------------------------------------------------------------------------------- /man/hpdi.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/calibration.R 3 | \name{hpdi} 4 | \alias{hpdi} 5 | \title{Computes the highest posterior density interval (HPDI) for calibrated dates} 6 | \usage{ 7 | hpdi( 8 | x, 9 | credMass = 0.95, 10 | asList = TRUE, 11 | calendar = "BP", 12 | sep = "|", 13 | pdigits = 3 14 | ) 15 | } 16 | \arguments{ 17 | \item{x}{A \code{CalDates} class object.} 18 | 19 | \item{credMass}{Interval probability mass} 20 | 21 | \item{asList}{Logical variable determining whether the output should be a list (TRUE) or a character vector (FALSE). Default is TRUE} 22 | 23 | \item{calendar}{Whether daes should be reported in cal BP (\code{"BP"}) or in BCAD (\code{"BCAD"}). Default is 'BP'. Ignored when \code{"asList=TRUE"}.} 24 | 25 | \item{sep}{character string to separate date ranges. Default is '|'. Ignored when \code{"asList==TRUE"}.} 26 | 27 | \item{pdigits}{indicate the number of decimal places for reporting probabilities. Default is 3. Ignored when \code{"asList==TRUE"}.} 28 | } 29 | \value{ 30 | A list of matrices with HPDI ranges and associated probabilities in cal BP. Note that the sum of the probability mass will be only approximately equal to the argument \code{credMass}. 31 | } 32 | \description{ 33 | Computes the highest posterior density interval (HPDI) for calibrated dates 34 | } 35 | \examples{ 36 | x <- calibrate(c(2000,3050,2950),c(35,20,20)) 37 | hpdi(x) 38 | hpdi(x,asList=FALSE,calendar='BCAD') 39 | } 40 | \seealso{ 41 | \code{\link{calibrate}} 42 | } 43 | -------------------------------------------------------------------------------- /man/medCal.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/calibration.R 3 | \name{medCal} 4 | \alias{medCal} 5 | \title{Computes the median date of calibrated dates} 6 | \usage{ 7 | medCal(x) 8 | } 9 | \arguments{ 10 | \item{x}{A \code{CalDates} class object.} 11 | } 12 | \value{ 13 | A vector of median dates in cal BP 14 | } 15 | \description{ 16 | Function for generating a vector median calibrated dates from a \code{CalDates} class object. 17 | } 18 | \examples{ 19 | x <- calibrate(c(3050,2950),c(20,20)) 20 | medCal(x) 21 | } 22 | \seealso{ 23 | \code{\link{calibrate}}, \code{\link{barCodes}} 24 | } 25 | -------------------------------------------------------------------------------- /man/mixCurves.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/calibration.R 3 | \name{mixCurves} 4 | \alias{mixCurves} 5 | \title{Creates mixed calibration curves.} 6 | \usage{ 7 | mixCurves( 8 | calCurve1 = "intcal20", 9 | calCurve2 = "marine20", 10 | p = 0.5, 11 | resOffsets = 0, 12 | resErrors = 0 13 | ) 14 | } 15 | \arguments{ 16 | \item{calCurve1}{Name of the first curve, chosen from 'intcal20','intcal13','intcal13nhpine16','shcal20','shcal13','shcal13shkauri16',''marine13','marine20'. Default is 'intcal20'.} 17 | 18 | \item{calCurve2}{Name of the second curve, from the same list. Default is 'marine20'.} 19 | 20 | \item{p}{The proportion of contribution of the first curve. Default is 1.} 21 | 22 | \item{resOffsets}{Offset value for the marine reservoir effect to be applied to calCurve2. Default is 0.} 23 | 24 | \item{resErrors}{Error of the marine reservoir effect offset to be applied to calCurve2. Default is 0.} 25 | } 26 | \value{ 27 | A three-column matrix containing calibrated year BP, uncalibrated age bp, and standard deviation. To be used as custom calibration curve for the \code{\link{calibrate}} function. 28 | } 29 | \description{ 30 | Function for generating mixed calibration curves (e.g. intcal20/marine20, intcal20/shcal20) with user-defined proportions. 31 | } 32 | \details{ 33 | The function is based on the \code{mix.calibrationcurves} function of the \code{clam} package. 34 | } 35 | \examples{ 36 | myCurve <- mixCurves('intcal20','marine20',p=0.7,resOffsets=300,resErrors=20) 37 | x <- calibrate(4000,30,calCurves=myCurve) 38 | } 39 | \references{ 40 | Blaauw, M. and Christen, J.A.. 2011. Flexible paleoclimate age-depth models using an autoregressive gamma process. \emph{Bayesian Analysis}, 6, 457-474. 41 | Blaauw, M. 2018. clam: Classical Age-Depth Modelling of Cores from Deposits. R package version 2.3.1. https://CRAN.R-project.org/packacge=clam 42 | Marsh, E.J., Bruno, M.C., Fritz, S.C., Baker, P., Capriles, J.M. and Hastorf, C.A., 2018. IntCal, SHCal, or a Mixed Curve? Choosing a 14 C Calibration Curve for Archaeological and Paleoenvironmental Records from Tropical South America. Radiocarbon, 60(3), pp.925-940. 43 | } 44 | \seealso{ 45 | \code{\link{calibrate}} 46 | } 47 | -------------------------------------------------------------------------------- /man/modelTest.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/tests.R 3 | \name{modelTest} 4 | \alias{modelTest} 5 | \title{Monte-Carlo simulation test for SPDs} 6 | \usage{ 7 | modelTest( 8 | x, 9 | errors, 10 | nsim, 11 | bins = NA, 12 | runm = NA, 13 | timeRange = NA, 14 | backsight = 50, 15 | changexpr = expression((t1/t0)^(1/d) - 1), 16 | gridclip = TRUE, 17 | raw = FALSE, 18 | model = c("exponential"), 19 | method = c("uncalsample"), 20 | predgrid = NA, 21 | normalised = NA, 22 | datenormalised = NA, 23 | spdnormalised = FALSE, 24 | ncores = 1, 25 | fitonly = FALSE, 26 | a = 0, 27 | b = 0, 28 | edgeSize = 500, 29 | verbose = TRUE 30 | ) 31 | } 32 | \arguments{ 33 | \item{x}{A \code{CalDates} object containing calibrated radiocarbon ages} 34 | 35 | \item{errors}{A vector of errors corresponding to each radiocarbon age} 36 | 37 | \item{nsim}{Number of simulations} 38 | 39 | \item{bins}{A vector indicating which bin each radiocarbon date is assigned to.} 40 | 41 | \item{runm}{A number indicating the window size of the moving average to smooth both observed and simulated SPDs. If set to \code{NA} no moving average is applied.Default is \code{NA}.} 42 | 43 | \item{timeRange}{A vector of length 2 indicating the start and end date of the analysis in cal BP. The fitting process is applied considering the SPD within the interval defined by this parameter. If no values are supplied the earliest and latest median calibrated dates of the observed data will be used.} 44 | 45 | \item{backsight}{A single numeric value defining the distance in time between the focal year and the backsight year for computing the rate of change. Default is 10.} 46 | 47 | \item{changexpr}{An expression for calculating the rate of change in SPD between the focal year and a backsight year. Available input options are t1 (the SPD for the focal year), t0 (the SPD for the backsight year), d (the distance between t0 and t1), and any other standard constants and mathematical operators. A sensible default is provided.} 48 | 49 | \item{gridclip}{Whether the sampling of random dates is constrained to the observed range (TRUE) or not (FALSE). Default is TRUE.} 50 | 51 | \item{raw}{A logical variable indicating whether all permuted SPDs should be returned or not. Default is FALSE.} 52 | 53 | \item{model}{A vector indicating the model to be fitted. Currently the acceptable options are \code{'uniform'}, \code{'linear'}, \code{'exponential'} and \code{'custom'}. Default is \code{'exponential'}.} 54 | 55 | \item{method}{Method for the creation of random dates from the fitted model. Either \code{'uncalsample'} or \code{'calsample'}. Default is \code{'uncalsample'}. See below for details.} 56 | 57 | \item{predgrid}{A data.frame containing calendar years (column \code{calBP}) and associated summed probabilities (column \code{PrDens}). Required when \code{model} is set to \code{'custom'}.} 58 | 59 | \item{normalised}{Whether the simulated dates should be normalised or not. Default based on whether x is normalised or not.} 60 | 61 | \item{datenormalised}{Argument kept for backward compatibility with previous versions.} 62 | 63 | \item{spdnormalised}{A logical variable indicating whether the total probability mass of the SPD is normalised to sum to unity for both observed and simulated data.} 64 | 65 | \item{ncores}{Number of cores used for for parallel execution. Default is 1.} 66 | 67 | \item{fitonly}{A logical variable. If set to TRUE, only the the model fitting is executed and returned. Default is FALSE.} 68 | 69 | \item{a}{Starter value for the exponential fit with the \code{\link{nls}} function using the formula \code{y ~ exp(a + b * x)} where \code{y} is the summed probability and \code{x} is the date. Default is 0.} 70 | 71 | \item{b}{Starter value for the exponential fit with the \code{\link{nls}} function using the formula \code{y ~ exp(a + b * x)} where \code{y} is the summed probability and \code{x} is the date. Default is 0.} 72 | 73 | \item{edgeSize}{Controls edge effect by expanding the fitted model beyond the range defined by \code{timeRange}.} 74 | 75 | \item{verbose}{A logical variable indicating whether extra information on progress should be reported. Default is TRUE.} 76 | } 77 | \value{ 78 | An object of class \code{SpdModelTest} with the following elements 79 | \itemize{ 80 | \item{\code{result}} {A four column data.frame containing the observed probability density (column \emph{PrDens}) and the lower and the upper values of the simulation envelope (columns \emph{lo} and \emph{hi}) for each calendar year column \emph{calBP}} 81 | \item{\code{result.roc}} {A four column data.frame containing the observed rates of change (column \emph{roc}) and the lower and the upper values of the simulation envelope (columns \emph{lo.roc} and \emph{hi.roc}) for the mid point between two chronological blocks \emph{calBP}} 82 | \item{\code{sim}} {A matrix containing the simulation results of the summed probabilities. Available only when \code{raw} is set to TRUE} 83 | \item{\code{sim.roc}} {A matrix containing the simulation results of the rate of change of summed probabilities. Available only when \code{raw} is set to TRUE} 84 | \item{\code{pval}} {A numeric vector containing the p-value of the global significance test for the summed probabilities} 85 | \item{\code{pval.roc}} {A numeric vector containing the p-value of the global significance test for the rates of change} 86 | \item{\code{fit}} {A data.frame containing the probability densities of the fitted model for each calendar year within the time range of analysis} 87 | \item{\code{fitobject}} {Fitted model. Not available when \code{model} is \code{'custom'}} 88 | \item{\code{n}} {Number of radiocarbon dates.} 89 | \item{\code{nbins}}{Number of bins.} 90 | \item{\code{nsim}}{Number of Monte-Carlo simulations.} 91 | \item{\code{backsight}}{Backsight size.} 92 | } 93 | } 94 | \description{ 95 | Comparison of an observed summed radiocarbon date distribution (aka SPD) with simulated outcomes from a theoretical model. 96 | } 97 | \details{ 98 | The function implements a Monte-Carlo test for comparing a theoretical or fitted statistical model to an observed summed radiocarbon date distribution (aka SPD) and associated rates of changes. A variety of theoretical expectations can be compared to the observed distribution by setting the \code{model} argument, for example to fit basic \code{'uniform'} (the mean of the SPD), \code{'linear'} (fitted using the \code{\link{lm}} function) or \code{model='exponential'} models (fitted using the \code{\link{nls}} function). Models are fitted to the period spanned by \code{timeRange} although \code{x} can contain dates outside this range to mitigate possible edge effects (see also \code{bracket}). Notice that estimating growth model parameters directly from SPD can be biased, resulting into a null hypothesis that is not necessarily representative (see Crema 2022). It is also possible for the user to provide a model of their own by setting \code{model='custom'} and then supplying a two-column data.frame to \code{predgrid}. The function generates \code{nsim} theoretical SPDs from the fitted model via Monte-Carlo simulation, this is then used to define a 95\% critical envelope for each calendar year. The observed SPD is then compared against the simulation envelope; local departures from the model are defined as instances where the observed SPD is outside such an envelope, while an estimate of the global significance of the observed SPD is also computed by comparing the total areas of observed and simulated SPDs that fall outside the simulation envelope. The theoretical SPDs can be generated using two different sampling approaches defined by the parameter \code{method}. If \code{method} is set to \code{'uncalsample'} each date is drawn after the fitted model is backcalibrated as a whole and adjusted for a baseline expectation; if it is set to \code{'calsample'} samples are drawn from the fitted model in calendar year then individually back calibrated and recalibrated (the approach of Timpson et al. 2014). For each simulation, both approaches produces \eqn{n} samples, with \eqn{n} equal to the number of bins or number of dates (when bins are not defined). Differences between these two approaches are particularly evident at dates coincident with steeper portions of the calibration curve. If more than one type of calibration curve is associated with the observed dates, at each Monte-Carlo iteration, the function randomly assigns each bin to one of the calibration curves with probability based on the proportion of dates within the bin associated to the specific curves. For example, if a bin is composed of four dates and three are calibrated with 'intcal20' the probability of that particular bin being assigned to 'intcal20' is 0.75. 99 | } 100 | \note{ 101 | \itemize{ 102 | \item {Windows users might receive a memory allocation error with larger time span of analysis (defined by the parameter \code{timeRange}). This can be avoided by increasing the memory limit with the \code{\link{memory.limit}} function.} 103 | \item {Users experiencing a \code{Error: cannot allocate vector of size ...} error message can increase the memory size using the \code{Sys.setenv()}, for example: \code{Sys.setenv("R_MAX_VSIZE" = 16e9)}.} 104 | \item {The function currently supports only dates calibrated with 'intcal20',intcal13','intcal13nhpine16','shcal20','shcal13','shcal13shkauri16', 'marine20', and 'marine13'.} 105 | } 106 | } 107 | \examples{ 108 | ## Example with Younger Dryas period Near East, including site bins 109 | \dontrun{ 110 | data(emedyd) 111 | caldates <- calibrate(x=emedyd$CRA, errors=emedyd$Error, normalised=FALSE) 112 | bins <- binPrep(sites=emedyd$SiteName, ages=emedyd$CRA, h=50) 113 | nsim=5 #toy example 114 | expnull <- modelTest(caldates, errors=emedyd$Error, bins=bins, nsim=nsim, runm=50, 115 | timeRange=c(16000,9000), model="exponential", datenormalised=FALSE) 116 | plot(expnull, xlim=c(16000,9000)) 117 | round(expnull$pval,4) #p-value 118 | summary(expnull) 119 | } 120 | } 121 | \references{ 122 | Crema, E.R. (2022). Statistical inference of prehistoric demography from frequency distributions of radiocarbon dates: a review and a guide for the perplexed. Journal of Archaeological Method and Theory. doi:10.1007/s10816-022-09559-5 123 | 124 | Timpson, A., Colledge, S., Crema, E., Edinborough, K., Kerig, T., Manning, K., Thomas, M.G., Shennan, S., (2014). Reconstructing regional population fluctuations in the European Neolithic using radiocarbon dates: a new case-study using an improved method. Journal of Archaeological Science, 52, 549-557. doi:10.1016/j.jas.2014.08.011 125 | } 126 | -------------------------------------------------------------------------------- /man/multiplot.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/plots.R 3 | \name{multiplot} 4 | \alias{multiplot} 5 | \title{Plot multiple dates} 6 | \usage{ 7 | multiplot( 8 | x, 9 | type = "d", 10 | calendar = "BP", 11 | HPD = FALSE, 12 | credMass = 0.95, 13 | decreasing = NULL, 14 | label = TRUE, 15 | label.pos = 0.5, 16 | label.offset = 0, 17 | xlim = NULL, 18 | xlab = NA, 19 | ylab = NA, 20 | col.fill = "grey50", 21 | col.fill2 = "grey82", 22 | col.line = "black", 23 | lwd = 1, 24 | cex.id = 1, 25 | cex.lab = 1, 26 | cex.axis = 1, 27 | ydisp = FALSE, 28 | gapFactor = 0.2, 29 | rescale = FALSE 30 | ) 31 | } 32 | \arguments{ 33 | \item{x}{A CalDates class object with length > 1.} 34 | 35 | \item{type}{Whether the calibrated dates are displayed as distributions (\code{'d'}) or as horizontal bars (\code{'b'}) spanning the HPD interval. Default is \code{'d'}.} 36 | 37 | \item{calendar}{Either \code{'BP'} or \code{'BCAD'}. Indicate whether the calibrated date should be displayed in BP or BC/AD. Default is \code{'BP'}.} 38 | 39 | \item{HPD}{Logical value indicating whether intervals of higher posterior density should be displayed. Default is FALSE.} 40 | 41 | \item{credMass}{A numerical value indicating the size of the higher posterior density interval. Default is 0.95.} 42 | 43 | \item{decreasing}{Whether dates should be plotted with decreasing order of median calibrated date (i.e. old to new; TRUE) or increasing order (i.e. new to old; FALSE). If set to NULL the dates plotted in the supplied order. Default is NULL} 44 | 45 | \item{label}{Whether the ID of each date should be displayed. Default is TRUE.} 46 | 47 | \item{label.pos}{Relative position of the label in relation to the calibrated distribution expressed in quantiles. Default is 0.5 (median).} 48 | 49 | \item{label.offset}{Horrizontal offset of label position in number of years. Default is 0.} 50 | 51 | \item{xlim}{the x limits of the plot. In BP or in BC/AD depending on the choice of the parameter \code{calender}. Notice that if BC/AD is selected BC ages should have a minus sign (e.g. \code{c(-5000,200)} for 5000 BC to 200 AD).} 52 | 53 | \item{xlab}{(optional) Label for the x axis. If unspecified the default setting will be applied ("Year BP" or "Year BC/AD").} 54 | 55 | \item{ylab}{(optional) Label for the y axis.} 56 | 57 | \item{col.fill}{A vector of primary fill color for the calibrated date distribution. Default is 'grey50'.} 58 | 59 | \item{col.fill2}{A vector of secondary secondary colour fill color for the calibrated date distribution, used for regions outside the higher posterior interval. Ignored when \code{HPD=FALSE}. Default is 'grey82'.} 60 | 61 | \item{col.line}{A vector of line color (ignored when \code{type} is set to \code{'d'}. Default is 1.} 62 | 63 | \item{lwd}{Line width (ignored when \code{type} is set to \code{'d'}). Default is 1.} 64 | 65 | \item{cex.id}{The magnification to be used the date labels relative to the current setting of cex. Default is adjusted to 1.} 66 | 67 | \item{cex.lab}{The magnification to be used for x and y labels relative to the current setting of cex. Default is adjusted to 1.} 68 | 69 | \item{cex.axis}{The magnification to be used for axis annotation relative to the current setting of cex. Default is adjusted to 1.} 70 | 71 | \item{ydisp}{Whether the y axis should be displayed. Ignored when \code{type} is set to \code{'b'}. Default is FALSE} 72 | 73 | \item{gapFactor}{Defines spacing between calibrated dates (when \code{type} is set to \code{'d'}) or the distance between the lines and the labels (when \code{type} is set to \code{'b'}) as proportion of individual y-axis ranges. Default is 0.2.} 74 | 75 | \item{rescale}{Whether probability distributions should be rescaled (applicable only when \code{type} is set to \code{'d'}, default is FALSE).} 76 | } 77 | \description{ 78 | Plot multiple radiocarbon dates. 79 | } 80 | \examples{ 81 | data("emedyd") 82 | tellaswad = subset(emedyd,SiteName=='Tell Aswad') 83 | x = calibrate(tellaswad$CRA,tellaswad$Error,ids=tellaswad$LabID) 84 | multiplot(x,HPD=TRUE,decreasing=TRUE,label=FALSE,gapFactor = 0.1) 85 | multiplot(x,type='b',calendar='BCAD',cex.id = 0.5,lwd=2,gapFactor = 0.5) 86 | } 87 | \seealso{ 88 | \code{\link{calibrate}} 89 | } 90 | -------------------------------------------------------------------------------- /man/p2pTest.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/tests.R 3 | \name{p2pTest} 4 | \alias{p2pTest} 5 | \title{Point to point test of SPD} 6 | \usage{ 7 | p2pTest(x, p1 = NA, p2 = NA, interactive = TRUE, plot = FALSE) 8 | } 9 | \arguments{ 10 | \item{x}{result of \code{\link{modelTest}} with raw=TRUE.} 11 | 12 | \item{p1}{calendar year (in BP) of start point.} 13 | 14 | \item{p2}{calendar year (in BP) of end point.} 15 | 16 | \item{interactive}{if set to TRUE enables an interactive selection of p1 and p2 from a graphical display of the SPD. Disabled when \code{p1} and \code{p2} are defined.} 17 | 18 | \item{plot}{if set to TRUE the function plots the location of p1 and p2 on the SPD. Default is FALSE.} 19 | } 20 | \value{ 21 | A list with: the BP dates for the two points and the p-value obtained from a two-sided test. 22 | } 23 | \description{ 24 | Test for evaluating the difference in the summed probability values associated with two points in time. 25 | } 26 | \details{ 27 | The function compares observed differences in the summed probability values associated with two points in time against a distribution of expected values under the null hypothesis defined with the \code{\link{modelTest}} function. The two points can be specified manually (assigning BP dates to the arguments \code{p1} and \code{p2}) or interactively (clicking on a SPD plot). Note that \code{\link{modelTest}} should be executed setting the argument \code{raw} to \code{TRUE} (default is \code{FALSE}). 28 | } 29 | \examples{ 30 | ## Example with Younger Dryas period Near East, including site bins 31 | \dontrun{ 32 | data(emedyd) 33 | caldates <- calibrate(x=emedyd$CRA, errors=emedyd$Error, normalised=FALSE) 34 | bins <- binPrep(sites=emedyd$SiteName, ages=emedyd$CRA, h=50) 35 | nsim=10 #toy example 36 | expnull <- modelTest(caldates, errors=emedyd$Error, bins=bins, nsim=nsim, runm=50, 37 | timeRange=c(16000,9000), model="exponential", datenormalised=FALSE, raw=TRUE) 38 | p2pTest(x=expnull,p1=13000,p2=12500) #non-interactive mode 39 | p2pTest(x=expnull) #interactive mode 40 | } 41 | } 42 | \references{ 43 | Edinborough, K., Porcic, M., Martindale, A., Brown, T.J., Supernant, K., Ames, K.M., (2017). Radiocarbon test for demographic events in written and oral history. PNAS 201713012. doi:10.1073/pnas.1713012114 44 | } 45 | \seealso{ 46 | \code{\link{modelTest}}. 47 | } 48 | -------------------------------------------------------------------------------- /man/permTest.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/tests.R 3 | \name{permTest} 4 | \alias{permTest} 5 | \title{Random mark permutation test for SPDs} 6 | \usage{ 7 | permTest( 8 | x, 9 | marks, 10 | timeRange, 11 | backsight = 10, 12 | changexpr = expression((t1/t0)^(1/d) - 1), 13 | nsim, 14 | bins = NA, 15 | runm = NA, 16 | datenormalised = FALSE, 17 | spdnormalised = FALSE, 18 | raw = FALSE, 19 | verbose = TRUE 20 | ) 21 | } 22 | \arguments{ 23 | \item{x}{A \code{CalDates} class object containing the calibrated radiocarbon dates.} 24 | 25 | \item{marks}{A numerical or character vector containing the marks associated to each radiocarbon date.} 26 | 27 | \item{timeRange}{A vector of length 2 indicating the start and end date of the analysis in cal BP.} 28 | 29 | \item{backsight}{A single numeric value defining the distance in time between the focal year and the backsight year for computing the rate of change. Default is 10.} 30 | 31 | \item{changexpr}{An expression for calculating the rate of change in SPD between the focal year and a backsight year. Available input options are t1 (the SPD for the focal year), t0 (the SPD for the backsight year), d (the distance between t0 and t1), and any other standard constants and mathematical operators. A sensible default is provided.} 32 | 33 | \item{nsim}{Number of random permutations} 34 | 35 | \item{bins}{A vector indicating which bin each radiocarbon date is assigned to.} 36 | 37 | \item{runm}{A number indicating the window size of the moving average to smooth the SPD. If set to \code{NA} no moving average is applied.Default is NA.} 38 | 39 | \item{datenormalised}{If set to TRUE the total probability mass of each calibrated date will be made to sum to unity (the default in most radiocarbon calibration software). This argument will only have an effect if the dates in \code{x} were calibrated without normalisation (via normalised=FALSE in the \code{\link{calibrate}} function), in which case setting \code{datenormalised=TRUE} here will rescale each dates probability mass to sum to unity before aggregating the dates, while setting \code{datenormalised=FALSE} will ensure unnormalised dates are used for both observed and simulated SPDs. Default is FALSE.} 40 | 41 | \item{spdnormalised}{A logical variable indicating whether the total probability mass of the SPD is normalised to sum to unity.} 42 | 43 | \item{raw}{A logical variable indicating whether all permuted SPDs should be returned or not. Default is FALSE.} 44 | 45 | \item{verbose}{A logical variable indicating whether extra information on progress should be reported. Default is TRUE.} 46 | } 47 | \value{ 48 | An object of class \code{SpdPermTest} with the following elements 49 | \itemize{ 50 | \item{\code{observed}} {A list containing data.frames with the summed probability (column \emph{PrDens} for each calendar year (column \emph{calBP} for each mark/group} 51 | \item{\code{envelope}} {A list containing matrices with the lower and upper bound values of the simulation envelope for each mark/group} 52 | \item{\code{pValueList}} {A list of p-value associated with each mark/group} 53 | } 54 | } 55 | \description{ 56 | Global and local significance test for comparing shapes of multiple SPDs using random permutations. 57 | } 58 | \details{ 59 | The function generates a distribution of expected SPDs by randomly shuffling the marks assigned to each \emph{bin} (see \code{\link{spd}} for details on binning). The resulting distribution of probabilities for each \emph{mark} (i.e. group of dates) for each calendar year is z-transformed, and a 95\% simulation envelope is computed. Local significant departures are defined as instances where the observed SPD (which is also z-transformed) is outside such envelope. A global significance is also computed by comparing the total "area" outside the simulation envelope in the observed and simulated data. 60 | } 61 | \examples{ 62 | ## compare demographic trajectories in Netherlands and Denmark 63 | \dontrun{ 64 | data(euroevol) 65 | nld.dnk = subset(euroevol,Country=="Netherlands"|Country=="Denmark") 66 | bins = binPrep(nld.dnk$SiteID,nld.dnk$C14Age,h=200) 67 | dates = calibrate(nld.dnk$C14Age,nld.dnk$C14SD,normalised=FALSE) 68 | res = permTest(dates,marks=as.character(nld.dnk$Country),nsim=1000, 69 | bins=bins,runm=200,timeRange=c(10000,4000)) 70 | round(res$pValueList,4) #extract p-values 71 | summary(res) 72 | par(mfrow=c(2,1)) 73 | plot(res,focalm="Netherlands",main="Netherlands") 74 | plot(res,focalm="Denmark",main="Denmark") 75 | } 76 | } 77 | \references{ 78 | Crema, E.R., Habu, J., Kobayashi, K., Madella, M., (2016). Summed Probability Distribution of 14 C Dates Suggests Regional Divergences in the Population Dynamics of the Jomon Period in Eastern Japan. PLOS ONE 11, e0154809. doi:10.1371/journal.pone.0154809 79 | } 80 | -------------------------------------------------------------------------------- /man/plot.CalDates.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/plots.R 3 | \name{plot.CalDates} 4 | \alias{plot.CalDates} 5 | \title{Plot calibrated dates} 6 | \usage{ 7 | \method{plot}{CalDates}( 8 | x, 9 | ind = 1, 10 | label = NA, 11 | calendar = "BP", 12 | type = "standard", 13 | xlab = NA, 14 | ylab = NA, 15 | axis4 = TRUE, 16 | HPD = FALSE, 17 | credMass = 0.95, 18 | customCalCurve = NA, 19 | add = FALSE, 20 | col = "grey50", 21 | col2 = "grey82", 22 | cex.axis = 0.75, 23 | cex.xylab = 0.75, 24 | cex.label = 0.75, 25 | ... 26 | ) 27 | } 28 | \arguments{ 29 | \item{x}{\code{CalDates} class object containing calibrated radiocarbon dates.} 30 | 31 | \item{ind}{Number indicating the index value of the calibrated radiocarbon date to be displayed. Default is 1.} 32 | 33 | \item{label}{(optional) Character vector to be shown on the top-right corner of the display window.} 34 | 35 | \item{calendar}{Either \code{'BP'} or \code{'BCAD'}. Indicate whether the calibrated date should be displayed in BP or BC/AD. Default is \code{'BP'}.} 36 | 37 | \item{type}{Either \code{'standard'} or \code{'auc'}. If set to \code{'auc'}, displays both the normalised (dashed line) and unnormalised curves. Default is \code{'standard'}.} 38 | 39 | \item{xlab}{(optional) Label for the x axis. If unspecified the default setting will be applied ("Year BP" or "Year BC/AD").} 40 | 41 | \item{ylab}{(optional) Label for the y axis. If unspecified the default setting will be applied ("Radiocarbon Age").} 42 | 43 | \item{axis4}{Logical value indicating whether an axis of probabilities values should be displayed. Default is TRUE.} 44 | 45 | \item{HPD}{Logical value indicating whether intervals of higher posterior density should be displayed. Default is FALSE.} 46 | 47 | \item{credMass}{A numerical value indicating the size of the higher posterior density interval. Default is 0.95.} 48 | 49 | \item{customCalCurve}{A three column data.frame or matrix that allows you to pass and plot a custom calibration curve if you used one during calibration. You can currently only provide one such custom curve which is used for all dates.} 50 | 51 | \item{add}{if set to \code{TRUE} the calibrated date is displayed over the existing plot. Default is \code{FALSE}.} 52 | 53 | \item{col}{The primary fill color for the calibrated date distribution.} 54 | 55 | \item{col2}{The secondary colour fill color for the calibrated date distribution, used for regions outside the higher posterior interval. Ignored when \code{HPD=FALSE}.} 56 | 57 | \item{cex.axis}{The magnification to be used for axis annotation relative to the current setting of cex. Default is adjusted to 0.75.} 58 | 59 | \item{cex.xylab}{The magnification to be used for x and y labels relative to the current setting of cex. Default is adjusted to 0.75.} 60 | 61 | \item{cex.label}{The magnification to be used for the label on the top right corner defined by the argument \code{label}. Default is adjusted to 0.75.} 62 | 63 | \item{...}{Additional arguments affecting the plot.} 64 | } 65 | \description{ 66 | Plot calibrated radiocarbon dates. 67 | } 68 | \examples{ 69 | x <- calibrate(x=c(3402,3490,4042),errors=c(20,20,30)) 70 | plot(x) #display the first date 71 | plot(x,2) #displays the second date 72 | plot(x,3, calendar="BCAD", HPD=TRUE) #display in BC/AD with higher posterior density interval 73 | } 74 | \seealso{ 75 | \code{\link{calibrate}} 76 | } 77 | -------------------------------------------------------------------------------- /man/plot.CalGrid.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/plots.R 3 | \name{plot.CalGrid} 4 | \alias{plot.CalGrid} 5 | \title{Plot a summed probability distribution (from a CalGrid object)} 6 | \usage{ 7 | \method{plot}{CalGrid}( 8 | x, 9 | runm = NA, 10 | calendar = "BP", 11 | fill.p = "grey50", 12 | border.p = NA, 13 | xlim = NA, 14 | ylim = NA, 15 | cex.lab = 0.75, 16 | cex.axis = cex.lab, 17 | mar = c(4, 4, 1, 3), 18 | add = FALSE, 19 | ... 20 | ) 21 | } 22 | \arguments{ 23 | \item{x}{A "CalGrid" class object of summed probabilities per calendar year BP.} 24 | 25 | \item{runm}{A number indicating the window size of the moving average to smooth the SPD. If set to \code{NA} no moving average is applied. Default is NA} 26 | 27 | \item{calendar}{Either \code{'BP'} or \code{'BCAD'}. Indicate whether the calibrated date should be displayed in BP or BC/AD. Default is \code{'BP'}.} 28 | 29 | \item{fill.p}{Fill colour of the polygon depicting the summed probability distribution.} 30 | 31 | \item{border.p}{Border colour of the polygon depicting the summed probability distribution.} 32 | 33 | \item{xlim}{the x limits of the plot. In BP or in BC/AD depending on the choice of the parameter \code{calender}. Notice that if BC/AD is selected BC ages should have a minus sign (e.g. \code{c(-5000,200)} for 5000 BC to 200 AD).} 34 | 35 | \item{ylim}{Adjust y axis limits (otherwise sensible default).} 36 | 37 | \item{cex.lab}{Size of label text.} 38 | 39 | \item{cex.axis}{Size of axis text.} 40 | 41 | \item{mar}{Adjust margins around plot.} 42 | 43 | \item{add}{Whether or not the new graphic should be added to an existing plot.} 44 | 45 | \item{...}{Additional arguments affecting the plot} 46 | } 47 | \description{ 48 | Plot a summed radiocarbon probability distribution. This is a basic function for plotting SPDs that have been constructed manually or by calibrating a summed or otherwise irregular CRA grid. In most instances, it is sensible to use \code{plot.CalSPD} instead. 49 | } 50 | \examples{ 51 | data(euroevol) 52 | mycaldates <- calibrate(euroevol[1:10,"C14Age"], euroevol[1:10,"C14SD"], normalised=FALSE) 53 | myspd <- spd(mycaldates, timeRange=c(8000,2000)) 54 | plot(myspd) #ordinary plot using \code{plot.CalSPD} 55 | plot(myspd$grid) #working plot using the internal CalGrid object 56 | } 57 | \seealso{ 58 | \code{\link{spd}}; \code{\link{plot.CalSPD}} 59 | } 60 | -------------------------------------------------------------------------------- /man/plot.CalSPD.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/plots.R 3 | \name{plot.CalSPD} 4 | \alias{plot.CalSPD} 5 | \title{Plot a summed probability distribution} 6 | \usage{ 7 | \method{plot}{CalSPD}( 8 | x, 9 | runm = NA, 10 | calendar = "BP", 11 | type = "standard", 12 | xlim = NA, 13 | ylim = NA, 14 | ylab = "Summed Probability", 15 | spdnormalised = FALSE, 16 | rescale = FALSE, 17 | fill.p = "grey75", 18 | border.p = NA, 19 | xaxt = "s", 20 | yaxt = "s", 21 | add = FALSE, 22 | cex.axis = 1, 23 | ... 24 | ) 25 | } 26 | \arguments{ 27 | \item{x}{A \code{CalSPD} class object.} 28 | 29 | \item{runm}{A number indicating the window size of the moving average to smooth the SPD. If set to \code{NA} no moving average is applied. Default is NA} 30 | 31 | \item{calendar}{Either \code{'BP'} or \code{'BCAD'}. Indicate whether the calibrated date should be displayed in BP or BC/AD. Default is \code{'BP'}.} 32 | 33 | \item{type}{Either \code{'standard'} or \code{'simple'}. The former visualise the SPD as an area graph, while the latter as line chart.} 34 | 35 | \item{xlim}{the x limits of the plot. In BP or in BC/AD depending on the choice of the parameter \code{calender}. Notice that if BC/AD is selected BC ages should have a minus sign (e.g. \code{c(-5000,200)} for 5000 BC to 200 AD).} 36 | 37 | \item{ylim}{the y limits of the plot.} 38 | 39 | \item{ylab}{(optional) Label for the y axis. If unspecified the default setting will be applied ("Summed Probability")} 40 | 41 | \item{spdnormalised}{A logical variable indicating whether the total probability mass of the SPD is normalised to sum to unity.} 42 | 43 | \item{rescale}{A logical variable indicating whether the SPD should be rescaled to range 0 to 1.} 44 | 45 | \item{fill.p}{Fill colour for the SPD} 46 | 47 | \item{border.p}{Border colour for the SPD} 48 | 49 | \item{xaxt}{Whether the x-axis tick marks should be displayed (\code{xaxt='s'}, default) or not (\code{xaxt='n'}).} 50 | 51 | \item{yaxt}{Whether the y-axis tick marks should be displayed (\code{xaxt='s'}, default) or not (\code{xaxt='n'}).} 52 | 53 | \item{add}{Whether or not the new graphic should be added to an existing plot.} 54 | 55 | \item{cex.axis}{The magnification to be used for axis annotation relative to the current setting of cex. Default is 1.} 56 | 57 | \item{...}{Additional arguments affecting the plot} 58 | } 59 | \description{ 60 | Plot a summed probability distribution (SPD) of radiocarbon dates 61 | } 62 | \examples{ 63 | \dontrun{ 64 | data(emedyd) 65 | levant <- emedyd[emedyd$Region=="1"|emedyd$Region=="2",] 66 | bins <- binPrep(levant$SiteName, levant$CRA, h=50) 67 | x <- calibrate(levant$CRA, levant$Error, normalised=FALSE) 68 | spd.levant <- spd(x, bins=bins, timeRange=c(17000,8000)) 69 | spd.northernlevant <- spd(x[levant$Region=="2"], bins=bins[levant$Region=="2"], 70 | timeRange=c(17000,8000)) 71 | plot(spd.levant, runm=50, xlim=c(16000,9000)) 72 | plot(spd.northernlevant, runm=50, add=TRUE, fill.p="black") 73 | legend("topleft", legend=c("All Levant dates","Northern Levant only"), 74 | fill=c("grey75","black"), border=NA) 75 | plot(spd.levant, runm=50, xlim=c(16000,9000), type="simple") 76 | plot(spd.northernlevant, runm=50, col="red", type="simple", add=TRUE) 77 | } 78 | } 79 | \seealso{ 80 | \code{\link{spd}}; \code{\link{plot.CalGrid}} 81 | } 82 | -------------------------------------------------------------------------------- /man/plot.SpdModelTest.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/plots.R 3 | \name{plot.SpdModelTest} 4 | \alias{plot.SpdModelTest} 5 | \title{Plot result of Monte-Carlo simulation of observed versus modelled SPDs} 6 | \usage{ 7 | \method{plot}{SpdModelTest}( 8 | x, 9 | calendar = "BP", 10 | type = "spd", 11 | ylim = NA, 12 | xlim = NA, 13 | col.obs = "black", 14 | lwd.obs = 0.5, 15 | xaxs = "i", 16 | yaxs = "i", 17 | bbty = "f", 18 | bbtyRet = TRUE, 19 | drawaxes = TRUE, 20 | ... 21 | ) 22 | } 23 | \arguments{ 24 | \item{x}{A \code{SpdModelTest} class object generated using the \code{\link{modelTest}} function.} 25 | 26 | \item{calendar}{Either \code{'BP'} or \code{'BCAD'}. Indicate whether the calibrated date should be displayed in BP or BC/AD. Default is \code{'BP'}.} 27 | 28 | \item{type}{Whether to display SPDs ('spd') or rates of change ('roc'). Default is 'spd'.} 29 | 30 | \item{ylim}{the y limits of the plot.} 31 | 32 | \item{xlim}{the x limits of the plot. In BP or in BC/AD depending on the choice of the parameter \code{calender}. Notice that if BC/AD is selected BC ages should have a minus sign (e.g. \code{c(-5000,200)} for 5000 BC to 200 AD).} 33 | 34 | \item{col.obs}{Line colour for the observed SPD.} 35 | 36 | \item{lwd.obs}{Line width for the observed SPD.} 37 | 38 | \item{xaxs}{The style of x-axis interval calculation (see \code{\link{par}})} 39 | 40 | \item{yaxs}{The style of y-axis interval calculation (see \code{\link{par}})} 41 | 42 | \item{bbty}{Display options; one between \code{'b'},\code{'n'},and \code{'f'}. See details below.} 43 | 44 | \item{bbtyRet}{Whether details on the intervals of positive and negative deviations are returned. Default is TRUE.} 45 | 46 | \item{drawaxes}{A logical value determining whether the axes should be displayed or not. Default is TRUE.} 47 | 48 | \item{...}{Additional arguments affecting the plot} 49 | } 50 | \description{ 51 | The function visualises the observed summed probability distribution of radiocarbon dates along with a simulation envelope for the null model and regions of positive and negative deviation. 52 | } 53 | \details{ 54 | The argument \code{bbty} controls the display options of the Monte-Carlo Test. Default settings (\code{bbty='f'}) displays the observed SPD (solid black line), the simulation envelope of the fitted model (shaded grey polygon) and regions of significance positive (red semi-transparent rectangle) and negative (blue semi-transparent rectangle) deviation. The option \code{bbty='b'} removes the regions of positive/negative deviations, whilst the option \code{bbty='n'} displays the simulation envelope on existing plot. 55 | } 56 | \seealso{ 57 | \code{\link{modelTest}} 58 | } 59 | -------------------------------------------------------------------------------- /man/plot.SpdPermTest.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/plots.R 3 | \name{plot.SpdPermTest} 4 | \alias{plot.SpdPermTest} 5 | \title{Plot result of mark permutation test of SPDs} 6 | \usage{ 7 | \method{plot}{SpdPermTest}( 8 | x, 9 | focalm = 1, 10 | type = "spd", 11 | calendar = "BP", 12 | xlim = NA, 13 | ylim = NA, 14 | col.obs = "black", 15 | col.env = rgb(0, 0, 0, 0.2), 16 | lwd.obs = 0.5, 17 | xaxs = "i", 18 | yaxs = "i", 19 | bbty = "f", 20 | drawaxes = TRUE, 21 | ... 22 | ) 23 | } 24 | \arguments{ 25 | \item{x}{A \code{SpdPermTest} class object. Result of random mark permutation test (see \code{\link{permTest}})} 26 | 27 | \item{focalm}{Value specifying the name of the focal mark (group) to be plotted.} 28 | 29 | \item{type}{Whether to display SPDs ('spd') or rates of change ('roc'). Default is 'spd'.} 30 | 31 | \item{calendar}{Either \code{'BP'} or \code{'BCAD'}. Indicate whether the calibrated date should be displayed in BP or BC/AD. Default is \code{'BP'}.} 32 | 33 | \item{xlim}{the x limits of the plot. In BP or in BC/AD depending on the choice of the parameter \code{calender}. Notice that if BC/AD is selected BC ages should have a minus sign (e.g. \code{c(-5000,200)} for 5000 BC to 200 AD).} 34 | 35 | \item{ylim}{the y limits of the plot.} 36 | 37 | \item{col.obs}{Line colour for the observed SPD} 38 | 39 | \item{col.env}{Colour for the simulation envelope} 40 | 41 | \item{lwd.obs}{Line width for the observed SPD} 42 | 43 | \item{xaxs}{The style of x-axis interval calculation (see \code{\link{par}})} 44 | 45 | \item{yaxs}{The style of y-axis interval calculation (see \code{\link{par}})} 46 | 47 | \item{bbty}{Display options; one between \code{'b'},\code{'n'},and \code{'f'}. See details in \code{\link{plot.SpdModelTest}}.} 48 | 49 | \item{drawaxes}{A logical value determining whether the axes should be displayed or not. Default is TRUE.} 50 | 51 | \item{...}{Additional arguments affecting the plot} 52 | } 53 | \description{ 54 | Visualises the observed SPD along with the simulation envelope generated from \code{\link{permTest}}, with regions of positive and negative deviations highlighted in red and blue. 55 | } 56 | \seealso{ 57 | \code{\link{permTest}}; \code{\link{plot.SpdModelTest}}; 58 | } 59 | -------------------------------------------------------------------------------- /man/plot.compositeKDE.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/plots.R 3 | \name{plot.compositeKDE} 4 | \alias{plot.compositeKDE} 5 | \title{Plots a Composite Kernel Density Estimate of sampled radiocarbon dates.} 6 | \usage{ 7 | \method{plot}{compositeKDE}( 8 | x, 9 | calendar = "BP", 10 | type = "envelope", 11 | ylim = NA, 12 | xlim = NA, 13 | fill.col = "lightgrey", 14 | interval = 0.95, 15 | line.col = "black", 16 | line.type = 2, 17 | multiline.alpha = NA, 18 | multiline.col = "black", 19 | ... 20 | ) 21 | } 22 | \arguments{ 23 | \item{x}{A \code{compositeKDE} class object generated using the \code{\link{ckde}} function.} 24 | 25 | \item{calendar}{Either \code{'BP'} or \code{'BCAD'}. Indicate whether the calibrated date should be displayed in BP or BC/AD. Default is \code{'BP'}.} 26 | 27 | \item{type}{Either \code{envelope} or \code{multiline}. Default is \code{envelope}.} 28 | 29 | \item{ylim}{the y limits of the plot.} 30 | 31 | \item{xlim}{the x limits of the plot. In BP or in BC/AD depending on the choice of the parameter \code{calender}. Notice that if BC/AD is selected BC ages should have a minus sign (e.g. \code{c(-5000,200)} for 5000 BC to 200 AD).} 32 | 33 | \item{fill.col}{Envelope color when \code{type='envelope'}. Default is 'lightgrey'.} 34 | 35 | \item{interval}{Quantile interval for the envelope. Default is 0.95.} 36 | 37 | \item{line.col}{Line color when \code{type='envelope'}. Default is 'black.} 38 | 39 | \item{line.type}{Line type when \code{type='envelope'}. Default is 2.} 40 | 41 | \item{multiline.alpha}{Alpha level for line transparency when \code{type='multiline'}. Default is 10/\code{nsim}, where \code{nsim} is the number of simulations. If \code{nsim} is smaller than 10, \code{multiline.alpha} will be set to 1.} 42 | 43 | \item{multiline.col}{Line color when \code{type='multiline'}. Default is 'black'.} 44 | 45 | \item{...}{Additional arguments affecting the plot} 46 | } 47 | \description{ 48 | Plots a Composite Kernel Density Estimate of sampled radiocarbon dates. 49 | } 50 | \details{ 51 | Visualise a \code{compositeKDE} class object. If \code{type} is set \code{'envelope'} an envelope of the percentile interval defined by the parameter \code{interval} is shown along with the mean KDE. If \code{type} is set \code{'multiline'} all KDEs are shown. 52 | } 53 | \seealso{ 54 | \code{\link{ckde}}; 55 | } 56 | -------------------------------------------------------------------------------- /man/plot.spatialTest.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/plots.R 3 | \name{plot.spatialTest} 4 | \alias{plot.spatialTest} 5 | \title{Plot results of the local spatial permutation test of summed probability distributions.} 6 | \usage{ 7 | \method{plot}{spatialTest}( 8 | x, 9 | index = 1, 10 | option, 11 | breakRange, 12 | breakLength = 7, 13 | rd = 5, 14 | baseSize = 0.5, 15 | plim = 0.05, 16 | qlim = 0.05, 17 | legend = FALSE, 18 | legSize = 1, 19 | location = "bottomright", 20 | ... 21 | ) 22 | } 23 | \arguments{ 24 | \item{x}{A \code{spatialTest} class object} 25 | 26 | \item{index}{A numerical value indicating which transition to display. Ignored when \code{option="rawlegend"} or \code{option="testlegend"}. Default is 1.} 27 | 28 | \item{option}{Either "\code{raw}" to display local growth rates, "\code{test}" to display the test results (i.e. q and p values), or "\code{return}" to return a \code{sf} class object containing all relevant information for the given \code{index} value.} 29 | 30 | \item{breakRange}{A vector of length 2 defining the minimum and maximum values of growth rate to be displayed in the legend. If set to NA its computed from data range (default).} 31 | 32 | \item{breakLength}{A numerical vector defining the number of breaks for growth rates to be displayed in the legend.} 33 | 34 | \item{rd}{Number of decimal places of the growth rate to be displayed in the Legend} 35 | 36 | \item{baseSize}{Numerical value giving the amount by which points should be magnified relative to the default settings in R. Default is 0.5} 37 | 38 | \item{plim}{Threshold value for the p-values. Default is 0.05.} 39 | 40 | \item{qlim}{Threshold value for the q-values. Default is 0.05.} 41 | 42 | \item{legend}{Logical values specifying whether the legend should be displayed or not. Default is FALSE.} 43 | 44 | \item{legSize}{Numerical value giving the amount by which points should be magnified relative to the default settings in R for the Legend. Default is 1.} 45 | 46 | \item{location}{A single keyword from the list "bottomright", "bottom", "bottomleft", "left", "topleft", "top", "topright", "right" and "center" to specify the location of the Legend. Default is "bottomright".} 47 | 48 | \item{...}{Graphical parameters to be passed to methods.} 49 | } 50 | \description{ 51 | Displays local growth rates, p-values, and q-values retrieved from a \code{spatialTest} class object. 52 | } 53 | \details{ 54 | The function displays a distribution map of local growth rates (when \code{option="raw"}), q- and p-values (when \code{option="test"}), and the associated legends (when \code{option="rawlegend"} or \code{option="testlegend"}). 55 | } 56 | \seealso{ 57 | \code{\link{sptest}} 58 | } 59 | -------------------------------------------------------------------------------- /man/plot.spdRC.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/plots.R 3 | \name{plot.spdRC} 4 | \alias{plot.spdRC} 5 | \title{Plot \code{spdRC} class objects} 6 | \usage{ 7 | \method{plot}{spdRC}( 8 | x, 9 | calendar = "BP", 10 | col.obs = "black", 11 | lwd.obs = 0.5, 12 | xaxs = "i", 13 | yaxs = "i", 14 | xlim = NA, 15 | ... 16 | ) 17 | } 18 | \arguments{ 19 | \item{x}{\code{spdRC} class object containing geometric growth rates.} 20 | 21 | \item{calendar}{Either \code{'BP'} or \code{'BCAD'}. Indicate whether the calibrated date should be displayed in BP or BC/AD. Default is \code{'BP'}.} 22 | 23 | \item{col.obs}{Line colour for the observed SPD} 24 | 25 | \item{lwd.obs}{Line width for the observed SPD} 26 | 27 | \item{xaxs}{The style of x-axis interval calculation (see \code{\link{par}})} 28 | 29 | \item{yaxs}{The style of y-axis interval calculation (see \code{\link{par}})} 30 | 31 | \item{xlim}{Limits for the x axis.} 32 | 33 | \item{...}{Additional arguments affecting the plot.} 34 | } 35 | \description{ 36 | Plot rates of change between time-blocks 37 | } 38 | \seealso{ 39 | \code{\link{spd2rc}} 40 | } 41 | -------------------------------------------------------------------------------- /man/plot.stKde.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/plots.R 3 | \name{plot.stKde} 4 | \alias{plot.stKde} 5 | \title{Plot map(s) of the spatio-temporal intensity of radiocarbon dates.} 6 | \usage{ 7 | \method{plot}{stKde}( 8 | x, 9 | focalyears = NULL, 10 | type = "focal", 11 | plotdir = NULL, 12 | imnames = "byyear", 13 | zlim = NULL, 14 | box = FALSE, 15 | main = "auto", 16 | col.mask = "grey75", 17 | ncolours = 256, 18 | ramptype = "raw", 19 | imdim = c(10, 10), 20 | mars = c(0.5, 0.5, 2.5, 2), 21 | ribbon = TRUE, 22 | ribargs = list(), 23 | cex.ribbon = 0.5, 24 | withpts = "n", 25 | cex.main = 0.8, 26 | pch.pts = 19, 27 | col.pts = "grey50", 28 | cex.pts = 0.1, 29 | tidydevs = TRUE, 30 | verbose = TRUE, 31 | ... 32 | ) 33 | } 34 | \arguments{ 35 | \item{x}{An object of class stKde.} 36 | 37 | \item{focalyears}{A vector of numeric values for focal years, in calBP, that will be timesteps at which date intensity maps will be plotted.} 38 | 39 | \item{type}{A single character string stipulating which type of plot to create. Current options are "nonfocal", "mask", "focal", "proportion", "change" and "all".} 40 | 41 | \item{plotdir}{Optional output directory for plots. If NULL, then only a single plot is made to the current device. If a valid output direcotry is provided then one or more timeslices maps are saved as png files (e.g. as source images for an animation).} 42 | 43 | \item{imnames}{The format of the output files if output is as png files to a directory. The current two options are "basic" (labelling the images in basic sequence as preferred by animation software such as ffmpeg) or "byyear" (labelling the images by calBP year).} 44 | 45 | \item{zlim}{Numeric vector of length=2 which controlls the maximum or minimum of the colour ramp.} 46 | 47 | \item{box}{Logical. Plot a border around the map or not.} 48 | 49 | \item{main}{Single character string specifying a main title. "auto" implies internal default titles are used.} 50 | 51 | \item{col.mask}{The colour used to depict any areas that are being masked out.} 52 | 53 | \item{ncolours}{The maximum number of colours to use in the colour ramp.} 54 | 55 | \item{ramptype}{What kind of treatment for the colour ramp. Current options are "raw" (do not try to standardise the ramps across timeslices),"std" (standardise each plot, typically by capturing the first 3sd in the main colour ramp and then outliers beyond that with the extreme colours of the ramp),"unl" (do not standardise but plot generalised high/low ramp labels) and "mmx" (scale to the minimum and maximum values across all timeslices).} 56 | 57 | \item{imdim}{Height and width of the plot to png in cm.} 58 | 59 | \item{mars}{Margins of the plot to png.} 60 | 61 | \item{ribbon}{Whether to plot the colour ramp legend or not.} 62 | 63 | \item{ribargs}{Whether to plot the colour ramp legend or not.} 64 | 65 | \item{cex.ribbon}{The size of the ribbon font.} 66 | 67 | \item{withpts}{Plot with the original sample locations shown (current options are "y" and "n").} 68 | 69 | \item{cex.main}{The size of the title font.} 70 | 71 | \item{pch.pts}{The symbols used for the plotted points.} 72 | 73 | \item{col.pts}{The colours used for the plotted points.} 74 | 75 | \item{cex.pts}{The size used for the plotted points.} 76 | 77 | \item{tidydevs}{Logical for whether to clean up any open grpahics devices or not (default is TRUE).} 78 | 79 | \item{verbose}{A logical variable indicating whether extra information on progress should be reported. Default is TRUE.} 80 | 81 | \item{...}{Additional arguments affecting the plot.} 82 | } 83 | \description{ 84 | Plotting function for single or multiple maps of the spatio-temporal intensity of radiocarbon dates at given focal years. 85 | } 86 | \details{ 87 | This function plots to a screen device if a single focal year is stipulated and no output directory. Or if an output directory is stipulated, it plots one or more focal years to png files, with some basic formatting options and optional cross-year standardisation of the colour ramps (with a view to them being stills-for-video). For even more control of plotting, call this function one year at a time in a loop. 88 | } 89 | \examples{ 90 | \dontrun{ 91 | ## Example with a subset of English and Welsh dates from the Euroevol dataset 92 | data(ewdates) 93 | data(ewowin) 94 | dir.create(file.path("im"), showWarnings=FALSE) 95 | x <- calibrate(x=ewdates$C14Age, errors=ewdates$C14SD, normalised=FALSE) 96 | bins1 <- binPrep(sites=ewdates$SiteID, ages=ewdates$C14Age, h=50) 97 | stkde1 <- stkde(x=x, coords=ewdates[,c("Eastings", "Northings")], 98 | win=ewowin, sbw=40000, cellres=2000, focalyears=seq(6500, 5000, -100), 99 | tbw=50, bins=bins1, backsight=200, outdir="im") 100 | 101 | ## Plot just the proportion surface for just 5900 calBP 102 | plot(stkde1, 5900, type="proportion") 103 | 104 | ## Plot an example of all four basic outputs for just 5900 calBP 105 | dev.new(height=2.5, width=8) 106 | par(mar=c(0.5, 0.5, 2.5, 2)) 107 | plot(stkde1, 5900, type="all") 108 | 109 | ## Plot standardised change surfaces to a sub-directory called 110 | ## /png for all timeslices and save to file. 111 | dir.create(file.path("png"), showWarnings=FALSE) 112 | plot(stkde1, seq(6500,5000,-100), type="change", ramptype="std", withpts=TRUE, plotdir="png") 113 | 114 | ## Plot all four summary surfaces in one image, saving them to a sub-directory call 'pngall', 115 | ## and with the output of the change map standardised to a common ramp 116 | ## (but leaving the focal and proportion maps unstandardised with simple ramp labelling) 117 | dir.create(file.path("pngall"), showWarnings=FALSE) 118 | plot(stkde1, seq(6500,5000,-100), type="all", ramptype=c("unl","unl","std"), imdim=cm(c(2.5,8)), 119 | withpts=TRUE, plotdir="pngall") 120 | } 121 | 122 | } 123 | -------------------------------------------------------------------------------- /man/plot.stackCalSPD.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/plots.R 3 | \name{plot.stackCalSPD} 4 | \alias{plot.stackCalSPD} 5 | \title{Plot a stack of SPDs} 6 | \usage{ 7 | \method{plot}{stackCalSPD}( 8 | x, 9 | type = "stacked", 10 | calendar = "BP", 11 | spdnormalised = FALSE, 12 | rescale = FALSE, 13 | runm = NA, 14 | xlim = NA, 15 | ylim = NA, 16 | xaxt = "s", 17 | yaxt = "s", 18 | gapFactor = 0.2, 19 | col.fill = NA, 20 | col.line = NA, 21 | lwd.obs = 1, 22 | lty.obs = 1, 23 | cex.lab = 1, 24 | cex.axis = cex.lab, 25 | legend = TRUE, 26 | legend.arg = NULL, 27 | ylab = NA, 28 | ymargin = 1.1, 29 | rnd = 2, 30 | ... 31 | ) 32 | } 33 | \arguments{ 34 | \item{x}{A \code{stackCalSPD} class object. Result of \code{\link{stackspd}} function.} 35 | 36 | \item{type}{How to display the SPDs.Current options are \code{'stacked'},\code{'lines'}, '\code{'proportion'}. and \code{'multipanel'}. Default is \code{'stacked'}.} 37 | 38 | \item{calendar}{Either \code{'BP'} or \code{'BCAD'}. Indicate whether the calibrated date should be displayed in BP or BC/AD. Default is \code{'BP'}.} 39 | 40 | \item{spdnormalised}{A logical variable indicating whether the total probability mass of the SPDs are normalised to sum to unity. Default is FALSE.} 41 | 42 | \item{rescale}{A logical variable indicating whether the summed probabilities values should be rescaled to range 0 to 1. Default is FALSE.Notice that this is different from setting \code{spdnormalised} to TRUE.} 43 | 44 | \item{runm}{A number indicating the window size of the moving average to smooth the SPD. If set to \code{NA} no moving average is applied. Default is NA} 45 | 46 | \item{xlim}{the x limits of the plot. In BP or in BC/AD depending on the choice of the parameter \code{calender}. Notice that if BC/AD is selected BC ages should have a minus sign (e.g. \code{c(-5000,200)} for 5000 BC to 200 AD).} 47 | 48 | \item{ylim}{the y limits of the plot.} 49 | 50 | \item{xaxt}{Whether the x-axis tick marks should be displayed (\code{xaxt='s'}, default) or not (\code{xaxt='n'}).} 51 | 52 | \item{yaxt}{Whether the y-axis tick marks should be displayed (\code{xaxt='s'}, default) or not (\code{xaxt='n'}).} 53 | 54 | \item{gapFactor}{Defines spacing between SPDs as proportion of the y-axis range for multipanel plots. Default is 0.2.} 55 | 56 | \item{col.fill}{Vector of fill color for the observed SPDs. The default color scheme is based on the Dark2 pallette of RColorBrewer package.} 57 | 58 | \item{col.line}{Line colour for the observed SPDs.The default color scheme is based on the Dark2 palette of RColorBrewer package.} 59 | 60 | \item{lwd.obs}{Line width for the observed SPDs. Default is 1.} 61 | 62 | \item{lty.obs}{Line type for the observed SPDs. Default is 1.} 63 | 64 | \item{cex.lab}{The magnification to be used for x and y labels relative to the current setting of cex. Default is adjusted to 1.} 65 | 66 | \item{cex.axis}{The magnification to be used for axis annotation relative to the current setting of cex. Default is adjusted to 1.} 67 | 68 | \item{legend}{Whether legend needs to be displayed. Item names will be retrieved from the values supplied in the argument \code{group} in \code{\link{stackspd}}. Default is TRUE.} 69 | 70 | \item{legend.arg}{list of additional arguments to pass to \code{\link{legend}}; names of the list are used as argument names. Only used if \code{legend} is set to TRUE. If supplied legend position must be given (e.g. \code{legend.arg=list(x='bottomright')}.} 71 | 72 | \item{ylab}{a title for the y axis} 73 | 74 | \item{ymargin}{multiplier for the maximum value on ylim range. Default is 1.1.} 75 | 76 | \item{rnd}{integer indicating the number of decimal places to be displayed in the y-axis for when \code{type} is set "multitype".} 77 | 78 | \item{...}{Additional arguments affecting the plot.} 79 | } 80 | \description{ 81 | Visualises multiple SPDs grouped as a \code{stackCalSPD} object. 82 | } 83 | \details{ 84 | The display order of the SPDs is given by the factor levels of the user-supplied \code{group} argument in the \code{stackspd()} function. 85 | } 86 | \examples{ 87 | \dontrun{ 88 | data(emedyd) 89 | x = calibrate(x=emedyd$CRA, errors=emedyd$Error,normalised=FALSE) 90 | bins = binPrep(sites=emedyd$SiteName, ages=emedyd$CRA,h=100) 91 | res = stackspd(x=x,timeRange=c(16000,8000),bins=bins,group=emedyd$Region) 92 | plot(res,type='stacked') 93 | plot(res,type='lines') 94 | plot(res,type='proportion') 95 | plot(res,type='multipanel') 96 | } 97 | } 98 | \references{ 99 | Erich Neuwirth (2014). RColorBrewer: ColorBrewer Palettes. R package version 1.1-2. \url{https://CRAN.R-project.org/package=RColorBrewer}. 100 | } 101 | -------------------------------------------------------------------------------- /man/poolDates.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/aggregation.R 3 | \name{poolDates} 4 | \alias{poolDates} 5 | \title{Combine radiocarbon ages from the same event.} 6 | \usage{ 7 | poolDates(x, errors, id = NULL, F14C = TRUE) 8 | } 9 | \arguments{ 10 | \item{x}{A vector of uncalibrated radiocarbon ages} 11 | 12 | \item{errors}{A vector of standard deviations corresponding to each estimated radiocarbon age} 13 | 14 | \item{id}{A vector of event/object identifiers to be matched with radiocarbon ages. If not supplied all radiocarbon ages are assumed to be from the same event/object.} 15 | 16 | \item{F14C}{Whether calculations are carried out in F14C space or not. Default is TRUE.} 17 | } 18 | \value{ 19 | A data.frame containing the weighted radiocarbon ages and errors for each event and the associated T-values and P-values. 20 | } 21 | \description{ 22 | Computes a combined weighted mean and error and carries out a statistical test for internal consistency. 23 | } 24 | \details{ 25 | The function calculates combined weighted error mean and standard error for each set of radiocarbon ages associated with the same event or object and computes a significance test for evaluating internal consistency following Ward and Wilson's method (1978). This is equivalent to OxCal's R_Combine routine. 26 | } 27 | \examples{ 28 | x = c(4300,4330,5600,5603,5620) 29 | errors = c(20,30,30,30,45) 30 | id = c(1,1,2,2,2) 31 | poolDates(x,errors,id) 32 | } 33 | \references{ 34 | Ward, G. K., & Wilson, S. R. (1978). Procedures for Comparing and Combining Radiocarbon Age Determinations: A Critique. Archaeometry, 20(1), 19–31. https://doi.org/10.1111/j.1475-4754.1978.tb00208.x 35 | } 36 | -------------------------------------------------------------------------------- /man/qCal.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/calibration.R 3 | \name{qCal} 4 | \alias{qCal} 5 | \title{Computes the quantile date of calibrated dates} 6 | \usage{ 7 | qCal(x, p = 0.5) 8 | } 9 | \arguments{ 10 | \item{x}{A \code{CalDates} class object.} 11 | 12 | \item{p}{A numeric value of probability. Default is 0.5 (median).} 13 | } 14 | \value{ 15 | A vector of quantile dates in cal BP 16 | } 17 | \description{ 18 | Function for generating a vector quantile calibrated dates from a \code{CalDates} class object. 19 | } 20 | \examples{ 21 | x <- calibrate(c(3050,2950),c(20,20)) 22 | qCal(x,p=0.2) 23 | } 24 | \seealso{ 25 | \code{\link{calibrate}}, \code{\link{barCodes}} 26 | } 27 | -------------------------------------------------------------------------------- /man/rcarbon-deprecated.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/rcarbon-deprecated.R 3 | \name{rcarbon-deprecated} 4 | \alias{rcarbon-deprecated} 5 | \title{Deprecated functions.} 6 | \description{ 7 | The functions listed below are deprecated and will be defunct in 8 | the near future. When possible, alternative functions with similar 9 | functionality are also mentioned. Help pages for deprecated functions are 10 | available at \code{help("-deprecated")}. 11 | } 12 | \keyword{internal} 13 | -------------------------------------------------------------------------------- /man/rcarbon.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/package-rcarbon.R 3 | \docType{package} 4 | \name{rcarbon} 5 | \alias{rcarbon} 6 | \alias{rcarbon-package} 7 | \title{rcarbon:Calibration and analysis of radiocarbon dates} 8 | \description{ 9 | The \pkg{rcarbon} package handles the calibration and analysis of radiocarbon, often but not exclusively for the purposes of archaeological research. It includes functions not only for basic calibration, uncalibration and plotting of one or more dates, but also a statistical framework for building demographic and related longitudinal inferences from aggregate radiocarbon date lists. 10 | } 11 | \details{ 12 | Core functions in the \pkg{rcarbon} package can be grouped as follows: 13 | \describe{ 14 | \item{\strong{Calibration Functions}}{\code{\link{calibrate}} and \code{\link{uncalibrate}} enable the calibration and back-calibration for a variety of curves.} 15 | \item{\strong{Aggregation Functions}}{\code{\link{spd}} generates a summed probability distribution (SPD) of radiocarbon dates; \code{\link{binPrep}} can be used to define clusters of radiocarbon dates associated with the same context/phase} 16 | \item{\strong{Statistical Test Functions}}{\code{\link{modelTest}} compares the observed SPD against a variety of theoretical models (most typically an exponential curve) using the Monte-Carlo approach; \code{\link{p2pTest}} compares observed differences in SPD between two user-specified points in time against differences expected from a theoretical model; \code{\link{permTest}} compares two or more SPDs and test for the null hypothesis that all sets are derived from the same population; \code{\link{sptest}} identifies, for defined intervals, locations with significantly higher or lower growth rate in the SPD compared to the pan-regional trend in the data} 17 | } 18 | } 19 | \note{ 20 | Up-to-date development version, bug-reports, and further information concerning the \pkg{rcarbon} package can be found on GitHub (\url{https://github.com/ahb108/rcarbon}). 21 | To see the preferred citation for the package, type citation("rcarbon"). 22 | } 23 | \references{ 24 | See individual functions for references. 25 | } 26 | \author{ 27 | The \pkg{rcarbon} is developed and maintained by Andrew Bevan and Enrico Crema 28 | } 29 | -------------------------------------------------------------------------------- /man/reScale.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/utilities.R 3 | \name{reScale} 4 | \alias{reScale} 5 | \title{Rescale a numeric vector to a specified minimum and maximum} 6 | \usage{ 7 | reScale(x, type = "simple", to = c(0, 1), na.rm = TRUE) 8 | } 9 | \arguments{ 10 | \item{x}{numeric vector to smooth.} 11 | 12 | \item{type}{what kind of rescaling to perform. Current options are 'simple' (default) and 'normal' which produces a z-score and 'custom' for which the 'to' argument must be specified.} 13 | 14 | \item{to}{numeric vector of length 2 specifying the minimum and maximum value to perform a linear rescale between (default is 0 and 1)} 15 | 16 | \item{na.rm}{Set to TRUE,this removes NAs before rescaling.} 17 | } 18 | \value{ 19 | A numeric vector of rescaled values. 20 | } 21 | \description{ 22 | Rescale a numeric vector to a specified minimum and maximum. 23 | } 24 | \examples{ 25 | reScale(15:200) 26 | } 27 | -------------------------------------------------------------------------------- /man/runMean.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/utilities.R 3 | \name{runMean} 4 | \alias{runMean} 5 | \title{Calculate a running mean from a numeric vector.} 6 | \usage{ 7 | runMean(x, n, edge = "NA") 8 | } 9 | \arguments{ 10 | \item{x}{numeric vector to smooth.} 11 | 12 | \item{n}{the size of the window in which to smooth.} 13 | 14 | \item{edge}{How to treat edge cases where a full window is unavailable. Current options are 'NA' to fill with NAs or 'fill' to fill with original values} 15 | } 16 | \value{ 17 | A numeric vector of smoothed values. 18 | } 19 | \description{ 20 | Calculate a running mean from a numeric vector. 21 | } 22 | \examples{ 23 | x <- rnorm(1000) 24 | y <- c(1:1000) 25 | plot(y,x, type="l") 26 | lines(runMean(x,50), col="red") 27 | } 28 | -------------------------------------------------------------------------------- /man/sampleDates.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/utilities.R 3 | \name{sampleDates} 4 | \alias{sampleDates} 5 | \title{Sample random calendar dates} 6 | \usage{ 7 | sampleDates(x, bins = NA, nsim, boot = FALSE, verbose = TRUE) 8 | } 9 | \arguments{ 10 | \item{x}{A 'CalDates' class object.} 11 | 12 | \item{bins}{A vector containing the bin names associated with each radiocarbon date. If set to NA, binning is not carried out.} 13 | 14 | \item{nsim}{Number of sampling repetitions.} 15 | 16 | \item{boot}{A logical value indicating whether bootstrapping is carried out (see details below). Default is FALSE.} 17 | 18 | \item{verbose}{A logical variable indicating whether extra information on progress should be reported. Default is TRUE.} 19 | } 20 | \value{ 21 | An object of class \code{simdates} with the following elements 22 | \itemize{ 23 | \item{\code{sdates}} {A matrix containing the randomly sampled calendar dates, with rows containing each of the \code{nsim} repetitions.} 24 | \item{\code{weight}} {A vector (or matrix in when \code{boot=TRUE}) containing the total area under the curve of each date, normalised to sum to unity. Notice this will be identical for all dates if the calibration is carried out with the argument \code{normalised} set to TRUE.} 25 | } 26 | } 27 | \description{ 28 | Randomly samples calendar dates from each calibrated date or bin. 29 | } 30 | \details{ 31 | The function randomly samples calendar dates based from calibrated probability distributions. When the \code{bins} argument is supplied a single calendar date is sampled from each bin. When \code{boot=TRUE}, dates (or bins) are randomly sampled with replacement before calendar dates are sampled. 32 | } 33 | -------------------------------------------------------------------------------- /man/smoothGauss.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/utilities.R 3 | \name{smoothGauss} 4 | \alias{smoothGauss} 5 | \title{Smooth a numeric vector using a Gaussian window} 6 | \usage{ 7 | smoothGauss(x, alpha, window = 0.1) 8 | } 9 | \arguments{ 10 | \item{x}{numeric vector of values to smooth.} 11 | 12 | \item{alpha}{numeric value controlling the size of the gaussian smoothing window. Proportional to the standard deviation of the Gaussian smoothing kernel where sd=(N-1)/(2*alpha) with N being the length of the input vector.} 13 | 14 | \item{window}{a fraction between 0 and 1 representing the proportion of the input vector to include in the moving window.} 15 | } 16 | \description{ 17 | Smooth a numeric vector using a Gaussian window 18 | } 19 | \details{ 20 | Adapted from \code{smth.gaussian} in the \code{smoother} package. 21 | } 22 | \examples{ 23 | smoothGauss(runif(200),alpha=5) 24 | } 25 | \references{ 26 | Hamilton, N. (2015). smoother: Functions Relating to the Smoothing of Numerical Data, R package version 1.1, https://CRAN.R-project.org/package=smoother 27 | } 28 | -------------------------------------------------------------------------------- /man/spd.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/aggregation.R 3 | \name{spd} 4 | \alias{spd} 5 | \title{Summed probability distributions (SPD) of radiocarbon dates.} 6 | \usage{ 7 | spd( 8 | x, 9 | timeRange, 10 | bins = NA, 11 | datenormalised = FALSE, 12 | spdnormalised = FALSE, 13 | runm = NA, 14 | verbose = TRUE, 15 | edgeSize = 500 16 | ) 17 | } 18 | \arguments{ 19 | \item{x}{A \code{CalDates} class object containing the calibrated radiocarbon dates.} 20 | 21 | \item{timeRange}{A vector of length 2 indicating the start and end date of the analysis in cal BP.} 22 | 23 | \item{bins}{A vector containing the bin names associated with each radiocarbon date. If set to NA, binning is not carried out.} 24 | 25 | \item{datenormalised}{Controls for calibrated dates with probability mass outside the timerange of analysis. If set to TRUE the total probability mass within the time-span of analysis is normalised to sum to unity. Should be set to FALSE when the parameter \code{normalised} in \code{\link{calibrate}} is set to FALSE. Default is FALSE.} 26 | 27 | \item{spdnormalised}{A logical variable indicating whether the total probability mass of the SPD is normalised to sum to unity.} 28 | 29 | \item{runm}{A number indicating the window size of the moving average to smooth the SPD. If set to \code{NA} no moving average is applied. Default is NA} 30 | 31 | \item{verbose}{A logical variable indicating whether extra information on progress should be reported. Default is TRUE.} 32 | 33 | \item{edgeSize}{Extra margin in C14 Age time to handle edge effect when \code{datenormalise} is set to TRUE. Default is 500.} 34 | } 35 | \value{ 36 | An object of class \code{CalSPD} with the following elements 37 | \itemize{ 38 | \item{\code{metadata}} {A data.frame containing relevant information regarding the parameters used to create the SPD as well as sample size and number of bins} 39 | \item{\code{grid}} {A \code{CalGrid} class object containing the summed probability associated to each calendar year between \code{timeRange[1]} and \code{timeRange[2]}} 40 | } 41 | } 42 | \description{ 43 | The function generates Summed probability distributions (SPD) of radiocarbon dates, with optional binning routine for controlling inter-site or inter-phase variation in sampling intensity. 44 | } 45 | \details{ 46 | The binning routine consists of computing summed probability distribution of all dates associated to a given bin, divided by the number of contributing dates. This controls for any striking differences in sampling intensity, and ensures that each site phase is equally contributing to the final SPD (see Timpson et al 2014 for details). Bins can be generated using the \code{\link{binPrep}}, whilst the sensitivity to parameter choice can be explored with the \code{\link{binsense}} function. 47 | } 48 | \references{ 49 | Timpson, A., et al, (2014). Reconstructing regional population fluctuations in the European Neolithic using radiocarbon dates: a new case-study using an improved method. Journal of Archaeological Science 52: 549-557. DOI:10.1016/j.jas.2014.08.011 50 | } 51 | \seealso{ 52 | \code{\link{calibrate}} for calibrating radiocarbon dates; \code{\link{binPrep}} for preparing bins. 53 | } 54 | -------------------------------------------------------------------------------- /man/spd2rc.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/utilities.R 3 | \name{spd2rc} 4 | \alias{spd2rc} 5 | \title{Computes rates of change from SPDs} 6 | \usage{ 7 | spd2rc( 8 | spd, 9 | breaks = NULL, 10 | backsight = NULL, 11 | changexpr = expression((t1/t0)^(1/d) - 1) 12 | ) 13 | } 14 | \arguments{ 15 | \item{spd}{Summed Probability Distribution obtained using the \code{\link{spd}} function.} 16 | 17 | \item{breaks}{A vector giving the breakpoints between the time-blocks.} 18 | 19 | \item{backsight}{A single numeric value defining the distance in time between the focal year and the backsight year for computing the rate of change.} 20 | 21 | \item{changexpr}{An expression defining how the rate of change is calculated, where \code{t1} is the summed probability for a focal block or year, \code{t0} is the summed probability for previous block or backsight year, and \code{d} is the duration of the block or the length of the backsight. Default is a geometric growth rate (i.e \code{expression((t1/t0)^(1/d)-1)}).} 22 | } 23 | \value{ 24 | An object of class \code{spdRC}. 25 | } 26 | \description{ 27 | Function for computing rates of change between abutting user-defined time-blocks. 28 | } 29 | \details{ 30 | When the argument \code{breaks} is supplied the function aggregates the summed probability within each time-block and compared them across abutting blocks using the expression defined by \code{changexpr}. When the argument \code{backsight} is provided he expression is based on the comparison between the summed probability of each year and the associated backsight year. 31 | } 32 | \examples{ 33 | \dontrun{ 34 | data(emedyd) 35 | caldates <- calibrate(x=emedyd$CRA, errors=emedyd$Error, normalised=FALSE, calMatrix=TRUE) 36 | bins <- binPrep(sites=emedyd$SiteName, ages=emedyd$CRA, h=50) 37 | emedyd.spd <- spd(caldates,bins,timeRange=c(16000,9000),runm=100) 38 | emedyd.gg <- spd2rc(emedyd.spd,breaks=seq(16000,9000,-1000)) 39 | emedyd.gg2 <- spd2rc(emedyd.spd,backsight=10) 40 | plot(emedyd.gg) 41 | plot(emedyd.gg2) 42 | } 43 | } 44 | -------------------------------------------------------------------------------- /man/spkde.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/aggregation.R 3 | \name{spkde} 4 | \alias{spkde} 5 | \title{Map the spatial intensity of a set of radiocarbon dates for a given focal year.} 6 | \usage{ 7 | spkde( 8 | x, 9 | coords, 10 | sbw, 11 | focalyear, 12 | tbw, 13 | win, 14 | cellres, 15 | bins = NA, 16 | backsight = NA, 17 | nsim = NULL, 18 | maskthresh = 0, 19 | changexpr = expression((t1 - t0)/tk), 20 | raw = FALSE, 21 | spjitter = TRUE, 22 | amount = NULL, 23 | verbose = TRUE, 24 | ... 25 | ) 26 | } 27 | \arguments{ 28 | \item{x}{An object of class CalDates with calibrated radiocarbon ages.} 29 | 30 | \item{coords}{A two column matrix of geographical coordinates from a a projected coordinate system (no checks are made for this) and with the same number of rows as length(x).} 31 | 32 | \item{sbw}{A single numeric value for the spatial bandwidth to be applied around each raster cell, expressed as the standard deviation of a continuous Gaussian kernel (passed as the sigma argument to density.ppp()).} 33 | 34 | \item{focalyear}{A single numeric value for the focal year for the intensity map.} 35 | 36 | \item{tbw}{A single numeric value for the temporal bandwidth to be applied around each focal year, expressed as the standard deviation of a continuous Gaussian kernel.} 37 | 38 | \item{win}{The bounding polygon for the mapping (must be an object of class 'owin', see the spatstat package)} 39 | 40 | \item{cellres}{The cell or pixel resolution of the output raster maps.} 41 | 42 | \item{bins}{A vector of labels corresponding to site names, ids, bins or phases (same length as x)} 43 | 44 | \item{backsight}{A single numeric value (which will be coerced to be positive) that specifies a comparison timestep in the past for a mapping of temporal change.} 45 | 46 | \item{nsim}{How many bootstrap simulations to run (default is none).} 47 | 48 | \item{maskthresh}{A single numeric value for a lower-bound cut-off for all maps, based on a minimum required spatial intensity of all dates in x.} 49 | 50 | \item{changexpr}{An expression for calculating the change in spatial intensity between the focal year and a backsight year (as defined via the backsight argument). Available input options are t1 (the spatial intensity for the focal year), t0 (the spatial intensity for the backsight year) and tk (the overall spatial intensity for all dates irrespective of year), plus any other standard constants and mathematical operators. A sensible default is provided.} 51 | 52 | \item{raw}{Whether to output the raw simulations (if nsim is set) or just the summaries (the latter is default).} 53 | 54 | \item{spjitter}{Whether noise is applied to the spatial coordinates or not. Default is TRUE.} 55 | 56 | \item{amount}{Amount of jitter applied to the spatial coordinates when \code{spjitter=TRUE}. Default is d/5, where d is difference between the closest coordinates.} 57 | 58 | \item{verbose}{A logical variable indicating whether extra information on progress should be reported. Default is TRUE.} 59 | 60 | \item{...}{ignored or passed to internal functions.} 61 | } 62 | \value{ 63 | A list object of class spKde with the following elements: 64 | \itemize{ 65 | \item {A series of list items storing some of the input parameters such as the focal year, sbw, tbw, backsight, maskthresh.} 66 | \item{\code{nonfocal}} {An im object mapping the basic spatial intensity of all dates, without reference to a focal year.} 67 | \item{\code{focal}} {An im object mapping the spatial intensity of dates for the focal year (i.e. weighted by how much each dates probability distribution overlaps with a Gaussian kernel centred on the focal year with a standard deviation of tbw).} 68 | \item{\code{proportion}} {An im object mapping the proportional intensity of dates for the focal year (i.e. the focal surface divided by the nonfocal surface).} 69 | \item{\code{change}} {An im object mapping the amount of change between the intensity of dates for the focal year and a chosen backsight year (i.e. as defined by changexpr).} 70 | } 71 | } 72 | \description{ 73 | Function for mapping the spatial intensity of radiocarbon dates for a given geographical region and focal year. 74 | } 75 | \details{ 76 | This function is not really intended for general use, but rather as an internal function for stkde(). Most applications should use the latter, but spkde has been exported and made externally available, both because this function retains the result in memory (in contrast to stkde) and with a view to possible addition of bootstrap methods in the future. Some function arguments therefore remain experimental. The function computes timeslice maps of the spatio-temporal kernel intensity of radiocarbon dates across a geographic region for a specific focal year. The user specifies the arbitrary size of both the spatial and the temporal Gaussian kernels that will be used to summarise radiocarbon date intensity per grid cell. 77 | } 78 | \examples{ 79 | \dontrun{ 80 | ## Example for the focal year 5600 calBP (also with site binning), 81 | ## using a subset of English and Welsh dates from the Euroevol dataset 82 | data(ewdates) 83 | data(ewowin) 84 | x <- calibrate(x=ewdates$C14Age, errors=ewdates$C14SD, normalised=FALSE) 85 | bins1 <- binPrep(sites=ewdates$SiteID, ages=ewdates$C14Age, h=50) 86 | spkde1 <- spkde(x=x, coords=ewdates[,c("Eastings", "Northings")], win=ewowin, 87 | sbw=40000, cellres=2000, focalyear=5600, tbw=50, bins=bins1, backsight=200,amount=1) 88 | plot(spkde1$focal) 89 | plot(spkde1$proportion) 90 | } 91 | 92 | } 93 | -------------------------------------------------------------------------------- /man/sptest.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/tests.R 3 | \name{sptest} 4 | \alias{sptest} 5 | \title{Spatial Permutation Test of summed probability distributions.} 6 | \usage{ 7 | sptest( 8 | calDates, 9 | timeRange, 10 | bins, 11 | locations, 12 | locations.id.col = NULL, 13 | breaks, 14 | h, 15 | kernel = "gaussian", 16 | rate = expression((t2/t1)^(1/d) - 1), 17 | nsim = 1000, 18 | runm = NA, 19 | permute = "locations", 20 | ncores = 1, 21 | datenormalised = FALSE, 22 | verbose = TRUE, 23 | raw = FALSE 24 | ) 25 | } 26 | \arguments{ 27 | \item{calDates}{A \code{CalDates} class object.} 28 | 29 | \item{timeRange}{A vector of length 2 indicating the start and end date of the analysis in cal BP} 30 | 31 | \item{bins}{A vector indicating which bin each radiocarbon date is assigned to. Must have the same length as the number of radiocarbon dates. Can be created using the \code{\link{binPrep}}) function. Bin names should follow the format "x_y", where x refers to a unique location (e.g. a site) and y is a integer value (e.g. "S023_1", "S023_2","S034_1", etc.).} 32 | 33 | \item{locations}{A \code{sf} class object of the site locations.} 34 | 35 | \item{locations.id.col}{Column name containing the first part of the supplied bin names. If missing rownames are used.} 36 | 37 | \item{breaks}{A vector of break points for defining the temporal slices.} 38 | 39 | \item{h}{distance parameter for calculating spatial weights.} 40 | 41 | \item{kernel}{indicates the type of weighting function, either 'fixed' or 'gaussian'. When set to "fixed" weight is equal to 1 within a radius of \code{h} km from each focal sie, and 0 outside this range. When set "gaussian" the weight declines with an exponential rate equal to exp(-d^2/h^2), where the d is the distance to the focal site. Default is "gaussian".} 42 | 43 | \item{rate}{An expression defining how the rate of change is calculated, where \code{t1} is the summed probability for a focal block, \code{t2} is the summed probability for next block, and \code{d} is the duration of the blocks. Default is a geometric growth rate (i.e \code{expression((t2/t1)^(1/d)-1)}).} 44 | 45 | \item{nsim}{The total number of simulations. Default is 1000.} 46 | 47 | \item{runm}{The window size of the moving window average. Must be set to \code{NA} if the rates of change are calculated from the raw SPDs.} 48 | 49 | \item{permute}{Indicates whether the permutations should be based on the \code{"bins"} or the \code{"locations"}. Default is \code{"locations"}.} 50 | 51 | \item{ncores}{Number of cores used for for parallel execution. Default is 1.} 52 | 53 | \item{datenormalised}{A logical variable indicating whether the probability mass of each date within \code{timeRange} is equal to 1. Default is FALSE.} 54 | 55 | \item{verbose}{A logical variable indicating whether extra information on progress should be reported. Default is TRUE.} 56 | 57 | \item{raw}{A logical variable indicating whether permuted sets of geometric growth rates for each location should be returned. Default is FALSE.} 58 | } 59 | \value{ 60 | A \code{spatialTest} class object 61 | } 62 | \description{ 63 | This function carries out local spatial permutation tests of summed radiocarbon probability distributions in order to detect local deviations in growth rates (Crema et al 2017). 64 | } 65 | \details{ 66 | The function consists of the following seven steps: 1) generate a weight matrix based on inter-site distance; 2) for each location (e.g. a site) generate a local SPD of radiocarbon dates, weighting the contribution of dates from neighbouring sites using a weight scheme computed in step 1; 3) define temporal slices (using \code{breaks} as break values), then compute the total probability mass within each slice; 4) compute the rate of change between abutting temporal slices by using the formula: \eqn{(SPD_{t}/SPD_{t+1}^{1/\Delta t}-1)}; 5) randomise the location of individual bins or the entire sequence of bins associated with a given location and carry out steps 2 to 4; 6) repeat step 5 \code{nsim} times and generate, for each location, a distribution of growth rates under the null hypothesis (i.e. spatial independence); 7) compare, for each location, the observed growth rate with the distribution under the null hypothesis and compute the p-values; and 8) compute the false-discovery rate for each location. 67 | } 68 | \examples{ 69 | ## Reproduce Crema et al 2017 ## 70 | \dontrun{ 71 | data(euroevol) #load data 72 | 73 | ## Subset only for ca 8000 to 5000 Cal BP (7500-4000 14C Age) 74 | euroevol2=subset(euroevol,C14Age<=7500&C14Age>=4000) 75 | 76 | ## define chronological breaks 77 | breaks=seq(8000,5000,-500) 78 | 79 | ## Create a sf class object 80 | library(sf) 81 | sites.df = unique(data.frame(SiteID=euroevol2$SiteID, 82 | Longitude=euroevol2$Longitude,Latitude=euroevol2$Latitude)) 83 | sites.sf = st_as_sf(sites.df,coords=c('Longitude','Latitude'),crs=4326) 84 | 85 | ## Calibration and binning 86 | bins=binPrep(sites=euroevol2$SiteID,ages=euroevol2$C14Age,h=200) 87 | calDates=calibrate(x=euroevol2$C14Age,errors=euroevol2$C14SD,normalised=FALSE) 88 | 89 | ## Main Analysis (over 2 cores; requires doSnow package) 90 | ## NOTE: the number of simulations should be ideally larger 91 | ## to ensure more accurate and precise estimates of the p/q-values. 92 | res.locations=sptest(calDates,timeRange=c(8000,5000),bins=bins, 93 | locations=sites.sf,locations.id.col="SiteID",h=100,breaks=breaks,ncores=2,nsim=100, 94 | permute="locations",datenormalised=FALSE) 95 | 96 | ## Plot results 97 | library(rnaturalearth) 98 | win <- ne_countries(continent = 'europe',scale=10,returnclass='sf') 99 | #retrieve coordinate limits 100 | xrange <- st_bbox(sites.sf)[c(1,3)] 101 | yrange <- st_bbox(sites.sf)[c(2,4)] 102 | 103 | par(mfrow=c(1,2)) 104 | par(mar=c(0.1,0.1,0,0.5)) 105 | plot(sf::st_geometry(win),col="antiquewhite3",border="antiquewhite3",xlim=xrange,ylim=yrange) 106 | plot(res.locations,index=4,add=TRUE,legend=TRUE,option="raw",breakRange=c(-0.005,0.005)) 107 | plot(sf::st_geometry(win),col="antiquewhite3",border="antiquewhite3",xlim=xrange,ylim=yrange) 108 | plot(res.locations,index=4,add=TRUE,legend=TRUE,option="test") 109 | } 110 | } 111 | \references{ 112 | Crema, E.R., Bevan, A., Shennan, S. (2017). Spatio-temporal approaches to archaeological radiocarbon dates. Journal of Archaeological Science, 87, 1-9. 113 | } 114 | \seealso{ 115 | \code{\link{permTest}} for a non-spatial permutation test; \code{\link{plot.spatialTest}} for plotting; \code{\link{spd2rc}} for computing geometric growth rates. 116 | } 117 | -------------------------------------------------------------------------------- /man/stackspd.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/aggregation.R 3 | \name{stackspd} 4 | \alias{stackspd} 5 | \title{Stacked Summed Probability Distribution} 6 | \usage{ 7 | stackspd( 8 | x, 9 | timeRange, 10 | bins = NA, 11 | group = NULL, 12 | datenormalised = FALSE, 13 | runm = NA, 14 | verbose = TRUE, 15 | edgeSize = 500 16 | ) 17 | } 18 | \arguments{ 19 | \item{x}{A \code{CalDates} class object containing the calibrated radiocarbon dates.} 20 | 21 | \item{timeRange}{A vector of length 2 indicating the start and end date of the analysis in cal BP.} 22 | 23 | \item{bins}{A vector containing the bin names associated with each radiocarbon date. If set to NA, binning is not carried out.} 24 | 25 | \item{group}{A character or factor vector containing the grouping variable.} 26 | 27 | \item{datenormalised}{Controls for calibrated dates with probability mass outside the timerange of analysis. If set to TRUE the total probability mass within the time-span of analysis is normalised to sum to unity. Should be set to FALSE when the parameter \code{normalised} in \code{\link{calibrate}} is set to FALSE. Default is FALSE.} 28 | 29 | \item{runm}{A number indicating the window size of the moving average to smooth the SPD. If set to \code{NA} no moving average is applied. Default is NA} 30 | 31 | \item{verbose}{A logical variable indicating whether extra information on progress should be reported. Default is TRUE.} 32 | 33 | \item{edgeSize}{Controls edge effect by expanding the fitted model beyond the range defined by \code{timeRange}.} 34 | } 35 | \value{ 36 | An object of class \code{stackCalSPD} 37 | } 38 | \description{ 39 | Generates and combines multiple SPDs based on a user defined grouping. 40 | } 41 | \examples{ 42 | \dontrun{ 43 | data(emedyd) 44 | x = calibrate(x=emedyd$CRA, errors=emedyd$Error,normalised=FALSE) 45 | bins = binPrep(sites=emedyd$SiteName, ages=emedyd$CRA,h=50) 46 | res = stackspd(x=x,timeRange=c(16000,8000),bins=bins,group=emedyd$Region) 47 | } 48 | } 49 | -------------------------------------------------------------------------------- /man/stkde.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/aggregation.R 3 | \name{stkde} 4 | \alias{stkde} 5 | \title{Map the spatio-temporal intensity of a set of radiocarbon dates} 6 | \usage{ 7 | stkde( 8 | x, 9 | coords, 10 | sbw, 11 | focalyears, 12 | tbw, 13 | win, 14 | cellres, 15 | outdir = ".", 16 | bins = NA, 17 | backsight = NA, 18 | maskthresh = 0, 19 | changexpr = expression((t1 - t0)/tk), 20 | spjitter = TRUE, 21 | amount = NULL, 22 | verbose = TRUE, 23 | ... 24 | ) 25 | } 26 | \arguments{ 27 | \item{x}{An object of class CalDates with calibrated radiocarbon ages.} 28 | 29 | \item{coords}{A two column matrix of geographical coordinates from a a projected coordinate system (no checks are made for this) and with the same number of rows as length(x).} 30 | 31 | \item{sbw}{A single numeric value for the spatial bandwidth to be applied around each raster cell, expressed as the standard deviation of a continuous Gaussian kernel (passed as the sigma argument to density.ppp()).} 32 | 33 | \item{focalyears}{A vector of numeric values for focal years, in calBP, that will be timesteps at which date intensity maps will be produced.} 34 | 35 | \item{tbw}{A single numeric value for the temporal bandwidth to be applied around each focal year, expressed as the standard deviation of a continuous Gaussian kernel.} 36 | 37 | \item{win}{The bounding polygon for the mapping (must be an object of class 'owin', see the spatstat package)} 38 | 39 | \item{cellres}{The cell or pixel resolution of the output raster maps.} 40 | 41 | \item{outdir}{The output directory for timeslice maps and data that are saved to file.} 42 | 43 | \item{bins}{A vector of labels corresponding to site names, ids, bins or phases (same length as x)} 44 | 45 | \item{backsight}{A single numeric value (which will be coerced to be positive) that specifies a comparison timestep in the past for a mapping of temporal change.} 46 | 47 | \item{maskthresh}{A single numeric value for a lower-bound cut-off for all maps, based on a minimum required spatial intensity of all dates in x.} 48 | 49 | \item{changexpr}{An expression for calculating the change in spatial intensity between the focal year and a backsight year (as defined via the backsight argument). Available input options are t1 (the spatial intensity for the focal year), t0 (the spatial intensity for the backsight year) and tk (the overall spatial intensity for all dates irrespective of year), plus any other standard constants and mathematical operators. A sensible default is provided.} 50 | 51 | \item{spjitter}{Whether noise is applied to the spatial coordinates or not. Default is TRUE.} 52 | 53 | \item{amount}{Amount of jitter applied to the spatial coordinates when \code{spjitter=TRUE}. Default is d/5, where d is difference between the closest coordinates.} 54 | 55 | \item{verbose}{A logical variable indicating whether extra information on progress should be reported. Default is TRUE.} 56 | 57 | \item{...}{ignored or passed to internal functions.} 58 | } 59 | \value{ 60 | A list object of class stKde with the following elements: 61 | \itemize{ 62 | \item {A series of list items storing some of the input parameters such as the focalyears, sbw, tbw, backsight, maskthresh} 63 | \item{\code{nonfocal}} {An im object mapping the basic spatial intensity of all dates, without reference to a focal year.} 64 | \item{\code{impaths}} {A character vector of the paths to the individual timeslices stored on file. Maps are not stored in memory (see spkde() for further details of what is stored).} 65 | \item{\code{stats}} {A list of data.frames offering summary statistics on each of the different types of output surface across all timeslices. Used primarily to allow consistent colour ramps across time-slices.} 66 | \item{\code{ppp}} {The ppp object for all dates and the observation window.} 67 | } 68 | } 69 | \description{ 70 | Function for mapping the spatio-temporal intensity of radiocarbon dates for a given geographical region in one or more tim. 71 | } 72 | \details{ 73 | This function computes one or more timeslice maps of the spatio-temporal kernel intensity of radiocarbon dates across a geographic region and for a specific focal year. The user specifies the arbitrary sizes of both the spatial and the temporal Gaussian kernels that will be used to summarise radiocarbon date intensity per grid cell per timestep. The results allow standardisation of colour ramps, etc. across timesteps and are amenable to plotting individually via plot.stKde and/or for output to png for animation. 74 | } 75 | \examples{ 76 | \dontrun{ 77 | ## Example with a subset of English and Welsh dates from the Euroevol dataset 78 | data(ewdates) 79 | data(ewowin) 80 | x <- calibrate(x=ewdates$C14Age, errors=ewdates$C14SD, normalised=FALSE) 81 | ## Create centennial timeslices (also with site binning) 82 | bins1 <- binPrep(sites=ewdates$SiteID, ages=ewdates$C14Age, h=50) 83 | stkde1 <- stkde(x=x, coords=ewdates[,c("Eastings", "Northings")], win=ewowin, 84 | sbw=40000, cellres=2000, focalyears=seq(6500, 5000, -100), tbw=50, bins=bins1, 85 | backsight=200, outdir="im",amount=1) 86 | ## Plot an example of all four basic outputs for 5900 calBP 87 | dev.new(height=2.5, width=8) 88 | par(mar=c(0.5, 0.5, 2.5, 2)) 89 | plot(stkde1, 5900, type="all") 90 | } 91 | 92 | } 93 | -------------------------------------------------------------------------------- /man/subset.CalDates.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/utilities.R 3 | \name{subset.CalDates} 4 | \alias{subset.CalDates} 5 | \title{Subsetting calibrated dates} 6 | \usage{ 7 | \method{subset}{CalDates}(x, s, p, ...) 8 | } 9 | \arguments{ 10 | \item{x}{A CalDates class object} 11 | 12 | \item{s}{Logical expression indicating dates to keep. The expression should include the term \code{BP} which refers to specific dates.} 13 | 14 | \item{p}{Probability mass meeting the condition defined by \code{ss}.} 15 | 16 | \item{...}{Further arguments to be passed to or from other methods (ignored).} 17 | } 18 | \value{ 19 | A CalDates class object. 20 | } 21 | \description{ 22 | Subsets calibrated dates (\code{CalDates} class object) based on Logical expressions of time intervals. 23 | } 24 | \details{ 25 | The function subsets \code{CalDates} class objects by identifying all dates that have a probability mass larger than \code{p} for a user defined logical expression of temporal interval containing the term \code{BP}, where \code{BP} refers to radiocarbon date. See examples for further detailes 26 | } 27 | \examples{ 28 | ## Generate some calibrated dates 29 | x = calibrate(c(12100,5410,5320,3320),errors=c(20,20,30,30)) 30 | ## Subsets all dates that have a probability mass above 0.8 before 10000 BP 31 | x2 = subset(x,BP>10000,p=0.8) 32 | ## Subsets all dates that have a probability mass above 0.5 between 6000 and 6300 BP 33 | x3 = subset(x,BP>6000&BP<6300,p=0.5) 34 | } 35 | -------------------------------------------------------------------------------- /man/summary.CalDates.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/calibration.R 3 | \name{summary.CalDates} 4 | \alias{summary.CalDates} 5 | \title{Summarise a \code{CalDates} class object} 6 | \usage{ 7 | \method{summary}{CalDates}(object, prob = NA, calendar = "BP", ...) 8 | } 9 | \arguments{ 10 | \item{object}{A \code{CalDates} class object.} 11 | 12 | \item{prob}{A vector containing probabilities for the higher posterior density interval. Default is \code{c(0.683,0.954)}, i.e. 1 and 2-Sigma range.} 13 | 14 | \item{calendar}{Whether the summary statistics should be computed in cal BP (\code{"BP"}) or in BCAD (\code{"BCAD"}).} 15 | 16 | \item{...}{further arguments passed to or from other methods.} 17 | } 18 | \value{ 19 | A \code{data.frame} class object containing the ID of each date, along with the median date and one and two sigma (or a user specified probability) higher posterior density ranges. 20 | } 21 | \description{ 22 | Returns summary statistics of calibrated dates. 23 | } 24 | -------------------------------------------------------------------------------- /man/summary.SpdModelTest.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/tests.R 3 | \name{summary.SpdModelTest} 4 | \alias{summary.SpdModelTest} 5 | \title{Summarise a \code{SpdModelTest} class object} 6 | \usage{ 7 | \method{summary}{SpdModelTest}(object, type = "spd", ...) 8 | } 9 | \arguments{ 10 | \item{object}{A \code{SpdModelTest} class object produced using the \code{link{modelTest}} function.} 11 | 12 | \item{type}{Specifies whether the summary should be based on SPD ('spd') or associated rates of change ('roc'). Default is 'spd'.} 13 | 14 | \item{...}{Ignored} 15 | } 16 | \description{ 17 | \code{summary} method for class "\code{SpdModelTest}" 18 | } 19 | \details{ 20 | The summary function returns metadata (number of radiocarbon dates, bins, and simulations), the p-value of the global significance test, and the chronological interval of local positive and negative deviations from the simulation envelope. 21 | } 22 | \seealso{ 23 | \code{\link{modelTest}}. 24 | } 25 | -------------------------------------------------------------------------------- /man/summary.SpdPermTest.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/tests.R 3 | \name{summary.SpdPermTest} 4 | \alias{summary.SpdPermTest} 5 | \title{Summarise a \code{SpdPermTest} class object} 6 | \usage{ 7 | \method{summary}{SpdPermTest}(object, type = "spd", ...) 8 | } 9 | \arguments{ 10 | \item{object}{A \code{SpdPermTest} class object produced using the \code{link{permTest}} function.} 11 | 12 | \item{type}{Specifies whether the summary should be based on SPD ('spd') or associated rates of change ('roc'). Default is 'spd'.} 13 | 14 | \item{...}{Ignored} 15 | } 16 | \description{ 17 | \code{summary} method for class "\code{SpdPermTest}" 18 | } 19 | \details{ 20 | The summary function returns metadata (number of radiocarbon dates, bins, and simulations), the p-value of the global significance test, and the chronological interval of local positive and negative deviations from the simulation envelope for each set. 21 | } 22 | \seealso{ 23 | \code{\link{permTest}}. 24 | } 25 | -------------------------------------------------------------------------------- /man/thinDates.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/aggregation.R 3 | \name{thinDates} 4 | \alias{thinDates} 5 | \title{Sampling function to select a maximum number of dates per site, bin or phase.} 6 | \usage{ 7 | thinDates(ages, errors, bins, size, thresh = 0.5, method = "random", seed = NA) 8 | } 9 | \arguments{ 10 | \item{ages}{A vector of uncalibrated radiocarbon ages} 11 | 12 | \item{errors}{A vector of uncalibrated radiocarbon errors (same length as ages)} 13 | 14 | \item{bins}{A vector of labels corresponding to site names, ids, bins or phases (same length as ages)} 15 | 16 | \item{size}{A single integer specifying the maximum number of desired dates for each label stated bin.} 17 | 18 | \item{thresh}{A single numeric value between 0 and 1 specifying the approximate proportion (after rounding) of the resulting sample that will be chosen according to lowest date errors. At the extremes, O produces a simple random sample whereas 1 selects the sample dates with the lowest errors. Ignored if method="random".} 19 | 20 | \item{method}{The method to be applied where "random" simple selects a random sample, whereas "splitsample", picks some proportion (see thresh) of the sample to minimise errors, and randomly samples the rest. At present, these are the only two options.} 21 | 22 | \item{seed}{Allows setting of a random seed to ensure reproducibility.} 23 | } 24 | \value{ 25 | A numeric vector of the row indices corresponding to those of the input data. 26 | } 27 | \description{ 28 | Function to select a subset of uncalibrated radiocarbon dates up to a maximum sample size per site, bin or phase. 29 | } 30 | \examples{ 31 | data(euroevol) 32 | foursites <- euroevol[euroevol$SiteID \%in\% c("S2072","S4380","S6139","S9222"),] 33 | table(as.character(foursites$SiteID)) 34 | ## Thin so each site has 10 dates each max, with random selection 35 | thinInds<- thinDates(ages=foursites$C14Age, errors=foursites$C14SD, 36 | bins=foursites$SiteID, size=10, method="random", seed=123) 37 | tdates <- foursites[thinInds,] 38 | tdates 39 | ## Same but choose the first 60\% (i.e. 6 dates) from the lowest errors 40 | ## and then fill in the rest randomly. 41 | thinInds<- thinDates(ages=foursites$C14Age, errors=foursites$C14SD, 42 | bins=foursites$SiteID, size=10, method="splitsample", thresh=0.6, seed=123) 43 | tdates1 <- foursites[thinInds,] 44 | tdates1 45 | } 46 | \seealso{ 47 | \code{\link{binPrep}} 48 | } 49 | -------------------------------------------------------------------------------- /man/transformSPD.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/utilities.R 3 | \name{transformSPD} 4 | \alias{transformSPD} 5 | \title{Apply taphonomic corrections or other transformations to an SPD.} 6 | \usage{ 7 | transformSPD( 8 | x, 9 | correction = expression(PrDens/(5.726442 * 10^6 * (CalBP + 2176.4)^-1.3925309)) 10 | ) 11 | } 12 | \arguments{ 13 | \item{x}{An object of class \code{CalSPD}, \code{compositeKDE} or \code{stackCalSPD}.} 14 | 15 | \item{correction}{An expression for transforming the SPD. Available input terms include: CalBP, the vector of \code{calBP} year within the time range; and \code{PrDens}, a matching vector of summed probability. The default expression is the taphonomic correction formula proposed by Surovell et al 2009.} 16 | } 17 | \value{ 18 | An object of the same class as x 19 | } 20 | \description{ 21 | Apply taphonomic corrections or other transformations to an SPD. 22 | } 23 | \examples{ 24 | 25 | \dontrun{ 26 | data(emedyd) 27 | region1 = subset(emedyd,Region==1) 28 | x = calibrate(x=region1$CRA, errors=region1$Error,normalised=FALSE) 29 | bins = binPrep(sites=region1$SiteName, ages=region1$CRA,h=50) 30 | region1.spd = spd(x=x,bins=bins,timeRange=c(16000,8000)) 31 | region1.spd.corrected = transformSPD(region1.spd) 32 | } 33 | } 34 | \references{ 35 | Surovell, T.A., Finley, J.B., Smith, G.M., Brantingham, P.J., Kelly, R., 2009. Correcting temporal frequency distributions for taphonomic bias. Journal of Archaeological Science 36, 1715–1724. 36 | } 37 | -------------------------------------------------------------------------------- /man/uncalibrate.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/calibration.R 3 | \name{uncalibrate} 4 | \alias{uncalibrate} 5 | \alias{uncalibrate.default} 6 | \alias{uncalibrate.CalGrid} 7 | \title{Uncalibrate (back-calibrate) a calibrated radiocarbon date (or summed probability distribution).} 8 | \usage{ 9 | uncalibrate(x, ...) 10 | 11 | \method{uncalibrate}{default}(x, CRAerrors = 0, roundyear = TRUE, calCurves = "intcal20", ...) 12 | 13 | \method{uncalibrate}{CalGrid}( 14 | x, 15 | calCurves = "intcal20", 16 | eps = 1e-05, 17 | compact = TRUE, 18 | verbose = TRUE, 19 | ... 20 | ) 21 | } 22 | \arguments{ 23 | \item{x}{Either a vector of calibrated radiocarbon ages or an object of class CalGrid.} 24 | 25 | \item{...}{ignored} 26 | 27 | \item{CRAerrors}{A vector of standard deviations corresponding to each estimated radiocarbon age (ignored if x is a CalGrid object).} 28 | 29 | \item{roundyear}{Whether the randomised estimate is rounded or not. Default is TRUE.} 30 | 31 | \item{calCurves}{A string naming a calibration curve already provided with the rcarbon package (currently 'intcal20','intcal13','intcal13nhpine16','shcal20','shcal13','shcal13shkauri16',''marine13','marine20' and 'normal') or a custom curve provided as matrix/data.frame in three columns ("CALBP","C14BP","Error"). The default is the 'intcal20' curve and only one curve can currently be specified for all dates.} 32 | 33 | \item{eps}{Cut-off value for density calculation (for CalGrid objects only).} 34 | 35 | \item{compact}{A logical variable indicating whether only uncalibrated ages with non-zero probabilities should be returned (for CalGrid objects only).} 36 | 37 | \item{verbose}{A logical variable indicating whether extra information on progress should be reported (for CalGrid objects only).} 38 | } 39 | \value{ 40 | A data.frame with specifying the original data, the uncalibrated age without the calibration curve error (ccCRA), the calibration curve error at this point in the curve (ccError), a randomised uncalibrated age (rCRA) given both the stated ccError and any further hypothesised instrumental error provided by the CRAerrors argument (rError). 41 | } 42 | \description{ 43 | Function for uncalibrating one or more radiocarbon dates. 44 | } 45 | \details{ 46 | This function takes one or more calibrated calendars and looks-up the corresponding uncalibrated age, error of the stated calibration curve at that point. It also provides a randomised estimate of the uncalibrate age based on the curve error (and optionally also a hypothetical measurement error. 47 | } 48 | \examples{ 49 | # Uncalibrate two calendar dates 50 | uncalibrate(c(3050,2950)) 51 | } 52 | -------------------------------------------------------------------------------- /man/which.CalDates.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/utilities.R 3 | \name{which.CalDates} 4 | \alias{which.CalDates} 5 | \title{Which indices for calibrated dates} 6 | \usage{ 7 | which.CalDates(x, s, p) 8 | } 9 | \arguments{ 10 | \item{x}{A CalDates class object} 11 | 12 | \item{s}{Logical expression indicating dates to keep. The expression should include the term \code{BP} which refers to specific dates.} 13 | 14 | \item{p}{Probability mass meeting the condition defined by \code{ss}.} 15 | } 16 | \value{ 17 | A CalDates class object. 18 | } 19 | \description{ 20 | Gives the TRUE indices of calibrated dates (\code{CalDates} class object) based on Logical expressions of time intervals. 21 | } 22 | \details{ 23 | The function subsets \code{CalDates} class objects by identifying all dates that have a probability mass larger than \code{p} for a user defined logical expression of temporal interval containing the term \code{BP}, where \code{BP} refers to radiocarbon date. See examples for further detailes 24 | } 25 | \examples{ 26 | ## Generate some calibrated dates 27 | x = calibrate(c(12100,5410,5320,3320),errors=c(20,20,30,30)) 28 | ## Subsets all dates that have a probability mass above 0.8 before 10000 BP 29 | x2 = which.CalDates(x,BP>10000,p=0.8) 30 | ## Subsets all dates that have a probability mass above 0.5 between 6000 and 6300 BP 31 | x3 = which.CalDates(x,BP>6000&BP<6300,p=0.5) 32 | } 33 | --------------------------------------------------------------------------------