Merge pull request #732 from ElectionDataAnalysis/feature-version-2.0.1

Version 2.0.1

Author: sfsinger19103

CODE_OF_CONDUCT.md

@@ -0,0 +1,14 @@
+
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the [Contributor Covenant](http:contributor-covenant.org), version 1.0.0, available at https://www.contributor-covenant.org/version/1/0/0/code-of-conduct.html

CONTACT_US.md

@@ -0,0 +1 @@
+Contact [Stephanie Singer](http://symmetrysinger.com/index.php?id=contact). 

CONTRIBUTING.md

@@ -0,0 +1,73 @@
+Please note that electiondata is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). 
+By contributing to this project, 
+you agree to abide by its terms.
+
+# Contributing to electiondata development
+
+## Report a Problem
+
+To report a problem, [file an issue on GitHub](https://github.com/ElectionDataAnalysis/electiondata/issues). When filing an issue, the most important thing is to include a minimal 
+reproducible example so that we can quickly verify the problem, and then figure 
+out how to fix it. Please include
+
+1.  Link to the exact version of electiondata you are using.
+  
+1.  A copy of your working directory, following the model in the [Sample Session](docs/Sample_Session.md). Include:
+    * a `run_time.ini` file (Feel free to redact the login information for your local postgres instance.) 
+    * all subdirectories referenced in the `run_time.ini` file. 
+    * If the issue involves loading a particular results data file, be sure to include that file. If possible, avoid submitting large results files -- if your file is precinct-based, for example, see if you can demonstrate the issue with a truncated results file.
+    * all error and warnings files placed by the system into the `reports_and_plots_dir` specified in `run_time.ini`.
+  
+1.  A transcript of the python session, where python is called from the working directory.
+
+You can check you have actually made a reproducible example by:
+1. creating a virtual environment
+1. installing the indicated version of electiondata
+1. if files or folders were moved by the system to the archive directory, move them back to the input directory, removing any timestamps from directory names.
+1. navigating to the working directory, calling python, and producing the behavior in question.
+
+## Revise the Code
+
+To contribute a change to `electiondata` follow these steps:
+
+1. Create a branch in git and make your changes.
+1. Run unit tests to check for broken functionality. See [pytest instructions](docs/Testing_Code_with_pytest.md).
+1. Run python `black` to format your code to our standard.
+1. Push branch to github and issue pull request (PR).
+1. Discuss the pull request.
+1. Iterate until either we accept the PR or decide that it's not
+   a good fit for `electiondata`.
+
+Each of these steps are described in more detail below. This might feel 
+overwhelming the first time you get set up, but it gets easier with practice. 
+If you get stuck at any point, feel free to [contact us](CONTACT_US.md) for help.
+
+If you're not familiar with git or github, please read a tutorial such as [https://realpython.com/python-git-github-intro/](https://realpython.com/python-git-github-intro/).
+
+
+Pull requests will be evaluated against this checklist:
+
+1.  __Motivation__. Your pull request should clearly and concisely motivate the
+    need for change.
+
+1.  __Only related changes__. Before you submit your pull request, please
+    check to make sure that you haven't accidentally included any unrelated
+    changes. These make it harder to see exactly what's changed, and to
+    evaluate any unexpected side effects.
+
+    Each PR corresponds to a git branch, so if you expect to submit
+    multiple changes make sure to create multiple branches. If you have
+    multiple changes that depend on each other, start with the first one
+    and don't submit any others until the first one has been processed.
+    
+1.  __Documentation__ Any new parameters or a new functions must be documented both in the code and in the [User Guide](docs/User_Guide.md), [Sample Session](docs/Sample_Session.md) and any other relevant documents. If you're adding a new graphical or analytical feature, please add a short example to [Sample Session](docs/Sample_Session.md).
+
+1.  __Tests__ If fixing a bug or adding a new feature to a non-graphical function,
+    please add a [pytest](https://docs.pytest.org) unit test. Document the new test in [pytest instructions](docs/Testing_Code_with_pytest.md).
+
+This seems like a lot of work but don't worry if your pull request isn't perfect.
+Unless you've submitted a few in the
+past it's unlikely that your pull request will be accepted as is. All PRs require
+review and approval from at least one member of the `electiondata` development team 
+before merge.
+

MANIFEST.in

@@ -1,37 +1,31 @@
 [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/4078/badge)](https://bestpractices.coreinfrastructure.org/projects/4078)
 
-
 # Overview
-This repository hopes to provide reliable tools for consolidation and analysis of raw election results from the most reliable sources -- the election agencies themselves. 
+This repository provides tools for consolidation and analysis of raw election results from the most reliable sources -- the election agencies themselves. 
  * Consolidation: take as input election results files from a wide variety of sources and load the data into a relational database
- * Export: create tab-separated flat export files of results sets rolled up to any desired intermediate geography (e.g., by county, or by congressional district)
- * Analysis: provide a variety of analysis tools
- * Visualization: provide a variety of visualization tools.
+ * Export: create consistent-format export files of results sets rolled up to any desired intermediate geography
+   * tabular (tab-separated text)
+   * xml (following NIST Election Results Reporting Common Data Format V2)
+   * json (following NIST Election Results Reporting Common Data Format V2)
+ * Analysis: 
+   * Curates one-county outliers of interest
+   * Calculates difference-in-difference for results available by vote type
+ * Visualization: 
+   * Scatter plots
+   * Bar charts
 
 # Target Audience
-This system is intended to be of use to candidates and campaigns, election officials, students of politics and elections, and anyone else who is interested in assembling and understanding election results.
-
-# How to Contribute Code
-Please contribute code that works in python 3.7, with the package versions specified in [requirements.txt](requirements.txt). We follow the [black](https://pypi.org/project/black/) format.
-
-# How to Help in Other Ways
-If you have skills to contribute to building the system, we can definitely use your help:
- * Creating visualizations
- * Importing and exporting data via xml feeds
- * Preparing for intake of specific states' results files
- * Managing collection of data files in real time
- * Writing documentation
- * Merging other data sets of interest (e.g., demographics)
- * Building our open source community
- * What else? Let us know!
- 
-If you are a potential end user -- an election official, political scientist or campaign consultant, for instance -- we would love to talk with you about what you want to from this system.
- 
-If you are interested in contributing, or just staying updated on the progress of this project, please [contact Stephanie Singer](http://symmetrysinger.com/index.php?id=contact). 
+This system is intended to be of use to news media, campaigns, election officials, students of politics and elections, and anyone else who is interested in assembling and understanding election results. If you have ideas for using this system or if you would like to stay updated on the progress of this project, [we'd like to hear from you](CONTACT_US.md). 
 
 # How to use the app
-Detailed instructions can be found [here](docs/User_Guide.md).
-  
+See [documentation directory](docs), which includes
+ * for users
+   * [Installation instructions](docs/Installation.md)
+   * Instructions for a [sample dataloading session](docs/Sample_Session.md)
+   * Detailed [User Guide](docs/User_Guide.md)
+ 
+# How to Contribute Code
+See [CONTRIBUTING.MD](CONTRIBUTING.md).
 
 # Contributors
  * [Stephanie Singer](http://campaignscientific.com/), Hatfield School of Government (Portland State University), former Chair, Philadelphia County Board of Elections
@@ -42,9 +36,10 @@ Detailed instructions can be found [here](docs/User_Guide.md).
  * Elliot Meyerson
 
 # Funding
-Funding provided October 2019 - September 2021 by the National Science Foundation
+Funding provided October 2019 - November 2021 by the National Science Foundation
  * Award #1936809, "EAGER: Data Science for Election Verification" 
  * Award #2027089, "RAPID: Election Result Anomaly Detection for 2020"
+Data collection and consolidation for the 2020 US General Election funded in part by the Verified Voting Foundation.
 
 # License
 See [LICENSE.md](./LICENSE.md)

README.md

@@ -0,0 +1,25 @@
+# Installation Instructions
+
+## Environment
+You will need:
+ * `python3.9` 
+ * `postgresql`
+ * all python packages given in [requirements.txt](../requirements.txt), and any packages those packages may require
+
+Not absolutely required, but recommended, is a package manager, such as `homebrew` for macOS.
+
+### python3.9   
+If your environment has a `python` command without a specified version, that `python` may or may not point to `python3.9`. In linux-flavored shells, you can check the version with the command `python --version`. Similarly, your system may have a `python3` command, whose version can be checked with `python3 --version`.
+
+### postgresql
+If postgresql is present, the command `postgres --version` will yield the version number; otherwise the command will fail. The `electiondata` package has been tested with postgres version 13, but probably any reasonably recent version will do. If `postgresql` is not present, you should be able to install it with any reasonable package manager. (On macOS with package manager `homebrew`, use the command `brew install postgresql`) The default values you will need to connect to your `postgresql` instance are:
+ * host: `localhost`
+ * port: `5432`
+ * user: `postgres`
+ * password: (leave the password blank)
+
+### python packages
+To install the required packages, run `python3.9 -m pip install -r requirements.txt` from the [root folder of the repository](../).  Because some of the required packages have requirements of their own, which may or may not be installed already, your system prompt you to install some other packages. If so, install the suggested packages and try `python3.9 -m pip install -r requirements.txt` again.
+
+## Installation
+From the [root folder of the repository](../) run `python3.9 setup.py install`. (You may be able to use `python setup.py install` or `python3 setup.py install` instead, if those point to `python3.9`, as described above.)