Skip to content

Commit

Permalink
updated README, setup, resources
Browse files Browse the repository at this point in the history
  • Loading branch information
jGaboardi committed Oct 1, 2020
1 parent ab16ee6 commit 2bae2cb
Show file tree
Hide file tree
Showing 6 changed files with 18 additions and 20 deletions.
30 changes: 14 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,11 @@
# NHGISXWALK
## Spatio-temporal [NHGIS Crosswalks](https://www.nhgis.org/user-resources/geographic-crosswalks)

[![Documentation](https://img.shields.io/static/v1.svg?label=docs&message=current&color=4ca)](https://jgaboardi.github.io/nhgisxwalk/) [![GitHub release](https://img.shields.io/github/v/tag/jGaboardi/nhgisxwalk?include_prereleases&logo=GitHub)](https://img.shields.io/github/v/tag/jGaboardi/nhgisxwalk?include_prereleases&logo=GitHub) [![unittests](https://github.com/jGaboardi/nhgisxwalk/workflows/.github/workflows/unittests.yml/badge.svg)](https://github.com/jGaboardi/nhgisxwalk/actions?query=workflow%3A.github%2Fworkflows%2Funittests.yml) [![codecov](https://codecov.io/gh/jGaboardi/nhgisxwalk/branch/master/graph/badge.svg)](https://codecov.io/gh/jGaboardi/nhgisxwalk) [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/jGaboardi/nhgisxwalk/master)
[![Documentation](https://img.shields.io/static/v1.svg?label=docs&message=current&color=4ca)](https://ipums.github.io/nhgisxwalk/) [![GitHub release](https://img.shields.io/github/v/tag/ipums/nhgisxwalk?include_prereleases&logo=GitHub)](https://img.shields.io/github/v/tag/ipums/nhgisxwalk?include_prereleases&logo=GitHub) [![unittests](https://github.com/ipums/nhgisxwalk/workflows/.github/workflows/unittests.yml/badge.svg)](https://github.com/ipums/nhgisxwalk/actions?query=workflow%3A.github%2Fworkflows%2Funittests.yml) [![codecov](https://codecov.io/gh/ipums/nhgisxwalk/branch/master/graph/badge.svg)](https://codecov.io/gh/ipums/nhgisxwalk) [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/ipums/nhgisxwalk/master)
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
[![made-with-python](https://img.shields.io/badge/Made%20with-Python-1f425f.svg)](https://www.python.org/)

***This project will eventually be transferred to the [`IPUMS`](https://github.com/ipums) project space.***

This pacakge allows for the generation of temporal crosswalks of census geographic data built from the smallest intersecting units (atoms). Each row in a crosswalk represents a single atom and is comprised of a source ID (`geo+year+gj`), a target ID (`geo+year+gj`), and at least one column of weights. An example of a source ID is `bgp1990gj` (block group parts from 1990) and an example of a target ID is `tr1990gj` (tracts from 2010) — see [`notebooks/data-subset-sample-workflow-bgp1990tr2010.ipynb`](https://github.com/jGaboardi/nhgisxwalk/blob/master/notebooks/data-subset-sample-workflow-bgp1990tr2010.ipynb) for the `nhgis_bgp1990gj_to_tr1990gj` crosswalk extract of Delaware. The weights are the interpolated proportions of source attributes that are are calculated as being within the target units. For a description of the algorithmic workflow see the [General Crosswalk Construction Framework](https://github.com/jGaboardi/nhgisxwalk/blob/master/resources/frameworks/general-crosswalk-construction-framework.pdf). Data from 1990 poses a specific problem due to the US Census Bureau not explicitly including blocks with no population/housing units in the summary files (SF1). For a description of the algorithmic workflow in the 1990 "no data" scenarios see [Handling 1990 No-Data Blocks in Crosswalks](https://github.com/jGaboardi/nhgisxwalk/blob/master/resources/frameworks/handling-1990-no-data-blocks-in-crosswalks.pdf). For more information of the base crosswalks see their [technical details](https://www.nhgis.org/user-resources/geographic-crosswalks#details). For further description see Schroeder (2007).
This pacakge allows for the generation of temporal crosswalks of census geographic data built from the smallest intersecting units (atoms). Each row in a crosswalk represents a single atom and is comprised of a source ID (`geo+year+gj`), a target ID (`geo+year+gj`), and at least one column of weights. An example of a source ID is `bgp1990gj` (block group parts from 1990) and an example of a target ID is `tr1990gj` (tracts from 2010) — see [`notebooks/data-subset-sample-workflow-bgp1990tr2010.ipynb`](https://github.com/ipums/nhgisxwalk/blob/master/notebooks/data-subset-sample-workflow-bgp1990tr2010.ipynb) for the `nhgis_bgp1990gj_to_tr1990gj` crosswalk extract of Delaware. The weights are the interpolated proportions of source attributes that are are calculated as being within the target units. For a description of the algorithmic workflow see the [General Crosswalk Construction Framework](https://github.com/ipums/nhgisxwalk/blob/master/resources/frameworks/general-crosswalk-construction-framework.pdf). Data from 1990 poses a specific problem due to the US Census Bureau not explicitly including blocks with no population/housing units in the summary files (SF1). For a description of the algorithmic workflow in the 1990 "no data" scenarios see [Handling 1990 No-Data Blocks in Crosswalks](https://github.com/ipums/nhgisxwalk/blob/master/resources/frameworks/handling-1990-no-data-blocks-in-crosswalks.pdf). For more information of the base crosswalks see their [technical details](https://www.nhgis.org/user-resources/geographic-crosswalks#details). For further description see Schroeder (2007).

#### Currently supported crosswalks include:

Expand All @@ -35,41 +33,41 @@ This pacakge allows for the generation of temporal crosswalks of census geograph

## Examples

* [Proportionally-weighted Synthetic Atoms](https://github.com/jGaboardi/nhgisxwalk/blob/master/notebooks/weighted-portion-synthetic-atoms.ipynb)
* [Synthetic Example](https://github.com/jGaboardi/nhgisxwalk/blob/master/notebooks/synthetic-example.ipynb)
* Sample Workflow (see all [here](https://github.com/jGaboardi/nhgisxwalk/blob/master/notebooks)):
* [1990 block group parts to 2010 tracts](https://github.com/jGaboardi/nhgisxwalk/blob/master/notebooks/data-subset-sample-workflow-bgp1990tr2010.ipynb)
* [Proportionally-weighted Synthetic Atoms](https://github.com/ipums/nhgisxwalk/blob/master/notebooks/weighted-portion-synthetic-atoms.ipynb)
* [Synthetic Example](https://github.com/ipums/nhgisxwalk/blob/master/notebooks/synthetic-example.ipynb)
* Sample Workflow (see all [here](https://github.com/ipums/nhgisxwalk/blob/master/notebooks)):
* [1990 block group parts to 2010 tracts](https://github.com/ipums/nhgisxwalk/blob/master/notebooks/data-subset-sample-workflow-bgp1990tr2010.ipynb)

## Resources

* [Frequently Asked Questions](https://github.com/jGaboardi/nhgisxwalk/wiki/FAQ-&-Resources)
* [What are "block group parts" and how can I download them?](https://github.com/jGaboardi/nhgisxwalk/wiki/FAQ-&-Resources#what-are-block-group-parts-and-how-can-i-download-them)
* [How are the crosswalks sorted?](https://github.com/jGaboardi/nhgisxwalk/wiki/FAQ-&-Resources#how-are-the-crosswalks-sorted)
* [Frequently Asked Questions](https://github.com/ipums/nhgisxwalk/wiki/FAQ-&-Resources)
* [What are "block group parts" and how can I download them?](https://github.com/ipums/nhgisxwalk/wiki/FAQ-&-Resources#what-are-block-group-parts-and-how-can-i-download-them)
* [How are the crosswalks sorted?](https://github.com/ipums/nhgisxwalk/wiki/FAQ-&-Resources#how-are-the-crosswalks-sorted)

## Installation

Currently `nhgisxwalk` officially supports Python [3.6](https://docs.python.org/3.6/), [3.7](https://docs.python.org/3.7/), and [3.8](https://docs.python.org/3.8/). Please make sure that you are operating in a Python >= 3.6 environment. Install the most current development version of `nhgisxwalk` by running:

```
$ pip install git+https://github.com/jGaboardi/nhgisxwalk
$ pip install git+https://github.com/ipums/nhgisxwalk
```

## Contribute

NHGISXWALK is under active development and contributors are welcome. If you have any suggestions, feature requests, or bug reports, please open new [issues](https://github.com/jGaboardi/nhgisxwalk/issues) on GitHub. To submit patches, please review the `nhgisxwalk` [contributing guidelines](https://github.com/jGaboardi/nhgisxwalk/blob/master/.github/CONTRIBUTING.md) before opening a [pull request](https://github.com/jGaboardi/nhgisxwalk/pulls).
NHGISXWALK is under active development and contributors are welcome. If you have any suggestions, feature requests, or bug reports, please open new [issues](https://github.com/ipums/nhgisxwalk/issues) on GitHub. To submit patches, please review the `nhgisxwalk` [contributing guidelines](https://github.com/ipums/nhgisxwalk/blob/master/.github/CONTRIBUTING.md) before opening a [pull request](https://github.com/ipums/nhgisxwalk/pulls).

## Support

If you are having issues, please [create an issue](https://github.com/jGaboardi/nhgisxwalk/issues).
If you are having issues, please [create an issue](https://github.com/ipums/nhgisxwalk/issues).

## Citations
If you use `nhgisxwalk` in a scientific publication, we would appreciate using the following citations:
* **Steven Manson, Jonathan Schroeder, David Van Riper, and Steven Ruggles**. *IPUMS National Historical Geographic Information System: Version 14.0* [Database]. Minneapolis, MN: IPUMS. 2019. http://doi.org/10.18128/D050.V14.0
* **James Gaboardi**. *[jGaboardi/nhgisxwalk](https://github.com/jGaboardi/nhgisxwalk)*. Zenodo. 2020. [![DOI](https://zenodo.org/badge/259962549.svg)](https://zenodo.org/badge/latestdoi/259962549)
* **James Gaboardi**. *[jGaboardi/nhgisxwalk](https://github.com/ipums/nhgisxwalk)*. Zenodo. 2020. [![DOI](https://zenodo.org/badge/259962549.svg)](https://zenodo.org/badge/latestdoi/259962549)


## License
The package is licensed under the [MPL-2.0 License](https://github.com/jGaboardi/nhgisxwalk/blob/master/LICENSE).
The package is licensed under the [MPL-2.0 License](https://github.com/ipums/nhgisxwalk/blob/master/LICENSE).



Expand Down
Binary file modified resources/frameworks/general-crosswalk-construction-framework.pdf
Binary file not shown.
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,7 @@ \section{General steps}
\item Else if possible, derive $\mathbf{S}$ identifiers from source sub-zone data from step 2.
\item Else, obtain identifiers through other means...
\begin{enumerate}
\item 1990 block-group parts require some \href{https://github.com/jGaboardi/nhgisxwalk/blob/master/resources/frameworks/handling-1990-no-data-blocks-in-crosswalks.pdf}{special handling} because neither 4a nor 4b pertain to all BGPs.
\item 1990 block-group parts require some \href{https://github.com/ipums/nhgisxwalk/blob/master/resources/frameworks/handling-1990-no-data-blocks-in-crosswalks.pdf}{special handling} because neither 4a nor 4b pertain to all BGPs.
\item If we generate crosswalks for target zones that cannot be identified from block IDs (e.g., places, county subdivisions, etc.), we'll need to add a step to join block crosswalk to target-year block data that includes identifiers for the target zones.
\end{enumerate}
\item Where $\bm{s^\prime}$ is \textit{null} (= ``''), omit these dummy sub-zone atoms from subsequent computations.
Expand Down
Binary file modified resources/frameworks/handling-1990-no-data-blocks-in-crosswalks.pdf
Binary file not shown.
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@

\section{Problem}
\begin{itemize}
\item \href{https://github.com/jGaboardi/nhgisxwalk/blob/master/resources/frameworks/general-crosswalk-construction-framework.pdf}{General goal}: Generate a crosswalk from source zones to target zones by aggregating up from a block-to-block crosswalk.
\item \href{https://github.com/ipums/nhgisxwalk/blob/master/resources/frameworks/general-crosswalk-construction-framework.pdf}{General goal}: Generate a crosswalk from source zones to target zones by aggregating up from a block-to-block crosswalk.
\begin{itemize}
\item Ideally, the crosswalk should include at least one record for every source zone and at least one for every target zone, so all source and target zones are represented.
\end{itemize}
Expand All @@ -46,7 +46,7 @@ \section{Solution}

\item Construct initial BGP crosswalk using only the ``inhabited'' blocks--those in 1990 data table.
\begin{enumerate}
\item Follow \href{https://github.com/jGaboardi/nhgisxwalk/blob/master/resources/frameworks/general-crosswalk-construction-framework.pdf}{general steps} 1-8, using option 4a for target zones and 4b for source zones
\item Follow \href{https://github.com/ipums/nhgisxwalk/blob/master/resources/frameworks/general-crosswalk-construction-framework.pdf}{general steps} 1-8, using option 4a for target zones and 4b for source zones
\end{enumerate}

\item Construct BG crosswalk using \textit{only} no-data blocks (all counts are 0)
Expand Down
2 changes: 1 addition & 1 deletion setup.py
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ def setup_package():
description=description,
long_description=long_description,
long_description_content_type="text/markdown",
url="https://github.com/jGaboardi/" + package,
url="https://github.com/ipums/" + package,
download_url="https://pypi.org/project/" + package,
maintainer="James D. Gaboardi",
maintainer_email="jgaboardi@gmail.com",
Expand Down

0 comments on commit 2bae2cb

Please sign in to comment.