Parsing and converting a CVR

Cast vote record files come in all kinds of file formats. Often it can be handy to covert a CVR into a more easily shareable format, such as a Excel-friendly csv file. The first step to performing this conversion with the rcv-cruncher package is selecting a parser function to use in reading the format of CVR you have. The package has several parsers implemented (you can see the full list in the parsers module parsers).

Parse

Once you’ve found the one that matches your CVR file(s), you can use it to create a cvr.base.CastVoteRecord object. In the example below, I am parsing the 2017 Minneapolis mayoral election

from rcv_cruncher import CastVoteRecord, rank_column_csv
from pathlib import Path

# CVR file assumed to be downloaded and in current working directory
cvr_file = Path.cwd() / '2017-mayor-cvr.csv'

# initialize the object with optional details about the election (state, date, office, ..)
# along with the parser function and parser function arguments. As described in the
# documentation the only argument for this parser is the path to the CVR file.
cvr = CastVoteRecord(
     jurisdiction='Minneapolis',
     state='MN',
     year='2017',
     office='Mayor',
     parser_func=rank_column_csv,
     parser_args={'cvr_path': cvr_file}
)

Convert

The constructor will parse the CVR. The next step is to write out a converted version of it. There are two conversions that are available: rank column format and candidate column format. Examples for each are show below. (More details on each conversion format can be learned from looking at their respective parser functions in parsers)

rank column format

The rank column format has rank numbers as column names with candidate names appearing in row cells. Each row is one ballot.

# an output directory, rooted in current working directory
out_dir = Path.cwd() / 'output/minneapolis2017/rank'

# rank column format
CastVoteRecord.write_cvr_table(cvr, out_dir, table_format='rank')

# the file written to out_dir will have an automatically
# generated name following the format {jurisdiction}_{year}_{office}.csv.

candidate column format

The candidate column format has candidate names as column names with candidate rank numbers appearing in row cells. Each row is one ballot.

# an output directory, rooted in current working directory
out_dir = Path.cwd() / 'output/minneapolis2017/candidate'

# candidate column format
CastVoteRecord.write_cvr_table(cvr, out_dir, table_format='candidate')

# the file written to out_dir will have an automatically
# generated name following the format {jurisdiction}_{year}_{office}.csv.