Skip to content

Commit

Permalink
Overhaul Sheets function reference pages (#517)
Browse files Browse the repository at this point in the history 
* 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 d35bc34.

* 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
  • Loading branch information
@kmoscoe
kmoscoe authored Oct 15, 2024
1 parent e4d52c4 commit 2cb8a88
Show file tree
Hide file tree
Showing 6 changed files with 190 additions and 193 deletions.
36 changes: 21 additions & 15 deletions api/sheets/get_cohort_members.md
View file
Original file line number Diff line number Diff line change
@@ -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:

![](/assets/images/sheets/sheets_get_cohort_members_input.png)
1. Place your cursor in any cell, say A1, and enter `CDC500_City`.
1. In cell B1, enter `=DCCOHORTMEMBERS(A1)`.

### Output (truncated)
![DCCOHORTMEMBERS example](/assets/images/sheets/sheets_get_cohort_members_input.png)

![](/assets/images/sheets/sheets_get_cohort_members_output.png)
The list of member DCIDs populates column B.

![DCCOHORTMEMBERS example](/assets/images/sheets/sheets_get_cohort_members_output.png)
1. (Optional) To get the names of the members, in cell C1, enter `DCGETNAME(B1:B500)`.
56 changes: 27 additions & 29 deletions api/sheets/get_name.md
View file
Original file line number Diff line number Diff line change
@@ -1,72 +1,70 @@
---
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

```
=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 <code><b>=DCGETNAME(A1)</b></code> to retrieve the name. *California* populates the cell.
1. Enter the formula `=DCGETNAME(A1)` to retrieve the name. `California` populates the cell.

![Retrieving the name of a country by its DCIC](/assets/images/sheets/sheets_get_name_california.png)
![DCGETNAME example 1](/assets/images/sheets/sheets_get_name_california.png)

### 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 <code><b>=DCGETNAME(A2:A4)</b></code>. 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.

![Retrieving the names of a collection of power plants](/assets/images/sheets/sheets_get_name_power_plant.png)
![DCGETNAME example 2](/assets/images/sheets/sheets_get_name_power_plant.png)

### 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 <code><b>=DCGETNAME(A2:A4)</b></code>. 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.

![Retrieving the names of a collection of power plants](/assets/images/sheets/sheets_get_name_sv.png)
![DCGETNAME example 3](/assets/images/sheets/sheets_get_name_sv.png)

## 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:

![No value returned for a DCID that does not exist](/assets/images/sheets/sheets_get_name_wrong_dcid_cropped.png)
![DCGETNAME error example](/assets/images/sheets/sheets_get_name_wrong_dcid_cropped.png)

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:

![#ERROR! value returned for an empty cell for a DCID](/assets/images/sheets/sheets_get_name_no_input_cropped.png)
![DGCETNAME error example](/assets/images/sheets/sheets_get_name_no_input_cropped.png)

79 changes: 35 additions & 44 deletions api/sheets/get_property.md
View file
Original file line number Diff line number Diff line change
@@ -1,91 +1,82 @@
---
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

```
=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 <code><b>country/CIV</b></code> for the country Ivory Coast.
3. Next, place your cursor in cell B2 and enter <code><b>=DCPROPERTY(A1, "name")</b></code> 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:

![Retrieve the Common Name of a Country by its DCID](/assets/images/sheets/sheets_get_property_ivory_coast.png)
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
![DCPROPERTY example 1](/assets/images/sheets/sheets_get_property_ivory_coast.png)

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 <code><b>dc/bsmvthtq89217</b></code> for the plant *Austrobaileya Scandens*.
3. Place your cursor in cell B2 and enter <code><b>=DCPROPERTY(A1, "order")</b></code>.
4. Note that the order *Austrobaileyales* appears in cell B2.
To retrieve the order to which the plant Austrobaileya Scandens belongs:

![Retrieve the Order to which the Plant Austrobaileya Scandens Belongs](/assets/images/sheets/sheets_get_property_austrobaileyales_order.png)
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
![DCPROPERTY example 2](/assets/images/sheets/sheets_get_property_austrobaileyales_order.png)

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 <code><b>nces/360007702877</b></code> for *Stuyvesant Hight School in New York*.
2. Place your cursor in cell A2 and enter <code><b>nces/062961004587</b></code> for *Gunn High School in California*.
3. Enter the formula <code><b>=DCPROPERTY(A1:A2, "address")</b></code> 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:

![Retrieve the Addresses of Stuyvesant High School in New York and Gunn High School in California](/assets/images/sheets/sheets_get_property_school_addresses.png)
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.

![DCPROPERTY example 3](/assets/images/sheets/sheets_get_property_school_addresses.png)

## 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:

![Google Sheets nonexistent property return](/assets/images/sheets/sheets_get_property_bad_property.png)
![DCPROPERTY error example](/assets/images/sheets/sheets_get_property_bad_property.png)

If you pass a bad DCID, an empty value is returned:

![Google Sheets empty value return](/assets/images/sheets/sheets_get_property_bad_dcid.png)
![DCPROPERTY error example](/assets/images/sheets/sheets_get_property_bad_dcid.png)

If you pass an empty DCID, an error is returned:
If you pass an empty DCID, a response of `#ERROR!` is returned:

![Google Sheets empty DCID error return](/assets/images/sheets/sheets_get_property_empty_dcid.png)
![DCPROPERTY error example](/assets/images/sheets/sheets_get_property_empty_dcid.png)

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:

![Google Sheets return for missing required property argument](/assets/images/sheets/sheets_get_property_bad_args.png)
![DCPROPERTY error example](/assets/images/sheets/sheets_get_property_bad_args.png)

Loading

0 comments on commit 2cb8a88

Please sign in to comment.