rhud: A R interface for the US Department of Housing and Urban Development APIs

[etam4260]

Submitting Author Name: Name
Submitting Author Github Handle: @etam4260
Other Package Authors Github handles: (comma separated, delete if none)
Repository: https://github.com/etam4260/rhud
Version submitted:
Submission type: Standard
Editor: @jhollist
Reviewers: @rtaph, @khueyama

Due date for @rtaph: 2022-06-07

Due date for @khueyama: 2022-06-09
Archive: TBD
Version accepted: TBD
Language: en

• Paste the full DESCRIPTION file inside a code block below:

Package: hudr
Title: A R interface for accessing HUD (US Department of Housing and Urban Development) APIs
Version: 0.1.0.9000
Authors@R: 
    c(person("Emmet", "Tam", ,"emmet_tam@yahoo.com", role = c("aut", "cre", "cph")),
    person("Allison", "Reilly", ,"areilly2@umd.edu", role = c("ctb")),
    person("Hamed", "Ghaedi", ,"hghaedi@terpmail.umd.edu", role = c("ctb")))
Description: 
	An R interface for accessing HUD (US Department of Housing and Urban Development) API.
	The HUD has four main datasets, USPS Crosswalk, Fair Markets Rent,
	Income Limits, and the Comprehensive Housing Affordability Strategy.
License: GPL (>= 2)
Language: en-US
Encoding: UTF-8
LazyData: true
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.1.2.9000
URL: https://github.com/etam4260/hudr, https://etam4260.github.io/hudr/index.html
BugReports: https://github.com/etam4260/hudr/issues
Suggests: 
    covr,
    httptest,
    knitr,
    rmarkdown,
    testthat (>= 3.0.0)
Imports: 
    httr,
    devtools,
    zoo,
    rio
Config/testthat/edition: 3
VignetteBuilder: knitr
ByteCompile: true

Scope

• Please indicate which category or categories from our package fit policies this package falls under: (Please check an appropriate box below. If you are unsure, we suggest you make a pre-submission inquiry.):

  • data retrieval
  • data extraction
  • data munging
  • data deposition
  • workflow automation
  • version control
  • citation management and bibliometrics
  • scientific software wrappers
  • field and lab reproducibility tools
  • database software bindings
  • geospatial data
  • text analysis

• Explain how and why the package falls under these categories (briefly, 1-2 sentences):

It is a data retrieval package because it retrieves data from an API. It 'will' be a data munging package after implementation of additional features such as cross walking an entire dataset. Furthermore, the APIs which this package retrieves data from are associated with geographic identifiers.

• Who is the target audience and what are scientific applications of this package?

I am hoping to reach professors, researchers, and students with this package. This gives access to the crosswalk files which is a geospatial technique described very well in these journal articles:

Din, Alexander and Wilson, Ron, 2020. “Crosswalking ZIP Codes to Census Geographies: Geoprocessing the U.S. Department of Housing & Urban Development’s ZIP Code Crosswalk Files,” Cityscape: A Journal of Policy Development and Research, Volume 22, Number 1, https://www.huduser.gov/portal/periodicals/cityscpe/vol22num1/ch12.pdf

Wilson, Ron and Din, Alexander, 2018. “Understanding and Enhancing the U.S. Department of Housing and Urban Development’s ZIP Code Crosswalk Files,” Cityscape: A Journal of Policy Development and Research, Volume 20 Number 2, 277 – 294.

Additionally, it provides access to Income Limits and Fair Markets Rent as well as Comprehensive Housing and Affordability datasets provided by HUD which is of interest to housing and social science researchers.

Implementation of a crosswalk function is planned in future releases, which will help crosswalk a US dataset from one geographic identifier into another using the method described in the papers above.

• Are there other R packages that accomplish the same thing? If so, how does yours differ or meet our criteria for best-in-category?

