Package 'getACS'

ACS survey, "acs5", "acs3", or "acs1".

The execution environment of a currently running function, e.g. caller_env(). The function will be mentioned in error messages as the source of the error. See the call argument of abort() for more information.

Based on the year and survey, acs_survey_ts() returns a vector of years for non-overlapping ACS samples to allow comparison.

The execution environment of a currently running function, e.g. caller_env(). The function will be mentioned in error messages as the source of the error. See the call argument of abort() for more information.

Pattern passed to glue::glue(). Allows use of the year_start variable which is the earliest year for a survey sample specified by the survey parameter.

Text to insert before ACS survey label.

One or more table IDs to include in label or source note.

Label to use when referring to table or tables. A "s" is appended to the end of the table_label if tables is more than length 1.

Separator to be inserted between words.

Character string to be prepended to the last word.

A character string to be added before/after each word.

A character string appended to the end of the full label. Defaults to ".".

Whether to insert the separator between the last two elements in the list.

An ACS table ID string.

Character vector of race iteration codes to return. If NULL (default), codes is set to c("", race_iteration[["code"]]).

The execution environment of a currently running function, e.g. caller_env(). The function will be mentioned in error messages as the source of the error. See the call argument of abort() for more information.

An ACS table ID string.

A numeric vector corresponding to the line number of the variables.

If data is provided and table is NULL, table is set based on the unique values in the "table_id" column of data. If data contains more than one table_id value, the function will error

Survey, "acs5", "acs3", or "acs1".

Sample year (between 2006 and 2022).

A separator character between the table ID string and variable ID values.

Variable ID suffix width.

The execution environment of a currently running function, e.g. caller_env(). The function will be mentioned in error messages as the source of the error. See the call argument of abort() for more information.

A data frame with a column of estimate values. Typically created with tidycensus::get_acs() or a function in this package such as get_acs_tables() or get_acs_geographies().

Value and margin of error column names (default to "estimate" and "moe").

The confidence level of the margin of error. Defaults to 90 (which is the same default as tidycensus::get_acs()).

Type of reliability rating to assign. Either "census" (default) or "esri". In both cases, the added reliability column values are "high", "medium", or "low".

Number of digits to use for values in the coefficient of variation column. Passed to base::round().

Coefficient of variation column name. Defaults to "cv".

Reliability category column name. Defaults to "reliability".

ACS data frame input.

<dynamic-dots> A series of named character vectors. The levels in each vector will be replaced with the name.

Value of level used for "other" values. Always placed at end of levels.

Name column name, Default: 'NAME'

Variable column name, Default: 'variable'

Label column name, Default: 'label'. Label is a factor column added to the returned data frame.

Value and margin of error column names (default to "estimate" and "moe").

The confidence level of the margin of error. Defaults to 90 (which is the same default as tidycensus::get_acs()).

If TRUE, use assign_acs_reliability() to assign a reliability value to estimate values based on the specified moe_level.

Passed to sum(), Default: TRUE

If TRUE, and the collapsed sum of a MOE is 0, replaced MOE value with NA. This is beneficial for percent estimates with the margin of error falls below 1% and is rounded to 0 with the default number of digits.

Passed to round(), Default: 2

When FALSE, the default, group_by() will override existing groups. To add to the existing groups, use .add = TRUE.

This argument was previously called add, but that prevented creating a new grouping variable called add, and conflicts with our naming conventions.

Must be TRUE. If FALSE (not currently supported), summarize collapsed variables using a weighted mean.

The gt table data object

⁠obj:<gt_tbl>⁠ // required

This is the gt table object that is commonly created through use of the gt() function.

State name. Required if state is included in pattern.

Passed to glue::glue() and stringr::str_replace() for fmt_acs_county() or just to stringr::str_replace() by fmt_acs_minutes(). Defaults to ", {state}" which strips the state name from a column of county-level name values or "[:space:]minutes$" which strips the trailing text for minutes.

Passed to stringr::str_replace(). Defaults to "".

Name for column with place name values. Defaults to "NAME"

Columns to target

⁠<column-targeting expression>⁠ // default: everything()

Can either be a series of column names provided in c(), a vector of column indices, or a select helper function (e.g. starts_with(), ends_with(), contains(), matches(), num_range() and everything()).

Arguments passed on to gt::fmt

rows

Rows to target

⁠<row-targeting expression>⁠ // default: everything()

In conjunction with columns, we can specify which of their rows should undergo formatting. The default everything() results in all rows in columns being formatted. Alternatively, we can supply a vector of row captions within c(), a vector of row indices, or a select helper function (e.g. starts_with(), ends_with(), contains(), matches(), num_range(), and everything()). We can also use expressions to filter down to the rows we need (e.g., ⁠[colname_1] > 100 & [colname_2] < 50⁠).

compat

Formatting compatibility

⁠vector<character>⁠ // default: NULL (optional)

An optional vector that provides the compatible classes for the formatting. By default this is NULL.

fns

Formatting functions

⁠function|list of functions⁠ // required

Either a single formatting function or a named list of functions.

Column title column.

