Type: | Package |
Title: | Operations to Ease Data Analyses Specific to Nigeria |
Version: | 0.6.2 |
Depends: | R (≥ 3.6) |
Imports: | RColorBrewer (≥ 1.1.2), cli (≥ 3.6.0), lifecycle (≥ 0.2.0), grDevices, graphics, mapdata (≥ 2.3.0), maps (≥ 3.3.0), rlang (≥ 0.4.0), sf (≥ 1.0-12), stats, stringi (≥ 1.7.6), utils |
Suggests: | ISOcodes, covr, here, knitr, purrr, readxl, rmarkdown, testthat (≥ 3.0.0), usethis, WikidataR |
Description: | A set of convenience functions as well as geographical/political data about Nigeria, aimed at simplifying work with data and information that are specific to the country. |
License: | GPL-3 |
LazyData: | TRUE |
Encoding: | UTF-8 |
RoxygenNote: | 7.3.2 |
VignetteBuilder: | knitr |
RdMacros: | lifecycle |
URL: | https://docs.ropensci.org/naijR/ |
BugReports: | https://github.com/ropensci/naijR/issues |
Config/testthat/edition: | 3 |
NeedsCompilation: | no |
Packaged: | 2025-04-09 16:38:18 UTC; user |
Author: | Victor Ordu |
Maintainer: | Victor Ordu <victorordu@outlook.com> |
Repository: | CRAN |
Date/Publication: | 2025-04-09 20:20:02 UTC |
naijR: Operations to Ease Data Analyses Specific to Nigeria
Description
The naijR package is essentially an R package about Nigeria and for Nigeria.
Details
naijR contains a number of functions that facilitate the management of data sets of interest including data cleaning and wrangling, as well as making available a number of facilities for geospatial data visualisation.
Author(s)
Victor Ordu
See Also
Useful links:
Disambiguate Synonymous States and LGAs
Description
Some LGAs in Nigeria bear the name of the States to which they belong to. This function will apply an attribute to such an LGA to distinguish it from its State.
Usage
disambiguate_lga(lga, state = NULL, ...)
Arguments
lga |
An object of class |
state |
The name of the State to which the LGA is to belong to. |
... |
Arguments to be passed to |
Details
For state
, if it is not provided by the user, an interactive
prompt will be presented to the user to select the appropriate state - but
only in interactive sessions; if run as a batch command, this function
will signal an error.
Value
The object of class lgas
with the (possibly) modified
State
attribute.
Examples
obi.lga <- lgas("Obi") # Warning
try(map_ng(obi.lga)) # Error
obi.benue <- disambiguate_lga(obi.lga, "Benue")
if (interactive())
map_ng(obi.benue)
Fix mobile numbers
Description
Fixes up local mobile phone numbers to a uniform text format.
Usage
fix_mobile(x)
Arguments
x |
A character vector of numerical strings. |
Details
This format is specific to that used in a given location - for
now the function is useful only for Nigeria mobile numbers, which come in
the format expressed by the regex pattern "^0[7-9][0-1][0-9]{8}$"
.
Value
The updated vector, usually the column of a data frame.
Note
There is an option for producing warnings on any mobile number entries
that may have been removed from the vector, by setting the option
verbose
to TRUE
.
Examples
fix_mobile("803-123-4567") # Adds leading '0" and removes separators
Fix Misspelling of Administrative Regions
Description
Correct any misspelled names of administrative regions e.g. States and LGAs.
Usage
fix_region(x, ...)
## S3 method for class 'states'
fix_region(x, ...)
## S3 method for class 'lgas'
fix_region(x, interactive = FALSE, quietly = FALSE, graphic = FALSE, ...)
## Default S3 method:
fix_region(x, ...)
fix_region_manual(x, wrong, correct)
Arguments
x |
An S3 object of class |
... |
Arguments passed to methods. |
interactive |
Logical. When |
quietly |
Logical; default argument is |
graphic |
Whether to make use of native GUI elements (on Windows only). |
wrong |
The misspelled element(s) of |
correct |
The correction that is to be applied to the misspelled element(s) |
Details
fix_region
will look through a character vector and try to
determine if State or LGA names have been wrongly entered. This presupposes
that the atomic vector is of type character
. It does not test any
missing values in the vector, leaving them untouched.
fix_region_manual
allows users to interactively and directly change
update the spelling.
Value
The transformed object. If all names are correct, the object is returned unchanged.
Note
When passed a character vector of length 1L
, in the case of a
misspelled LGA, the function signals an error; the presumption is that a fix
can readily be applied interactively. When all the items provided are
misspelled, nothing happens, but the user is advised to use the appropriate
constructor function so as to improve the accuracy of the repairs. When
there is a mix of misspelled and properly spelled LGAs, other avenues
for fixing the mistakes are available via mode interactive
.
Examples
try(fix_region("Owerri north")) # ERROR
fix_region(c("Owerri north", "Owerri West"))
x <- c("Pankshen", "Pankshin", "Q'uan Pam")
is_lga(x)
x <- fix_region(x, quietly = TRUE)
is_lga(x)
fix_region_manual(x, "Q'uan Pam", "Qua'an Pan")
all(is_lga(x))
Objects for Representing the Local Government Areas (LGAs) of Nigeria
Description
Objects for Representing the Local Government Areas (LGAs) of Nigeria
Usage
lgas(region = NA_character_, strict = FALSE, warn = TRUE)
is_lga(x)
as_lga(x)
## S3 method for class 'lgas'
print(x, ...)
## S3 method for class 'lgas'
c(...)
## S3 method for class 'lgas'
x[[i, exact = TRUE]]
## S3 method for class 'lgas'
x[i]
## S3 method for class 'lgas'
na.exclude(object, ...)
Arguments
region |
Context-dependent. Either State(s) of the Federation
or Local Government Area(s) - internal checks are performed to determine
what applies. In cases where States are synonymous to LGAs, the default
behaviour is to use the State as a basis for selecting the LGAs. This
can be modified with |
strict |
logical; in the event of a name clash between State/LGA,
return only the specified LGA when this argument is set to |
warn |
logical; issue a warning when one or more elements are not actually Local Government Areas (or were misspelt). |
x |
An object of type |
... |
Arguments used for methods. See documentation of generic for details. |
i , exact |
See help file for |
object |
An object of class |
Value
If length of ng.state
== 1L, a character vector containing
the names of Local Government Areas; otherwise a named list, whose elements
are character vectors of the LGAs in each state.
is_lga
returms a vector the same length as the input object
(each element that is not a valid Local Government Area will evaluate to
FALSE
); with as_lga
, an object of class lgas
.
Note
There are six (6) LGAs that share names with their State - Bauchi, Ebonyi, Gombe, Katsina, Kogi and Ekiti.
Examples
how_many_lgas <- function(state) {
require(naijR)
stopifnot(all(is_state(state)))
cat(sprintf("No. of LGAs in %s State:", state),
length(lgas(state)),
fill = TRUE)
}
how_many_lgas("Sokoto")
how_many_lgas("Ekiti")
is_lga(c("Pankshen", "Pankshin"))
# With coercion
kt.st <- states("Katsina") # Ensure this is a State, not an LGA.
kt.lg <- suppressWarnings(as_lga(kt.st))
is_state(kt.st) # TRUE
is_lga(kt.lg) # TRUE
## Where there's no ambiguity, it doesn't make sense to coerce
## This kind of operation ends with an error
## Not run:
as_state("Kano")
as_lga("Michika")
## End(Not run)
Local Government Areas of Nigeria
Description
A dataset containing the 774 Local Government Areas of Nigeria
Usage
lgas_nigeria
Format
A dataframe with 774 rows and 2 columns
- lga
Local Government Area
- state
State of the Federation
- gpz
Geo-political zone
Map of Nigeria
Description
Maps of the Federal Republic of Nigeria that are based on the basic plotting idiom utilised by maps:map and its variants.
Usage
map_ng(
region = character(),
data = NULL,
x = NULL,
y = NULL,
breaks = NULL,
categories = NULL,
excluded = NULL,
exclude.fill = NULL,
title = NULL,
caption = NULL,
show.neighbours = FALSE,
show.text = FALSE,
legend.text = NULL,
leg.title,
plot = TRUE,
...
)
Arguments
region |
A character vector of regions to be displayed. This could be States or Local Government Areas. |
data |
An object containing data, principally the variables required to plot in a map. |
x , y |
Numeric object or factor (or coercible to one). See Details. |
breaks |
Numeric. A vector of length >= 1. If a single value i.e.
scalar, it denotes the expected number of breaks. Internally, the function
will attempt to compute appropriate category sizes or fail if out-of bounds.
Where length is >= 3L, it is expected to be an arithmetic sequence that
represents category bounds as for |
categories |
The legend for the choropleth-plotted categories. If not defined, internally created labels are used. |
excluded |
Regions to be excluded from a choropleth map. |
exclude.fill |
Colour-shading to be used to indicate |
title , caption |
An optional string for annotating the map. |
show.neighbours |
Logical; |
show.text |
Logical. Whether to display the labels of regions. |
legend.text |
Logical (whether to show the legend) or character vector
(actual strings for the legend). The latter will override whatever is
provided by |
leg.title |
String. The legend title. If missing, a default value is
acquired from the data. To turn off the legend title, pass |
plot |
Logical. Turn actual plotting of the map off or on. |
... |
Further arguments passed to |
Details
The default value for region
is to print all State
boundaries.
data
enables the extraction of data for plotting from an object
of class data.frame
. Columns containing regions (i.e. States as well
as supported sub-national jurisdictions) are identified. The argument also
provides context for quasiquotation when providing the x
and
y
arguments.
For x
and y
, when both arguments are supplied, they are taken
to be point coordinates, where x
represent longitude and y
latitude. If only x
is supplied, it is assumed that the intention of
the user is to make a choropleth map, and thus, numeric vector arguments are
converted into factors i.e. number classes. Otherwise factors or any object
that can be coerced to a factor should be used.
For plain plots, the col
argument works the same as with
map
. For choropleth maps, the colour provided represents
a (sequential) colour palette based on RColorBrewer::brewer.pal
. The
available colour options can be checked with
getOption("choropleth.colours")
and this can also be modified by the
user.
If the default legend is unsatisfactory, it is recommended that the user
sets the legend.text
argument to FALSE
; the next function
call should be legend
which will enable finer
control over the legend.
Value
An object of class sf
, which is a standard format containing
the data used to draw the map and thus can be used by this and other
popular R packages to visualize the spatial data.
Note
When adjusting the default colour choices for choropleth maps, it is
advisable to use one of the sequential palettes. For a list of of available
palettes, especially for more advanced use, review
RColorBrewer::display.brewer.all
.
See Also
vignette("nigeria-maps")
for additional ways to use this
function.
Examples
## Not run:
map_ng() # Draw a map with default settings
map_ng(states("sw"))
map_ng("Kano")
## End(Not run)
Objects for Representing the Federal States of Nigeria
Description
Objects for Representing the Federal States of Nigeria
Usage
states(states, gpz = NULL, all = TRUE, warn = TRUE)
is_state(x)
as_state(x)
## S3 method for class 'states'
print(x, ...)
## S3 method for class 'states'
c(...)
## S3 method for class 'states'
x[[i, exact = TRUE]]
## S3 method for class 'states'
x[i]
## S3 method for class 'states'
na.exclude(object, ...)
Arguments
states |
A character vector with strings representing one or more
States of Nigeria. If missing, the function will return a |
gpz |
|
all |
logical; whether to include the Federal Capital Territory (FCT) in the result. |
warn |
logical; issue a warning when one or more elements are not actually States (i.e. they were misspelt). |
x |
For |
... |
Arguments used for methods. See documentation of generic for details. |
i , exact |
See help file for |
object |
An object of class |
Details
gpz
represents a geopolitical zone which, in the Nigerian
context, is a national subdivision that groups contiguous states that bear
certain socio-cultural and political similarities. Historically, they arise
from sub-national administrative divisions known as 'Regions' that existed
at the time of the country's independence. There are at present 6 such
zones - North-Central, North-East, North-West, South-East,South-South and
South-West.
For is_state
, An element-wise check of a supplied vector is carried
out. To test an entire vector and return a single boolean value, functions
such as base::all
or base::any
should be used (see examples).
Value
The States of Nigeria as a whole or by zones, as an S3 object
of class states
. is_state
returns a logical vector.of same
length as the input. If the input object is not even of type
character
, return the object unaltered, with a warning. In the case
of as_state
, an object of class states
.
Note
is_state
throws a warning, when a missing value is among the
elements. It works only for atomic vectors, throwing an error when this
is not the case or when NULL
is passed to it. This design decision
was made to allow rapid iteration through data frames without interruption,
since spelling mistakes tend to be common.
Examples
states() # lists names of all States
states(gpz = "se") # lists States in South-East zone
all(is_state(naijR::states()))
is_state(c("Maryland", "Baden-Baden", "Plateau", "Sussex"))
# With coercion
kt.st <- states("Katsina") # Ensure this is a State, not an LGA.
kt.lg <- suppressWarnings(as_lga(kt.st))
is_state(kt.st) # TRUE
is_lga(kt.lg) # TRUE
## Where there's no ambiguity, it doesn't make sense to coerce
## This kind of operation ends with an error
## Not run:
as_state("Kano")
as_lga("Michika")
## End(Not run)
States of Nigeria
Description
A dataset of the 36 States and Federal Capital Territory of Nigeia
Usage
states_nigeria
Format
A data.frame
with 37 rows and 2 columns
- isocode
ISO 3661 Alpha 2 code
- state
Name of the State or Territory
- gpz
Geo-political zone