Data

Tools

Indexes

Applications

Experiments

Open Source Science

py3-us

A package for easily working with US and state metadata

https://github.com/unitedstates/python-us

Science Score: 36.0%

This score indicates how likely this project is to be science-related based on various indicators:

  • ○
    CITATION.cff file
  • ✓
    codemeta.json file
    Found codemeta.json file
  • ✓
    .zenodo.json file
    Found .zenodo.json file
  • ○
    DOI references
  • ○
    Academic publication links
  • ✓
    Committers with academic emails
    1 of 18 committers (5.6%) from academic institutions
  • ○
    Institutional organization owner
  • ○
    JOSS paper metadata
  • ○
    Scientific vocabulary similarity
    Low similarity (8.1%) to scientific vocabulary

Keywords

fips metadata states united-states
Last synced: 6 months ago · JSON representation

Repository

A package for easily working with US and state metadata

Basic Info
Statistics
  • Stars: 504
  • Watchers: 22
  • Forks: 71
  • Open Issues: 24
  • Releases: 1
Topics
fips metadata states united-states
Created over 13 years ago · Last pushed over 1 year ago
Metadata Files
Readme Contributing License

README.md

Workflow status badge

US: The Greatest Package in the World

A package for easily working with US and state metadata.

  • all US states and territories
  • postal abbreviations
  • Associated Press style abbreviations
  • FIPS codes
  • capitals
  • years of statehood
  • time zones
  • phonetic state name lookup
  • is contiguous or continental
  • URLs to shapefiles for state, census, congressional districts, counties, and census tracts

Installation

As per usual:

pip install us

Features

Easy access to state information:

```python

import us us.states.MD State:Maryland us.states.MD.fips '24' us.states.MD.name 'Maryland' us.states.MD.is_contiguous True ```

Includes territories too:

```python

us.states.VI.name 'Virgin Islands' us.states.VI.isterritory True us.states.MD.isterritory False ```

List of all (actual) states:

```python

us.states.STATES [State:Alabama, State:Alaska, State:Arizona, State:Arkansas, ... us.states.TERRITORIES [, State:Guam, , ... ```

And the whole shebang, if you want it:

```python

us.states.STATESANDTERRITORIES [State:Alabama, State:Alaska, , ... ```

For convenience, STATES, TERRITORIES, and STATES_AND_TERRITORIES can be accessed directly from the us module:

```python

us.states.STATES [State:Alabama, State:Alaska, State:Arizona, State:Arkansas, ... us.STATES [State:Alabama, State:Alaska, State:Arizona, State:Arkansas, ... ```

Some states like to be fancy and call themselves commonwealths:

```python

us.states.COMMONWEALTHS [State:Kentucky, State:Massachusetts, State:Pennsylvania, State:Virginia] ```

There's also a list of obsolete territories:

```python

us.states.OBSOLETE [State:Dakota, State:Orleans, ] ```

The state lookup method allows matching by FIPS code, abbreviation, and name:

```python

us.states.lookup('24') State:Maryland us.states.lookup('MD') State:Maryland us.states.lookup('md') State:Maryland us.states.lookup('maryland') State:Maryland ```

Get useful information:

```python

state = us.states.lookup('maryland') state.abbr 'MD' ```

And for those days that you just can't remember how to spell Mississippi, we've got phonetic name matching too:

```python

us.states.lookup('misisipi') State:Mississippi ```

Shapefiles

You want shapefiles too? As long as you want 2010 shapefiles, we've gotcha covered.

```

urls = us.states.MD.shapefileurls() sorted(urls.keys()) ['block', 'blockgroup', 'cd', 'county', 'state', 'tract', 'zcta'] urls['block'] 'https://www2.census.gov/geo/tiger/TIGER2010/TABBLOCK/2010/tl201024tabblock10.zip' ```

The shapefile_urls() method on the State object generates shapefile URLs for the following regions:

  • block
  • blockgroup
  • census tract (tract)
  • congressional district (cd)
  • county
  • state
  • zcta

Mappings

Mappings between various state attributes are a common need. The mapping() method will generate a lookup between two specified fields.