A gt object.

Column names for the estimate and margin of error values in the table data.

If NULL (default), columns is set to c(col_est, col_moe). If spanner is NULL, columns is passed to cols_merge_uncert_ext() and must be a length 2 character vector.

Column name used for one or more columns passed to cols_label_ext()

If NULL, gt table is passed to cols_merge_uncert_ext(). If not NULL, spanner is passed to the label parameter of gt::tab_spanner().

Number of decimal places

scalar<numeric|integer>(val>=0) // default: 2

This corresponds to the exact number of decimal places to use. A value such as 2.34 can, for example, be formatted with 0 decimal places and it would result in "2". With 4 decimal places, the formatted value becomes "2.3400".

Use digit group separators

⁠scalar<logical>⁠ // default: TRUE

An option to use digit group separators. The type of digit group separator is set by sep_mark and overridden if a locale ID is provided to locale. This setting is TRUE by default.

Additional parameters passed to gt::fmt_number() by fmt_acs_estimate() or to gt::fmt_percent() by fmt_acs_percent().

The execution environment of a currently running function, e.g. caller_env(). The function will be mentioned in error messages as the source of the error. See the call argument of abort() for more information.

Data frame with ACS data

Aesthetic mapping. Recommend leaving this as NULL.

The data to be displayed in this layer. There are three options:

If NULL, the default, the data is inherited from the plot data as specified in the call to ggplot().

A data.frame, or other object, will override the plot data. All objects will be fortified to produce a data frame. See fortify() for which variables will be created.

A function will be called with a single argument, the plot data. The return value must be a data.frame, and will be used as the layer data. A function can be created from a formula (e.g. ~ head(.x, 10)).

A position adjustment to use on the data for this layer. This can be used in various ways, including to prevent overplotting and improving the display. The position argument accepts the following:

• The result of calling a position function, such as position_jitter(). This method allows for passing extra arguments to the position.

• A string naming the position adjustment. To give the position as a string, strip the function name of the position_ prefix. For example, to use position_jitter(), give the position as "jitter".

• For more information and other ways to specify the position, see the layer position documentation.

Other arguments passed on to layer()'s params argument. These arguments broadly fall into one of 4 categories below. Notably, further arguments to the position argument, or aesthetics that are required can not be passed through .... Unknown arguments that are not part of the 4 categories below are ignored.

• Static aesthetics that are not mapped to a scale, but are at a fixed value and apply to the layer as a whole. For example, colour = "red" or linewidth = 3. The geom's documentation has an Aesthetics section that lists the available options. The 'required' aesthetics cannot be passed on to the params. Please note that while passing unmapped aesthetics as vectors is technically possible, the order and required length is not guaranteed to be parallel to the input data.

• When constructing a layer using a ⁠stat_*()⁠ function, the ... argument can be used to pass on parameters to the geom part of the layer. An example of this is stat_density(geom = "area", outline.type = "both"). The geom's documentation lists which parameters it can accept.

• Inversely, when constructing a layer using a ⁠geom_*()⁠ function, the ... argument can be used to pass on parameters to the stat part of the layer. An example of this is geom_area(stat = "density", adjust = 0.5). The stat's documentation lists which parameters it can accept.

• The key_glyph argument of layer() may also be passed on through .... This can be one of the functions described as key glyphs, to change the display of the layer in the legend.

String values with column names mapped to aesthetics. Optional if mapping is supplied.

Column name for estimate value column. Defaults to "estimate".

Column name for margin of error column. Defaults to "moe".

Prefix string for percent value columns.

Separator string between perc_prefix and the value_col and moe_col strings.

If TRUE, return percent value and margin of error columns.

The orientation of the layer. The default (NA) automatically determines the orientation from the aesthetic mapping. In the rare event that this fails it can be given explicitly by setting orientation to either "x" or "y". See the Orientation section for more detail.

If TRUE (default), apply geom_acs_errorbar() function to geom.

Parameters passed to geom_acs_errorbar() if errorbar_value = TRUE. Defaults to list(linewidth = 0.5, height = 0.35)

If TRUE (default), apply scale_x_acs() or scale_y_acs() function to geom.

Parameters passed to scale_x_acs() or scale_y_acs() function if scale_value = TRUE. Defaults to list().

Required character vector of one or more geographies. See https://walker-data.com/tidycensus/articles/basic-usage.html#geography-in-tidycensus for supported options. Defaults to c("county", "state") for get_acs_geographies(). If a supplied geography does not support county and state parameters, these options are dropped before calling tidycensus::get_acs(). Any required parameters are also bound to the returned data frame as new columns.

A character vector of tables.

Whether or not to cache table names for faster future access. Defaults to FALSE; if TRUE, only needs to be called once per dataset. If variables dataset is already cached via the load_variables function, this can be bypassed.

The year, or endyear, of the ACS sample. 5-year ACS data is available from 2009 through 2022; 1-year ACS data is available from 2005 through 2022, with the exception of 2020. Defaults to 2022.

The ACS contains one-year, three-year, and five-year surveys expressed as "acs1", "acs3", and "acs5". The default selection is "acs5."

