How to use roadDB
The use of roadDB can be summarised as follows:
- Functions starting with
road_get_*define the structure and content of the output table. - Arguments are optional and allow you to refine your queries using filters.
- Helper functions assist in writing more effective and accurate queries.
road_get_* functions
The road_get_* functions are used to query data from the
ROAD server. They support three Levels of Detail (LOD),
which determine the granularity of the returned data frame. Accordingly,
each row (or observation) in the output will represent
a locality, an assemblage, or a
specific object, depending on the selected level of
detail (see fig. 1)
Figure 1: Three levels of detail determine the granularity of the data frame.
Since ROAD contains extensive information at the assemblage level—and because different types of assemblages may include diverse and sometimes unique sets of columns (or variables)—additional subordinate functions are provided to handle these cases.
A large number of these functions are specifically related to archaeological content. The available functions include:
- LOD 1: Locality level
road_get_localities()
- LOD 2: Assemblage level
road_get_assemblages()road_get_human_remains()road_get_paleofauna()road_get_plantremains()road_get_lithic_typologies()road_get_lithic_raw_materials()road_get_organic_tools()road_get_symbolic_artifacts()road_get_features()road_get_miscellaneous_finds()
- LOD 3: Object level
road_get_dates()road_get_publications()
Arguments
Arguments allow you to refine the queries made through the
road_get_* functions. They are optional—if no arguments are
provided, the query returns all available information from ROAD.
In practice, however, most research questions require more focused data. You can tailor your query to your needs by filtering, for example, by continent or cultural_period.
Arguments can also be combined, and you may supply a single value or a list of values.
# Single argument
road_get_localities(cultural_period="MSA")
# Multiple arguments
road_get_localities(cultural_period="MSA", country="South Africa")
# Lists of arguments
road_get_localities(cultural_period=c("MSA","LSA"), country=c("South Africa","Namibia"))The package provides two sets of arguments:
First, the general arguments (tab. 1) which are
available for all road_get_* functions. These arguments
provide flexible ways to filter and refine your queries.
And second, the function-specific arguments (tab.
2), which are only available for certain road_get_*
functions. These arguments refine queries in ways that are unique to the
corresponding function. Some of them use exact search terms,
whereas others use fuzzy search. Figure 2 gives a compact
overview over all possible combinations of functions and arguments:
Figure 2: All possible combinations of functions and arguments. Click here for a PDF version.
Table 1: General arguments are available for all
road_get_* functions.
| Argument | Type | Example |
|---|---|---|
continent |
character | “Africa” |
subcontinent |
character | “Southern Africa” |
country |
character | “South Africa” |
locality_type |
character | “rock shelter” |
category |
character | “symbolic artifacts, typology” |
age_min |
numeric | 20000 |
age_max |
numeric | 3000000 |
technocomplex |
character | “ESA/ Early Acheulean” |
cultural_period |
character | “Middle Stone Age” |
Table 2: Function-specific arguments are available
for certain road_get_* functions.
| Argument | Type | Search Type | Example(s) |
|---|---|---|---|
tool_list |
character | contains | “bladelet” |
raw_material_list |
character | contains | “ironstone banded” |
transport_distance |
character | exact | “regional (6–20 km)” |
organic_tool_interpretation |
character | contains | “retoucher” |
symbolic_artifact_interpretation |
character | contains | “anthropomorphic” |
feature_interpretation |
character | exact | “stone construction” |
miscellaneous_find_material |
character | exact | “ostrich egg shell” |
human_genus |
character | exact | “Homo” |
human_species |
character | exact | “sapiens” |
plant_remains |
character | exact | “phytoliths” |
plant_family |
character | exact | “Anarcadiaceae” |
plant_genus |
character | exact | “Jasione” |
plant_species |
character | exact | “Potamogeton gramineus L.” |
fauna_genus |
character | exact | “Lemniscomys” |
fauna_species |
character | exact | “atapuerquensis” |
localities |
dataframe | exact | Output from road_get_localities() |
assemblages |
dataframe | exact | Output from road_get_assemblages() |
Helper functions
help()
Each function in ROAD comes with detailed documentation, accessible through the standard help() function in R. The documentation describes what the function does, the arguments it accepts, the columns it returns, and how to interpret them.
road_list_argument_values()
If you are unsure which values are valid for a given argument, use
road_list_argument_values().
For instance, you might not know how specific cultural periods are spelled in ROAD, or which human genera are available. This helper function returns all unique values for the specified argument, allowing you to explore available options before constructing your query.
road_summarize_archaeology()
When working with archaeological data, it can be helpful to summarise content across multiple road_get_* functions. For example, you may want to identify all datasets containing the term “egg shell”.
The summary table shows which road_get_* functions include the term, and in which columns it appears. This allows you to refine and target your queries more effectively.
#> term road_get_ attribute hit_number
#> 1 egg shell miscellaneous_finds material 96
#> 2 egg shell symbolic_artifacts material 92
#> 3 egg shell symbolic_artifacts comments 3
#> 4 egg shell miscellaneous_finds comments 1