```python

us.states.mapping('fips', 'abbr') {'01': 'AL', '02': 'AK', '04': 'AZ', '05': 'AR', '06': 'CA', ... us.states.mapping('abbr', 'name') {'AL': 'Alabama', 'AK': 'Alaska', 'AZ': 'Arizona', 'AR': 'Arkansas', ... ```

This method uses us.STATES_AND_TERRITORIES as the default list of states it will create a mapping for, but this can be overridden by passing an additional states argument:

```python

us.states.mapping('fips', 'abbr', states=[us.states.DC]) {'11': 'DC'} ```

DC should be granted statehood

Washington, DC does not appear in us.STATES or any of the related state lists, but is often treated as a state in practice and should be granted statehood anyway. DC can be automatically included in these lists by setting a DC_STATEHOOD environment variable to any truthy value before importing this package.

DC_STATEHOOD=1

CLI

When you need to know state information RIGHT AWAY, there's the states script.

``` $ states md

*** The great state of Maryland (MD) ***

FIPS code: 24

other attributes:
  ap_abbr: Md.
  capital: Annapolis
  capital_tz: America/New_York
  is_contiguous: True
  is_continental: True
  is_obsolete: False
  name_metaphone: MRLNT
  statehood_year: 1788
  time_zones: America/New_York

shapefiles:
  tract: https://www2.census.gov/geo/tiger/TIGER2010/TRACT/2010/tl_2010_24_tract10.zip
  cd: https://www2.census.gov/geo/tiger/TIGER2010/CD/111/tl_2010_24_cd111.zip
  county: https://www2.census.gov/geo/tiger/TIGER2010/COUNTY/2010/tl_2010_24_county10.zip
  state: https://www2.census.gov/geo/tiger/TIGER2010/STATE/2010/tl_2010_24_state10.zip
  zcta: https://www2.census.gov/geo/tiger/TIGER2010/ZCTA5/2010/tl_2010_24_zcta510.zip
  block: https://www2.census.gov/geo/tiger/TIGER2010/TABBLOCK/2010/tl_2010_24_tabblock10.zip
  blockgroup: https://www2.census.gov/geo/tiger/TIGER2010/BG/2010/tl_2010_24_bg10.zip

```

Running Tests

GitHub Actions are set up to automatically run unit tests against any new commits to the repo. To run these tests yourself:

pip install -e .[dev] pytest .

Changelog

3.2.0

3.1.1

  • add support for Python 3.11
  • upgrade to jellyfish 0.11.2

3.0.0

  • upgrade to jellyfish 0.7.2
  • drop support for Python 2.7
  • add us.states.COMMONWEALTHS list of states that call themselves commonwealths 🎩
  • add DC to STATES, STATESANDTERRITORIES, STATESCONTIGUOUS, or STATESCONTINENTAL when DC_STATEHOOD environment variable is set
  • remove region parameter from shapefile_urls() method
  • mapping() no longer includes obsolete states
  • added type annotations

2.0.2

  • restore DC in lookup() and mapping()

2.0.1

  • fix Python 2.7 tests that ran with Python 3
  • revert to jellyfish 0.6.1 to support Python 2.7

2.0.0

  • add support for Python 3.7 and 3.8
  • remove support for Python 3.4 and 3.5
  • remove pickled objects and database in favor of pure Python code
  • upgrade jellyfish to 0.7.2 to fix metaphone bug
  • fixes for IN, KY, ND, and NM timezones
  • set AZ timezone to America/Phoenix
  • obsolete entries are no longer included in STATESANDTERRITORIES
  • DC is no longer included in STATES, STATESANDTERRITORIES, STATESCONTIGUOUS, or STATESCONTINENTAL

1.0.0

  • full Python 3.6 support
  • use pytest

0.10.0

  • upgrade jellyfish to 0.5.3 to fix metaphone bug

0.9.0

  • add information on whether a state is contiguous and/or continental, thanks to chebee7i

0.8.0

0.7.1

  • upgrade to jellyfish 0.5.1 to fix metaphone case bug

0.7

