/hmda-tools

Permalink
Browse files

Added documentation

  • Loading branch information...
1 parent 3f8e0df commit 4566494faa7ffbfc4df1bde2aeba653a779f2dc6 @cndreisbach cndreisbach committed Feb 16, 2013
View
20 docs/Makefile
@@ -4,6 +4,7 @@
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
+SPHINXAPI = sphinx-apidoc
PAPER =
BUILDDIR = _build
@@ -41,7 +42,12 @@ help:
clean:
-rm -rf $(BUILDDIR)/*
-html:
+apirst:
+ $(SPHINXAPI) -o $(BUILDDIR)/api -H API -f ../hmda_tools
+ @echo
+ @echo "API documentation is generated. The RST pages are in $(BUILDDIR)/api."
+
+html: apirst
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
@@ -70,13 +76,13 @@ htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
- ".hhp project file in $(BUILDDIR)/htmlhelp."
+ ".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
- ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+ ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/hmda_tools.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/hmda_tools.qhc"
@@ -100,7 +106,7 @@ latex:
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
- "(use \`make latexpdf' here to do that automatically)."
+ "(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@@ -123,7 +129,7 @@ texinfo:
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
- "(use \`make info' here to do that automatically)."
+ "(use \`make info' here to do that automatically)."
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@@ -145,9 +151,9 @@ linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
- "or in $(BUILDDIR)/linkcheck/output.txt."
+ "or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
- "results in $(BUILDDIR)/doctest/output.txt."
+ "results in $(BUILDDIR)/doctest/output.txt."
View
35 docs/api/hmda_tools.data.rst
@@ -0,0 +1,35 @@
+data Package
+============
+
+:mod:`data` Package
+-------------------
+
+.. automodule:: hmda_tools.data
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+:mod:`cbsa` Module
+------------------
+
+.. automodule:: hmda_tools.data.cbsa
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+:mod:`geo` Module
+-----------------
+
+.. automodule:: hmda_tools.data.geo
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+:mod:`schemas` Module
+---------------------
+
+.. automodule:: hmda_tools.data.schemas
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
View
26 docs/api/hmda_tools.rst
@@ -0,0 +1,26 @@
+hmda_tools Package
+==================
+
+:mod:`hmda_tools` Package
+-------------------------
+
+.. automodule:: hmda_tools.__init__
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+:mod:`unicode_csv` Module
+-------------------------
+
+.. automodule:: hmda_tools.unicode_csv
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+Subpackages
+-----------
+
+.. toctree::
+
+ hmda_tools.data
+
View
7 docs/api/modules.rst
@@ -0,0 +1,7 @@
+API
+===
+
+.. toctree::
+ :maxdepth: 4
+
+ hmda_tools
View
5 docs/conf.py
@@ -11,12 +11,13 @@
# All configuration values have a default; values that are commented out
# serve to show the default.
-import sys, os
+import sys
+import os, os.path
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('..'))
# -- General configuration -----------------------------------------------------
View
185 docs/creating_databases.rst
@@ -0,0 +1,185 @@
+Creating Databases
+==================
+
+To create a database to hold HMDA data, run the script ``hmda_create_schemas``
+with a database URL as your argument. The database URL should be specified `as
+it would be in SQLAlchemy`__.
+
+.. __: http://docs.sqlalchemy.org/en/latest/core/engines.html#sqlalchemy.create_engine
+
+Examples:
+
+.. code-block:: bash
+
+ hmda_create_schemas sqlite://hmda.db
+ hmda_create_schemas mysql://root@localhost/hmda
+ hmda_create_schemas postgresql://peter:rabbit@10.0.0.34/hmda
+
+You will need to install the Python libraries for your database separately.
+``hmda_tools`` does not require any DB libraries, as it tries to stay agnostic.
+
+You can also create these schemas programatically using
+:py:func:`hmda_tools.data.create_schemas`.
+
+The created schema will look like the following (dependent on database):
+
+.. generate by running "mysqldump -u root --skip-opt --compact --no-data --compatible=ansi hmda | grep -v '^/\*\!'"
+
+.. code-block:: sql
+
+ CREATE TABLE "action_taken" (
+ "id" int(11) NOT NULL,
+ "action_taken" varchar(255) NOT NULL,
+ PRIMARY KEY ("id")
+ );
+ CREATE TABLE "agency" (
+ "id" int(11) NOT NULL,
+ "agency_abbr" varchar(10) NOT NULL,
+ "agency" varchar(255) NOT NULL,
+ PRIMARY KEY ("id")
+ );
+ CREATE TABLE "cbsa" (
+ "cbsa_code" int(11) NOT NULL,
+ "parent_code" int(11) DEFAULT NULL,
+ "name" varchar(255) NOT NULL,
+ PRIMARY KEY ("cbsa_code")
+ );
+ CREATE TABLE "county" (
+ "county_fips_code" int(11) NOT NULL,
+ "state_fips_code" int(11) NOT NULL,
+ "ansi_code" varchar(8) NOT NULL,
+ "cbsa_code" int(11) DEFAULT NULL,
+ "name" varchar(255) NOT NULL,
+ "population" int(11) DEFAULT NULL,
+ "housing_units" int(11) DEFAULT NULL,
+ "land_area" bigint(20) DEFAULT NULL,
+ "water_area" bigint(20) DEFAULT NULL,
+ "latitude" varchar(20) DEFAULT NULL,
+ "longitude" varchar(20) DEFAULT NULL,
+ PRIMARY KEY ("county_fips_code","state_fips_code")
+ );
+ CREATE TABLE "denial_reason" (
+ "id" int(11) NOT NULL,
+ "denial_reason" varchar(255) NOT NULL,
+ PRIMARY KEY ("id")
+ );
+ CREATE TABLE "edit_status" (
+ "id" int(11) NOT NULL,
+ "edit_status" varchar(255) NOT NULL,
+ PRIMARY KEY ("id")
+ );
+ CREATE TABLE "ethnicity" (
+ "id" int(11) NOT NULL,
+ "ethnicity" varchar(255) NOT NULL,
+ PRIMARY KEY ("id")
+ );
+ CREATE TABLE "hmda" (
+ "year" int(11) NOT NULL,
+ "respondent" varchar(10) DEFAULT NULL,
+ "agency" int(11) DEFAULT NULL,
+ "loan_type" int(11) DEFAULT NULL,
+ "property_type" int(11) DEFAULT NULL,
+ "loan_purpose" int(11) DEFAULT NULL,
+ "occupancy" int(11) DEFAULT NULL,
+ "loan_amount" int(11) DEFAULT NULL,
+ "preapproval" int(11) DEFAULT NULL,
+ "action_type" int(11) DEFAULT NULL,
+ "msa_md" int(11) DEFAULT NULL,
+ "state_code" int(11) DEFAULT NULL,
+ "county_code" int(11) DEFAULT NULL,
+ "census_tract_number" varchar(8) DEFAULT NULL,
+ "applicant_ethnicity" int(11) DEFAULT NULL,
+ "co_applicant_ethnicity" int(11) DEFAULT NULL,
+ "applicant_race_1" int(11) DEFAULT NULL,
+ "applicant_race_2" int(11) DEFAULT NULL,
+ "applicant_race_3" int(11) DEFAULT NULL,
+ "applicant_race_4" int(11) DEFAULT NULL,
+ "applicant_race_5" int(11) DEFAULT NULL,
+ "co_applicant_race_1" int(11) DEFAULT NULL,
+ "co_applicant_race_2" int(11) DEFAULT NULL,
+ "co_applicant_race_3" int(11) DEFAULT NULL,
+ "co_applicant_race_4" int(11) DEFAULT NULL,
+ "co_applicant_race_5" int(11) DEFAULT NULL,
+ "applicant_sex" int(11) DEFAULT NULL,
+ "co_applicant_sex" int(11) DEFAULT NULL,
+ "applicant_income" int(11) DEFAULT NULL,
+ "purchaser_type" int(11) DEFAULT NULL,
+ "denial_reason_1" int(11) DEFAULT NULL,
+ "denial_reason_2" int(11) DEFAULT NULL,
+ "denial_reason_3" int(11) DEFAULT NULL,
+ "rate_spread" varchar(10) DEFAULT NULL,
+ "hoepa_status" int(11) DEFAULT NULL,
+ "lien_status" int(11) DEFAULT NULL,
+ "edit_status" int(11) DEFAULT NULL,
+ "sequence_number" int(11) DEFAULT NULL,
+ "population" int(11) DEFAULT NULL,
+ "minority_population" float DEFAULT NULL,
+ "hud_median_family_income" int(11) DEFAULT NULL,
+ "tract_to_msa" float DEFAULT NULL,
+ "number_of_owner_occupied_units" int(11) DEFAULT NULL,
+ "number_of_family_units" int(11) DEFAULT NULL,
+ "application_date_indicator" int(11) DEFAULT NULL,
+ KEY "state_code" ("county_code"),
+ KEY "ix_hmda_occupancy" ("occupancy"),
+ KEY "ix_hmda_state_code" ("state_code"),
+ KEY "ix_hmda_year" ("year"),
+ KEY "ix_hmda_msa_md" ("msa_md"),
+ KEY "ix_hmda_applicant_ethnicity" ("applicant_ethnicity"),
+ KEY "ix_hmda_loan_amount" ("loan_amount"),
+ KEY "ix_hmda_census_tract_number" ("census_tract_number")
+ );
+ CREATE TABLE "hoepa" (
+ "id" int(11) NOT NULL,
+ "hoepa" varchar(255) NOT NULL,
+ PRIMARY KEY ("id")
+ );
+ CREATE TABLE "lien_status" (
+ "id" int(11) NOT NULL,
+ "lien_status" varchar(255) NOT NULL,
+ PRIMARY KEY ("id")
+ );
+ CREATE TABLE "loan_purpose" (
+ "id" int(11) NOT NULL,
+ "loan_purpose" varchar(255) NOT NULL,
+ PRIMARY KEY ("id")
+ );
+ CREATE TABLE "loan_type" (
+ "id" int(11) NOT NULL,
+ "loan_type" varchar(255) NOT NULL,
+ PRIMARY KEY ("id")
+ );
+ CREATE TABLE "owner_occupancy" (
+ "id" int(11) NOT NULL,
+ "owner_occupancy" varchar(255) NOT NULL,
+ PRIMARY KEY ("id")
+ );
+ CREATE TABLE "preapproval" (
+ "id" int(11) NOT NULL,
+ "preapproval" varchar(255) NOT NULL,
+ PRIMARY KEY ("id")
+ );
+ CREATE TABLE "property_type" (
+ "id" int(11) NOT NULL,
+ "property_type" varchar(255) NOT NULL,
+ PRIMARY KEY ("id")
+ );
+ CREATE TABLE "purchaser_type" (
+ "id" int(11) NOT NULL,
+ "purchaser_type" varchar(255) NOT NULL,
+ PRIMARY KEY ("id")
+ );
+ CREATE TABLE "race" (
+ "id" int(11) NOT NULL,
+ "race" varchar(255) NOT NULL,
+ PRIMARY KEY ("id")
+ );
+ CREATE TABLE "sex" (
+ "id" int(11) NOT NULL,
+ "sex" varchar(255) NOT NULL,
+ PRIMARY KEY ("id")
+ );
+ CREATE TABLE "state" (
+ "fips_code" int(11) NOT NULL,
+ "abbr" varchar(2) NOT NULL,
+ PRIMARY KEY ("fips_code")
+ );
View
14 docs/index.rst
@@ -6,12 +6,22 @@
Welcome to hmda_tools's documentation!
======================================
-Contents:
+hmda_tools makes working with HMDA data much easier.
+
+"HMDA" refers to the `Home Mortgage Disclosure Act`_, a law that requires
+financial institutions to maintain and annually disclose data about home
+purchases, home purchase pre-approvals, home improvement, and refinance applications. This data is made public and is available from the US Government at the `FFIEC HMDA Products`_ site.
+
+.. _Home Mortgage Disclosure Act: http://en.wikipedia.org/wiki/Home_Mortgage_Disclosure_Act
+.. _FFIEC HMDA Products: http://www.ffiec.gov/hmda/hmdaproducts.htm
+
.. toctree::
:maxdepth: 2
-
+ creating_databases
+ loading_data
+ api/modules
Indices and tables
==================
Oops, something went wrong.

0 comments on commit 4566494

Please sign in to comment.