Character string or vector of character strings of variable IDs. tidycensus automatically returns the estimate and the margin of error associated with the variable.

The confidence level of the returned margin of error. One of 90 (the default), 95, or 99.

Arguments passed on to tidycensus::get_acs

output

One of "tidy" (the default) in which each row represents an enumeration unit-variable combination, or "wide" in which each row represents an enumeration unit and the variables are in the columns.

zcta

The zip code tabulation area(s) for which you are requesting data. Specify a single value or a vector of values to get data for more than one ZCTA. Numeric or character ZCTA GEOIDs are accepted. When specifying ZCTAs, geography must be set to '"zcta"' and 'state' must be specified with 'county' left as 'NULL'. Defaults to NULL.

geometry

if FALSE (the default), return a regular tibble of ACS data. if TRUE, uses the tigris package to return an sf tibble with simple feature geometry in the 'geometry' column.

keep_geo_vars

if TRUE, keeps all the variables from the Census shapefile obtained by tigris. Defaults to FALSE.

shift_geo

(deprecated) if TRUE, returns geometry with Alaska and Hawaii shifted for thematic mapping of the entire US. Geometry was originally obtained from the albersusa R package. As of May 2021, we recommend using tigris::shift_geometry() instead.

summary_var

Character string of a "summary variable" from the ACS to be included in your output. Usually a variable (e.g. total population) that you'll want to use as a denominator or comparison.

key

Your Census API key. Obtain one at https://api.census.gov/data/key_signup.html

show_call

if TRUE, display call made to Census API. This can be very useful in debugging and determining if error messages returned are due to tidycensus or the Census API. Copy to the API call into a browser and see what is returned by the API directly. Defaults to FALSE.

Coordinate reference system to use for returned sf tibble when geometry = TRUE is passed to tidycensus::get_acs(). Defaults to NULL.

If TRUE (default), label the returned ACS data with label_acs_metadata() before returning the data frame.

If TRUE (default), use the denominator column ID to calculate each estimate as a percent share of the denominator value and use tidycensus::moe_prop() to calculate a new margin of error for the percent estimate.

If TRUE, use assign_acs_reliability() to assign a reliability value to estimate values based on the specified moe_level.

If TRUE (default), bind geography and any supplied county or state columns to the returned data frame.

A GeoID column name to use if perc is TRUE, Defaults to 'GEOID'.

If FALSE (default), leave cli.default_handler option unchanged. If TRUE, set cli.default_handler to suppressMessages temporarily with rlang::local_options()

The execution environment of a currently running function, e.g. caller_env(). The function will be mentioned in error messages as the source of the error. See the call argument of abort() for more information.

An optional vector of states for which you are requesting data. State names, postal codes, and FIPS codes are accepted. Defaults to NULL.

The county for which you are requesting data. County names and FIPS codes are accepted. Must be combined with a value supplied to 'state'. Defaults to NULL.

Name or GeoID of a metro area that should be filtered from the overall list of metro areas returned when geography or geographies is "metropolitan/micropolitan statistical area", "cbsa", or "metropolitan statistical area/micropolitan statistical area".

Required character vector of one or more geographies. See https://walker-data.com/tidycensus/articles/basic-usage.html#geography-in-tidycensus for supported options. Defaults to c("county", "state") for get_acs_geographies(). If a supplied geography does not support county and state parameters, these options are dropped before calling tidycensus::get_acs(). Any required parameters are also bound to the returned data frame as new columns.

Character string or vector of character strings of variable IDs. tidycensus automatically returns the estimate and the margin of error associated with the variable.

A character vector of tables.

Whether or not to cache table names for faster future access. Defaults to FALSE; if TRUE, only needs to be called once per dataset. If variables dataset is already cached via the load_variables function, this can be bypassed.

A numeric vector of years. If length 1, the function uses acs_survey_ts() to get data for all comparable survey years back to the start of the ACS. This is the recommended approach for using get_acs_ts(). If length is greater than 1, return the selected years even if those years may not be valid to compare.

An optional vector of states for which you are requesting data. State names, postal codes, and FIPS codes are accepted. Defaults to NULL.

The county for which you are requesting data. County names and FIPS codes are accepted. Must be combined with a value supplied to 'state'. Defaults to NULL.

The ACS contains one-year, three-year, and five-year surveys expressed as "acs1", "acs3", and "acs5". The default selection is "acs5."

Other keyword arguments

If FALSE (default), leave cli.default_handler option unchanged. If TRUE, set cli.default_handler to suppressMessages temporarily with rlang::local_options()

The geography of your data.

If any year value is 2020, variables must be the same length as year with each value corresponding to one of the years requested. This is a temporary requirement to address the mismatch between the available data for 2000 and 2010 relative to 2020. Default: NULL

The Census table for which you would like to request all variables. Uses lookup tables to identify the variables; performs faster when variable table already exists through load_variables(cache = TRUE). Only one table may be requested per call.

Whether or not to cache table names for faster future access. Defaults to FALSE; if TRUE, only needs to be called once per dataset. If variables dataset is already cached via the load_variables function, this can be bypassed.

