Updates to Sheets get_variable.md file (#370)

* Updates to Sheets get_variable.md file

* Updates from Carolyn and extensive image updates

* Updated Gemfile

* Update text and images

* pr comments

* standardize text and formatting; some glossary updates

* examples formatting update

---------

Co-authored-by: Carolyn Au <[email protected]>

api/sheets/get_property.md

@@ -21,7 +21,7 @@ The `=DCPROPERTY(dcids, property)` formula returns values associated with the gi
 
 ### Required Arguments
 
-* [`dcids`](https://docs.datacommons.org/glossary.html): A list of [Place](/glossary.html#place) nodes, identified by their DCIDs.
+* `dcids`: A list of [Place](/glossary.html#place) nodes, identified by their [DCIDs](/glossary.html#dcid).
 * `property`: The property whose value you are interested in,  such as “name” for the name of a node, or “typeOf” for the type of a node. If you aren’t sure what properties are available for a particular DCID, you can use the [Data Commons graph browser](https://datacommons.org/browser/)
   to look up the DCID of interest and see what properties it is associated with.
 

api/sheets/get_variable.md

@@ -1,111 +1,119 @@
 ---
 layout: default
-title: Statistical Variable Value
+title: Statistical Variable Values
 nav_order: 3
 parent: Google Sheets
 grand_parent: API
 ---
 
-# Get the value of a statistical variable at a given place and time
+# Getting the Value of a Statistical Variable at a Given Place and Time
 
-Given a list of [DCIDs](/glossary.html) representing [Place](https://datacommons.org/browser/Place) objects, a [StatisticalVariable](https://datacommons.org/browser/StatisticalVariable), and optionally a date, get the measurements of the specified variable in the specified places with a date (if specified).
+The`=DCGET(dcids, variable, date)` formula returns the measurements of a specified [statistical variable](/glossary.html#variable) at a given place and optional time based on a list of parent [Place](https://datacommons.org/browser/Place) [DCIDs](/glossary.html#dcid). A complete list of variables can be found in the [Statistical Variable Explorer](https://datacommons.org/tools/statvar).
 
-## General information about this formula
+> **Note**: Be sure to follow the instructions for [Installing and Enabling the Sheets Add-On](/api/sheets/) before using this formula.
 
-**Formula**: `=DCGET(dcids, variable, date)`
+## Formula
 
-**Required arguments**:
-
-*   [`dcids`](/glossary.html): A list of `Place` nodes, identified by their DCIDs.
-
-*   `variable` - The [StatisticalVariable](/glossary.html) whose measurement is sought.
-
-**Optional arguments**:
-
-*   `date` - The date or dates of interest. If this argument is not specified, the API will return the latest observation of the variable.
+```
+=DCGET(dcids, variable, date)
+```
 
-## Assembling the information you will need to use this formula
+### Required Arguments
 
-This endpoint requires the arguments `dcids` and `variable`. [DCIDs](/glossary.html) are unique node identifiers defined by Data Commons. Your query will need to specify the DCIDs for the parent places of interest. You are also required to specify the [statistical variable](/glossary.html) whose measurement you seek. Statistical variables are the metrics tracked by Data Commons.
+* `dcids`: A list of [Place](/glossary.html#place) nodes, identified by their [DCIDs](/glossary.html#dcid).
+* `variable`: The [statistical variable](/glossary.html#variable) whose measurements you want to query.
 
-You may choose to specify the `date` argument. You may specify this argument as a single value, a row, or a column. All dates must be in ISO 8601 format (e.g. 2017, "2017", "2017-12") or as a Google sheets [date value](https://support.google.com/docs/answer/3092969?hl=en).
+### Optional Arguments
 
-**Returns**
+`date`: The date or dates of interest. If this argument is not specified, the API returns the latest variable observation. You can specify this argument as a single value, row, or column. All dates must be in ISO 8601 format (such as 2017, “2017”, “2017-12”) or as a Google sheets [date value](https://support.google.com/docs/answer/3092969?hl=en).
 
-The value of the variable at those places on the specified date (or on the latest available date, if no date is specified).
+## Returns
 
->  **NOTE:**
->
->  It's best to minimize the number of function calls to `DCGET` by using a single call to get a variable for a row/column of places and/or a column/row of times. This is because a spreadsheet will make one call to a Google server [per custom function call](https://developers.google.com/apps-script/guides/sheets/functions#optimization). If your sheet contains thousands of separate calls to `DCGET`, expect it to be slow.
+The value of the variable at those places on the specified date or on the latest available date, if no date is specified.
 
-You can find a list of StatisticalVariables with human-readable names [here](/statistical_variables.html).
+> **Note**: It’s best to minimize the number of function calls to `=DCGET(dcids, variable, date)` by using a single call to get the names for a column of nodes. This is because a spreadsheet will make one call to a Google server [per custom function call](https://developers.google.com/apps-script/guides/sheets/functions#optimization). If your sheet contains thousands of separate calls to `=DCGET(dcids, variable, date)` you can expect it to be slow and return with errors.
 
 ## Examples
 
-Before trying this method out, make sure to follow the setup directions in [the main section for Sheets docs](/api/sheets/index.html).
+This section contains examples of using the `=DCGET(dcids, variable, date)` formula to returns lists of [statistical variable](/glossary.html#variable) such as "Count_Person" and "Median_Income_Person". A complete list of variables can be found in the [Statistical Variable Explorer](https://datacommons.org/tools/statvar).
+
+### Example 1: Get the Total Population of Hawaii in 2017
 
-### Get the total population of Hawaii in 2017.
+The following formula returns the total population of Hawaii in 2017 using the "geoId/15" DCID and "Count_Person" variable:
 
 ```
 =DCGET("geoId/15", "Count_Person", 2017)
 ```
 
-### Get the population of multiple places with a single function call.
+Running the preceding formula returns a value of 1425763.
 
-#### Input
+### Example 2: Get the Population of Multiple Places with a Single Call
 
-![](/assets/images/sheets/sheets_get_variable_input.png)
+The following sheet returns the population of the five Hawaii counties in 2017. Column A contains the Hawaii state DCID of "geoId/15" and column B contains the county DCIDs. Column C uses the `=DCGETNAME()` formula to retrieve the county names based on the values in column B. Column D uses the following formula to retrieve the 2017 population:
 
-#### Output
+```
+=DCGET(B2:B6, "Count_Person", 2017)
+```
 
-![](/assets/images/sheets/sheets_get_variable_output.png)
+![Getting the population of multiple places with a single call](/assets/images/sheets/sheets_get_variable_input.png)
 
-### Get the population of a single place in multiple years.
+Here is the output after running the <code><b>=DCGET(B2:B6, "Count_Person", 2017)</b></code> formula:
 
-#### Input
+![Output after running the =DCGET(B2:B6, "Count_Person", 2017) formula](/assets/images/sheets/sheets_get_variable_output.png)
 
-![](/assets/images/sheets/sheets_get_variable_one_place_multiple_years_input.png)
+### Example 3: Get the Median Income of a Single Place in Multiple Years
 
-#### Output
+The following sheet demonstrates how to retrieve the median income from a single place in multiple years. Cell C2 uses the DCID for Hawaii (geoId/15) from cell B2 to retrieve the data using the following formula:
 
-![](/assets/images/sheets/sheets_get_variable_one_place_multiple_years_output.png)
+```
+=DCGET(B2, "Median_Income_Person", C1:E1)
+```
 
-### Get the median age of multiple places in multiple years.
+![Getting the median income of a single place in multiple years](/assets/images/sheets/sheets_get_variable_one_place_multiple_years_input.png)
 
-With places as a column and dates as a row:
+Here is the output after running the <code><b>=DCGET(B2, "Median_Income_Person", C1:E1)</b></code> formula:
 
-#### Input
+![Output after running the =DCGET(B2, "Median_Income_Person", C1:E1) formula](/assets/images/sheets/sheets_get_variable_one_place_multiple_years_output.png)
 
-![](/assets/images/sheets/sheets_get_variable_places_column_years_row_input.png)
+### Example 4: Get the Median Age of Multiple Places in Multiple Years
 
-#### Output
+The following sheet demonstrates how to retrieve the median age of multiple places in multiple years, with places as a column and dates as a row. Cell E2 uses the Hawaii county DCIDs from column C to retrieve the data using the following formula:
+
+```
+=DCGET(C2:C6, "Median_Age_Person", F1:H1)
+```
 
-![](/assets/images/sheets/sheets_get_variable_places_column_years_row_output.png)
+![Getting the median age of multiple places in multiple years](/assets/images/sheets/sheets_get_variable_places_column_years_row_input.png)
 
-With places as a row and dates as a column:
+Here is the output after running the <code><b>=DCGET(C2:C6, "Median_Age_Person", F1:H1)</b></code> formula:
 
-#### Input
+![Output after running the =DCGET(C2:C6, "Median_Age_Person", F1:H1) formula](/assets/images/sheets/sheets_get_variable_places_column_years_row_output.png)
 
-![](/assets/images/sheets/sheets_get_variable_places_row_years_column_input.png)
+Here's another example, but this time with places as a row and dates as a column using the formula:
 
-#### Output
+```
+=DCGET(B3:F3, "Median_Age_Person", A5:A9)
+```
 
-![](/assets/images/sheets/sheets_get_variable_places_row_years_column_output.png)
+![Retrieving places as a row and dates as a column using the formula =DCGET(B3:F3, "Median_Age_Person", A5:A9)](/assets/images/sheets/sheets_get_variable_places_row_years_column_input.png)
 
-## Error outputs
+Here is the output after running the <code><b>=DCGET(B3:F3, "Median_Age_Person", A5:A9)</b></code> formula:
 
-If you provide an invalid DCID, the API returns an error:
+![Output after running the =DCGET(B3:F3, "Median_Age_Person", A5:A9) formula](/assets/images/sheets/sheets_get_variable_places_row_years_column_output.png)
 
-![](/assets/images/sheets/sheets_get_variable_nonexistent_dcid.png)
+## Error Responses
 
-If you provide a nonexistent statistical variable, the API returns a blank value:
+The `=DCGET(dcids)` formula returns a blank value under the following circumstances:
 
-![](/assets/images/sheets/sheets_get_variable_nonexistent_statvar.png)
+* A DCID does not exist (e.g. "geoId/123123123")
+* You provide a nonexistent statistical variable (e.g. "Count")
+* You provide an incorrectly formatted date (e.g. "July 12, 2013")
 
-If you provide an invalidly formatted date, the API returns a blank value:
+For example, because the “geoId/123123123” DCID does not exist, no value is returned to cell B1 in the following sheet for the formula `=DCGET(A1, "Count_Person")`:
 
-![](/assets/images/sheets/sheets_get_variable_incorrect_date.png)
+![No value is returned to cell B1 in the following sheet for the formula `=DCGET(A1, "Count_Person")` because the DCID does not exist](/assets/images/sheets/sheets_get_variable_nonexistent_dcid.png)
 
 If you fail to provide all required arguments, you will receive an error:
 
-![](/assets/images/sheets/sheets_get_variable_incorrect_args.png)
+![Error returned if you fail to provide all required arguments](/assets/images/sheets/sheets_get_variable_incorrect_args.png)
+

glossary.md

@@ -69,7 +69,7 @@ The time period over which an [observation](#observation) is made. Specified in
 ### Place
 {: #place}
 
-Entities that describe specific geographic locations.
+Entities that describe specific geographic locations. Use the search box in [Place Explorer](https://datacommons.org/place) to search for places in the graph, or view the [Graph Browser entry for Place](https://datacommons.org/browser/Place) for a full view of the node.
 
 ### Preferred Facet
 {: #preferred-facet}
@@ -115,12 +115,12 @@ USA -- containedInPlace --> northamerica
 
 The unit of measurement. Examples include [kilowatt hours](https://datacommons.org/browser/KilowattHour), [inches](https://datacommons.org/browser/Inch), and [Indian Rupees](https://datacommons.org/browser/IndianRupee). A complete list of properties can be found in the [graph browser](https://datacommons.org/browser/unit).
 
-### [(Statistical) Variable](https://datacommons.org/browser/StatisticalVariable)
+### [Statistical Variable](https://datacommons.org/browser/StatisticalVariable)
 {: #variable}
 
 Any type of metric, statistic, or measure that can be measured at a place and time. Examples include [median income of persons older than 16](https://datacommons.org/browser/Median_Income_Person_16OrMoreYears), [number of female high school graduates aged 18 to 24](https://datacommons.org/browser/Count_Person_18To24Years_EducationalAttainmentHighSchoolGraduateIncludesEquivalency_Female), [unemployment rate](https://browser.datacommons.org/browser/UnemploymentRate_Person), or [percentage of persons with diabetes](https://browser.datacommons.org/browser/Percent_Person_WithDiabetes). A complete list of variables can be found in the [graph browser](https://datacommons.org/browser/StatisticalVariable).
 
-### [(Statistical) Variable Group](https://datacommons.org/browser/StatVarGroup)
+### [Statistical Variable Group](https://datacommons.org/browser/StatVarGroup)
 {: #variable-group}
 
 Represents a grouping of variables that are conceptually related. For example, variable group [Person With Gender = Female](https://datacommons.org/browser/dc/g/Person_Gender-Female) consists of variables like [Female Median Age](https://datacommons.org/browser/Median_Age_Person_Female), [Female Median Income](https://datacommons.org/browser/Median_Income_Person_15OrMoreYears_Female_WithIncome) and etc. A variable group could also have child variable groups, which describe a subset of the parent variable group. For example, variable group [Person With Age, Gender = Female](https://datacommons.org/browser/dc/g/Person_Age_Gender-Female) is a child of [Person With Gender = Female](https://datacommons.org/browser/dc/g/Person_Gender-Female). It contains variables that have age constraints.