Merge pull request #9 from lsteinmann/packagedoc

lsteinmann · web-flow · commit 624094f183b1 · 2021-01-17T00:23:06.000+01:00
documentation, corrections
diff --git a/.Rbuildignore b/.Rbuildignore
@@ -2,3 +2,5 @@
 ^\.Rproj\.user$
 ^\.github$
 ^data-raw$
+^\.travis\.yml$
+^codecov\.yml$
diff --git a/.travis.yml b/.travis.yml
@@ -4,8 +4,7 @@ language: R
 cache: packages
 
 
-r_packages:
-  - covr
-
-after_success:
-  - Rscript -e 'library(covr); codecov()'
+addons:
+  apt:
+    packages:
+      - libgit2-dev
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -21,5 +21,5 @@ Suggests:
     reshape2,
     covr
 Depends: 
-    R (>= 2.10)
+    R (>= 3.3)
 VignetteBuilder: knitr
diff --git a/R/datplot_utility.R b/R/datplot_utility.R
@@ -196,9 +196,9 @@ create.sub.objects <- function(DAT_mat, stepsize) {
   result <- as.data.frame(matrix(ncol = 6, nrow = outputrows+100))
 
   diffs <- DAT_mat[,"datmax"]-DAT_mat[,"datmin"]
+  diffs[diffs == 0] <- 1
 
   if (any(diffs < stepsize)) {
-    diffs <- diffs[diffs < stepsize]
     warning(paste("stepsize is larger than the range of the closest dated object at Index = ",
                 paste(which(diffs < stepsize), collapse = ", "), "). For information see documentation of get.step.sequence().", sep = ""))
   }
diff --git a/README.md b/README.md
@@ -11,31 +11,32 @@ Converting date ranges into dating 'steps' eases the visualization of changes in
 
 A rather common problem in archaeology is the fuzzyness of dates assigned to objects. If one wants to visualize overall changes in - let's say - pottery consumption, bar charts often fall short in that regard. If, e.g., the Phases a -- f are employed, then some of the objects can usually be dated to a, c, and f, as an example, but others will by classified as "a to c" or "b to c". But how can these data still be used for examining changes in a large set of objects without completely disregarding the information added by providing multiple phases for one object?
 
-This package proposes a method to prepare archaeological data for the visualization using density plots. An example is shown in /vignettes/. Density plots are easy to understand and are usually aesthetically pleasing. They do omit a some information, such as individual counts, that bar histograms can communicate better. On the other hand, ranges can be incorporated into the visualization as well to regard the variety of timespans archaeological objects may be dated to.
+This package proposes implements the concepts of aoristic analysis to prepare archaeological data for the visualization using density plots. An example is shown in the vignettes, which can be found at
 
-I imagine this to be mostly useful for surveys and other analysis aimed at the longue duree. 
+    browseVignettes("datplot")
+
+after installing the package, or on GitHub in the /vignettes/ directory. Density plots are easy to understand and are usually aesthetically pleasing. They do omit a some information, such as individual counts, that bar histograms can communicate better. On the other hand, ranges can be incorporated into the visualization as well to regard the variety of timespans archaeological objects may be dated to.
+
+I imagine this to be mostly useful for surveys and other analysis aimed at the longue duree. The package has been published along with a case study on the Inscriptions of Bithynia, which are now included as a Data object in the datplot-package itself, in (citation). 
 
 ![Attic Pottery from BAPD by Date](inst/extdata/demo_readme.png "Attic Pottery from BAPD by Date")
 
-Installation 
--------
-'datplot' can be installed from GitHub directly with devtools:
 
-    devtools::install_github("lsteinmann/datplot")
 
 Recommendation
 -------
-People interested in employing this method should also consider taking a look at [ISAAKiel's package aoristAAR](https://github.com/ISAAKiel/aoristAAR/). 
+People interested in employing this method should also consider taking a look at [ISAAKiel's package aoristAAR](https://github.com/ISAAKiel/aoristAAR/), or at [archSeries](github.com/davidcorton/archSeries), [tabula](github.com/nfrerebeau/tabula/) and [rtefact](github.com/ahb108/rtefact). 
+
 
 Installation 
 -------
-'datplot' can be installed from GitHub directly with devtools:
+'datplot' is not currently on CRAN. It can be installed from GitHub with devtools:
 
     devtools::install_github("lsteinmann/datplot")
 
-Recommendation
--------
-People interested in employing this method should also consider taking a look at [ISAAKiel's package aoristAAR](https://github.com/ISAAKiel/aoristAAR/). 
+Or via downloading the latest release and installing from the file: 
+
+    install_local(path = "../datplot_0.2.4.tar.gz")
 
 Contact
 -------
diff --git a/data-raw/Inscr_Bithynia.R b/data-raw/Inscr_Bithynia.R
@@ -129,12 +129,17 @@ join_dating <- rbind(join_dating, num_dating[!is.na(num_dating$DAT_min),])
 num_dating <- num_dating[which(is.na(num_dating$DAT_min)),]
 unique(num_dating$Dating)[1:20]
 
+join_dating$DAT_min[which(join_dating$DAT_min == 0)] <- 1
+join_dating$DAT_max[which(join_dating$DAT_max == 0)] <- -1
+
+
 #write.csv(num_dating, file = "num_dating.csv", fileEncoding = "UTF-8")
 num_dating <- read.csv(file = system.file('extdata', 'num_dating_edit.csv', package = 'datplot', mustWork = TRUE),
                        encoding = "UTF-8",
                        row.names = 1,
                        colClasses = c("character", "character", "integer", "integer"))
 
+
 join_dating <- join_dating %>%
   mutate(DAT_min = as.integer(DAT_min),
          DAT_max = as.integer(DAT_max)) %>%
@@ -174,4 +179,7 @@ attr(inscriptions$DAT_max, "descr") <- "uppper border of the dating timespan"
 
 Inscr_Bithynia <- inscriptions
 
+#inscriptions[which(inscriptions$DAT_min == 0),c(1,2,4,5,8,9)]
+#inscriptions[which(inscriptions$DAT_max == 0),c(1,2,4,5,8,9)]
+
 usethis::use_data(Inscr_Bithynia, overwrite = TRUE)
diff --git a/data/Inscr_Bithynia.rda b/data/Inscr_Bithynia.rda
diff --git a/inst/extdata/num_dating_edit.csv b/inst/extdata/num_dating_edit.csv
@@ -2,23 +2,23 @@
 1,end of the 2nd c. AD,180,199
 2,end of 1st c. BC – beg. of 1st c. AD,-20,20
 3,end 2nd c. BC,-120,-100
-4,early 1st c. AD,0,20
-7,after 212 AD,212,250
+4,early 1st c. AD,1,20
+7,after 212 AD,212,222
 8,AD 531,531,531
 10,5th/6th century AD,400,599
 14,3rd/4th century AD,200,399
 19,2nd – 3rd c. AD,100,299
-20,2nd – 1st c. BC,-199,0
-27,1st – beg. of the 2nd c. AD,0,120
-28,1st – 2nd c. AD,0,199
+20,2nd – 1st c. BC,-199,-1
+27,1st – beg. of the 2nd c. AD,1,120
+28,1st – 2nd c. AD,1,199
 35,2nd century AD,100,199
 38,late 3rd – early 2nd c. BC,-220,-180
 43,5th – 6th c. AD,400,599
 50,3rd quarter of the 6th c. BC,-550,-525
 51,3rd – 2nd c. BC,-299,-100
 52,340/339 BC,-340,-339
 54,27 BC–14 AD,-27,14
-56,1st century AD,0,99
+56,1st century AD,1,99
 57,1st c. BC – 1st c. AD,-99,99
 60,middle 2nd c. AD,140,160
 61,end of the 3rd c. AD,280,299
@@ -33,19 +33,19 @@
 84,end of the 2nd - end of the 4th century AD,180,380
 87,2nd century BC,-199,-100
 88,2nd century AD ,100,199
-89,1st/2nd century AD,0,199
+89,1st/2nd century AD,1,199
 92,mid. 2nd c. AD,140,160
 93,mid. 1st c. AD,40,60
 94,late 2nd c. AD,180,199
 95,end of the 1st c. AD,80,99
 96,AD 123,123,123
-100,1st - 3rd century AD,0,299
+100,1st - 3rd century AD,1,299
 102,2nd/3rd century AD or 4th - 5th century AD ,100,499
 104,mid. 3rd c. AD,240,260
 105,late 3rd century AD,280,299
 106,late 2nd century AD,180,199
 107,end of the 2nd/beg. of the 3rd century AD,180,220
-108,after 98 AD,98,120
+108,after 98 AD,98,108
 111,AD 209,209,209
 113,6th century AD,500,599
 114,5th - 6th century AD,400,599
@@ -58,18 +58,18 @@
 147,beg. of the 3rd c. AD,200,220
 148,beg. of the 2nd c. AD,100,120
 149,after ca. 70–79 AD,70,79
-150,after 128 AD,128,150
+150,after 128 AD,128,138
 152,AD 243/244,243,244
 154,97/98–98/99 AD,97,99
 158,5th/4th century BC,-499,-300
 160,4th – 5th c. AD,300,499
 168,2nd/3rd century AD ,100,299
 169,2nd half of the 2nd c. AD,150,199
 170,2nd – 3rd C. AD,100,299
-183,1st century BC,-99,0
+183,1st century BC,-99,-1
 200,102–114,102,114
 201,early 3rd century AD,200,220
-203,after 138 AD,138,150
+203,after 138 AD,138,148
 207,3rd/4th century AD (or later),200,450
 208,3rd or 4th century AD,200,399
 209,3rd c. AD or before,180,299
@@ -80,21 +80,21 @@
 234,122/123–126/127 AD,122,127
 237,early 3rd c. AD,200,220
 238,ca. 2nd century AD,100,199
-239,before 212 AD,200,212
-240,before 211 AD,200,211
-241,after 202 AD,202,250
+239,before 212 AD,202,212
+240,before 211 AD,201,211
+241,after 202 AD,202,212
 259,mid – end of 3rd c. AD,240,299
 263,281 or 190 BC,-281,-190
 270,AD 288/289,288,289
 271,mid – end of 2nd c. AD,140,199
 272,late 2nd century AD ,180,199
 273,end of the 2nd – 3rd c. AD,180,299
 274,beg. of the 2nd c. BC,-200,-180
-275,"after 171 BC, ca. 188 BC",-188,-171
+275,"after 171 BC, ca. 188 BC",-188,-161
 279,7th century AD,600,699
 281,5th – 6th C AD,400,599
 283,4th – 6th c. AD,300,599
 284,3rd c. AD (after 211 AD),211,299
-285,1st – early 2nd c. AD,0,120
+285,1st – early 2nd c. AD,1,120
 288,123–131/132 AD,123,132
 289,AD 140,140,140
diff --git a/inst/extdata/periods_edit.csv b/inst/extdata/periods_edit.csv
@@ -12,7 +12,7 @@
 11,Hellenistic period,-336,-74
 12,Early Roman period,-74,-31
 13,Chr.–Byz.,100,799
-14,AD,0,799
+14,AD,1,799
 15,Christian,300,799
 16,Antonine or Severan,96,235
 17,Roman period,-74,395
diff --git a/inst/extdata/periods_edit_AD.csv b/inst/extdata/periods_edit_AD.csv
@@ -1,6 +1,6 @@
 ,Dating,DAT_min,DAT_max
-1,Roman Imp. period,0,395
-6,Early/Middle Roman Imp. p.,0,192
-7,Early Roman Imp. period,0,69
-10,Roman Imperial period,0,395
-26,Roman Imp. period ,0,395
+1,Roman Imp. period,1,395
+6,Early/Middle Roman Imp. p.,1,192
+7,Early Roman Imp. period,1,69
+10,Roman Imperial period,1,395
+26,Roman Imp. period ,1,395
diff --git a/inst/literatur.bib b/inst/literatur.bib
@@ -42,5 +42,47 @@ @article{weissova_HinterlandNikaiaNicaea_2019
 }
 
 
+@article{ratcliffe_Aoristicanalysisspatial_2000,
+  title = {Aoristic analysis: the spatial interpretation of unspecific temporal events},
+  shorttitle = {Aoristic analysis},
+  author = {Ratcliffe, Jerry H.},
+  date = {2000-10},
+  journaltitle = {International Journal of Geographical Information Science},
+  volume = {14},
+  pages = {669--679},
+  doi = {10.1080/136588100424963},
+  number = {7}
+}
+
+
+
+@article{orton_CatchUnitResearch_2017,
+  title = {Catch Per Unit Research Effort: Sampling Intensity, Chronological Uncertainty, and the Onset of Marine Fish Consumption in Historic London},
+  shorttitle = {Catch Per Unit Research Effort},
+  author = {Orton, David and Morris, James and Pipe, Alan},
+  date = {2017-01-20},
+  journaltitle = {Open Quaternary},
+  volume = {3},
+  pages = {1},
+  doi = {10.5334/oq.29}
+}
+
+@incollection{johnson_AoristicAnalysisSeeds_2004,
+  ids = {:unknunknown\_AoristicAnalysisSeeds\_2004},
+  title = {Aoristic Analysis: Seeds of a New Approach to Mapping Archaeological Distributions through Time},
+  booktitle = {2003 - Enter the Past. The E-way into the four Dimensions of Cultural Heritage. CAA 2003. Computer Applications and Quantitative Methods in Archaeology},
+  author = {Johnson, I.},
+  editor = {B\"orner, W. and Goriany, M.},
+  date = {2004},
+  publisher = {Archaeopress},
+  location = {Oxford},
+  url = {https://publikationen.uni-tuebingen.de/xmlui/handle/10900/60663}
+}
+
+
+
+
+
+
 
 @Comment{jabref-meta: databaseType:bibtex;}
diff --git a/tests/testthat/test-datplot_utility.R b/tests/testthat/test-datplot_utility.R
@@ -73,3 +73,23 @@ test_that("check.structure issues warning", {
   expect_warning(check.structure(testdf), regexp = "recommended")
 })
 
+
+testdf <- create.testing.df()
+testdf[,3] <- sample(-200:0, nrow(testdf))
+testdf[,4] <- sample(1:200, nrow(testdf))
+testdf[1,3:4] <- c(4,4)
+
+DAT_mat <- matrix(ncol = 5, nrow = nrow(testdf))
+DAT_mat[,1] <- 1:nrow(testdf)
+DAT_mat[,2] <- testdf[,3]
+DAT_mat[,3] <- testdf[,4]
+colnames(DAT_mat) <- c("index", "datmin", "datmax", "weight", "step")
+
+test_that("create.sub.objects issues no warning", {
+  expect_failure(expect_warning(create.sub.objects(DAT_mat, stepsize = 1),
+                                regexp = "stepsize is larger"))
+  expect_warning(create.sub.objects(DAT_mat, stepsize = 5),
+                 regexp = "stepsize is larger")
+})
+
+
diff --git a/tests/testthat/test-datsteps.R b/tests/testthat/test-datsteps.R
@@ -14,3 +14,13 @@ test_that("error for wrong value of stepsize", {
   expect_warning(datsteps(DAT_df), regexp = "wrong order")
 
 })
+
+testdf <- create.testing.df()
+testdf[,3] <- sample(-200:0, nrow(testdf))
+testdf[,4] <- sample(1:200, nrow(testdf))
+testdf[1,3:4] <- c(4,4)
+
+test_that("error for wrong value of stepsize", {
+  expect_warning(datsteps(testdf), regexp = "the same value")
+  expect_failure(expect_warning(datsteps(testdf, stepsize = 1), regexp = "larger than the range of the closest"))
+})
diff --git a/vignettes/data_preparation.Rmd b/vignettes/data_preparation.Rmd
@@ -248,7 +248,7 @@ num_dating <- num_dating[which(is.na(num_dating$DAT_min)),]
 
 ### Reformatting of Imprecise Dating Values
 
-For dates that are around a certain value, i.e. of the format "ca. 190 AD", we decided to take a total span of 20 years, i.e. 10 years before and 10 years after the mentioned value. "ca. 190 AD" thus becomes "180--200 AD", with the same mechanism for BC in negative values.
+For dates that are around a certain value, i.e. of the format "ca. 190 AD", we are not able to make a more informed decision than guess about what the researchers providing this assessment had in mind. This might also change from inscription to inscription. While a closer look at the individual inscriptions may yield a more sensible estimate, this seems not feasible as part of the data preparation process. It seems that in most cases, if the dating can be as precise as a span of around 10 years, researchers tend to emphasize this. Therefore we decided to take a total span of 20 years, i.e. 10 years before and 10 years after the mentioned value, reflecting some uncertainty on the precision and duration of the estimate. "ca. 190 AD" thus becomes "180--200 AD", with the same mechanism for BC in negative values.
 
 
 ```{r }
@@ -281,7 +281,13 @@ num_dating <- num_dating[which(is.na(num_dating$DAT_min)),]
 unique(num_dating$Dating)[1:20]
 ```
 
-Due to the heterogeneous nature of these `r nrow(num_dating)` values, we decided to convert them manually again. Our criteria for translating terms like "beginning of" are the following: "beginning of", "end of", "early", "late" all translate to 20 years, as we assume that more information would have been given if the time span was greater than a quarter century. For the other values, we employed the same criteria as seen above in the automated process. For another transformation used later on we decided to treat e.g. -199 / 100 as the beginning of century, and e.g. -100 / 199 as the end of the century and did so accordingly in the manual assignment. 
+Due to the heterogeneous nature of these `r nrow(num_dating)` values, we decided to convert them manually again. Our criteria for translating terms like "beginning of" are the following: "beginning of", "end of", "early", "late" are -- similarly to ca. -- all translated to 20 years, as we assume that more information would have been given if the time span was greater than a quarter century. For the other values, we employed the same criteria as seen above in the automated process. For another transformation used later on we decided to treat e.g. -199 / 100 as the beginning of century, and e.g. -100 / 199 as the end of the century and did so accordingly in the manual assignment. Since the data is epigraphical, in the case of "before" or "after" (i.e. terminus ante/post quem) dates, we assume some connection to a datable event, and therefore add or subtract a span of 10 years, which is, however, still rather arbitrary. 
+
+As a last step, we switch the in some cases automatically assigned year 0, so that it will be treated as either 1 oder -1:
+```{r}
+join_dating$DAT_min[which(join_dating$DAT_min == 0)] <- 1
+join_dating$DAT_max[which(join_dating$DAT_max == 0)] <- -1
+```
 
 We then have to reload the corrected data. The values that we put aside in the `join_dating` `data.frame` beforehand serve as the basis for our new `data.frame` that we use as a look-up table. As the variables were treated as character-strings, we need to convert them to a numeric format first. We append the newly loaded manually assigned values to this data.frame. Again, to keep this process as transparent as possible, we included the *.csv-Table in the "data/prep/" subfolder as "num_dating_edit.csv".
 
@@ -292,7 +298,6 @@ num_dating <- read.csv(file = system.file('extdata', 'num_dating_edit.csv',
                        encoding = "UTF-8",
                        row.names = 1, 
                        colClasses = c("character", "character", "integer", "integer"))
-
 join_dating <- join_dating %>% 
   mutate(DAT_min = as.integer(DAT_min),
          DAT_max = as.integer(DAT_max)) %>%
@@ -318,7 +323,8 @@ knitr::kable(na.omit(inscriptions)[sample(1:nrow(na.omit(inscriptions)), 15),c(6
 
 We can now make a 'test run' using datplot with the stepsize-value set to 5 in order to save as much time as possible[^3] and check for errors first. We have to select exactly 4 columns in the correct order of: Identifier, Grouping Variable, Minimum Dating, Maximum Dating. We transform the output from the pipe operator to a `data.frame` before handing it to `datstepts()`, as **datplot** needs this format.
 
-[^3]: Using different stepsizes is a bit of an artifact left over from a less efficient version of datplot, where is processing would take more than a minute if stepsize was set to 1, so I would usually start out with 100 or 25 just to look for errors and problems. This, however, is technically not necessary anymore as the function now works fast enough.
+
+[^3]: Using different stepsizes is a bit of an artifact left over from a less efficient version of datplot, where is processing would take more than a minute if stepsize was set to 1, so I would usually start out with 100 or 25 just to look for errors and problems and to not lose much time. This, however, is technically not necessary in any way. The function now works faster, though there is a lot of room for improvement, as it may still take several seconds or longer, but generally not several minutes. We determined that the feature might still be useful, and therefore it was not removed.
 
 ```{r warning = TRUE, message = TRUE, out.lines = 20}
 #inscriptions$
@@ -350,9 +356,9 @@ inscriptions[which(inscriptions$ID == "I_2725"),c("DAT_min", "DAT_max")] <-
 
 Note that `datsteps()` changes the date and proceeds, but warns you of the possibility of errors. It is therefore recommended to check the data mentioned in that warning. As we 'fixed' out data set, we should save it again, so that the same error will not occur twice:
 
-```{r }
-write.table(inscriptions, file = "../data-raw/inscriptions.csv", 
-            fileEncoding = "UTF-8", sep = ";", row.names = FALSE)
+```{r eval = FALSE}
+#write.table(inscriptions, file = "../data-raw/inscriptions.csv", 
+#            fileEncoding = "UTF-8", sep = ";", row.names = FALSE)
 ```
 
 
@@ -388,20 +394,13 @@ summary(inscr_clean)
 
 # datplot
 
-We can now begin using the **datplot**-package. Since `datplot` is not on CRAN, it is necessary to either install it from our github repository directly or download the source file and install it. For this, R needs the `devtools`-package to be installed.
+We can now begin using the **datplot**-package... 
 
 ```{r eval = FALSE}
-library(devtools)
-# either
-install_github("lsteinmann/datplot") # (redacted)
-# or 
-install_local(path = "../datplot_0.1.0.tar.gz")
+library(datplot)
 ```
 
-
-# The Output of `datsteps()`
-
-Now we can actually try to use `datsteps()`, first with a `stepsize` of 25 years[^3]:
+...and can actually try to use `datsteps()`, first with a `stepsize` of 25 years[^3]:
 
 ```{r warning=TRUE, out.lines = 13}
 inscr_steps <- inscr_clean %>% 
diff --git a/vignettes/how-to.Rmd b/vignettes/how-to.Rmd

Original file line number	Diff line number	Diff line change
`@@ -196,9 +196,9 @@ create.sub.objects <- function(DAT_mat, stepsize) {`
`196`	`196`	`result <- as.data.frame(matrix(ncol = 6, nrow = outputrows+100))`
`197`	`197`
`198`	`198`	`diffs <- DAT_mat[,"datmax"]-DAT_mat[,"datmin"]`
	`199`	`+ diffs[diffs == 0] <- 1`
`199`	`200`
`200`	`201`	`if (any(diffs < stepsize)) {`
`201`		`- diffs <- diffs[diffs < stepsize]`
`202`	`202`	`warning(paste("stepsize is larger than the range of the closest dated object at Index = ",`
`203`	`203`	`paste(which(diffs < stepsize), collapse = ", "), "). For information see documentation of get.step.sequence().", sep = ""))`
`204`	`204`	`}`