Merge pull request #742 from ElectionDataAnalysis/issue730-get-started

Issue730 get started

Author: sfsinger19103

README.md

@@ -10,13 +10,13 @@ This repository provides tools for consolidation and analysis of raw election re
    * json (following NIST Election Results Reporting Common Data Format V2)
  * Analysis: 
    * Curates one-county outliers of interest
-   * Calculates difference-in-difference for reaults available by vote type
+   * 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.
+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.
 
 # How to Contribute Code
 Please contribute code that works in python 3.9, with the package versions specified in [requirements.txt](requirements.txt). We follow the [black](https://pypi.org/project/black/) format.
@@ -36,9 +36,15 @@ If you are a potential end user -- an election official, political scientist or
 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). 
 
 # 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_Dataloading_Session.md)
+   * Detailed [User Guide](docs/User_Guide.md)
+ * for developers
+   * [Information about the code](docs/About_the_Code.md)
+   * [Information about the tests](docs/Testing_Code_with_pytest.md)
+   
 # Contributors
  * [Stephanie Singer](http://campaignscientific.com/), Hatfield School of Government (Portland State University), former Chair, Philadelphia County Board of Elections
  * Janaki Raghuram Srungavarapu, Hatfield School of Government (Portland State University)
@@ -48,7 +54,7 @@ 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.

docs/Sample_Dataloading_Session.md

@@ -0,0 +1,34 @@
+# Results files for dataloading tests
+The dataloading tests rely on having some raw results data to load. And the results data should be various enough to test the various components of the data-loading code. In other words, effective testing requires a reasonable variety of input files. The repository does not contain sufficient results data for testing. A test set is available in a separate repository, [***TODO](***TODO). If [test_dataloading_by_ej.py](../tests/dataloading_tests/test_dataloading_by_ej.py) does not find results data, it will default to downloading the files from that repository.
+
+# Sample Testing Session
+
+## Directory and File Structure
+ Call the tests from a working directory with the following structure and files:
+```
+.
++-- input_results
+|   +-- Alabama
+|   |   + <Alabama results file>
+|   |   + <maybe another Alabama results file>
+|   +-- Alaska
+|   |   + <Alaska results file>
+|   +-- American-Samoa
+|   |   + <American Samoa results file>
+|   +-- <etc>
+|
++-- reports_and_plots
++-- run_time.ini
+```
+The file `run_time.ini` can be the same as in the [Sample Dataloading Session](Sample_Dataloading_Session.md). 
+
+## Note on dataloading tests
+The tests in [test_dataloading_by_ej.py](../tests/dataloading_tests/test_dataloading_by_ej.py) will attempt to load all raw results files in `input_results` that are specified by some file in the [`ini_file_for_results` directory](../src/ini_files_for_results). You can check which jurisdictions had files loaded:
+ * if the test is successful, look at the `compare_*` directories in the `reports_and_plots` directory.
+ * if the test fails, look in the output from the test.
+
+## Running the tests
+You will need pytest to be installed on your system (see [pytest installation instructions](https://docs.pytest.org/en/6.2.x/getting-started.html) if necessary). Commands are run from the shell
+ * dataloading routines: `pytest ~/PycharmProjects/electiondata/tests/dataloading_tests`
+ * jurisdiction prep routines: `pytest ~/PycharmProjects/electiondata/tests/jurisdiction_prepper_tests/`
+ * analysis routines: `pytest ~/PycharmProjects/electiondata/tests/analyzer_tests/  `