If year is length 1, it is treated as the max year and decennial Census years back to 2000, are added to the vector of requested years. Default: 2020

The Census summary file; if NULL, defaults to "pl" when the year is 2020 and "sf1" for 2000 and 2010. Not all summary files are available for each decennial Census year. Make sure you are using the correct summary file for your requested variables, as variable IDs may be repeated across summary files and represent different topics.

The state for which you are requesting data. State names, postal codes, and FIPS codes are accepted. Defaults to NULL.

The county for which you are requesting data. County names and FIPS codes are accepted. Must be combined with a value supplied to 'state'. Defaults to NULL.

if FALSE (the default), return a regular tibble of ACS data. if TRUE, uses the tigris package to return an sf tibble with simple feature geometry in the 'geometry' column.

Character string of a "summary variable" from the decennial Census to be included in your output. Usually a variable (e.g. total population) that you'll want to use as a denominator or comparison.

If TRUE (default), use label_decennial_data() to add formatted label columns to the decennial Census data frame.

Arguments passed on to tidycensus::get_decennial

output

One of "tidy" (the default) in which each row represents an enumeration unit-variable combination, or "wide" in which each row represents an enumeration unit and the variables are in the columns.

keep_geo_vars

if TRUE, keeps all the variables from the Census shapefile obtained by tigris. Defaults to FALSE.

shift_geo

(deprecated) if TRUE, returns geometry with Alaska and Hawaii shifted for thematic mapping of the entire US. Geometry was originally obtained from the albersusa R package. As of May 2021, we recommend using tigris::shift_geometry() instead.

pop_group

The population group code for which you'd like to request data. Applies to summary files for which population group breakdowns are available like the Detailed DHC-A file.

pop_group_label

If TRUE, return a "pop_group_label" column that contains the label for the population group. Defaults to FALSE.

key

Your Census API key. Obtain one at https://api.census.gov/data/key_signup.html

show_call

if TRUE, display call made to Census API. This can be very useful in debugging and determining if error messages returned are due to tidycensus or the Census API. Copy to the API call into a browser and see what is returned by the API directly. Defaults to FALSE.

Input data table

⁠obj:<data.frame>|obj:<tbl_df>⁠ // required

A data.frame object or a tibble (tbl_df).

Use data frame row labels in the stub

⁠scalar<logical>⁠ // default: FALSE

An option to take rownames from the input data table (should they be available) as row labels in the display table stub.

Mode for displaying row group labels in the stub

⁠scalar<logical>⁠ // default: FALSE

An option that alters the display of row group labels. By default this is FALSE and row group labels will appear in dedicated rows above their respective groups of rows. If TRUE row group labels will occupy a secondary column in the table stub.

Additional parameters passed to gt::fmt_number() by fmt_acs_estimate() or to gt::fmt_percent() by fmt_acs_percent().

Column name for estimate value column. Defaults to "estimate".

Column name for margin of error column. Defaults to "moe".

Prefix string for percent value columns.

Separator string between perc_prefix and the value_col and moe_col strings.

If TRUE, return percent value and margin of error columns.

Column title and label. If column_title_label is a string, column_title_col is required. column_title_label can also be a named vector in the format of c("label" = "column"). column_title_col defaults to "column_title". If column_title_label is "from_table", the label is set based on the simple_table_title column in the table metadata.

Place name column and label. name_label can be a string or a named vector (similar to column_title_label). name_col defaults to "NAME"

Percent value column label.

Value column label. Defaults to "Est.".

Spanner labels for estimate and percent estimate columns.

If not NULL, combined_spanner is passed to label parameter of gt::tab_spanner() using the value columns and percent columns as the columns parameter.

Number of decimal places

scalar<numeric|integer>(val>=0) // default: 2

This corresponds to the exact number of decimal places to use. A value such as 2.34 can, for example, be formatted with 0 decimal places and it would result in "2". With 4 decimal places, the formatted value becomes "2.3400".

Source note text

⁠scalar<character>⁠ // required

Text to be used in the source note. We can optionally use md() and html() to style the text as Markdown or to retain HTML elements in the text.

If TRUE, add source_note to the end of the generated ACS data label. If FALSE, any supplied source_note will be used instead of an ACS label.

If TRUE (default) and data is an sf object, drop geometry before turning the data frame into a table.

If TRUE (default), hide columns where all values are NA.

If TRUE, use gt::fmt_currency() to format value columns instead of gt::fmt_number().

ACS survey, "acs5", "acs3", or "acs1".

Based on the year and survey, acs_survey_ts() returns a vector of years for non-overlapping ACS samples to allow comparison.

One or more table IDs to include in label or source note.

Text to insert before ACS survey label.

A character string appended to the end of the full label. Defaults to ".".

Deprecated. Estimate and percent estimate columns.

A data frame to pivot.

Name column. Defaults to "NAME". Ignored if names_from is not set to name_col.

Column name for estimate value column. Defaults to "estimate".

Column name for margin of error column. Defaults to "moe".

Prefix string for percent value columns.

