Modify row(s) of a taxonomic database

Modify one or more rows in a taxonomic database in Darwin Core (DwC) format.

Usage

dct_modify_row(
  tax_dat,
  taxonID = NULL,
  scientificName = NULL,
  taxonomicStatus = NULL,
  acceptedNameUsageID = NULL,
  acceptedNameUsage = NULL,
  clear_usage_id = dct_options()$clear_usage_id,
  clear_usage_name = dct_options()$clear_usage_name,
  fill_usage_name = dct_options()$fill_usage_name,
  remap_names = dct_options()$remap_names,
  remap_variant = dct_options()$remap_variant,
  stamp_modified = dct_options()$stamp_modified,
  strict = dct_options()$strict,
  quiet = dct_options()$quiet,
  args_tbl = NULL,
  ...
)

Arguments

tax_dat: Dataframe; taxonomic database in DwC format.
taxonID: Character or numeric vector of length 1; taxonID of the row to be modified (the selected row).
scientificName: Character vector of length 1; scientificName of the row to be modified if taxonID is NULL, OR the scientificName to assign to the selected row if taxonID is provided (see Details).
taxonomicStatus: Character vector of length 1; taxonomicStatus to assign to the selected row.
acceptedNameUsageID: Character or numeric vector of length 1; acceptedNameUsageID to assign to the selected row.
acceptedNameUsage: Character vector of length 1; acceptedNameUsage to assign to the selected row.
clear_usage_id: Logical vector of length 1; should acceptedNameUsageID of the selected row be set to NA if the word "accepted" is detected in tax_status (not case-sensitive)? Default TRUE.
clear_usage_name: Logical vector of length 1; should acceptedNameUsageID of the selected row be set to NA if the word "accepted" is detected in tax_status (not case-sensitive)? Default TRUE.
fill_usage_name: Logical vector of length 1; should the acceptedNameUsage of the selected row be set to the scientificName corresponding to its acceptedNameUsageID? Default TRUE.
remap_names: Logical vector of length 1; should the acceptedNameUsageID be updated (remapped) for rows with the same acceptedNameUsageID as the taxonID of the row to be modified? Default TRUE.
remap_variant: Same as remap_names, but applies specifically to rows with taxonomicStatus of "variant". Default FALSE.
stamp_modified: Logical vector of length 1; should the modified column of any newly created or modified row include a timestamp with the date and time of its creation/modification? If the modified column does not yet exist it will be created. Default TRUE.
strict: Logical vector of length 1; should taxonomic checks be run on the updated taxonomic database? Default FALSE..
quiet: Logical vector of length 1; should warnings be silenced? Default FALSE..
args_tbl: A dataframe including columns corresponding to one or more of the above arguments, except for tax_dat. In this case, the input taxonomic database will be modified sequentially over each row of input in args_tbl. Other DwC terms can also be included as additional columns, similar to using ... to modify a single row.
...: other DwC terms to modify, specified as sets of named values. Each element of the vector must have a name corresponding to a valid DwC term; see dct_terms.

Value

Dataframe; taxonomic database in DwC format

Details

taxonID is only used to identify the row(s) to modify and is not itself modified. scientificName can be used in the same way if taxonID is not provided (as long as scientificName matches a single row). If both taxonID and scientificName are provided, scientificName will be assigned to the scientificName of the row identified by taxonID, replacing any value that already exists.

acceptedNameUsageID and acceptedNameUsage must match existing values of acceptedNameUsageID and acceptedNameUsage in the input data (tax_dat). On default settings, either can be used and the other will be filled in automatically (fill_usage_id and fill_usage_name are both TRUE).

Any other arguments provided that are DwC terms will be assigned to the selected row (i.e., they will modify the row).

If remap_names is TRUE (default) and acceptedNameUsageID is provided, any names that have an acceptedNameUsageID matching the taxonID of the selected row (i.e., synonyms of that row) will also have their acceptedNameUsageID replaced with the new acceptedNameUsageID. This behavior is not applied to names with taxonomicStatus of "variant" by default, but can be turned on for such names with remap_variant.

If clear_usage_id or clear_usage_name is TRUE and taxonomicStatus includes the word "accepted", acceptedNameUsageID or acceptedNameUsage will be set to NA respectively, regardless of the values of acceptedNameUsageID, acceptedNameUsage, or fill_usage_name.

Can either modify a single row in the input taxonomic database if each argument is supplied as a vector of length 1, or can apply a set of changes to the taxonomic database if the input is supplied as a dataframe via args_tbl.

