acs

ACS, the American Community Survey

ACS data comes from the US Census.

In the first implementation here (it's now September 2018) users have access to more than 15000 records from California in 2013. We hope to expand that, but this is a proof of concept.

Users can choose from among a few dozen attributes, grouped into categories. Typical attributes include sex, age, income, race, and education. This suggests obvious types of investigations, looking at relationships among these variables.

The data themselves are stored in a mySQL database. Javascript (being client-side) cannot access mySQL directly, so we use php as an intermediary. For more background on this interaction, see our page on how we use php to get to mySQL.

The files

Here is a list of the files and what they're responsible for:

• acs.html: Where we begin. Contains paths to the javascript and the DOM elements the user sees.
• acs.css: Styles what the user sees.
• acs.js: The main controller and catchall. Defines the acs global.
• acs.constants.js: Defines constants including the version number and the base URL for the php.
• acs.ui.js: Adjusts text and visibility of DOM elements in acs.ui.updateWholeUI(). Also constructs strings used in the UI such as sets of checkboxes or status strings.
• acs.userActions.js: Has functions called directly when the user takes an action such as clicking a checkbox or, of course, asking for a sample.
• acs.DBconnect.js: (née phpConnect) Contains functions that send commands to php in order to query the database. Asking for a sample triggers a call here to retrieve the sample from the database. This comes in as a JSON object.
• acs.CODAPConnect.js: Contains all of the functions that interact with the CODAP platform, for example, for creating new items when the user requests a sample. The JSON from the database interaction becomes a values parameter in the request to CODAP.
• Attribute.js: This is a class, really only a structure, that manages the various features of an 'attribute.' We create one of these for each attribute selected by the user; we retrieve that set of columns from the database. An Attribute contains the internal name of the attribute, the user-facing name, and other information such as a description. For example, PINCP is the total person's income, which we display as TotalIncome.
• acs.php: This is the php code called in DBconnect. It assembles and executes mySQL queries and reports the results back as JSON. Here, a typical query retrieves a number of records from the database.
• acs.establishCredentials.php: Note this is php! This file contains the URL of the file that contains the credentials. This file is not in a publicly-accessible place, and is not checked in to github. You can read about such files in the page about communicating with mySQL (referenced above).

mySQL tables

• 'peeps' : One record for each person. Note that SERIALNO is the serial number of the household, so it is not unique. The many values in each record are not decoded.
• 'variables' : one record per column in the peeps data set. The name here is the unique, often-impenetrable variable name used by ACS. This table includes a description, the nameout (a friendlier name that we use in CODAP tables), groupNumber for which group the attribute is in, decodeTable for the name of any table that has decoding information, and defcheck and defshow, which tell us whether the attribute appears in the list by default, and whether it's checked by default.
• 'groups': a table we made to group the variables. Contains the number (a key to variables) and the name of the group.
• 'decoder': each record contains a variable name (decoder.varname matches variable.name), a code, and a result. When we decode a value, we look in here to see if the varname/code combination exists; if so, we substitute the result for the code in our value output. For example, the first record is {varname: SEX, code: 1, result: Male}. Note: This is not the "decode table" thing in the variable table.
• ancestries, served, states, yesno: We use these tables for decoding iff their names appear in the decodeTable field in variables. That makes sense for a long set of codes as with ancestries. But why have a table with two values? There are a whole slew of variables with the same sets of codes; it saves us from repeating them over and over in the decoder table.
• pumas: information, including latitude and longitude, for every PUMA in the country. Could be used in the future to locate ACS people — or at least their PUMA.
• searches: records every search made by any user. Could be sued to see what people are looking at. Originally essential for Fathom so we could make a URL for dragging into a Fathom document and remember the search.