Separator string between perc_prefix and the value_col and moe_col strings.

If TRUE, return percent value and margin of error columns.

Variable column name. Defaults to "variable".

Column title column name and label. Defaults to "column_title" and NULL.

Value column label. Defaults to "Est.".

Margin of error column label. Defaults to "MOE".

Percent value column label.

Percent margin of error column label.

Defaults to column_title_col. See tidyr::pivot_longer() for details.

Should the values in the id_cols columns be expanded by expand() before pivoting? This results in more rows, the output will contain a complete expansion of all possible values in id_cols. Implicit factor levels that aren't represented in the data will become explicit. Additionally, the row values corresponding to the expanded id_cols will be sorted.

<tidy-select> A pair of arguments describing which column (or columns) to get the name of the output column (names_from), and which column (or columns) to get the cell values from (values_from).

If values_from contains multiple values, the value will be added to the front of the output column.

When names_from identifies a column (or columns) with multiple unique values, and multiple values_from columns are provided, in what order should the resulting column names be combined?

• "fastest" varies names_from values fastest, resulting in a column naming scheme of the form: ⁠value1_name1, value1_name2, value2_name1, value2_name2⁠. This is the default.

• "slowest" varies names_from values slowest, resulting in a column naming scheme of the form: ⁠value1_name1, value2_name1, value1_name2, value2_name2⁠.

Instead of names_sep and names_prefix, you can supply a glue specification that uses the names_from columns (and special .value) to create custom column names.

If names_from or values_from contains multiple variables, this will be used to join their values together into a single string to use as a column name.

Number of decimal places

scalar<numeric|integer>(val>=0) // default: 2

This corresponds to the exact number of decimal places to use. A value such as 2.34 can, for example, be formatted with 0 decimal places and it would result in "2". With 4 decimal places, the formatted value becomes "2.3400".

If TRUE, use gt::fmt_currency() to format value columns instead of gt::fmt_number().

If TRUE, use gt::cols_merge_uncert() to merge the value_col and moe_col and the percent value and margin of error columns.

Splitting side

⁠singl-kw:[last|first]⁠ // default: "last"

Should the delimiter splitting occur from the "last" instance of the delim character or from the "first"? The default here uses the "last" keyword, and splitting begins at the last instance of the delimiter in the column name. This option only has some consequence when there is a limit value applied that is lesser than the number of delimiter characters for a given column name (i.e., number of splits is not the maximum possible number).

Limit for splitting

⁠scalar<numeric|integer|character>⁠ // default: NULL (optional)

An optional limit to place on the splitting procedure. The default NULL means that a column name will be split as many times are there are delimiter characters. In other words, the default means there is no limit. If an integer value is given to limit then splitting will cease at the iteration given by limit. This works in tandem with split since we can adjust the number of splits from either the right side (split = "last") or left side (split = "first") of the column name.

Reverse vector of split names

⁠scalar<logical>⁠ // default: FALSE

Should the order of split names be reversed? By default, this is FALSE.

Source note text

⁠scalar<character>⁠ // required

Text to be used in the source note. We can optionally use md() and html() to style the text as Markdown or to retain HTML elements in the text.

If TRUE, add source_note to the end of the generated ACS data label. If FALSE, any supplied source_note will be used instead of an ACS label.

If TRUE (default), hide any columns with all NA values using gt::cols_hide().

ACS survey, "acs5", "acs3", or "acs1".

Based on the year and survey, acs_survey_ts() returns a vector of years for non-overlapping ACS samples to allow comparison.

One or more table IDs to include in label or source note.

Text to insert before ACS survey label.

A character string appended to the end of the full label. Defaults to ".".

If TRUE, pass source_note to gt::md() first.

If TRUE (default), create spanners for the comparison geographies.

Additional arguments passed on to methods.

A data frame with column names including "column_id", "column_title", "denominator_column_id", "estimate", and "moe".

A GeoID column name to use if perc is TRUE, Defaults to 'GEOID'.

Value column name

Margin of error column name

Column ID column name from Census Reporter metadata. Defaults to "column_id"

Column title column name. Defaults to "column_title".

Denominator column ID name from Census Reporter metadata. Defaults to NULL

Prefix to use for denominator column names.

Should two NA or two NaN values match?

• "na", the default, treats two NA or two NaN values as equal, like %in%, match(), and merge().

• "never" treats two NA or two NaN values as different, and will never match them together or to any other values. This is similar to joins for database sources and to base::merge(incomparables = NA).

integer indicating the number of decimal places (round) or significant digits (signif) to be used. For round, negative values are allowed (see ‘Details’).

The execution environment of a currently running function, e.g. caller_env(). The function will be mentioned in error messages as the source of the error. See the call argument of abort() for more information.

A data frame with column names matching the supplied parameters.

Variable column name to join as join variable, Default: 'variable'

Estimate and margin of error column names, Default: 'estimate' and 'moe'

Value in geography column to use as comparison values, Default: 'county'

Should two NA or two NaN values match?

• "na", the default, treats two NA or two NaN values as equal, like %in%, match(), and merge().

