https://github.com/ejfox/election-helpers
A collection of resources, tools, and patterns for election data analysis and viz
https://github.com/ejfox/election-helpers
data elections helpers
Last synced: about 1 year ago
JSON representation
A collection of resources, tools, and patterns for election data analysis and viz
- Host: GitHub
- URL: https://github.com/ejfox/election-helpers
- Owner: ejfox
- Created: 2022-07-04T16:01:43.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2024-02-05T17:09:14.000Z (over 2 years ago)
- Last Synced: 2025-04-06T04:18:00.083Z (about 1 year ago)
- Topics: data, elections, helpers
- Language: JavaScript
- Homepage: https://ejfox.github.io/election-helpers/global.html
- Size: 15.3 MB
- Stars: 3
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# Election Helpers
## Read [docs.md](https://github.com/ejfox/election-helpers/blob/master/docs.md) or [GH pages](https://ejfox.github.io/election-helpers/global.html) for documentation
[View on NPM](https://www.npmjs.com/package/election-helpers)
--
## Constants
-
stateNameHash ⇒string -
usBounds :USBounds -
The bounds of the United States.
## Functions
-
partyNameNormalizer(partyNameString) ⇒string -
Normalizes a party name string to a standardized format.
-
stateAbbrToName(stateAbbr) ⇒string -
getStateAbbrFromStateFips(stateFips) ⇒string -
getStateCodeFromCountyFips(countyFips) ⇒string -
Get the state code from the county fips string
-
candidateVotePercentage(candidateVote, totalVotes) ⇒number -
Given the absolute number of votes a candidate has received, and the total number of votes in the election, returns the percentage of votes the candidate has received.
-
sortCandidatesByVotes(candidates, sortFunction) ⇒Array -
Given an array of candidate objects, returns a sorted array of candidate objects, sorted by the number of votes they have received with the specified sort function.
-
stateFipsToName(stateFips) ⇒string -
stateAbbrToFips(stateAbbreviation) ⇒string -
Get the state fips code from the abbreviation, like 'NY' to '36'
-
stateNameToFips(stateName) ⇒string -
boundariesAvailableForRaceType(raceType) ⇒array - isBoundaryAvailableForRaceType(raceType, boundaryType)
## Typedefs
-
USBounds :Object -
Represents the bounds of the United States.
-
StatePlaneProjections :Object -
Represents the state planes and bounds for every state.
-
County :Object -
An array of county names with their corresponding FIPS codes.
## stateNameHash ⇒ string
**Kind**: global constant
**Returns**: string - - The state name
**Throws**:
- Error - If the state fips code is invalid.
| Param | Type | Description |
| --- | --- | --- |
| stateFips | string | The state fips code. |
**Example**
```js
stateNameHash['01']
// returns 'Alabama'
```
## usBounds : [USBounds](#USBounds)
The bounds of the United States.
## partyNameNormalizer(partyNameString) ⇒ string
Normalizes a party name string to a standardized format.
**Kind**: global function
**Returns**: string - The normalized party name.
| Param | Type | Description |
| --- | --- | --- |
| partyNameString | string | The party name string to be normalized. |
**Example**
```js
const partyName = partyNameNormalizer('R') // returns 'rep'
const partyName = partyNameNormalizer('REP') // returns 'rep'
const partyName = partyNameNormalizer('Republican') // returns 'rep'
const partyName = partyNameNormalizer('republican') // returns 'rep'
```
## stateAbbrToName(stateAbbr) ⇒ string
**Kind**: global function
**Returns**: string - - The state name
**Throws**:
- Error - If the state abbreviation is invalid.
| Param | Type | Description |
| --- | --- | --- |
| stateAbbr | string | Two letter state abbreviation |
**Example**
```js
getStateNameFromStateAbbr('AL')
// returns 'Alabama'
```
## getStateAbbrFromStateFips(stateFips) ⇒ string
**Kind**: global function
**Returns**: string - - The state abbreviation
**Throws**:
- Error - If the state fips code is invalid.
| Param | Type | Description |
| --- | --- | --- |
| stateFips | string | The state fips code. |
**Example**
```js
getStateAbbrFromStateFips('01')
// returns 'AL'
```
**Example**
```js
getStateAbbrFromStateFips('36')
// returns 'NY'
```
**Example**
```js
getStateAbbrFromStateFips('XX')
// throws an error
```
## getStateCodeFromCountyFips(countyFips) ⇒ string
Get the state code from the county fips string
**Kind**: global function
**Returns**: string - - The state fips code.
| Param | Type | Description |
| --- | --- | --- |
| countyFips | string | The county fips code. |
**Example**
```js
getStateCodeFromCountyFips('01001')
// returns '01'
```
**Example**
```js
getStateCodeFromCountyFips(01000)
// throws Error
```
**Example**
```js
getStateCodeFromCountyFips('01')
// throws Error
```
## candidateVotePercentage(candidateVote, totalVotes) ⇒ number
Given the absolute number of votes a candidate has received, and the total number of votes in the election, returns the percentage of votes the candidate has received.
**Kind**: global function
**Returns**: number - - The percentage of votes the candidate has received.
| Param | Type | Description |
| --- | --- | --- |
| candidateVote | number | The number of votes the candidate has received. |
| totalVotes | number | The total number of votes in the election. |
**Example**
```js
getPercentageOfVotes(100, 200)
// returns 50
```
## sortCandidatesByVotes(candidates, sortFunction) ⇒ Array
Given an array of candidate objects, returns a sorted array of candidate objects, sorted by the number of votes they have received with the specified sort function.
**Kind**: global function
**Returns**: Array - - A sorted array of candidate objects.
**Throws**:
- Error - If the candidates array is invalid.
| Param | Type | Description |
| --- | --- | --- |
| candidates | Array | An array of candidate objects. |
| sortFunction | function | The function to use to sort the candidates (like d3.descending) |
## stateFipsToName(stateFips) ⇒ string
**Kind**: global function
**Returns**: string - - The state name
**Throws**:
- Error - If the state fips code is invalid.
| Param | Type |
| --- | --- |
| stateFips | string |
**Example**
```js
stateFipsToName('01')
// returns 'Alabama'
```
## stateAbbrToFips(stateAbbreviation) ⇒ string
Get the state fips code from the abbreviation, like 'NY' to '36'
**Kind**: global function
**Returns**: string - - The state fips code.
| Param | Type | Description |
| --- | --- | --- |
| stateAbbreviation | string | The state abbreviation. |
**Example**
```js
getStateFipsFromAbbreviation('NY')
// returns '36'
```
## stateNameToFips(stateName) ⇒ string
**Kind**: global function
**Returns**: string - - The state fips code
**Throws**:
- Error - If the state name is invalid.
| Param | Type |
| --- | --- |
| stateName | string |
**Example**
```js
getStateFipsFromStateName('Alabama')
// returns '01'
```
## boundariesAvailableForRaceType(raceType) ⇒ array
**Kind**: global function
**Returns**: array - - An array of the available district types
| Param | Type |
| --- | --- |
| raceType | string |
**Example**
```js
boundariesAvailableForRaceType('president')
// returns ['state', 'county']
```
**Example**
```js
boundariesAvailableForRaceType('senate')
// returns ['state']
```
**Example**
```js
boundariesAvailableForRaceType('house')
// returns ['district']
```
**Example**
```js
boundariesAvailableForRaceType(2016)
// returns null
```
## isBoundaryAvailableForRaceType(raceType, boundaryType)
**Kind**: global function
| Param | Type | Description |
| --- | --- | --- |
| raceType | string | The race type, like 'president', 'house', or 'senate' |
| boundaryType | string | The type of boundary, like 'county', 'state', or 'district' |
**Example**
```js
isBoundaryAvailableForRaceType('president', 'county')
// returns true
```
**Example**
```js
isBoundaryAvailableForRaceType('president', 'state')
// returns true
```
**Example**
```js
isBoundaryAvailableForRaceType('president', 'district')
// returns false
```
## USBounds : Object
Represents the bounds of the United States.
**Kind**: global typedef
**Properties**
| Name | Type | Description |
| --- | --- | --- |
| type | string | The type of the feature collection. |
| features | Array.<Object> | The features of the collection. |
## StatePlaneProjections : Object
Represents the state planes and bounds for every state.
**Kind**: global typedef
**Properties**
| Name | Type | Description |
| --- | --- | --- |
| proj | string | The projection |
| rotate | Array.<number> | The rotation of the projection. |
| bounds | Array.<number> | The bounds of the projection. |
| parallels | Array.<number> | The parallels of the projection. |
## County : Object
An array of county names with their corresponding FIPS codes.
**Kind**: global typedef
**Properties**
| Name | Type | Description |
| --- | --- | --- |
| fips_code | number | The FIPS code of the county. |
| name | string | The name of the county. |