update documentation

R/data.R

@@ -9,5 +9,5 @@
 #'   \item{identifier}{The name of a building in Miletus.}
 #'   \item{period.start, period.end}{The earliest and latest period each building is dated to.}
 #' }
-#' @source <https://geoserver.dainst.org/catalogue/#/map/5764>
+#' @source <https://geoserver.dainst.org/catalogue/uuid/53438148-30d1-11ec-9582-0242ac140004>
 "BuildingsMilet"

R/duplicate_by.R

@@ -1,6 +1,11 @@
 #' Duplicate each Row for each Period in the Range from start to end
 #'
-#'
+#' For each period one object may be placed in according to the range
+#' provided by the `start` and `end` columns of the data.frame `data`, the
+#' associated row is duplicated as many times as possible periods the objects
+#' might be placed in according to the concordance object supplied to
+#' `conc` ([make_chrongler_conc()]). This way, each objects is
+#' represented by multiple rows in the result!
 #'
 #'
 #' @inheritParams group_periods

R/from_chronontology.R

@@ -27,6 +27,9 @@ dl_chrnt_json <- function(id = "") {
 
 #' Get Data for One Period from iDAI.chronontology
 #'
+#' Downloads one specific dataset from
+#' [iDAI.chronontology](https://chronontology.dainst.org/).
+#'
 #' @inheritParams dl_chrnt_json
 #'
 #' @source data: [iDAI.chronontology](https://chronontology.dainst.org/)
@@ -42,6 +45,7 @@ dl_chrnt_json <- function(id = "") {
 from_chronontology <- function(id = "") {
   res <- dl_chrnt_json(id = id)
   # todo ;)
+  # some formatting may (or may not) be helpful // maybe make optional via an argument
 
   return(res)
 }

R/query_chronontology.R

@@ -1,11 +1,19 @@
 #' Basic Query for iDAI.chronontology
 #'
-#'
+#' This function searches all iDAI.chronontology periods for the string
+#' supplied as 'value'. It always gets all available results.
+#' No further filtering or more specific querying is implemented (yet).
 #'
 #' @param value (chr) The value you want to search for in all chronontology-periods.
 #'
 #' @return A list of results as handed out by iDAI.chronontology.
 #'
+#' @source
+#'  * data: [iDAI.chronontology](https://chronontology.dainst.org/)
+#'  * api: [chronontology REST API reference](https://github.com/dainst/chronontology-backend/blob/master/docs/rest-api-reference.md)
+#'
+#' @seealso [from_chronontology()]
+#'
 #' @export
 #'
 #' @examples

README.md

@@ -1,28 +1,30 @@
-
 <!-- badges: start -->
-[![R-CMD-check](https://github.com/lsteinmann/chrongler/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/lsteinmann/chrongler/actions/workflows/R-CMD-check.yaml)
-[![Codecov test coverage](https://codecov.io/gh/lsteinmann/chrongler/branch/main/graph/badge.svg)](https://codecov.io/gh/lsteinmann/chrongler?branch=main)
+
+[![R-CMD-check](https://github.com/lsteinmann/chrongler/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/lsteinmann/chrongler/actions/workflows/R-CMD-check.yaml) [![Codecov test coverage](https://codecov.io/gh/lsteinmann/chrongler/branch/main/graph/badge.svg)](https://codecov.io/gh/lsteinmann/chrongler?branch=main)
+
 <!-- badges: end -->
 
-# chrongler wrangles categorical chronological data
+# *chrongler* wrangles categorical chronological data
 
-This package provides convenience functions that are helpful for working with archaeological or historical data, where chronological information is stored as a 'period' (categorical values that may indicate chronology in one way or another). The functions are purely for formatting and 'wrangling' such data, and do not contain any means of analysis or further processing. 
+This package provides convenience functions that are helpful for working with archaeological or historical data, where chronological information is stored as a 'period' (categorical values that may indicate chronology in one way or another). The functions are purely for formatting and 'wrangling' such data, and do not contain any means of analysis or further processing.
 
 # Installation
 
-chrongler is not on CRAN. You can install the current version from GitHub using: 
+*chrongler* is not (yet?) on CRAN. You can install the current version from GitHub using:
+
 ``` r
 remotes::install_github("lsteinmann/chrongler", build_vignettes = TRUE)
 ```
 
 # Scope
-Using chrongler (and a concordance of periods and their grouping and absolute dating made with `make_chrongler_conc()`) you can easily: 
 
-* group and un-group the categorical dating of objects (`group_periods()`, `ungroup_periods()`)
-* duplicate rows of objects according to their periods or groups (`duplicate_by()`)
-* add absolute dating based on the periods an object is dated to (`derive_dating()`)
-* add the period an object would be dated to based on absolute dating values (`derive_period()`)
-* download the data for one period from [iDAI.chronontology](https://chronontology.dainst.org/) (`from_chronontology()`, it's a bit of a work in progress...)
+Using *chrongler* (and a concordance of periods and their grouping and absolute dating made with `make_chrongler_conc()`) you can easily:
+
+-   group and un-group the categorical dating of objects (`group_periods()`, `ungroup_periods()`)
+-   duplicate rows of objects according to their periods or groups (`duplicate_by()`)
+-   add absolute dating based on the periods an object is dated to (`derive_dating()`)
+-   add the period an object would be dated to based on absolute dating values (`derive_period()`)
+-   download the data for one period from [iDAI.chronontology](https://chronontology.dainst.org/) (`from_chronontology()`, it's a bit of a work in progress...)
 
 The inaccurately named "example_workflow"-vignette explains the functions and especially setting up the concordance in detail, see:
 
@@ -31,6 +33,5 @@ browseVignettes("chrongler")
 ```
 
 # why
-I made it mainly for myself to avoid redundancies in various other projects and have the process a bit more organized. You may notice that it is very much tailored to data imported from [Field Desktop](https://github.com/dainst/idai-field) via [idaifieldR](https://github.com/lsteinmann/idaifieldR).
-
 
+I made it mainly for myself to avoid redundancies in various other projects and have the process a bit more organized. There is significant overlap with the way that data imported from [Field Desktop](https://github.com/dainst/idai-field) via [idaifieldR](https://github.com/lsteinmann/idaifieldR) is formatted, since this is my main use case. Of course, *chrongler* can be used with data gathered elsewhere as well, as long as you keep to the formats described in the vignette.

vignettes/example_workflow.Rmd

@@ -40,6 +40,12 @@ We will get the dates and values for our examples manually from [iDAI.chronontol
 ```{r eval = FALSE}
 from_chronontology(id = "RX2Rv7kcbLGk")
 ```
+Or by getting multiple results with a very simple and basic query that cannot do much (yet), and selecting the ones which fit:
+
+```{r eval = FALSE}
+query_chronontology(value = "roman")
+```
+
 
 This will give you a nested list with the data you can see on the page, including relations to other periods. It would be possible to automatically import a group of periods this way, but I have not implemented it, because the data can be rather heterogeneous. In any case, we will proceed to enter everything manually in this vignette.