• "never" treats two NA or two NaN values as different, and will never match them together or to any other values. This is similar to joins for database sources and to base::merge(incomparables = NA).

integer indicating the number of decimal places (round) or significant digits (signif) to be used. For round, negative values are allowed (see ‘Details’).

A data frame with the specified column names. Expected to be labelled using label_acs_metadata().

Column ID, column title, and parent column ID.

Suffix passed to dplyr::left_join(), Default: c("", "_parent")

Should two NA or two NaN values match?

• "na", the default, treats two NA or two NaN values as equal, like %in%, match(), and merge().

• "never" treats two NA or two NaN values as different, and will never match them together or to any other values. This is similar to joins for database sources and to base::merge(incomparables = NA).

Handling of the expected relationship between the keys of x and y. If the expectations chosen from the list below are invalidated, an error is thrown.

• NULL, the default, doesn't expect there to be any relationship between x and y. However, for equality joins it will check for a many-to-many relationship (which is typically unexpected) and will warn if one occurs, encouraging you to either take a closer look at your inputs or make this relationship explicit by specifying "many-to-many".

  See the Many-to-many relationships section for more details.

• "one-to-one" expects:

  • Each row in x matches at most 1 row in y.

  • Each row in y matches at most 1 row in x.

• "one-to-many" expects:

  • Each row in y matches at most 1 row in x.

• "many-to-one" expects:

  • Each row in x matches at most 1 row in y.

• "many-to-many" doesn't perform any relationship checks, but is provided to allow you to be explicit about this relationship if you know it exists.

relationship doesn't handle cases where there are zero matches. For that, see unmatched.

A data frame with column names including "column_id", "column_title", "denominator_column_id", "estimate", and "moe".

A GeoID column name to use if perc is TRUE, Defaults to 'GEOID'.

Column ID column name from Census Reporter metadata. Defaults to "column_id"

Denominator column ID name from Census Reporter metadata. Defaults to NULL

Prefix to use for denominator column names.

Value column name

Margin of error column name

If FALSE, return data joined with join_acs_denominator() and skip joining percent values. Defaults to TRUE.

Prefix string for percent value columns.

Separator string between perc_prefix and the value_col and moe_col strings.

Should two NA or two NaN values match?

• "na", the default, treats two NA or two NaN values as equal, like %in%, match(), and merge().

• "never" treats two NA or two NaN values as different, and will never match them together or to any other values. This is similar to joins for database sources and to base::merge(incomparables = NA).

integer indicating the number of decimal places (round) or significant digits (signif) to be used. For round, negative values are allowed (see ‘Details’).

Arguments passed on to ggplot2::labs

title

The text for the title.

subtitle

The text for the subtitle for the plot which will be displayed below the title.

tag

The text for the tag label which will be displayed at the top-left of the plot by default.

alt,alt_insight

Text used for the generation of alt-text for the plot. See get_alt_text for examples.

The text for the caption which will be displayed in the bottom-right of the plot by default.

ACS survey, "acs5", "acs3", or "acs1".

Based on the year and survey, acs_survey_ts() returns a vector of years for non-overlapping ACS samples to allow comparison.

Text to insert before ACS survey label.

One or more table IDs to include in label or source note.

Optional data frame with "table_id" column used in place of table if table is NULL. Ignored if table is supplied.

Sample year (between 2006 and 2022).

Survey, "acs5", "acs3", or "acs1".

Whether you would like to cache the dataset for future access, or load the dataset from an existing cache. Defaults to FALSE.

Variable column name. Defaults to "variable"

Ordered vector of geography levels used to convert the geography column returned by tidycensus::load_variables() into a factor. Default: c("block", "block group", "tract", "county", "state", "us")

Table ID to return.

Variable IDs to keep or to drop. If table is supplied (or if data only contains data for a single table), numeric values are allowed for vars and drop_vars (e.g. if table is "B14001" and vars is 2 data is filtered to variable "B14001_002").

A sf object with an arbitrary geography overlapping with the block_xwalk. Required. If area only partly overlaps with block_xwalk, coverage should be set to TRUE (default).

Block-tract crosswalk sf object. If NULL, state is required to create a crosswalk using make_block_xwalk()

The two-digit FIPS code (string) of the state you want. Can also be state name or state abbreviation.

The three-digit FIPS code (string) of the county you'd like to subset for, or a vector of FIPS codes if you desire multiple counties. Can also be a county name or vector of names.

the data year; defaults to 2022

Name column in area.

Column name in input block_xwalk to use for weighting. Generated weight_col used by use_area_xwalk() should be the same as the weight_col for make_area_xwalk() but include the "perc_" prefix. Defaults to "HOUSING20" for make_block_xwalk() and "perc_HOUSING20" for use_area_xwalk().

GeoID for Census tract and Census tract ID column in block_xwalk

Specification of join variables in the format of c("block column name for tract" = "tract column name"). Passed to dplyr::left_join().

Suffixes added to the output to disambiguate column names from the block and tract data. Unused for 2020 data.