0.6

  • add AP-style state abbreviations
  • use jellyfish instead of Metaphone package
  • update to requests v1.0.4 for tests
  • Python 3.3 compatibility

0.5

  • fix state abbreviation for Nebraska

0.4

  • add state capitals
  • add years of statehood

0.3

  • add mapping method to generate dicts of arbitrary fields

0.2

  • add command line script for quick access to state data

0.1

  • initial release
  • state names and abbreviations
  • FIPS codes
  • lookup() method
  • shapefile URLs for various regions

Owner

  • Name: @unitedstates
  • Login: unitedstates
  • Kind: organization
  • Location: The United States

A shared commons of data and tools for the United States. Made by the public, used by the public.

GitHub Events

Total
  • Issues event: 1
  • Watch event: 22
  • Issue comment event: 2
  • Pull request event: 2
  • Fork event: 3
Last Year
  • Issues event: 1
  • Watch event: 22
  • Issue comment event: 2
  • Pull request event: 2
  • Fork event: 3

Committers

Last synced: 7 months ago

All Time
  • Total Commits: 112
  • Total Committers: 18
  • Avg Commits per committer: 6.222
  • Development Distribution Score (DDS): 0.339
Past Year
  • Commits: 0
  • Committers: 0
  • Avg Commits per committer: 0.0
  • Development Distribution Score (DDS): 0.0
Top Committers
Name Email Commits
Jeremy Carbaugh j****h@g****m 74
Miles Watkins m****s@g****m 9
Jeremy Carbaugh j****y@i****o 7
David Gilman d****n@a****m 4
bchartoff b****f@g****m 3
Pedro Camargo c@m****o 2
chebee7i c****i@g****m 2
Jacob Fenton j****n@s****m 1
pveigadecamargo p****o@a****v 1
Adam J. Stewart a****6@g****m 1
Alexander Kulakov h****s@g****m 1
Andrey Mozgunov a****z@y****u 1
Jeff Paine J****e 1
Paul Hawk h****l@g****m 1
Sergii Bondarenko s****o@p****m 1
Tyler Garner g****b@g****m 1
Zohar Jackson J****i 1
owenam o****m@g****m 1
Committer Domains (Top 20 + Academic)
pfizer.com: 1 ya.ru: 1 anl.gov: 1 sunlightfoundation.com: 1 margo.co: 1 aidentified.com: 1 isl.co: 1

Issues and Pull Requests

Last synced: 6 months ago

All Time
  • Total issues: 44
  • Total pull requests: 42
  • Average time to close issues: about 1 year
  • Average time to close pull requests: 10 months
  • Total issue authors: 40
  • Total pull request authors: 28
  • Average comments per issue: 2.41
  • Average comments per pull request: 1.57
  • Merged pull requests: 22
  • Bot issues: 0
  • Bot pull requests: 4
Past Year
  • Issues: 3
  • Pull requests: 5
  • Average time to close issues: N/A
  • Average time to close pull requests: about 2 hours
  • Issue authors: 3
  • Pull request authors: 4
  • Average comments per issue: 0.33
  • Average comments per pull request: 0.8
  • Merged pull requests: 2
  • Bot issues: 0
  • Bot pull requests: 0
View more stats
Top Authors
Issue Authors
  • AlJohri (2)
  • MaxGhenis (2)
  • paultag (2)
  • coreyb42 (2)
  • mcorrigan (1)
  • msp1kpj (1)
  • rjskene (1)
  • rposborne (1)
  • msmall318 (1)
  • jbrockmendel (1)
  • alex-kaigorodov (1)
  • egnor (1)
  • dmoghavem (1)
  • mileswwatkins (1)
  • NickCrews (1)
Pull Request Authors
  • jcarbaugh (9)
  • dependabot[bot] (7)
  • mileswwatkins (3)
  • dgilmanAIDENTIFIED (3)
  • owenam (2)
  • BR0kEN- (2)
  • KlaasH (2)
  • weirdestnerd (2)
  • johnw-bluemark (2)
  • mfilenko (2)
  • kavigupta (2)
  • pedrocamargo (2)
  • saun4app (1)
  • bchartoff (1)
  • momyc (1)
