Package: rcvformats
RCV FormatsRCV Formats helps programmers and researchers build tools that analyze the results of a Ranked-Choice Voting election without having to support the many file formats used to report RCV results.RCV Formats converts data from several sources into a standardized format. It supports both python and command-line toolsCurrently supported input formats are:The Universal RCV Tabulator JSON formatThe Opavote JSON formatThe ElectionBuddy CSV formatThe Dominion XLSX formatThe Dominion TXT formatAs well as the Dominion first-round-only XML format (used in Alaska), which contains the first rounds of several elections. All other converters contain the results of just one election per file.The standardized output format is theUniversal RCV Tabulator JSON. To understand this format, look atexamplesorthe jsonschema.DemoCommand-linercvformatsconvert-i<input-filename>-o<output-filename>Pythonfromrcvformats.conversions.automaticimportAutomaticConverterstandardized_data=AutomaticConverter().convert_to_ut(input_filename)InstallationInstall the library via pip:pip3 install rcvformatsConvert to Standardized FormatYou can convert from any of the supported formats.
Use this functionality to support a wide array of input data while only writing code to support a single format.Command-linercvformatsconvert-i<input-filename>-o<output-filename>The bash script always uses the automatic converter.Pythonfromrcvformats.conversionsimportelectionbuddyconverter=electionbuddy.ElectionBuddyConverter()try:converter.convert_to_ut(filename)exceptExceptionase:print("Errors: ",e)Valid converters are:fromrcvformats.converters.automaticimportAutomaticConverterfromrcvformats.conversions.dominion_txtimportDominionTxtConverterfromrcvformats.conversions.dominion_xlsximportDominionXlsxConverterfromrcvformats.conversions.electionbuddyimportElectionBuddyConverterfromrcvformats.conversions.opavoteimportOpavoteConverterThe AutomaticConverter checks if the file matches any of the available schemas, and if it finds a matching schema, it runs the corresponding conversion (if a conversion is needed at all).Schema ValidationValidate that your file is supported by RCVFormats.Validation is only on the structure of the data, not on its contents: it is possible for a validly-formatted file to still contain invalid data.Command-linercvformatsvalidate-i<input-filename>-s<schema-type>Valid schema validators on the command line are 'eb' (for electionbuddy files),ov10(for opavote files pre-2022),ov11(for opavote files post-2022),ut(for universal tabulator files).
Dominion does not have a schema validation currently.Pythonfromrcvformats.schemasimportuniversaltabulatorschema=universaltabulator.SchemaV0()is_valid=schema.validate('/path/to/file.json')ifnotis_valid:print(schema.last_error())Valid schema validators for python are:fromrcvformats.schemas.electionbuddyimportSchemaV0fromrcvformats.schemas.opavoteimportSchemaV1_0fromrcvformats.schemas.universaltabulatorimportSchemaV0Fill in missing transfer dataTransfer data is useful to determine where votes went when a candidate was eliminated, or when a candidate was elected and had surplus votes (in STV).If you have a file format that does not have transfer data, there are three options: you can leave it out entirely, you can assign transfers proportionally to each eliminated candidate, or you can assign only the transfers that are unambiguous.
We recommend the last option, which prepares transfer data for any round that does not involve batch elimination.
The second option results in fake data which cannot be relied upon for any results reporting or analyses.Multi-convertersCallDominionMultiConverter.explode_to_files(fileObject), which will return a dictionary mapping election names to NamedTemporaryFiles.Command-linercvformatstransfer-i<input-filename>-o<output-filename>Pythonfromrcvformats.conversions.ut_without_transfersimportUTWithoutTransfersConverterconverter=UTWithoutTransfersConverter()try:converter.convert_to_ut(filename)exceptExceptionase:print("Errors: ",e)Upcoming plansIn addition to data normalization for RCV Summary formats, we would like similar functionality for cast vote records.Running test suitepip3 install -r requirements-test.txt, then runpytest rcvformats/testin the root directory, and./scripts/lint.shto run the linter.