String with option for joining area and block_xwalk: "largest", "surface", or "centroid". "largest" joins the two using sf::st_join() with largest set to TRUE. "surface" first transforms block_xwalk using sf::st_point_on_surface() and "centroid" uses sf::st_centroid().

Digits to use for percent share of weight value.

If TRUE (default) calculate new estimate values as weighted sums and re-calculate margin of error with tidycensus::moe_sum(). If FALSE, calculate new estimate values as weighted means (appropriate for ACS median variables) and drop the margin of error. perc is also always set to FALSE if extensive is FALSE.

If TRUE (default), it is assumed that area does not cover the full extent of the block_xwalk and an additional feature is added with the difference between the unioned area geometry and unioned block_xwalk geometry. This additional coverage ensures that blocks are accurately assigned to this alternate geography but it is excluded from the returned data frame. If coverage is TRUE and all features in area overlap with block_xwalk, the function issues a warning and then resets coverage to FALSE. The reverse option is applied if any features from area do not overlap. coverage can also be a sf or sfc object which may be useful in some limited cases.

If TRUE, apply tigris::erase_water() to input area and block_xwalk before joining. Defaults to FALSE. If erase is a sf object, the geometry of the input sf is erased from area and block_xwalk. This option is intended to support erasing open space or other non-developed land as well as water areas.

The percentile rank cutoff of water areas to use in the erase operation, ranked by size. Defaults to 0.75, representing the water areas in the 75th percentile and up (the largest 25 percent of areas). This value may need to be modified by the user to achieve optimal results for a given location.

If TRUE, area_xwalk is a sf object with the same geometry as the input area. Defaults to FALSE.

Coordinate reference system to use for input data. Recommended to set to a projected CRS if input area data is in a geographic CRS.

Default TRUE. If TRUE, apply sf::st_make_valid() to the input area geometry and to any sf or sfc object passed to the erase parameter. If this has any unexpected results, set make_valid = FALSE and prepare any invalid geometry before passing to this function.

Passed to make_block_xwalk().

A data frame downloaded with tidycensus::get_acs().

A area crosswalk data frame created with make_area_xwalk(). Required for use_area_xwalk().

A character string used as general description for area geography type. Defaults to "area" but typical values could include "neighborhood", "planning district", or "service area".

Variable column name. Defaults to "variable"

Value and margin of error column names (defaults to "estimate" and "moe").

If TRUE (default), use the denominator column ID to calculate each estimate as a percent share of the denominator value and use tidycensus::moe_prop() to calculate a new margin of error for the percent estimate.

If TRUE, use assign_acs_reliability() to assign a reliability value to estimate values based on the specified moe_level.

The confidence level of the margin of error. Defaults to 90 (which is the same default as tidycensus::get_acs()).

The two-digit FIPS code (string) of the state you want. Can also be state name or state abbreviation.

The three-digit FIPS code (string) of the county you'd like to subset for, or a vector of FIPS codes if you desire multiple counties. Can also be a county name or vector of names.

the data year; defaults to 2022

Specification of join variables in the format of c("block column name for tract" = "tract column name"). Passed to dplyr::left_join().

Passed to tigris::blocks() and tigris::tracts() to keep and re-use the zipped shapefile.

Suffixes added to the output to disambiguate column names from the block and tract data. Unused for 2020 data.

Coordinate reference system to return.

Arguments passed on to tigris::blocks

A data frame to pivot.

Name column. Defaults to "NAME". Ignored if names_from is not set to name_col.

Column name for estimate value column. Defaults to "estimate".

Column name for margin of error column. Defaults to "moe".

Prefix string for percent value columns.

Separator string between perc_prefix and the value_col and moe_col strings.

If TRUE, return percent value and margin of error columns.

tidyselect function to use with column names. Defaults to tidyselect::starts_with,

Arguments passed on to tidyr::pivot_wider

names_from,values_from

<tidy-select> A pair of arguments describing which column (or columns) to get the name of the output column (names_from), and which column (or columns) to get the cell values from (values_from).

If values_from contains multiple values, the value will be added to the front of the output column.

names_prefix

String added to the start of every variable name. This is particularly useful if names_from is a numeric vector and you want to create syntactic variable names.

names_sort

Should the column names be sorted? If FALSE, the default, column names are ordered by first appearance.

names_expand

Should the values in the names_from columns be expanded by expand() before pivoting? This results in more columns, the output will contain column names corresponding to a complete expansion of all possible values in names_from. Implicit factor levels that aren't represented in the data will become explicit. Additionally, the column names will be sorted, identical to what names_sort would produce.

values_fill

Optionally, a (scalar) value that specifies what each value should be filled in with when missing.

This can be a named list if you want to apply different fill values to different value columns.

values_fn

Optionally, a function applied to the value in each cell in the output. You will typically use this when the combination of id_cols and names_from columns does not uniquely identify an observation.

This can be a named list if you want to apply different aggregations to different values_from columns.

unused_fn

Optionally, a function applied to summarize the values from the unused columns (i.e. columns not identified by id_cols, names_from, or values_from).

The default drops all unused columns from the result.

This can be a named list if you want to apply different aggregations to different unused columns.

