diff --git a/.DS_Store b/.DS_Store index cfb25e9..e5d9f44 100644 Binary files a/.DS_Store and b/.DS_Store differ diff --git a/.gitignore b/.gitignore index 65bee3f..b81e3ed 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ .Rproj.user .Rhistory .DS_Store +inst/doc diff --git a/DESCRIPTION b/DESCRIPTION index 7f0fd82..e6cb429 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -25,5 +25,8 @@ Depends: R (>= 2.10) LazyData: true Suggests: + knitr, + rmarkdown, testthat (>= 3.0.0) Config/testthat/edition: 3 +VignetteBuilder: knitr diff --git a/README.Rmd b/README.Rmd new file mode 100644 index 0000000..f4bdca0 --- /dev/null +++ b/README.Rmd @@ -0,0 +1,135 @@ +--- +output: github_document +always_allow_html: yes +--- + + + +```{r setup, include = FALSE} +library(councilverse) +knitr::opts_chunk$set( + collapse = TRUE, + comment = "#>", + fig.path = "man/figures/README-", + out.width = "100%" +) +``` + +# Overview + +The `councilverse` is a set of packages that work in tandem to assist the NYCC's data team in doing their work. This package is designed to make it easy to install and load multiple 'councilverse' packages in a single step. + +## Installation + +You can install the released version of `councilverse` from GitHub + +``` r +remotes::install_github("newyorkcitycouncil/councilverse") +``` + +## Load Package + +Note that the order of loading the libraries is important. Make sure to load `councilverse` last. + +```{r eval=FALSE} +library(tidyverse) +# load last +library(councilverse) +``` + +## Vignette + +For a demo of the 2 largest packages (`councildown` and `councilcount`) available in `councilverse`, see `vignettes/councilverse.Rmd` + +## Quick Start + +First load the `councilverse` package as above. + +### Councildown +The `councildown` package implements style guide compliant defaults for R Markdown documents, `ggplot2` plots, and `leaflet` maps. For more information, please visit the package directly: https://github.com/NewYorkCityCouncil/councildown/ . The `councilverse` vignette goes through an example using most of `councildown`'s available functions. + +### Councilcount +The `councilcount` package allows easy access to ACS population data across various geographic boundaries. For the boundaries that are not native to the ACS, such as council districts, an estimate is provided. For more information, please visit the package directly: + +# Overview + +The `councilcount` package allows easy access to population data for around 70 demographic groups across various NYC geographic boundaries. This data was pulled from the 2017-2021 5-Year American Community Survey. For geographic boundaries that are not included in the ACS, like council districts, estimates were generated. + +## Installation + +You can install the released version of `councilcount` from GitHub + +``` r +remotes::install_github("newyorkcitycouncil/councilcount") +``` + +## Load Package + +Note that the order of loading the libraries is important. Make sure to +load `councilcount` last. + +```{r eval=FALSE} +library(tidyverse) +# load last +library(councilcount) +``` + +## Vignette + +For demos of the functions included in `councilcount`, please visit `vignettes/councilverse.Rmd`. + +## Quick Start + +First load the `councilcount` package as above. + +### Functions + +#### R + +`councilcount` includes 3 functions: + +`get_bbl_estimates()` -- Generates a dataframe that provides population estimates at the point level (there are also columns for various other geographies, like council district) +`get_census_variables()` -- Provides information on all of the ACS demographic variables that can be accessed using `get_geo_estimates()` via variable codes +`get_geo_estimates()` -- Creates a dataframe that provides population estimates for selected demographic variables along chosen geographic boundaries (e.g. council district, borough, etc.) + +Simply run `get_bbl_estimates()` and `get_census_variables()` to access the desired dataframes. They do not require any inputs. + +`get_geo_estimates()` has 3 parameters: + +`geo` -- The desired geographic region. Please select from the following list: +** Council Distrist: "councildist" +** Community Distrist: "communitydist" +** School District: "schooldist" +** Police Precinct: "policeprct" +** Neighborhood Tabulation Area: "nta" +** Borough: "borough" +`var_codes` -- The desired demographic group(s), as represented by the ACS variable code. To access the list of available demographic variables and their codes, please run `get_census_variables()` +`boundary_year` -- If "councildist" is selected, the boundary year must be specified as 2013 or 2023. The default is 2013. + +Here is an example, in which codes for "Female" and "Adults with Bachelor's degree or higher" are used. The data is requested along 2023 Council District boundaries. +``` r +vars <- c('DP05_0003PE', 'DP02_0068E') +get_geo_estimates(geo = "councildist", var_codes = vars, boundary_year = "2023") +``` + +#### Python + +The equivalent functions are also available in Python. To access them, use the following code: + +``` Python +import sys +# set absolute path to councilverse/inst/python location +sys.path.insert(0, "/{YOUR PATH}/councilverse/inst/python") +from retrieve_estimates import get_bbl_estimates, get_census_variables, get_geo_estimates +``` + +`get_bbl_estimates()` and `get_census_variables()` function the same in both R and Python. However, `get_geo_estimates()` has some differences in Python. Instead of having separate parameters for geo and boundary year, there are two input options for Council Districts, "councildist13" and "councildist23." Data for New York City as a whole is also available using "nyc" for geo. Otherwise, the geo input options are the same. There are also two additional parameters, `polygons` and `download`, with the defaults set at False. If `polygons` is set to True, the dataframe will include a column with the geometries associated with each geographic region. If `download` is set to True, the dataframe will automatically download as a CSV when the function runs. + + + + + + + + + diff --git a/README.md b/README.md index c8a8bfd..8c69228 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,12 @@ -# councilverse -The `councilverse` is a set of packages that work in tandem to assist the NYCC's data team in doing their work. This package is designed to make it easy to install and load multiple 'councilverse' packages in a single step. + + +# Overview + +The `councilverse` is a set of packages that work in tandem to assist +the NYCC’s data team in doing their work. This package is designed to +make it easy to install and load multiple ‘councilverse’ packages in a +single step. ## Installation @@ -9,3 +15,138 @@ You can install the released version of `councilverse` from GitHub ``` r remotes::install_github("newyorkcitycouncil/councilverse") ``` + +## Load Package + +Note that the order of loading the libraries is important. Make sure to +load `councilverse` last. + +``` r +library(tidyverse) +# load last +library(councilverse) +``` + +## Vignette + +For a demo of the 2 largest packages (`councildown` and `councilcount`) +available in `councilverse`, see `vignettes/councilverse.Rmd` + +## Quick Start + +First load the `councilverse` package as above. + +### Councildown + +The `councildown` package implements style guide compliant defaults for +R Markdown documents, `ggplot2` plots, and `leaflet` maps. For more +information, please visit the package directly: + . The +`councilverse` vignette goes through an example using most of +`councildown`’s available functions. + +### Councilcount + +The `councilcount` package allows easy access to ACS population data +across various geographic boundaries. For the boundaries that are not +native to the ACS, such as council districts, an estimate is provided. +For more information, please visit the package directly: + +# Overview + +The `councilcount` package allows easy access to population data for +around 70 demographic groups across various NYC geographic boundaries. +This data was pulled from the 2017-2021 5-Year American Community +Survey. For geographic boundaries that are not included in the ACS, like +council districts, estimates were generated. + +## Installation + +You can install the released version of `councilcount` from GitHub + +``` r +remotes::install_github("newyorkcitycouncil/councilcount") +``` + +## Load Package + +Note that the order of loading the libraries is important. Make sure to +load `councilcount` last. + +``` r +library(tidyverse) +# load last +library(councilcount) +``` + +## Vignette + +For demos of the functions included in `councilcount`, please visit +`vignettes/councilverse.Rmd`. + +## Quick Start + +First load the `councilcount` package as above. + +### Functions + +#### R + +`councilcount` includes 3 functions: + +* `get_bbl_estimates()` – Generates a dataframe that provides population +estimates at the point level (there are also columns for various other +geographies, like council district) +* `get_census_variables()` – Provides +information on all of the ACS demographic variables that can be accessed +using `get_geo_estimates()` via variable codes +* `get_geo_estimates()` – +Creates a dataframe that provides population estimates for selected +demographic variables along chosen geographic boundaries (e.g. council +district, borough, etc.) + +Simply run `get_bbl_estimates()` and `get_census_variables()` to access +the desired dataframes. They do not require any inputs. + +`get_geo_estimates()` has 3 parameters: + +* `geo` – The desired geographic region. Please select from the following +list: “councildist”, “communitydist”, “schooldist”, “policeprct”, “nta”, “borough” +* `var_codes` – The desired demographic group(s), as represented +by the ACS variable code. To access the list of available demographic +variables and their codes, please run `get_census_variables()` +* `boundary_year` – If “councildist” is selected, the boundary year must +be specified as 2013 or 2023. The default is 2013. + +Here is an example, in which codes for “Female” and “Adults with +Bachelor’s degree or higher” are used. The data is requested along 2023 +Council District boundaries. + +``` r +vars <- c('DP05_0003PE', 'DP02_0068E') +get_geo_estimates(geo = "councildist", var_codes = vars, boundary_year = "2023") +``` + +#### Python + +The equivalent functions are also available in Python. To access them, +use the following code: + +``` python +import sys +# set absolute path to councilverse/inst/python location +sys.path.insert(0, "/{YOUR PATH}/councilverse/inst/python") +from retrieve_estimates import get_bbl_estimates, get_census_variables, get_geo_estimates +``` + +`get_bbl_estimates()` and `get_census_variables()` function the same in +both R and Python. However, `get_geo_estimates()` has some differences +in Python. Instead of having separate parameters for geo and boundary +year, there are two input options for Council Districts, “councildist13” +and “councildist23.” Data for New York City as a whole is also available +using “nyc” for geo. Otherwise, the geo input options are the same. +There are also two additional parameters, `polygons` and `download`, +with the defaults set at False. If `polygons` is set to True, the +dataframe will include a column with the geometries associated with each +geographic region. If `download` is set to True, the dataframe will +automatically download as a CSV when the function runs. diff --git a/inst/python/__pycache__/retrieve_estimates.cpython-39.pyc b/inst/python/__pycache__/retrieve_estimates.cpython-39.pyc index 243f617..8be0198 100644 Binary files a/inst/python/__pycache__/retrieve_estimates.cpython-39.pyc and b/inst/python/__pycache__/retrieve_estimates.cpython-39.pyc differ diff --git a/vignettes/.gitignore b/vignettes/.gitignore new file mode 100644 index 0000000..097b241 --- /dev/null +++ b/vignettes/.gitignore @@ -0,0 +1,2 @@ +*.html +*.R diff --git a/vignettes/councilverse.Rmd b/vignettes/councilverse.Rmd new file mode 100644 index 0000000..630b60d --- /dev/null +++ b/vignettes/councilverse.Rmd @@ -0,0 +1,207 @@ +--- +title: "councilverse" +output: rmarkdown::html_vignette +vignette: > + %\VignetteIndexEntry{councilverse} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +--- + +```{r, include = FALSE} +knitr::opts_chunk$set( + collapse = TRUE, + comment = "#>" +) +``` + +## Data Example {.tabset .tabset-fade} + +### Install Package + +```{r dpi=300, eval=FALSE} +# replace councilverse with councildown if you only want councildown +remotes::install_github("newyorkcitycouncil/councilverse") +``` + +### Load Package + +```{r dpi=300, results='hide', message=FALSE} +library(tidyverse) +library(leaflet) +# load last; councilverse contains councildown +library(councilverse) +``` + +### Example Project Using CouncilVerse, CouncilVerse (CouncilCount) Functions + +#### Load CouncilCount Data + +CouncilCount data is a part of the CouncilVerse package. We will use this data as an example of how to make plots and maps. + +```{r dpi=300, message=FALSE} +# councilverse::get_census_variables to check available variables +census_vars <- get_census_variables() +# councilverse::get_geo_estimates to read in council district data for % work from home using 2013 council boundaries +# borough, communitydist, councildist, nta, policeprct, schooldist geographies are available +council_geo <- get_geo_estimates("councildist", var_codes = "DP03_0024E", boundary_year = "2013") +``` + +#### Visualize Data and Determine Map Breaks + +```{r dpi=300} +# check distribution of data (no councildown additions yet) +wfh_hist <- ggplot(data = council_geo, aes(percent_work_from_home_workers_16_and_older)) + geom_histogram(bins = 30) +# use fisher-jenks natural breaks after visualizing data +nat_intvl = classInt::classIntervals(council_geo$percent_work_from_home_workers_16_and_older, n = 5, style = 'fisher') +``` + +```{r dpi=300, out.width="75%"} +# visualize breaks using councilcount functions and styling +ggplot(data = council_geo, aes(percent_work_from_home_workers_16_and_older)) + + # use first color from nycc_palette "main" for the histogram bars + geom_histogram(bins = 30, aes(fill=pal_nycc("main")[1])) + + # use last color from nycc_palette "main" for the breaks + geom_vline(xintercept = nat_intvl$brks, color = pal_nycc("main")[6]) + + labs( + x = "% Work From Home", + y = "Count", + title = "Histogram of Data", + color = "" + ) + + # councildown::theme_nycc() for styling + theme_nycc() + + theme(legend.position="none") +``` + +#### Make Palette for Map + +```{r dpi=300} +# councildown::colorBin has default options for palette, bins, and na.color +pal_council = colorBin( + # use nycc_blue, which is the default palette for councildown::colorBin + palette = "nycc_blue", + # note: make sure rounding doesn't leave out any data in the bottom or top bin + bins = round(nat_intvl$brks,2), + domain = council_geo$percent_work_from_home_workers_16_and_older, + # use the default NA color for councildown::colorBin + na.color = "#FFFFFF" +) +``` + +#### Create Map + +```{r dpi=300} +map <- leaflet() %>% + # councildown::addCouncilStyle() for styling + addCouncilStyle() %>% + # councildown::addPolygons has default smoothFactor and weight + addPolygons(data = council_geo, + fillColor = ~pal_council(percent_work_from_home_workers_16_and_older), + fillOpacity = 1, + # councildown::councilPopup to style popups + label = ~lapply(councilPopup( + paste0("