Recently, a hudr package got published on CRAN, but it looks like some of derives from the work I currently have. I am not sure how this will affect my prospects of submitting this to CRAN. Furthermore, their package provides only access to the fair markets rent and income limits API provide by HUD. Mine gives access to all the APIs that are currently supported by HUD USER (https://www.huduser.gov/portal/home.html) as well as providing more flexibility and intuitiveness.

As for documentation and testing, I believe my package could be improved. I don't test very many edge cases and have not created vignettes for every function.

• (If applicable) Does your package comply with our guidance around Ethics, Data Privacy and Human Subjects Research?

For the most part, I think yes. The package requires an API key which I have users store using Sys.setenv(). I have not looked into the more sophisticated methods like the keyring package and do not instruct the user on how to set the key to be persistent.

• If you made a pre-submission inquiry, please paste the link to the corresponding issue, forum post, or other discussion, or @tag the editor you contacted.

#500
@jooolia

• Explain reasons for any pkgcheck items which your package is unable to pass.

I seem to get some errors when running pkgcheck. I manually made sure I had all the necessary components.
For the pkgcheck requirement that says all functions need examples, I am assuming that only includes exported ones?

Technical checks

Confirm each of the following by checking the box.

• I have read the guide for authors and rOpenSci packaging guide.

This package:

• does not violate the Terms of Service of any service it interacts with.
• has a CRAN and OSI accepted license.
• contains a README with instructions for installing the development version.
• includes documentation with examples for all functions, created with roxygen2.
• contains a vignette with examples of its essential functions and uses.
• has a test suite.
• has continuous integration, including reporting of test coverage using services such as Travis CI, Coveralls and/or CodeCov.

Publication options

• Do you intend for this package to go on CRAN?

• Do you intend for this package to go on Bioconductor?

• Do you wish to submit an Applications Article about your package to Methods in Ecology and Evolution? If so:

MEE Options

• The package is novel and will be of interest to the broad readership of the journal.
• The manuscript describing the package is no longer than 3000 words.
• You intend to archive the code for the package in a long-term repository which meets the requirements of the journal (see MEE's Policy on Publishing Code)
• (Scope: Do consider MEE's Aims and Scope for your manuscript. We make no guarantee that your manuscript will be within MEE scope.)
• (Although not required, we strongly recommend having a full manuscript prepared when you submit here.)
• (Please do not submit your package separately to Methods in Ecology and Evolution)

Code of conduct

• I agree to abide by rOpenSci's Code of Conduct during the review process and in maintaining my package should it be accepted.

[ropensci-review-bot]

Thanks for submitting to rOpenSci, our editors and @ropensci-review-bot will reply soon. Type @ropensci-review-bot help for help.

[ropensci-review-bot]

🚀

Editor check started

👋

[ropensci-review-bot]

Checks for hudr (v0.1.0.9000)

git hash: 660ad0e2

• ✖️ Package name is not available (on CRAN).
• ✔️ has a 'codemeta.json' file.
• ✖️ does not have a 'contributing' file.
• ✔️ uses 'roxygen2'.
• ✔️ 'DESCRIPTION' has a URL field.
• ✔️ 'DESCRIPTION' has a BugReports field.
• ✔️ Package has at least one HTML vignette
• ✔️ All functions have examples.
• ✔️ Package has continuous integration checks.
• ✖️ Package coverage failed
• ✖️ R CMD check process failed with message: 'Build process failed'.

Important: All failing checks above must be addressed prior to proceeding

Package License: GPL (>= 2)

---

1. Statistical Properties

This package features some noteworthy statistical properties which may need to be clarified by a handling editor prior to progressing.

Details of statistical properties (click to open)

The package has:

• code in R (100% in 11 files) and
• 1 authors
• 7 vignettes
• no internal data file
• 4 imported packages
• 30 exported functions (median 22 lines of code)
• 63 non-exported functions in R (median 20 lines of code)

---

Statistical properties of package structure as distributional percentiles in relation to all current CRAN packages
The following terminology is used:

• loc = "Lines of Code"
• fn = "function"
• exp/not_exp = exported / not exported

All parameters are explained as tooltips in the locally-rendered HTML version of this report generated by the checks_to_markdown() function

The final measure (fn_call_network_size) is the total number of calls between functions (in R), or more abstract relationships between code objects in other languages. Values are flagged as "noteworthy" when they lie in the upper or lower 5th percentile.

measure	value	percentile	noteworthy
files_R	11	62.6
files_vignettes	7	98.5
files_tests	10	90.7
loc_R	786	61.3
loc_vignettes	878	89.0
loc_tests	357	67.9
num_vignettes	7	99.2	TRUE
n_fns_r	93	74.6
n_fns_r_exported	30	78.3
n_fns_r_not_exported	63	73.5
n_fns_per_file_r	4	63.5
num_params_per_fn	4	54.6
loc_per_fn_r	22	64.1
loc_per_fn_r_exp	22	52.1
loc_per_fn_r_not_exp	20	63.0
rel_whitespace_R	37	79.7
rel_whitespace_vignettes	51	96.3	TRUE
rel_whitespace_tests	32	75.2
doclines_per_fn_exp	40	50.1
doclines_per_fn_not_exp	0	0.0	TRUE
fn_call_network_size	88	77.1

---

1a. Network visualisation

Click to see the interactive network visualisation of calls between objects in package

---

2. goodpractice and other checks

Details of goodpractice and other checks (click to open)

3a. Continuous Integration Badges

GitHub Workflow Results

name	conclusion	sha	date
pages build and deployment	success	660ad0	2022-04-01
R-CMD-check	success	660ad0	2022-04-01
test-coverage	success	06b739	2022-03-28

---

3b. goodpractice results

R CMD check with rcmdcheck

R CMD check generated the following error:

1. Error in proc$get_built_file() : Build process failed

R CMD check generated the following check_fail:

1. no_import_package_as_a_whole

Test coverage with covr

ERROR: Test Coverage Failed

Cyclocomplexity with cyclocomp

Error : Build failed, unknown error, standard output:

• checking for file ‘hudr/DESCRIPTION’ ... OK
• preparing ‘hudr’:
• checking DESCRIPTION meta-information ... OK
• installing the package to build vignettes
• creating vignettes ... ERROR
  --- re-building ‘authors.Rmd’ using rmarkdown
  --- finished re-building ‘authors.Rmd’

--- re-building ‘Community-Development-Block-Grant.Rmd’ using rmarkdown
--- finished re-building ‘Community-Development-Block-Grant.Rmd’

--- re-building ‘Comprehensive-Housing-and-Affordability-Strategy.Rmd’ using rmarkdown
--- finished re-building ‘Comprehensive-Housing-and-Affordability-Strategy.Rmd’

--- re-building ‘Crosswalk.Rmd’ using rmarkdown
Quitting from lines 101-105 (Crosswalk.Rmd)
Error: processing vignette 'Crosswalk.Rmd' failed with diagnostics:
Did you forget to set the key? Please go to https://www.huduser.gov/hudapi/public/register?comingfrom=1 to and sign up and get a token. Then save this to your environment using Sys.setenv('HUD_KEY' = YOUR_KEY)
--- failed re-building ‘Crosswalk.Rmd’

--- re-building ‘Fair-Markets-Rent.Rmd’ using rmarkdown
--- finished re-building ‘Fair-Markets-Rent.Rmd’

--- re-building ‘Income-Limits.Rmd’ using rmarkdown
--- finished re-building ‘Income-Limits.Rmd’

--- re-building ‘Setup.Rmd’ using rmarkdown
--- finished re-building ‘Setup.Rmd’

SUMMARY: processing the following file failed:
‘Crosswalk.Rmd’

Error: Vignette re-building failed.
Execution halted

Static code analyses with lintr

lintr found the following 351 potential issues:

message	number of times
Avoid 1:length(...) expressions, use seq_len.	10
Avoid 1:nrow(...) expressions, use seq_len.	2
Avoid using sapply, consider vapply instead, that's type safe	1
Lines should not be more than 80 characters.	306
Use <-, not =, for assignment.	32

---

Package Versions

package	version
pkgstats	0.0.3.96
pkgcheck	0.0.2.276

---

Editor-in-Chief Instructions:

Processing may not proceed until the items marked with ✖️ have been resolved.

[jooolia]

Dear @etam4260,
Thank you for your submission. Thank you for highlighting the new package hudr that is already on CRAN. Can you describe how you will deal with the name collision (I see it is already a bit problematic as the cran link on your pkgdown site links to that package or maybe that is on purpose?). Also, can you elaborate a bit more on the differences you see between the two packages? thanks, Julia

[etam4260]

Hi @jooolia

An easy solution to deal with the naming conflict I think would be to just rename the entire package as ‘rhud’ and update the documentation accordingly.

Otherwise, I have already contacted CRAN about this issue, but have not heard back about any resolutions. 😔

I’m not sure about any other options. Any other suggestions are appreciated. 🙏🏼

I took a look at the hudr package published on CRAN and it looks like they only implement APIs for two main datasets provided by HUD and they don’t have all the sub datasets. For example, Fair Markets Rent has state, county, and small area level data — they only have state level data. 🧐

hudr(CRAN)

• Fair Markets Rent (Single Query)
  • State Level
• Income Limits (Single Query)
  • State Level

They also provide functions for HUD miscellaneous APIs:

• Query for all US states
• Query for all counties in a state (Single Query)
• Query for all metropolitan areas in a state (Single Query)

Single query means their function calls only make 1 API call at a time, whereas multi query means multiple API calls can be done in a single function.

My package on the other hand supports the Crosswalk API and Comprehensive Housing and Affordability Strategy API as well.

hudr(etam4260/hudr)

• Fair Markets Rent (Multi Query)

  • State Level
  • County
  • Small Areas

• Income Limits (Multi Query)

  • State Level
  • County
  • Small Areas

• USPS Crosswalk Files (Multi Query)

• Comprehensive Housing and Affordability (Multi Query)

• Query for all US states

• Query for all counties in a state (Multi Query)

• Query for all metropolitan areas in a state (Multi Query)

• Query for all minor civil divisions in a state(Multi Query)

• Query for all places in a state (Multi Query)

My package I believe is more flexible and intuitive:

There are many ways of identifying US states such as using their abbreviation, full name, or fips code. My package allows the user to query based either of the options whereas the CRAN version strictly requires using the state abbreviation.

For example,

get_hud_fmr_statedata(entityid = “Virginia”, year = “2020”, hud_key = “dqwqdqwd”)

does not work because entityid must be strictly ‘VA'

Furthermore, their function arguments are less intuitive. For example:

get_hud_fmr_statedata(entityid = “VA”, year = “2020”, hud_key = “dqwqdqwd”)

'entityid' I believe should be better named as state because you are only allowed to query for states. Furthermore, the function name itself I believe is a little verbose. My function names do not need the additionaly ‘get_’ at the front. ‘hud_key’ argument I believe should be better named as ‘key’.

When specifying the year argument as well as arguments that are made of numbers, they don’t allow both character and numeric type to be used. For example, 11023 which can be represented as both a numeric or character can only be inputted as “11023”. I believe the flexibility could be both a good and a bad thing though.

Their functions also only strictly allow for only singular API calls.

For example, you cannot query:

get_hud_fmr_statedata(entityid = c(“VA”, “CA"), year = “2020”, hud_key = “dqwqdqwd”)
😕
and you cannot query:

get_hud_fmr_statedata(entityid = c(“VA”), year = c(“2020”, “2019"), hud_key = “dqwqdqwd”)
😕
Their functions only allow querying for state level data but not county and small areas.

My implementation allows all of them in one function call as well allowing for multiple state and year inputs.

hud_fmr(“VA”, year = 2020, key = “qdqdqdw”)
hud_fmr(c(“VA”, “CA”), year = “2020”, key = “dqdqdq”)
hud_fmr(51, 2021)

hud_fmr(c(“VA”, “CA”), year = c(“2020”, “2019"), key = “dqdqdq”)

hud_fmr(010099999, year = “2020”, key = “qdqdqdqq”)
hud_fmr(‘010099999’, year = “2020”, key = “qdqdqdqq”)

hud_fmr(‘METRO47900M47900’, year = 2020, key = “uefjhqiufd”)

For the X marks on the pkgcheck:

I have updated the repository to have a contributing file. Right now I have fixed rcmdcheck() so that it only give a single warning — a problem with rendering PDF documents with latex I think. It says something is wrong with Rd files. I’m not sure how to deal with the coverage error, as on my end codecov seems to be working fine. I made sure the HUD_KEY secret needed by the package is not "". If so, the tests and or code blocks are not run. 🤥

[jooolia]

@ropensci-review-bot check package

[ropensci-review-bot]

Thanks, about to send the query.

[ropensci-review-bot]

🚀

Editor check started

👋

[ropensci-review-bot]

Checks for hudr (v0.1.0.9000)

git hash: 120ebe8d

• ✖️ Package name is not available (on CRAN).
• ✔️ has a 'codemeta.json' file.
• ✔️ has a 'contributing' file.
• ✔️ uses 'roxygen2'.
• ✔️ 'DESCRIPTION' has a URL field.
• ✔️ 'DESCRIPTION' has a BugReports field.
• ✔️ Package has at least one HTML vignette
• ✔️ All functions have examples.
• ✔️ Package has continuous integration checks.
• ✖️ Package coverage failed
• ✖️ R CMD check found 1 error.
• ✔️ R CMD check found no warnings.

Important: All failing checks above must be addressed prior to proceeding

Package License: GPL (>= 2)

---

1. Statistical Properties

This package features some noteworthy statistical properties which may need to be clarified by a handling editor prior to progressing.

Details of statistical properties (click to open)

The package has:

• code in R (100% in 11 files) and
• 1 authors
• 7 vignettes
• no internal data file
• 4 imported packages
• 30 exported functions (median 22 lines of code)
• 63 non-exported functions in R (median 20 lines of code)

---

Statistical properties of package structure as distributional percentiles in relation to all current CRAN packages
The following terminology is used:

• loc = "Lines of Code"
• fn = "function"
• exp/not_exp = exported / not exported

All parameters are explained as tooltips in the locally-rendered HTML version of this report generated by the checks_to_markdown() function

The final measure (fn_call_network_size) is the total number of calls between functions (in R), or more abstract relationships between code objects in other languages. Values are flagged as "noteworthy" when they lie in the upper or lower 5th percentile.

measure	value	percentile	noteworthy
files_R	11	62.6
files_vignettes	7	98.5
files_tests	10	90.7
loc_R	786	61.3
loc_vignettes	878	89.0
loc_tests	392	69.9
num_vignettes	7	99.2	TRUE
n_fns_r	93	74.6
n_fns_r_exported	30	78.3
n_fns_r_not_exported	63	73.5
n_fns_per_file_r	4	63.5
num_params_per_fn	4	54.6
loc_per_fn_r	22	64.1
loc_per_fn_r_exp	22	52.1
loc_per_fn_r_not_exp	20	63.0
rel_whitespace_R	37	79.7
rel_whitespace_vignettes	51	96.3	TRUE
rel_whitespace_tests	29	74.9
doclines_per_fn_exp	40	50.1
doclines_per_fn_not_exp	0	0.0	TRUE
fn_call_network_size	88	77.1

---

1a. Network visualisation

Click to see the interactive network visualisation of calls between objects in package

---

2. goodpractice and other checks

Details of goodpractice and other checks (click to open)

3a. Continuous Integration Badges

GitHub Workflow Results

name	conclusion	sha	date
pages build and deployment	success	120ebe	2022-04-01
R-CMD-check	success	120ebe	2022-04-01
test-coverage	success	06b739	2022-03-28

---

3b. goodpractice results

R CMD check with rcmdcheck

R CMD check generated the following error:

1. checking tests ...
   Running ‘testthat.R’
   ERROR
   Running the tests in ‘tests/testthat.R’ failed.
   Last 13 lines of output:
   ══ Failed tests ════════════════════════════════════════════════════════════════
   ── Error (test-test_cdbgdr.R:2:3): Main CDBG-DR data files from DRGR Public Portal ──
   Error in curl::curl_fetch_memory(file): Timeout was reached: [drgr.hud.gov] Resolving timed out after 10000 milliseconds
   Backtrace:
   ▆
   1. └─hudr::hud_cdbg(1) at test-test_cdbgdr.R:2:2
   2. ├─base::suppressMessages(import("https://drgr.hud.gov/public/downloads/DR-CDBG/CDBG-DR%20Financial%20Report%20by%20Appropriation.xlsx"))
   3. │ └─base::withCallingHandlers(...)
   4. └─rio::import("https://drgr.hud.gov/public/downloads/DR-CDBG/CDBG-DR%20Financial%20Report%20by%20Appropriation.xlsx")

   5. └─rio:::remote_to_local(file, format = format)
      

   6.   └─curl::curl_fetch_memory(file)
      

[ FAIL 1 | WARN 0 | SKIP 35 | PASS 2 ]
Error: Test failures
Execution halted

R CMD check generated the following notes:

1. checking top-level files ... NOTE
   File
   LICENSE
   is not mentioned in the DESCRIPTION file.
2. checking dependencies in R code ... NOTE
   Namespace in Imports field not imported from: ‘devtools’
   All declared Imports should be used.

R CMD check generated the following test_fail:

1. library(testthat)

library(hudr)

test_check("hudr")
[ FAIL 1 | WARN 0 | SKIP 35 | PASS 2 ]

══ Skipped tests ═══════════════════════════════════════════════════════════════
• Sys.getenv("HUD_KEY") == "" is TRUE (35)

══ Failed tests ════════════════════════════════════════════════════════════════
── Error (test-test_cdbgdr.R:2:3): Main CDBG-DR data files from DRGR Public Portal ──
Error in curl::curl_fetch_memory(file): Timeout was reached: [drgr.hud.gov] Resolving timed out after 10000 milliseconds
Backtrace:
▆

1. └─hudr::hud_cdbg(1) at test-test_cdbgdr.R:2:2
2. ├─base::suppressMessages(import("https://drgr.hud.gov/public/downloads/DR-CDBG/CDBG-DR%20Financial%20Report%20by%20Appropriation.xlsx"))
3. │ └─base::withCallingHandlers(...)
4. └─rio::import("https://drgr.hud.gov/public/downloads/DR-CDBG/CDBG-DR%20Financial%20Report%20by%20Appropriation.xlsx")

5. └─rio:::remote_to_local(file, format = format)
   

6.   └─curl::curl_fetch_memory(file)
   

[ FAIL 1 | WARN 0 | SKIP 35 | PASS 2 ]
Error: Test failures
Execution halted

R CMD check generated the following check_fails:

1. no_import_package_as_a_whole
2. rcmdcheck_stale_license_file
3. rcmdcheck_imports_not_imported_from
4. rcmdcheck_tests_pass

Test coverage with covr

ERROR: Test Coverage Failed

Cyclocomplexity with cyclocomp

The following functions have cyclocomplexity >= 15:

function	cyclocomplexity
hud_chas	27
hud_cw	23
fmr_il_input_check_cleansing	19
cw_input_check_cleansing	17
hud_counties	17
hud_minor_civil_divisions	17
hud_places	17

Static code analyses with lintr

lintr found the following 351 potential issues:

message	number of times
Avoid 1:length(...) expressions, use seq_len.	10
Avoid 1:nrow(...) expressions, use seq_len.	2
Avoid using sapply, consider vapply instead, that's type safe	1
Lines should not be more than 80 characters.	306
Use <-, not =, for assignment.	32

---

Package Versions

package	version
pkgstats	0.0.3.96
pkgcheck	0.0.2.276

---

Editor-in-Chief Instructions:

Processing may not proceed until the items marked with ✖️ have been resolved.

[jooolia]

@ropensci-review-bot assign @jhollist as editor

[ropensci-review-bot]

Assigned! @jhollist is now the editor