Package: dorchester
dorchesterA tool for making dot-density maps in Python.Caveat emptorThis is very alpha right now. Use at your own risk and evaluate any editorial usage of this of this library before publishing.InstallationInstall this tool usingpip:$ pip install dorchesterUsageThe main command isdorchester plot. That takes an input file, an output file and one or more property keys to extract population counts.dorchesterplot--help
Usage:dorchesterplot[OPTIONS]SOURCEDESTGeneratedataforadot-densitymap.InputmaybeanyGISformatreadablebyFiona(Shapefile,GeoJSON,etc).

Options:-k,--keyTEXTPropertynameforapopulation.Usemultipletomapdifferentpopulationclasses.-f,--format[csv|geojson|null]Outputformat.Ifnotgiven,willguessbasedonoutputfileextension.-m,--mode[w|a|x]Filemodefordestination[default:w]--fidTEXTUseapropertykey(insteadoffeature.id)touniquelyidentifyeachfeature--coerceCoercepropertiespassedin--keytointegers.BECAREFUL.Thiscouldcauseincorrectresultsifmisused.--progressShowaprogressbar[default:False]-m,--multiprocessingUsemultiprocessing--helpShowthismessageandexit.Input can be in any format readable byFiona, such as Shapefiles and GeoJSON. The input file needs to contain both population data and boundaries. You may need to join different files together before plotting withdorchester.Output format (--format) can be CSV or GeoJSON (more formats coming soon). For GeoJSON, the output will be a stream of newline-delimitedPointfeatures, like this:{"type":"Feature","geometry":{"type":"Point","coordinates":[76,38]},"properties":{"group":"population","fid":1}}{"type":"Feature","geometry":{"type":"Point","coordinates":[77,39]},"properties":{"group":"population","fid":1}}{"type":"Feature","geometry":{"type":"Point","coordinates":[78,37]},"properties":{"group":"population","fid":1}}This will bebigfiles, because we are creating a point for every individual. Massachusetts, for example, had a population of 6.631 million in 2010, which means a dot density CSV file will be 6,336,107 lines long and 305 mb.Each key (--key) should correspond to a property on each feature whose value is a whole number. In a block like this, use--key POP10to extract population:{"geometry":{"coordinates":[...],"type":"Polygon"},"id":"0","properties":{"BLOCKCE":"4023","BLOCKID10":"250010112004023","COUNTYFP10":"001","HOUSING10":16,"PARTFLG":"N","POP10":12,"STATEFP10":"25","TRACTCE10":"011200"},"type":"Feature"}You can pass multiple--keyoptions to create different groups that will be layered together. This is how you would create a map showing different racial groups, for example.The--modeoption controls how the output file is opened:wwill create or overwrite the output fileawill append to an existing filexwill try to create a new file and fail if that file already existsSetting--fidwill use a property key to identify each feature, instead of the feature'sidfield (which is often missing, or will be an index number in shapefiles). In the Census block example above,BLOCKID10will uniquely identify this block, whileid: 0only identifies it as the first feature in its source shapefile.For data sources where properties are encoded as strings, the--coerceoption will recast anything passed via--keyto integers. Be careful with this option, as it involves changing data. It will fail (and stop plotting) if it encounters something that can't be coerced into an integer.Use the--progressflag to show a progress bar. This is off by default.Use-mor--multiprocessingto use Python'smultiprocessingmodule to significantly speed up point generation. This will try to use every processor on your machine instead of just one.Putting points on a mapFor small-ish areas, QGIS will render lots of points just fine. Generate points, and load the output as a delimited or GeoJSON file.To build an interactive dot density map, you can usetippecanoeto generate an MBTiles file, which can be uploaded to Mapbox (or possibly other hosting providers). This has worked for me:tippecanoe-zg-opoints.mbtiles--drop-densest-as-needed--extend-zooms-if-still-droppingpoints.csvAbout the nameDorchesteris the largest and most diverse neighborhood in Boston, Massachusetts, and is often referred to as Dot.The name is also a nod toEnglewood, built by the Chicago Tribune News Apps team. This is, hopefully, a worthy successor.DevelopmentTo contribute to this tool, first checkout the code. Then create a new virtual environment:cd dorchester
python -m venv .venv
source .venv/bin/activateOr if you are usingpipenv:pipenv shellNow install the dependencies and tests:pip install -e '.[test]'To run the tests:pytest