comments from @shawngraham

[kimpham54]

I think though there may be a fundamental issue in that this tutorial is trying to do too much. The author has I think at least 3 separate tutorials, each one of which would be valuable to Programming Historian readers. If the Geocoding, the ogr2ogr, and leaflet sections were spun into separate lessons, the author could go into the greater detail that both Jim and I are looking for.

• [ ] link to working tutorial files should go directly to the folder, eg https://github.com/kimpham54/proghist-mappingAPI/tree/master/tutorial-files
• [x] Import your folder in a text editor such as TextWrangler for OS X, Notepad++ for Windows, or Sublime Text I know this is pitched as 'intermediate', but I could see this as being problematic. It wasn't immediately obvious to me how I do this, as I don't tend to work with text editors in this particular way. Nor, after having gone through the whole thing, is it apparent what this step does/means.
• [x] Obtaining the source csv. The link we really want is the raw - https://raw.githubusercontent.com/Robinlovelace/Creating-maps-in-R/master/data/census-historic-population-borough.csv

Perhaps show the reader how to grab with curl etc from command line?

`curl https://raw.githubusercontent.com/Robinlovelace/Creating-maps-in-R/master/data/census-historic-population-borough.csv > census.csv `

• [x] Is it desirable to send the reader off-site to learn how to install the ancillary materials? Should there be a quick 'here's how to get pip'?
• [x] On OS X or Linux, the following commands will install the necessary packages: Explain why numpy, dateutils etc are necessary?
• [x] I get the following errors on an up-to-date Mac, up-to-date everything else:

File "geocoder.py", line 17, in <module>
    main()
  File "geocoder.py", line 12, in main
    io['latitude'] = io['Area_Name'].apply(geolocator.geocode).apply(lambda x: (x.latitude))
  File "/Library/Python/2.7/site-packages/pandas/core/frame.py", line 1969, in __getitem__
    return self._getitem_column(key)
  File "/Library/Python/2.7/site-packages/pandas/core/frame.py", line 1976, in _getitem_column
    return self._get_item_cache(key)
  File "/Library/Python/2.7/site-packages/pandas/core/generic.py", line 1091, in _get_item_cache
    values = self._data.get(item)
  File "/Library/Python/2.7/site-packages/pandas/core/internals.py", line 3211, in get
    loc = self.items.get_loc(item)
  File "/Library/Python/2.7/site-packages/pandas/core/index.py", line 1759, in get_loc
    return self._engine.get_loc(key)
  File "pandas/index.pyx", line 137, in pandas.index.IndexEngine.get_loc (pandas/index.c:3979)
  File "pandas/index.pyx", line 157, in pandas.index.IndexEngine.get_loc (pandas/index.c:3843)
  File "pandas/hashtable.pyx", line 668, in pandas.hashtable.PyObjectHashTable.get_item (pandas/hashtable.c:12265)
  File "pandas/hashtable.pyx", line 676, in pandas.hashtable.PyObjectHashTable.get_item (pandas/hashtable.c:12216)
KeyError: 'Area_Name'

• [x] Tip 1: If you want to pass the filenames from the command line rather than changing the input file name in the python script everytime, you can import the python 'sys' library to pass through arguments. example of how this works.
• [x] Tip 2: If you run it too many times because you get a timeout error, like this if you use the GoogleV3 geo I'm not sure what you're telling me here
• [ ] Option 1 for creating geojson - the animated figure shows the user dragging across a csv file, which might be confusing? maybe can you create a video clip that shows the user exactly what you're telling them?
• [x] Installing GDAL is not straightforward. More info here.
• [x] Perhaps the ogr2ogr portion should be spun off into a separate ancillary lesson? I was lost at 'Make sure that OGRVRTLayer, SrcDataSource have the same name as your filename (census_geocoded.vrt).' I think you're talking about your raw csv file becomes the .vrt?
• [ ] On cleaning the data - this should perhaps come first, just after the download of the data. You could write something to the effect: There are many 'Londons' in the world - it can help improve the accuracy of the geocoder if we add a bit more context. In this case, we can do this by adding another column with 'Country' ... etc.
• [ ] I think I would spin the leaflet tutorial out from this tutorial as well. I can imagine a reader might want to geocode, but then use CartoDB or some other service to do the mapping. This would also address some of Jim's concerns, as you could go into greater detail all the different ways leaflet could be used - you'd answer the 'what's in it for me' question.

[kimpham54]

agreed that ogr2ogr could probably be another lesson, it's probably not necessary to describe it here, just to allude to it as a possibility when there are clearly other easier options

[kimpham54]

pandas error moved to new issue #8