From 2cb8a883c09010f2c9c01802581382d205bac20e Mon Sep 17 00:00:00 2001
From: kmoscoe <165203920+kmoscoe@users.noreply.github.com>
Date: Tue, 15 Oct 2024 12:15:51 -0400
Subject: [PATCH] Overhaul Sheets function reference pages (#517)
* troubleshooting API
* Revert to gerund
Though the style guide says to just use imperatives, "get started" just sounds weird. Also this is more consistent with "troubleshooting"
* fixed egregiously out-of-date info and added mention of Sheets to the concepts doc
* overhaul Sheets index page
* fix few mis-wordings
* restore mention of Workspace Marketplace
* tweak procedure
* Revert "tweak procedure"
This reverts commit d35bc3466a19a946e7089072f090d33ae39a6e7e.
* tweak procedure again
* rewording suggested by Julia
* removed reference to video which I removed, and correct column number
* merge
* rewrote sort step of sleep tutorial
* updated data to 2020
* tweak images
* small tweaks
* redoing Covid tutorial
* more corrections to tutorials
* more tweaks
* merge
* revise all Sheets reference pages
* more fixes
* fix heading levels
* make alt text consistent
* more alt text fixes
---
api/sheets/get_cohort_members.md | 36 ++++++----
api/sheets/get_name.md | 56 +++++++--------
api/sheets/get_property.md | 79 +++++++++-----------
api/sheets/get_variable.md | 120 +++++++++++++++----------------
api/sheets/index.md | 20 ++++--
api/sheets/places_in.md | 72 +++++++++----------
6 files changed, 190 insertions(+), 193 deletions(-)
diff --git a/api/sheets/get_cohort_members.md b/api/sheets/get_cohort_members.md
index d8d26c27a..5b2a6219a 100644
--- a/api/sheets/get_cohort_members.md
+++ b/api/sheets/get_cohort_members.md
@@ -1,34 +1,40 @@
---
layout: default
-title: Cohort Members
-nav_order: 5
+title: Get members of a cohort
+nav_order: 7
parent: Google Sheets
grand_parent: API
---
-# Retrieve the values of a given property for a node
+# Retrieve members of a cohort
-Get the [members](http://browser.datacommons.org/kg?dcid=member) of each [cohort](/glossary.html) provided. Here a cohort is a general term for a group of entities, like [the CDC's list of the United States' 500 largest cities](https://datacommons.org/browser/CDC500_City).
+The `DCCOHORTMEMBERS` formula returns the [members](http://browser.datacommons.org/kg?dcid=member) of each [cohort](/glossary.html#cohort) provided. Here a cohort is a general term for a group of entities, like [the CDC's list of the United States' 500 largest cities](https://datacommons.org/browser/CDC500_City).
-## General information about this formula
+## Formula
-**Formula**: `=DCCOHORTMEMBERS(dcids)`
+```
+=DCCOHORTMEMBERS(dcids)
+```
-**Arguments**:
-* `dcids` - cohort DCIDs whose members are sought. Here a DCID refers to the unique ID assigned by Data Commons to every node in the knowledge graph.
+### Required arguments
+* `dcids` - A single node or range of cells representing nodes, identified by their [DCIDs](/glossary.html#dcid), whose members are sought.
-**Returns**
+### Returns
The DCIDs of the cohort members. For a single DCID, the result is a column of members of the cohort represented by that DCID. For a row of DCIDs, the result is a matrix with each column the members of the cohort whose DCID serves as the column's index. For a column of DCIDs, the result is a matrix with each row the members of the cohort whose DCID serves as the row's index.
-## Example
+## Example: Retrieve the list of cities that are members of the CDC 500 cohort
-This example uses the `DCCOHORTMEMBERS` method to retrieve the members of the [CDC500_City](https://datacommons.org/browser/CDC500_City) cohort. Before trying this method out, make sure to follow the setup directions in [the main section for Sheets docs](/api/sheets/index.html).
+> **Note**: Be sure to follow the instructions for for [enabling the Sheets add-on](/api/sheets/index.html#install) before trying this example.
-### Input
+To retrieve the members of the [CDC 500 cities](https://datacommons.org/browser/CDC500_City) cohort:
-
+1. Place your cursor in any cell, say A1, and enter `CDC500_City`.
+1. In cell B1, enter `=DCCOHORTMEMBERS(A1)`.
-### Output (truncated)
+ 
-
+ The list of member DCIDs populates column B.
+
+ 
+1. (Optional) To get the names of the members, in cell C1, enter `DCGETNAME(B1:B500)`.
diff --git a/api/sheets/get_name.md b/api/sheets/get_name.md
index 5eb91b667..7edf14e83 100644
--- a/api/sheets/get_name.md
+++ b/api/sheets/get_name.md
@@ -1,16 +1,14 @@
---
layout: default
-title: Names Associated with a DCID
-nav_order: 6
+title: Get names associated with DCIDs
+nav_order: 3
parent: Google Sheets
grand_parent: API
---
-# Returning the Names Associated with a DCID
+# Return the names associated with DCIDs
-The `=DCGETNAME(dcids)` formula returns the names associated with given [DCIDs](/glossary.html#dcid) to a cell or a column range of cells.
-
-> **Note**: Be sure to follow the instructions for [Installing and Enabling the Sheets Add-On](/api/sheets/) before using this formula.
+The `=DCGETNAME` formula returns the names associated with given [DCIDs](/glossary.html#dcid) to a cell or range of cells.
## Formula
@@ -18,55 +16,55 @@ The `=DCGETNAME(dcids)` formula returns the names associated with given [DCIDs](
=DCGETNAME(dcids)
```
-### Required Arguments
+### Required arguments
-`dcids` - A list of [node DCID](/glossary.html#dcid)s to query.
+* `dcids` - A node or range of cells representing multiple nodes, identified by their [DCIDs](/glossary.html#dcid).
-## Returns
+### Returns
The names associated with given node DCIDs to a cell or a range of cells.
-> **Note**: It’s best to minimize the number of function calls to `=DCGETNAME(dcids)` 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){: target="_blank"}. If your sheet contains thousands of separate calls to `=DCGETNAME(dcids)` you can expect it to be slow and return with errors.
-
## Examples
-This section contains examples of returning the names associated with given DCIDs.
+This section contains examples of using `DCGETNAME` to return the names associated with given DCIDs.
+
+> **Note**: Be sure to follow the instructions for for [enabling the Sheets add-on](/api/sheets/index.html#install) before trying these examples.
-### Example 1: Retrieve the Name of a Place by its DCID
+### Example 1: Retrieve the name of a place by its DCID
-To retrieve the name of a place by its DCID, perform the following steps:
+To retrieve the name of a place by its DCID:
-1. Place your cursor in the cell where you want to add a DCID. In this case, cell A1.
+1. Place your cursor in the cell where you want to add a DCID; in this case, cell A1, and enter `geoId/06`.
1. Move to the cell where you want to retrieve the place name.
-1. Enter the formula =DCGETNAME(A1) to retrieve the name. *California* populates the cell.
+1. Enter the formula `=DCGETNAME(A1)` to retrieve the name. `California` populates the cell.
-
+
-### Example 2: Retrieve the Names of a Collection of Power Plants
+### Example 2: Retrieve the names of a list of power plants
-To retrieve the names of a collection of power plants, perform the following steps:
+To retrieve the names of a list of power plants:
1. Enter into column A the DCIDs that are shown in the following image.
-1. In cell B2, enter the formula =DCGETNAME(A2:A4). The names of the countries for each DCID populates in column B.
+1. In cell B2, enter the formula `=DCGETNAME(A2:A4)`. The names of the power plants for each DCID populate column B.
-
+
### Example 3: Retrieve the names of a list of statistical variables
-Statistical Variables are also nodes in the Data Commons Graph with a DCID. To retrieve the names of a list of statistical variables, perform the following steps:
+Statistical variables are also nodes in the Data Commons knowledge with a DCID. To retrieve the names of a list of statistical variables:
1. Enter into column A the DCIDs that are shown in the following image.
-1. In cell B2, enter the formula =DCGETNAME(A2:A4). The names of the countries for each DCID populates in column B.
+1. In cell B2, enter the formula `=DCGETNAME(A2:A4)`. The names of the variables for each DCID populate column B.
-
+
-## Error Responses
+## Error responses
-If a DCID does not exist, the `=DCGETNAME(dcids)` formula does not return a value. For example, because the “geoId/123123123” DCID does not exist, no value is returned to cell B1 in the following sheet:
+If a DCID does not exist, the `=DCGETNAME` formula does not return a value. For example, because the DCID `geoId/123123123` does not exist, no value is returned to cell B1 in the following sheet:
-
+
-If you provide an empty cell for a DCID, the `=DCGETNAME(dcids)` formula returns a value of #ERROR!, as shown show in the following image:
+If you provide an empty cell for a DCID, the `=DCGETNAME` formula returns a value of `#ERROR!`, as shown show in the following image:
-
+
diff --git a/api/sheets/get_property.md b/api/sheets/get_property.md
index d473a51f3..ea66a1b4b 100644
--- a/api/sheets/get_property.md
+++ b/api/sheets/get_property.md
@@ -1,17 +1,14 @@
---
layout: default
-title: Node Property Values
-nav_order: 4
+title: Get node property values
+nav_order: 6
parent: Google Sheets
grand_parent: API
---
-# Retrieving Node Property Values
+# Retrieve node property values
-The `=DCPROPERTY(dcids, property)` formula returns values associated with the given property [Place](/glossary.html#place) [DCIDs](/glossary.html#dcid).
-
-> **Note**:
-> Be sure to follow the instructions for [Installing and Enabling the Sheets Add-On](/api/sheets/) before using this formula.
+The `=DCPROPERTY` formula returns values associated with the given property for a single [place](/glossary.html#place) [DCID](/glossary.html#dcid) or list of places.
## Formula
@@ -19,73 +16,67 @@ The `=DCPROPERTY(dcids, property)` formula returns values associated with the gi
=DCPROPERTY(dcids, property)
```
-### Required Arguments
+### Required arguments
-* `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 Knowledge Graph](https://datacommons.org/browser/){: target="_blank"}.
- to look up the DCID of interest and see what properties it is associated with.
+* `dcids`: A single [place](/glossary.html#place) node or range of cells representing nodes, identified by their [DCIDs](/glossary.html#dcid).
+* `property`: The label of the [property](/glossary.html#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 Knowledge Graph](https://datacommons.org/browser/){: target="_blank"} to look up the DCID of interest and see what properties it is associated with.
-## Returns
+### Returns
The values of the property label for the specified DCIDs.
-> **Note**:
-> It’s best to minimize the number of function calls to `=DCPROPERTY(dcids, property)` 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){: target="_blank"}. If your sheet contains thousands of separate calls to `=DCPROPERTY(dcids, property)` you can expect it to be slow and return with errors.
-
## Examples
-This section contains examples of using the `=DCPROPERTY(dcids, property)` to return values associated with the given property Place DCIDs.
+This section contains examples of using the `=DCPROPERTY` to return values associated with the given property.
-### Example 1: Retrieve the Common Name of a Country by its DCID
+> **Note**: Be sure to follow the instructions for for [enabling the Sheets add-on](/api/sheets/index.html#install) before trying these examples.
-To retrieve the name of a country by its DCID, perform the following steps:
+### Example 1: Retrieve the common name of a country by its DCID
-1. Place your cursor in the cell where you want to add a DCID. In this case, cell A1.
-2. Enter country/CIV for the country Ivory Coast.
-3. Next, place your cursor in cell B2 and enter =DCPROPERTY(A1, "name") to retrieve the Ivory Coast country names in column B.
-4. Note that the French and English spellings for Ivory Coast appear in column B.
+To retrieve the name of a country by its DCID:
-
+1. Place your cursor in the cell where you want to add a DCID; in this case, cell A1.
+2. Enter `country/CIV` for the country Ivory Coast.
+3. Place your cursor in cell B2 and enter `=DCPROPERTY(A1, "name")` to retrieve the Ivory Coast country names in column B; note that the French and English spellings for Ivory Coast appear in column B.
-### Example 2: Retrieve the Order to which the Plant Austrobaileya Scandens Belongs
+
-To retrieve the order to which the plant *Austrobaileya Scandens* belongs, perform the following steps:
+### Example 2: Retrieve the order to which a plant belongs
-1. Place your cursor in the cell where you want to add a DCID. In this case, cell A1.
-2. Enter dc/bsmvthtq89217 for the plant *Austrobaileya Scandens*.
-3. Place your cursor in cell B2 and enter =DCPROPERTY(A1, "order").
-4. Note that the order *Austrobaileyales* appears in cell B2.
+To retrieve the order to which the plant Austrobaileya Scandens belongs:
-
+1. Place your cursor in the cell where you want to add a DCID; in this case, cell A1.
+2. Enter `dc/bsmvthtq89217` for the plant Austrobaileya Scandens.
+3. Place your cursor in cell B2 and enter `=DCPROPERTY(A1, "order")`. `Austrobaileyales` appears in cell B2.
-### Example 3: Retrieve the Addresses of Stuyvesant High School in New York and Gunn High School in California
+
-To retrieve the addresses of Stuyvesant High School in New York and Gunn High School in California, perform the following steps:
+### Example 3: Retrieve the addresses of two high schools
-1. Place your cursor in cell A1 and enter nces/360007702877 for *Stuyvesant Hight School in New York*.
-2. Place your cursor in cell A2 and enter nces/062961004587 for *Gunn High School in California*.
-3. Enter the formula =DCPROPERTY(A1:A2, "address") into cell B2 and the addresses of both high schools are populated in column B.
+To retrieve the addresses of Stuyvesant High School in New York and Gunn High School in California:
-
+1. Place your cursor in cell A1 and enter `nces/360007702877` for Stuyvesant Hight School in New York.
+2. Place your cursor in cell A2 and enter `nces/062961004587` for Gunn High School in California.
+3. Place your cursor in cell B2, and enter the formula `=DCPROPERTY(A1:A2, "address")`. The addresses of both high schools are populated in column B.
+
-## Error Responses
-The `=DCPROPERTY(dcids, property)` returns the value of the property label for the specified DCIDs. See the Examples section above for examples of positive responses.
+## Error responses
If you pass a nonexistent property, an empty value is returned. For example, because the “nonexistent property” does not exist, no value is returned to cell B1 in the following sheet:
-
+
If you pass a bad DCID, an empty value is returned:
-
+
-If you pass an empty DCID, an error is returned:
+If you pass an empty DCID, a response of `#ERROR!` is returned:
-
+
-If you do not pass a required property argument, an error is returned:
+If you do not pass a required property argument, a response of `#ERROR!` is returned:
-
+
diff --git a/api/sheets/get_variable.md b/api/sheets/get_variable.md
index 7596f3d3c..389266272 100644
--- a/api/sheets/get_variable.md
+++ b/api/sheets/get_variable.md
@@ -1,119 +1,117 @@
---
layout: default
-title: Statistical Variable Values
-nav_order: 3
+title: Get statistical variable values
+nav_order: 5
parent: Google Sheets
grand_parent: API
---
-# Getting the Value of a Statistical Variable at a Given Place and Time
+# Retrieve the value of a statistical variable at a given place and time
-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){: target="_blank"} [DCIDs](/glossary.html#dcid). A complete list of variables can be found in the [Statistical Variable Explorer](https://datacommons.org/tools/statvar){: target="_blank"}.
-
-> **Note**: Be sure to follow the instructions for [Installing and Enabling the Sheets Add-On](/api/sheets/) before using this formula.
+The`=DCGET` 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){: target="_blank"} [DCIDs](/glossary.html#dcid). A complete list of variables can be found in the [Statistical Variable Explorer](https://datacommons.org/tools/statvar){: target="_blank"}.
## Formula
```
-=DCGET(dcids, variable, date)
+=DCGET(dcids, variable, [date])
```
-### Required Arguments
+### Required arguments
-* `dcids`: A list of [Place](/glossary.html#place) nodes, identified by their [DCIDs](/glossary.html#dcid).
+* `dcids`: A single [place](/glossary.html#place) node or range of cells represening place nodes, identified by their [DCIDs](/glossary.html#dcid).
* `variable`: The [statistical variable](/glossary.html#variable) whose measurements you want to query.
-### Optional Arguments
+### Optional arguments
`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){: target="_blank"}.
-## Returns
+### Returns
The value of the variable at those places on the specified date or on the latest available date, if no date is specified.
-> **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){: target="_blank"}. 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
-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){: target="_blank"}.
+This section contains examples of using the `=DCGET` formula to returns the values of [statistical variable](/glossary.html#variable)s such as `Count_Person` and `Median_Income_Person`.
-### Example 1: Get the Total Population of Hawaii in 2017
+> **Note**: Be sure to follow the instructions for for [enabling the Sheets add-on](/api/sheets/index.html#install) before trying these examples.
-The following formula returns the total population of Hawaii in 2017 using the "geoId/15" DCID and "Count_Person" variable:
+### Example 1: Get the total population of Hawaii in 2017
-```
-=DCGET("geoId/15", "Count_Person", 2017)
-```
+To get the total population of Hawaii in 2017:
-Running the preceding formula returns a value of 1425763.
+1. Place your cursor in the desired cell.
+1. Enter the formula `=DCGET("geoId/15", "Count_Person", 2017)`. The value `1425763` populates the cell.
-### Example 2: Get the Population of Multiple Places with a Single Call
+### Example 2: Get the population of five Hawaii counties in 2017
-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:
+To get the population of the five counties in 2017:
-```
-=DCGET(B2:B6, "Count_Person", 2017)
-```
+1. Place your cursor in the desired cell; in this case A2, and enter the DCID of Hawaii, namely `geoId/15`.
+1. In cell B2, enter the formula `=DCPLACESIN(A2, "County")`. The DCIDs of the Hawaii counties populate column B.
+1. (Optional) In cell C2, enter `=DCGETNAME(B2:B6)` to retrieve the names of the counties in column C.
+1. In cell D2, enter the formula `=DCGET(B2:B6, "Count_Person", 2017)`.
-
+ 
-Here is the output after running the =DCGET(B2:B6, "Count_Person", 2017) formula:
+ The values populate column D.
-
+ 
-### Example 3: Get the Median Income of a Single Place in Multiple Years
+### Example 3: Get the median income of a single place in multiple years
-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:
+This example shows how to get the median income in Hawaii for the years 2011 - 2013, with dates as columns:
-```
-=DCGET(B2, "Median_Income_Person", C1:E1)
-```
-
-
+1. In a new sheet, in row 1, create cells with the headings shown in the image below.
+1. In cell A2, enter `Hawaii`, and in cell B2, `geoId/15`.
+1. Select cells C2 to E2, and enter the formula `=DCGET(B2, "Median_Income_Person", C1:E1)`.
-Here is the output after running the =DCGET(B2, "Median_Income_Person", C1:E1) formula:
+ 
-
+ The values populate C2, D2 and E2.
-### Example 4: Get the Median Age of Multiple Places in Multiple Years
+ 
-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:
+### Example 4: Get the median age of multiple places in multiple years
-```
-=DCGET(C2:C6, "Median_Age_Person", F1:H1)
-```
+The following examples demonstrate how to retrieve the median age of five counties in Hawaii for the years 2011 - 2015.
-
+To get the results with the counties in rows and the dates in columns, do the following:
-Here is the output after running the =DCGET(C2:C6, "Median_Age_Person", F1:H1) formula:
+1. In a new sheet, in row 1, create cells with the headings shown in the image below, with columns for each year 2011 to 2015.
+1. In cell A2, enter `Hawaii`, and in cell B2, `geoId/15`.
+1. In cell C2, enter the formula `=DCPLACESIN(, "County")`. The county DCIDs populate column C.
+1. In cell D2, enter the formula `=DCGETNAME(C2:C6) `. The county names populate column D.
+1. Place your cursor in cell E2 and enter the formula `=DCGET(C2:C6, "Median_Age_Person", E1:I1)`. The ages for each county and year appear in columns E to I.
-
+
-Here's another example, but this time with places as a row and dates as a column using the formula:
+To get the results with the counties in columns and the dates in rows, do the following:
-```
-=DCGET(B3:F3, "Median_Age_Person", A5:A9)
-```
+1. In a new sheet, in column A, create cells with the headings shown in the image below.
+1. In cell B1, enter `Hawaii`, and in cell B2, `geoId/15`
+1. Manually enter the DCIDs for each county, in cells B3 to F3, as shown in the image below.
+1. Place your cursor in cell B4 and enter the formula `=DCGETNAME(B3:F3) `. The county names populate column D.
+1. Place your cursor in cell B5 and enter the formula `=DCGET(B3:F3, "Median_Age_Person", A5:A9)`.
-
+ 
-Here is the output after running the =DCGET(B3:F3, "Median_Age_Person", A5:A9) formula:
+ The ages for each county and year appear in rows 5 to 9.
-
+ 
-## Error Responses
+## Error responses
-The `=DCGET(dcids)` formula returns a blank value under the following circumstances:
+The `=DCGET` formula returns a blank value under the following circumstances:
-* 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")
+* 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`)
-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")`:
+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")`:
-
+
-If you fail to provide all required arguments, you will receive an error:
+If you fail to provide all required arguments, you will get a response of `#ERROR!`:
-
+
diff --git a/api/sheets/index.md b/api/sheets/index.md
index a5f0f3641..e726be85b 100644
--- a/api/sheets/index.md
+++ b/api/sheets/index.md
@@ -12,13 +12,14 @@ The Data Commons Google Sheets add-on allows you to import data from the Data Co
Read our [step-by-step guides](tutorials/) for examples on using the add-on for various analysis and visualization use cases.
-## Install and enable the Sheets add-on
+## Install and enable the Sheets add-on {#install}
1. Go to the [Google Workspace Marketplace](https://workspace.google.com/marketplace/app/data_commons/454343067575){: target="_blank"} page for Data Commons.
1. Click **Install**.
-1. To enable the Sheets add-on functions, follow the next procedure below to open the **Fill place dcids** feature and fill a place DCID.
+1. Open a new spreadsheet.
+1. Select **Extensions** > **Data Commons** > **Fill place dcids**.
-> **Note:** None of the Data Commons Sheets functions will work in a spreadsheet until you have enabled the add-on by opening the **Fill place dcids** sidebar.
+> **Note:** None of the Data Commons Sheets functions will work in a spreadsheet until you have enabled the add-on by opening the **Fill place dcids** sidebar. You need to open the sidebar every time you reopen the Sheets application or create a new sheet.
## Find a place's DCID {#find-dcid}
@@ -37,7 +38,7 @@ The Data Commons Sheets add-on provides the ability to look up a place’s [DCID
## Data Commons Sheets functions
-The Data Commons Sheets add-on includes the five formulas listed in the following table. Click the links in the table for detailed information on each formula.
+The Data Commons Sheets add-on includes the five formulas listed in the following table. Click the links in the table for detailed information on each formula.
| **Formula** | **Description** |
|----------------------------------------------------------------------------------------------|-------------------------------------------|
@@ -45,11 +46,18 @@ The Data Commons Sheets add-on includes the five formulas listed in the followin
| [=DCPLACESIN(dcids, place_type)](/api/sheets/places_in.html) | Returns places contained in other places. |
| [=DCGET(dcids, variable_name, [date])](/api/sheets/get_variable.html) | Returns statistical observations. |
| [=DCPROPERTY(dcids, property)](/api/sheets/get_property.html) | Returns node property values. |
-| [=DCCOHORTMEMBERS(dcids)](/api/sheets/get_cohort_members.html) | Gets the cohort members of a node. |
+| [=DCCOHORTMEMBERS(dcids)](/api/sheets/get_cohort_members.html) | Returns the cohort members of a node. |
+
+You supply arguments as follows:
+- A single value can be a string literal, such as `"geoId/05"` or `"County"` and must be enclosed quotation marks.
+- Multiple values must be a range of cells (row or column), such as `A2:A5`, and are not enclosed in quotation marks..
+See below for examples.
+
+> **Note**: It’s always best to minimize the number of calls to Data Commons functions by using arguments containing a column or row of values. This is because a spreadsheet will make one call to a Google server [per function call](https://developers.google.com/apps-script/guides/sheets/functions#optimization){: target="_blank"}, so if your sheet contains thousands of separate calls to a function, it will be slow and return with errors.
## Get started with Data Commons functions
-Here's a quick demo on using several of the Data Commons functions to get population data for all counties in the state of California:
+Here's a quick demo on using several of the Data Commons functions to get population data for all counties in the state of California.
1. Open a new sheet and create 3 column headings: `DCID`, `County name`, and `Population`.
1. Select cell A2 and enter the following formula to get a list of the DCIDs of all counties in California, whose DCID is `geoId/06`: `=DCPLACESIN("geoId/06", "County")`. The column fills with 58 DCIDs.
diff --git a/api/sheets/places_in.md b/api/sheets/places_in.md
index 77aa09e58..a8b297474 100644
--- a/api/sheets/places_in.md
+++ b/api/sheets/places_in.md
@@ -1,73 +1,69 @@
---
layout: default
-title: Places Contained Within Another Place
-nav_order: 2
+title: Get places contained in another place
+nav_order: 4
parent: Google Sheets
grand_parent: API
---
-# Retrieving Places Contained Within Another Place
+# Retrieve places contained within another place
-The `=DCPLACESIN(dcids, placeType)` formula returns lists of child places from a list of parent [Place](https://datacommons.org/browser/Place){: target="_blank"} [DCIDs](/glossary.html#dcid). It only returns children with a place type that matches the `placeType` parameter, such as [State](https://datacommons.org/browser/State){: target="_blank"}, [Country](https://datacommons.org/browser/Country){: target="_blank"}, and so on.
-
-> **Note**: Be sure to follow the instructions for [Installing and Enabling the Sheets Add-On](/api/sheets/) before using this formula.
+The `=DCPLACESIN` formula returns lists of child places from a list of parent [`Place`](https://datacommons.org/browser/Place){: target="_blank"} [DCIDs](/glossary.html#dcid). It only returns children with a place type that matches the `place_type` parameter, such as [`State`](https://datacommons.org/browser/State){: target="_blank"}, [`Country`](https://datacommons.org/browser/Country){: target="_blank"}, and so on.
## Formula
```
-=DCPLACESIN(dcids, placeType)
+=DCPLACESIN(dcids, place_type)
```
-## Required Arguments
-
-* `dcids`: A list of parent [Place](/glossary.html#place) nodes, identified by their [DCIDs](/glossary.html#dcid).
-* `placeType`: The type of the contained child `Place` nodes to filter by. For example,`City` and `County`are contained within `State`. For a full list of available types, see the [place types page](/place_types.html).
+### Required arguments
-## Returns
+* `dcids`: A single [place](/glossary.html#place) node or range of cells representing place nodes, identified by their [DCIDs](/glossary.html#dcid).
+* `place_type`: The type of the contained child place nodes to filter by. For example,`City` and `County`are contained within `State`. For a full list of available types, see the [place types page](/place_types.html).
-Lists of child places from a list of parent [Place](https://datacommons.org/browser/Place){: target="_blank"} [DCIDs](/glossary.html#dcid). Returns a list of child places of the specified place DCIDs, of the specified place type.
+### Returns
-> **Note**:
-> It’s best to minimize the number of function calls to `=DCPLACESIN(dcids, placeType)` 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){: target="_blank"}. If your sheet contains many separate calls to `=DCPLACESIN(dcids, placeType)` you can expect it to be slow and return with errors.
+A list of child place DCIDs of the specified place DCIDs, of the specified place type.
## Examples
-This section contains examples of using the `=DCPLACESIN(dcids, placeType)` formula.
+This section contains examples of using the `=DCPLACESIN` formula to return places contained in another place.
-### Example 1: Retrieve a List of Counties in Delaware
+> **Note**: Be sure to follow the instructions for for [enabling the Sheets add-on](/api/sheets/index.html#install) before trying these examples.
-To retrieve a list of counties in Delaware, perform the following steps:
+### Example 1: Retrieve a list of counties in Delaware
-1. Place your cursor in the cell where you want to add the DCID for Delaware. In this case, cell A2.
-2. Enter the Delaware DCID of geoId/10.
-3. (Optional) In cell B2, enter DCGETNAME(A2) to retrieve Delaware's name from the DCID in cell A2.
-4. Move to the cell C3 and enter the formula =DCPLACESIN(A2, "County") to retrieve the county names. The DCIDs for the three Delaware counties populate column C.
-5. Retrieve the Delaware county names by entering the formula =DCGETNAME(C2:C4) into cell D2.
+To retrieve a list of counties in Delaware:
+1. Place your cursor in the cell where you want to add the DCID for Delaware; in this case, cell A2.
+2. Enter the Delaware DCID of `geoId/10`.
+3. (Optional) In cell B2, enter `DCGETNAME(A2)` to retrieve Delaware's name from the DCID in cell A2.
+4. In cell C2, enter the formula `=DCPLACESIN(A2, "County")`. The DCIDs for the three Delaware counties populate column C.
+5. In cell D2, enter the formula `DCGETNAME(C2:C4)` to retrieve the names of the counties.
-
+
-### Example 2: Retrieve Congressional Districts in Alaska and Hawaii
+### Example 2: Retrieve congressional districts in Alaska and Hawaii
-To retrieve the congressional districts in Alaska and Hawaii, perform the following steps:
+To retrieve the congressional districts in Alaska and Hawaii:
-1. In cell A2, enter geoId/02 for the DCID of Alaska and in Cell A3, enter geoId/15 for the DCID of Hawaii.
-2. (Optional) Enter =DCGETNAME(A2:A3) in cell B1 to retrieve the names of Alaska and Hawaii into column B.
-3. Retrieve the DCIDs for the congressional districts by enter =DCPLACESIN(A2:A3, "CongressionalDistrict") into cell C2.
-4. Finally, retrieve the names of the congressional districts by entering =DCGETNAMES(C2:C4) into cell D2.
+1. In cell A2, enter `geoId/02` for the DCID of Alaska and in cell A3, enter `geoId/15` for the DCID of Hawaii.
+2. (Optional) In cell B1, enter `=DCGETNAME(A2:A3)` to retrieve the names of Alaska and Hawaii into column B.
+3. In cell C2, enter `=DCPLACESIN(A2:A3, "CongressionalDistrict")` to retrieve the DCIDs of the congressional districts.
+4. In cell D2, enter `=DCGETNAMES(C2:C4)` to retrieve the names of the congressional districts.
-
+
-## Error Responses
+## Error responses
-If a DCID does not exist, the `=DCPLACESIN(dcids, placeType)` formula returns a value of #REF!. For example, the `=DCPLACESIN(A1, "CongressionalDistrict")` formula should return the congressional districts for the DCID in cell A1. However, because the “geoId/123123123” DCID does not exist, an error of #REF! is returned to cell B1 in the following sheet:
+If a DCID does not exist, the `=DCPLACESIN` formula returns a value of `#REF!`. For example, because the `geoId/123123123` DCID does not exist, an error of `#REF!` is returned to cell B1 in the following sheet:
-
+
-If you provide an empty cell for a DCID, the `=DCPLACESIN(dcids, placeType)` formula returns a value of #ERROR!, as shown show in the following image:
+If you provide an empty cell for a DCID, the `=DCPLACESIN` formula returns a value of `#ERROR!`, as shown show in the following image:
-
+
-Finally, if you provide an invalid property to the `=DCPLACESIN(dcids, placeType)` formula, an error of #REF! is also returned, as follows:
+Finally, if you provide an invalid property to the `=DCPLACESIN` formula, an error of `#REF!` is also returned, as follows:
-
+