From 6bdd9ae15e617dee9929a77820f3eb23c774e347 Mon Sep 17 00:00:00 2001 From: Lisa Steinmann Date: Sun, 1 Sep 2024 13:57:02 +0200 Subject: [PATCH] update documentation --- R/data.R | 2 +- R/duplicate_by.R | 7 ++++++- R/from_chronontology.R | 4 ++++ R/query_chronontology.R | 10 +++++++++- README.md | 29 +++++++++++++++-------------- man/BuildingsMilet.Rd | 2 +- man/duplicate_by.Rd | 7 ++++++- man/from_chronontology.Rd | 3 ++- man/query_chronontology.Rd | 13 ++++++++++++- vignettes/example_workflow.Rmd | 6 ++++++ 10 files changed, 62 insertions(+), 21 deletions(-) diff --git a/R/data.R b/R/data.R index 780e1c5..ed80531 100644 --- a/R/data.R +++ b/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 +#' @source "BuildingsMilet" diff --git a/R/duplicate_by.R b/R/duplicate_by.R index f308267..22bad7b 100644 --- a/R/duplicate_by.R +++ b/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 diff --git a/R/from_chronontology.R b/R/from_chronontology.R index bc0873c..6b0465f 100644 --- a/R/from_chronontology.R +++ b/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) } diff --git a/R/query_chronontology.R b/R/query_chronontology.R index d0f469e..e8789ae 100644 --- a/R/query_chronontology.R +++ b/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 diff --git a/README.md b/README.md index 6de5e42..d902e01 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,30 @@ - -[![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) + -# 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. diff --git a/man/BuildingsMilet.Rd b/man/BuildingsMilet.Rd index c26ca5e..254b562 100644 --- a/man/BuildingsMilet.Rd +++ b/man/BuildingsMilet.Rd @@ -15,7 +15,7 @@ A data frame with 110 rows and 3 columns: } } \source{ -\url{https://geoserver.dainst.org/catalogue/#/map/5764} +\url{https://geoserver.dainst.org/catalogue/uuid/53438148-30d1-11ec-9582-0242ac140004} } \usage{ BuildingsMilet diff --git a/man/duplicate_by.Rd b/man/duplicate_by.Rd index 2e5194c..8971453 100644 --- a/man/duplicate_by.Rd +++ b/man/duplicate_by.Rd @@ -29,7 +29,12 @@ A data.frame, with a row for each period in which each row from the previous data would fall (see description). } \description{ -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 \code{start} and \code{end} columns of the data.frame \code{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 +\code{conc} (\code{\link[=make_chrongler_conc]{make_chrongler_conc()}}). This way, each objects is +represented by multiple rows in the result! } \examples{ data("BuildingsMilet") diff --git a/man/from_chronontology.Rd b/man/from_chronontology.Rd index 14d6870..4074422 100644 --- a/man/from_chronontology.Rd +++ b/man/from_chronontology.Rd @@ -19,7 +19,8 @@ A nested list with the data for one period downloaded from iDAI.chronontology. } \description{ -Get Data for One Period from iDAI.chronontology +Downloads one specific dataset from +\href{https://chronontology.dainst.org/}{iDAI.chronontology}. } \examples{ geometric <- from_chronontology("AqUgeWHp0xIl") diff --git a/man/query_chronontology.Rd b/man/query_chronontology.Rd index f7dce51..08fd736 100644 --- a/man/query_chronontology.Rd +++ b/man/query_chronontology.Rd @@ -3,6 +3,12 @@ \name{query_chronontology} \alias{query_chronontology} \title{Basic Query for iDAI.chronontology} +\source{ +\itemize{ +\item data: \href{https://chronontology.dainst.org/}{iDAI.chronontology} +\item api: \href{https://github.com/dainst/chronontology-backend/blob/master/docs/rest-api-reference.md}{chronontology REST API reference} +} +} \usage{ query_chronontology(value = "roman") } @@ -13,9 +19,14 @@ query_chronontology(value = "roman") A list of results as handed out by iDAI.chronontology. } \description{ -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). } \examples{ roman_periods <- query_chronontology(value = "roman") names <- unlist(lapply(roman_periods, function(x) x$resource$names$en)) } +\seealso{ +\code{\link[=from_chronontology]{from_chronontology()}} +} diff --git a/vignettes/example_workflow.Rmd b/vignettes/example_workflow.Rmd index 2793fa5..8ca760a 100644 --- a/vignettes/example_workflow.Rmd +++ b/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.