id_cols must be supplied for unused_fn to be useful, since otherwise all unspecified columns will be considered id_cols.

This is similar to grouping by the id_cols then summarizing the unused columns using unused_fn.

<tidy-select> A set of columns that uniquely identify each observation. Typically used when you have redundant variables, i.e. variables whose values are perfectly correlated with existing variables.

Defaults to all columns in data except for the columns specified through names_from and values_from. If a tidyselect expression is supplied, it will be evaluated on data after removing the columns specified through names_from and values_from.

Should the values in the id_cols columns be expanded by expand() before pivoting? This results in more rows, the output will contain a complete expansion of all possible values in id_cols. Implicit factor levels that aren't represented in the data will become explicit. Additionally, the row values corresponding to the expanded id_cols will be sorted.

<tidy-select> A pair of arguments describing which column (or columns) to get the name of the output column (names_from), and which column (or columns) to get the cell values from (values_from).

If values_from contains multiple values, the value will be added to the front of the output column.

If names_from or values_from contains multiple variables, this will be used to join their values together into a single string to use as a column name.

Instead of names_sep and names_prefix, you can supply a glue specification that uses the names_from columns (and special .value) to create custom column names.

When names_from identifies a column (or columns) with multiple unique values, and multiple values_from columns are provided, in what order should the resulting column names be combined?

• "fastest" varies names_from values fastest, resulting in a column naming scheme of the form: ⁠value1_name1, value1_name2, value2_name1, value2_name2⁠. This is the default.

• "slowest" varies names_from values slowest, resulting in a column naming scheme of the form: ⁠value1_name1, value2_name1, value1_name2, value2_name2⁠.

What happens if the output has invalid column names? The default, "check_unique" is to error if the columns are duplicated. Use "minimal" to allow duplicates in the output, or "unique" to de-duplicated by adding numeric suffixes. See vctrs::vec_as_names() for more options.

Other arguments passed on to ⁠scale_(x|y)_continuous()⁠

If TRUE, use the scale_x_acs_percent or scale_y_acs_percent. Defaults to FALSE.

The name of the scale. Used as the axis or legend title. If waiver(), the default, the name of the scale is taken from the first mapping used for that aesthetic. If NULL, the legend title will be omitted.

One of:

• NULL for no labels

• waiver() for the default labels computed by the transformation object

• A character vector giving labels (must be same length as breaks)

• An expression vector (must be the same length as breaks). See ?plotmath for details.

• A function that takes the breaks as input and returns labels as output. Also accepts rlang lambda function notation.

One of:

• NULL for no breaks

• waiver() for the default breaks computed by the transformation object

• A numeric vector of positions

• A function that takes the limits as input and returns breaks as output (e.g., a function returned by scales::extended_breaks()). Note that for position scales, limits are provided after scale expansion. Also accepts rlang lambda function notation.

ACS survey, "acs5", "acs3", or "acs1".

Based on the year and survey, acs_survey_ts() returns a vector of years for non-overlapping ACS samples to allow comparison.

A data frame, data frame extension (e.g. a tibble), or a lazy data frame (e.g. from dbplyr or dtplyr). See Methods, below, for more details.

<tidy-select> One or more unquoted expressions separated by commas. Variable names can be used as if they were positions in the data frame, so expressions like x:y can be used to select a range of variables.

ACS data column names to select using the Tidyverse selection helper in .fn. Set any parameter to NULL to avoid selecting columns.

Percent value prefix and separator. Set .perc_prefix to NULL or .perc = FALSE to drop the percent value and percent margin of error columns.

If TRUE, select the percent value and percent margin of error columns along with the supplied column values.

Tidyverse selection helper to use with named ACS columns. Defaults to tidyselect::any_of. See dplyr::select() for an overview of selection features.

A gt object.

Source note text

⁠scalar<character>⁠ // required

Text to be used in the source note. We can optionally use md() and html() to style the text as Markdown or to retain HTML elements in the text.

If TRUE, add source_note to the end of the generated ACS data label. If FALSE, any supplied source_note will be used instead of an ACS label.

ACS survey, "acs5", "acs3", or "acs1".

Based on the year and survey, acs_survey_ts() returns a vector of years for non-overlapping ACS samples to allow comparison.

One or more table IDs to include in label or source note.

Label to use when referring to table or tables. A "s" is appended to the end of the table_label if tables is more than length 1.

Text to insert before ACS survey label.

A character string appended to the end of the full label. Defaults to ".".

If TRUE, pass source_note to gt::md() first.

For tab_acs_source_note(), additional parameters passed to acs_survey_label_table(). For cols_merge_uncert_ext(), additional parameters passed to gt::cols_merge_uncert(). For fmt_acs_percent(), additional parameters passed to gt::fmt_percent().

Additional parameters passed to .fn.

Function to call with parameters, Defaults to tidycensus::get_acs. Function must require a geography parameter and return a data frame.

Desired output size.

The execution environment of a currently running function, e.g. caller_env(). The function will be mentioned in error messages as the source of the error. See the call argument of abort() for more information.