*! version 1.0.5 22june2017

maptile -- Instructions for creating a new geography template

Naming your new geography

The first step is to choose a name for your new geography (a geoname). It may consist of
lowercase letters, numbers, and underscores.

Building your new geography

A maptile geography consists of four files:

1) geoname_coords.dta

2) geoname_database.dta

These two datasets are created from a shapefile using shp2dta. They are
the same files one would use to create maps using spmap.

Typically, one obtains a shapefile for the geographic units of interest by downloading it from the
internet. For example, the U.S. Census Bureau provides shapefiles of the United States, and Statistics
Canada provides shapefiles of Canada.

After processing the shapefile into Stata format using shp2dta, you will have two files. The coordinates file contains 3 variables, _ID _X _Y, which define the shape of the polygons displayed
on the map and link them to a polygon ID. The database file is simply a crosswalk between a useful geographic
ID (ex: state) and the polygon IDs that are associated with each area.

Some post-processing is often necessary.
You will often have to adjust the database file to assign the variable name and variable type you want to each geographic ID variable, and ensure that it uses the coding that you desire.
You may also want to scale the coordinates file vertically or horizontally to adjust the aspect ratio of the map.
The program mergepoly can be used to combine geographic units into aggregated units.

On the maptile website
you can download Creation files for existing geography templates. You can use these as a reference to see how those shapefiles were processed.

3) geoname_maptile.ado

This ado-file contains all the customizations for how the map should look and handles any geography-specific options.
It is the template that directs maptile to an spmap command configured to look just right for the map you're creating.

To create your ado-file, you should work from a reference: demo_maptile.ado can be downloaded from the
maptile website. This demo file contains the most
barebones code for a working geography ado-file: it handles all of maptile's options without adding any
geography-specific options. It is annotated with comments indicating precisely which sections must to be changed. These
comments are marked with XX. You should avoid changing other sections of the ado-file without
understanding what they are doing.

By following the instructions marked with XX in the demo_maptile.ado template, you can create a working
geography template in 5-10 minutes without too much knowledge of how ado-files, maptile or spmap work.

Advanced

If you're ready to delve into the details, you will find that geography templates are
fully extensible and customizable. You can add arguments to the spmap command in the ado-file in order to
customize the formatting of the generated map. You can also create new options for users to specify in their
maptile command that are specific to your geography. Any option added to a maptile command that is not listed
in the maptile options will be passed to the geography ado-file.
You utilize this to add new features for customizing your maps.

You can refer to existing geographies' ado-files for examples of geo-specific options and
the code that implements them. The county1990 geography gives users an option to overlay the map with
a thicker line over the state boundaries, visually differentiating state boundaries from county boundaries.
The state geography uses a geo-specific option to accept a variety of geographic ID variables, that
identify U.S. states in different ways (2-letter abbreviations, full names, 2-digit codes).

4) geoname_maptile.smcl

This file is not necessary for maptile to run; it is a help file that explains your geography to its
users. It contains a description of the map that will be created and indicates the geographic
ID variable that must exist in the user's dataset.
It also explains any geography-specific options that you have defined.

If you are creating the geography only for your own use, you might decide not to bother creating a help
file.
But if you intend to share your geography with other people, you should write a help file to explain the
relevant information to others who will be using it.

It is easiest to start from a reference: demo_maptile.smcl can be downloaded from the
maptile website.
This is simply the help file for the county1990 geography.

The best way to write Stata help files is to open the .smcl file
in a basic text editor (like Notepad) and start editing. Unfortunately there is no graphical editor for .smcl
files, and the syntax is not particularly elegant. But if you're not doing anything fancy, it will be
straightforward to just edit the text in the demo_maptile.smcl file.

You can open your .smcl file in Stata's Viewer to see how it looks (File > View). As you edit the
file, save your changes and use the Refresh button in the Viewer to see how the changes you've made are
rendered.

One word of caution: there is a limit to the length of a line in a .smcl file. If the lines
get too long in your raw text file they will be chopped off in the Stata Viewer.
You should intersperse any long paragraphs with line breaks, which the Stata Viewer ignores, in order to keep
lines in the .smcl file relatively short.

To add new formatting to the help file, there are two resources that I use often.
First, all of the syntax for .smcl formatting is documented under smcl.
Second, you can look at the help files for existing Stata commands that you use regularly to see how they are
formatted (ex: help regress). If there is a format that you want to copy, find the corresponding
.sthlp file on your computer and open it in a text editor to see how the formatting was done.

Installing your new geography

There are three ways to install a geography.

1) Zip the 4 geography files listed above into a .zip file. Point
maptile_install to the .zip file on your computer, and it will
automatically extract the files to the
PERSONAL/maptile_geographies folder.
You can then use your new geography by running maptile with geo(geoname).

2) Manually place the 4 geography files in the PERSONAL/maptile_geographies folder
on your computer. You can then use your new geography by running maptile with geo(geoname).

3) Place the 4 geography files together in any folder on your computer. Then, when you run a
maptile command, you will need to specify geo(geoname) as well as geofolder(folder_name)
to direct maptile to look in that folder.

If you only have 3 geography files because you've omitted the geoname_maptile.smcl help file, all
of these installation methods will still work correctly.

Distributing your new geography

Once you've done the work to find a shapefile and make a geography template that generates beautiful
maps for a new region or a new set of geographic units, I hope you'll consider sharing your geography
template with the public. Many geography templates are hosted on the
maptile website, and with your help,
many more will be added. This repository makes it easy for Stata users to generate maps for a large variety
of places.

There are two conditions for hosting a geography on the
maptile website.
First, all of the files in your geography template and all inputs used in creating them
must be in the public domain, or
subject to an open license that allows free redistribution. For example, many of the U.S. geographies
were created using shapefiles released to the public domain by the U.S. Census Bureau. Second, the
geography must include a .smcl help file for users. This help file should contain a description
of the map, indicate the geographic ID variable required, and explain any geography-specific options.

If you'd like to make your geography template available on the
maptile website, please send an
e-mail to Michael Stepner using the contact information listed on the website.
Your e-mail should include two ZIP files. One ZIP file containing the four geography files.
And one ZIP file containing the raw shapefile that your geography is
derived from and the code you used to transform it into the database and coordinates .dta files. You can
include them in your e-mail as attachments, or as links to Dropbox or another hosting service if the files
are too large to attach. Both ZIP files will be posted online.