Top Labels
Issue Labels
bug (1)
Pull Request Labels
dependencies (7)

Packages

  • Total packages: 4
  • Total downloads:
    • pypi 787,686 last-month
  • Total docker downloads: 547
  • Total dependent packages: 22
    (may contain duplicates)
  • Total dependent repositories: 388
    (may contain duplicates)
  • Total versions: 31
  • Total maintainers: 2
pypi.org: us

US state meta information and other fun stuff

  • Homepage: https://github.com/unitedstates/python-us/
  • Documentation: https://us.readthedocs.io/
  • License: Copyright (c) 2014, Sunlight Labs All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of Sunlight Labs nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  • Latest release: 3.2.0
    published over 1 year ago
  • Versions: 17
  • Dependent Packages: 20
  • Dependent Repositories: 387
  • Downloads: 787,686 Last month
  • Docker Downloads: 547
Rankings
Downloads: 0.4%
Dependent repos count: 0.7%
Dependent packages count: 0.8%
Average: 2.0%
Docker downloads count: 2.1%
Stargazers count: 2.9%
Forks count: 4.7%
Maintainers (1)
jcarbaugh
Last synced: 6 months ago
alpine-edge: py3-us

US state meta information and other fun stuff

  • Versions: 6
  • Dependent Packages: 0
  • Dependent Repositories: 0
Rankings
Dependent repos count: 0.0%
Average: 10.6%
Stargazers count: 13.2%
Dependent packages count: 14.6%
Forks count: 14.7%
Maintainers (1)
fabian@affolter-engineering.ch
Last synced: 6 months ago
alpine-edge: py3-us-pyc

Precompiled Python bytecode for py3-us

  • Versions: 5
  • Dependent Packages: 0
  • Dependent Repositories: 0
Rankings
Dependent repos count: 0.0%
Average: 10.7%
Dependent packages count: 13.3%
Stargazers count: 13.9%
Forks count: 15.6%
Maintainers (1)
fabian@affolter-engineering.ch
Last synced: 6 months ago
conda-forge.org: us
  • Versions: 3
  • Dependent Packages: 2
  • Dependent Repositories: 1
Rankings
Stargazers count: 18.5%
Dependent packages count: 19.6%
Average: 21.2%
Forks count: 22.4%
Dependent repos count: 24.4%
Last synced: 6 months ago

Dependencies

Pipfile pypi
  • black ==19.10b0 develop
  • flake8 * develop
  • importlib_metadata * develop
  • pytest * develop
  • pytz * develop
  • requests <3.0 develop
  • jellyfish ==0.7.2
Pipfile.lock pypi
  • appdirs ==1.4.3 develop
  • attrs ==19.3.0 develop
  • black ==19.10b0 develop
  • certifi ==2020.4.5.1 develop
  • chardet ==3.0.4 develop
  • click ==7.1.1 develop
  • entrypoints ==0.3 develop
  • flake8 ==3.7.9 develop
  • idna ==2.9 develop
  • importlib-metadata ==1.6.0 develop
  • mccabe ==0.6.1 develop
  • more-itertools ==8.2.0 develop
  • packaging ==20.3 develop
  • pathspec ==0.8.0 develop
  • pluggy ==0.13.1 develop
  • py ==1.8.1 develop
  • pycodestyle ==2.5.0 develop
  • pyflakes ==2.1.1 develop
  • pyparsing ==3.0.0a1 develop
  • pytest ==5.4.1 develop
  • pytz ==2019.3 develop
  • regex ==2020.4.4 develop
  • requests ==2.23.0 develop
  • six ==1.14.0 develop
  • toml ==0.10.0 develop
  • typed-ast ==1.4.1 develop
  • urllib3 ==1.25.9 develop
  • wcwidth ==0.1.9 develop
  • zipp ==3.1.0 develop
  • jellyfish ==0.7.2
setup.py pypi
  • jellyfish ==0.7.2
.github/workflows/pythonpackage.yml actions
  • actions/checkout v1 composite
  • actions/setup-python v1 composite
  • dschep/install-pipenv-action v1 composite