Dealing with country names

Further options and warning messages

country_name() can identify countries even when they are provided in mixed formats or in different languages. It is robust to small misspellings and recognises alternative name formulations and old nomenclatures.

fuzzy_example <- c("US","C@ète d^Ivoire","Zaire","FYROM","Estados Unidos","ITA","blablabla")

country_name(x= fuzzy_example, to=c("UN_en"))
#> Multiple country IDs have been matched to the same country name.
#> There is low confidence on the matching of some country names, NA returned.
#> 
#> Set - verbose - to TRUE for more details
#> [1] "United States of America"         "Côte d’Ivoire"                   
#> [3] "Democratic Republic of the Congo" "North Macedonia"                 
#> [5] "United States of America"         "Italy"                           
#> [7] NA

More information on the country matching process can be obtained by setting verbose=TRUE. The function will print information on:

• The number of unique values provided by the user. In the example below 7 distinct strings have been provided.
• How many country names correspond exactly to the ones in the function’s reference list and how many have been processed with fuzzy matching. In the example below, "C@ète d^Ivoire" and "blablabla" are the only names processed with fuzzy matching. The function’s reference table can be accessed with the command data(country_reference_list). Finally, if any match is poor, the function will print the number of country names which are probably mismatched (in this example only "blablabla").

country_name(x= fuzzy_example, to=c("UN_en"), verbose=TRUE)
#> 
#> In total 7 unique country names were provided
#> 5/7 have been matched with EXACT matching
#> 2/7 have been matched with FUZZY matching, out of which:
#> 1/2 are a POOR match (likely wrongly identified)
#> 
#> 
#> Multiple arguments have been matched to the same country name:
#>   - Estados Unidos : United States of America 
#>   - US : United States of America
#> 
#> No close match found for the following countries, NA returned:
#> (set - poor_matches - to TRUE if you want the closest match to be returned or set - na_fill - to TRUE if you wish to fill the NAs with the original name supplied in - x)
#>  - blablabla
#> [1] "United States of America"         "Côte d’Ivoire"                   
#> [3] "Democratic Republic of the Congo" "North Macedonia"                 
#> [5] "United States of America"         "Italy"                           
#> [7] NA

In addition, setting verbose=TRUE will also print additional informations relating to specific warnings that are normally given by the function:

• Multiple country IDs have been matched to the same country name: This warning is issued if multiple strings have been matched to the same country. In verbose mode, the strings and corresponding countries will be listed. In the example above, both "US" and "Estados Unidos" are matched to the same country. If the vector of country names is a unique identifier, this could indicate that some country name was not recognised correctly. The user might consider using custom tables (refer to the next section).
• Unable to find an EXACT match for all country names: indicates that it is impossible to find an exact match for one or more country names with fuzzy_match=FALSE. The user might consider using fuzzy_match=TRUE or custom tables (refer to the next section).
• There is low confidence on the matching of some country names: This warning indicates that some strings have been matched poorly. Thus indicating that the country might have been misidentified. In verbose mode the function will provide a list of problematic strings (see the example below). If poor_matches is set to FALSE (the default), the function will return NA for these uncertain string. On the other hand, if poor_matches=TRUE the function will always return the closest match, even if poor. The user might consider using custom tables to solve issues with misidentification of country names (refer to the next section). Alternatively, the user can set na_fill=TRUE to replace the resulting NAs with the original name provided in x.
• Some country IDs have no match in one or more country naming conventions: Conversion is requested to a nomenclature for which there is no information on the country. For instance, in the example below “Taiwan” has no correspondence in the UN M49 standard. In verbose mode, the function will print all the country names affected by this problem. The user might consider using custom tables to solve this type of issues (refer to the next section). Alternatively, the user can set na_fill=TRUE to replace the resulting NAs with the original name provided in x.

country_name(x= c("Taiwan","lsajdèd"), to=c("UN_en"), verbose=FALSE)
#> Some country IDs have no match in one or more of the requested country naming conventions, NA returned.
#> There is low confidence on the matching of some country names, NA returned.
#> 
#> Set - verbose - to TRUE for more details
#> [1] NA NA

country_name(x= c("Taiwan","lsajdèd"), to=c("UN_en"), verbose=FALSE, na_fill = TRUE)
#> Some country IDs have no match in one or more of the requested country naming conventions, used original name to fill the NAs.
#> There is low confidence on the matching of some country names, keeping the original names in - x.
#> 
#> Set - verbose - to TRUE for more details
#> [1] "Taiwan"  "lsajdèd"

All the information from verbose mode can be accessed by setting ´simplify=FALSE´. This will return a list object containing:

• converted_data: the normal output of the function
• match_table: the conversion table with information on the closest match for each country name and distance metrics.
• summary: summary values for the distance metrics
• warning: logical value indicating whether a warning is issued by the function
• call: the arguments passed by the user