Examples

# Swap the accepted / synonym status of
# Cephalomanes crassum (Copel.) M. G. Price
# and Trichomanes crassum Copel.
dct_filmies |>
  dct_modify_row(
    scientificName = "Cephalomanes crassum (Copel.) M. G. Price",
    taxonomicStatus = "synonym",
    acceptedNameUsage = "Trichomanes crassum Copel."
  ) |>
  dct_modify_row(
    scientificName = "Trichomanes crassum Copel.",
    taxonomicStatus = "accepted"
  ) |>
  dct_validate(
    check_tax_status = FALSE,
    check_mapping_accepted_status = FALSE,
    check_sci_name = FALSE
  )
#> # A tibble: 2,451 × 6
#>    taxonID acceptedNameUsageID taxonomicStatus taxonRank scientificName modified
#>    <chr>   <chr>               <chr>           <chr>     <chr>          <chr>   
#>  1 541150… NA                  accepted        species   Cephalomanes … NA      
#>  2 541337… NA                  accepted        species   Trichomanes c… 2024-04…
#>  3 541150… 54133783            synonym         species   Cephalomanes … 2024-04…
#>  4 541337… 54115098            synonym         species   Trichomanes d… NA      
#>  5 541150… NA                  accepted        species   Cephalomanes … NA      
#>  6 541337… 54115100            synonym         species   Cephalomanes … NA      
#>  7 541337… 54115100            synonym         species   Cephalomanes … NA      
#>  8 541337… 54115100            synonym         species   Cephalomanes … NA      
#>  9 541337… 54115100            synonym         species   Cephalomanes … NA      
#> 10 541337… 54115100            synonym         species   Lacostea java… NA      
#> # ℹ 2,441 more rows
# Sometimes changing one name will affect others, if they map
# to the new synonym
dct_modify_row(
  tax_dat = dct_filmies |> head(),
  scientificName = "Cephalomanes crassum (Copel.) M. G. Price",
  taxonomicStatus = "synonym",
  acceptedNameUsage = "Cephalomanes densinervium (Copel.) Copel."
)
#> # A tibble: 6 × 6
#>   taxonID  acceptedNameUsageID taxonomicStatus taxonRank scientificName modified
#>   <chr>    <chr>               <chr>           <chr>     <chr>          <chr>   
#> 1 54115096 NA                  accepted        species   Cephalomanes … NA      
#> 2 54133783 54115098            synonym         species   Trichomanes c… 2024-04…
#> 3 54115097 54115098            synonym         species   Cephalomanes … 2024-04…
#> 4 54133784 54115098            synonym         species   Trichomanes d… NA      
#> 5 54115098 NA                  accepted        species   Cephalomanes … NA      
#> 6 54133786 54115100            synonym         species   Cephalomanes … NA      
# Apply a set of changes
library(tibble)
updates <- tibble(
  scientificName = c(
    "Cephalomanes atrovirens Presl",
    "Cephalomanes crassum (Copel.) M. G. Price"
  ),
  taxonomicStatus = "synonym",
  acceptedNameUsage = "Trichomanes crassum Copel."
)
dct_filmies |>
  dct_modify_row(args_tbl = updates) |>
  dct_modify_row(
    scientificName = "Trichomanes crassum Copel.",
    taxonomicStatus = "accepted"
  )
#> # A tibble: 2,451 × 6
#>    taxonID acceptedNameUsageID taxonomicStatus taxonRank scientificName modified
#>    <chr>   <chr>               <chr>           <chr>     <chr>          <chr>   
#>  1 541150… 54133783            synonym         species   Cephalomanes … NA      
#>  2 541337… NA                  accepted        species   Trichomanes c… 2024-04…
#>  3 541150… 54133783            synonym         species   Cephalomanes … NA      
#>  4 541337… 54115098            synonym         species   Trichomanes d… NA      
#>  5 541150… NA                  accepted        species   Cephalomanes … NA      
#>  6 541337… 54115100            synonym         species   Cephalomanes … NA      
#>  7 541337… 54115100            synonym         species   Cephalomanes … NA      
#>  8 541337… 54115100            synonym         species   Cephalomanes … NA      
#>  9 541337… 54115100            synonym         species   Cephalomanes … NA      
#> 10 541337… 54115100            synonym         species   Lacostea java… NA      
#> # ℹ 2,441 more rows

Usage

Arguments

Value

Details

Examples

About

Community

Resources