", paste0("CD: ",councildist13), "

", + "

", paste0("Work From Home: ", percent_work_from_home_workers_16_and_older, "%"), "

")), + htmltools::HTML)) %>% + # councildown::addLegend_decreasing to change the default ordering of the legend + addLegend_decreasing(position = "topleft", pal = pal_council, + title = paste0("% Work From Home"), + values = c(0,1), opacity = 1, decreasing = T, + labFormat = labelFormat(suffix = "%"), + na.label = "NA") %>% + # councildown::addSourceText to add text on bottom left for source + addSourceText("Source: NYCC Data Team") +map +``` + +```{r eval=FALSE} +# add districts for 2013 or 2023 +map_w_dists <- map %>% + # councildown::addCouncilStyle has options to add 2013 or 2023 council districts to map + addCouncilStyle(add_dists = T, dist_year = "2023") + +# note: can access cd shapefiles by themselves +councildown::nycc_cd_13 # 2013 council district lines +councildown::nycc_cd_23 # 2023 council district lines +``` + +#### Save Map + +```{r eval=FALSE} +# councildown::mapshot has default zoom, vwidth, vheight, remove_controls +map_png <- file_name_generator(description = "council_district_percent_work_from_home", date_year = 2022, file_extension = ".png") +mapshot(map, file = glue::glue("visuals/{map_png}")) + +map_html <- file_name_generator(description = "council_district_percent_work_from_home", date_year = 2022, file_extension = ".html") +# save leaflet html (function not a part of councilverse) +htmlwidgets::saveWidget(map, file=glue::glue("visuals/{map_html}"), selfcontained = T) +``` + +## Reference {.tabset .tabset-fade} + +### CouncilVerse + +#### Graphs and Tables + +`encodeGraphic()` -- Graphics to raw HTML +`gt_table()` -- gt table to raw HTML helper function + +#### Misc + +`file_name_generator()` -- Helper function for creating file names using accepted guidelines +`unzip_sf()` -- Helper function for loading in shapefiles that come zipped + +### CouncilCount + +#### Population Estimates + +`get_bbl_estimates()` -- Generates a dataframe that provides population estimates at the point level (there are also columns for various other geographies, like council district) + +`get_census_variables()` -- Provides information on all of the ACS demographic variables that can be accessed using `get_geo_estimates()` via variable codes + +`get_geo_estimates()` -- Creates a dataframe that provides population estimates for selected demographic variables along chosen geographic boundaries (e.g. council district, borough, etc.) + +### CouncilDown + +#### Plots + +`theme_nycc()` -- A `ggplot2` theme that uses Council fonts and style guidelines to produce plots + +`scale_fill_nycc()`, `scale_color_nycc()` -- Color and fill scales for `ggplot2` plots. Used to replace `scale_color_discrete()`, `scale_color_continuous()`, `scale_fill_discrete()`, and `scale_fill_continuous()` + +#### Colors + +`pal_nycc()` -- Makes a color palette using Council colors + +`nycc_pal()` DEPRECATED. Use `pal_nycc` instead + +#### Maps + +`addCouncilStyle()` -- Adds Council styles including tiles, council district outlines, and fonts to a `leaflet` map + +`addSourceText()` -- Adds Council "Source" note in the bottom right of `leaflet` map + +`addPolygons()` -- The `leaflet` function `addPolygons` with default `smoothFactor` and `weight` + +`colorBin()` -- The `leaflet` function `colorBin` with default `palette`, `bins`, `na.color` + +`councilPopup()` -- Basic styling for `leaflet` popups + +`mapshot()` -- Saves `leaflet` maps as a static png image and defaults map saves with standardized `width`, `height`, and `zoom` + +`addLegend_decreasing()` -- The `leaflet` function `addLegend` but with the option for the highest number to be at the top of the legend + +#### Data + +`nycc_cd_13` -- 2013-2023 NYC Council District sf collection + +`nycc_cd_23` -- 2023-2033 NYC Council District sf collection + +#### Templates + +`council_html()` -- Render a Council HTML report +`council_pdf()` -- Render a Council PDF report + +#### Misc + +`pretty_date` -- Make a pretty date