Add best practices for statvars for Custom DC

[kmoscoe]

This PR makes the following changes:

• Describes when to reuse existing statvars vs. creating new ones
• Adds naming convention guidelines (based on go/dcguidebook)
• Fixes description of groupStatVarsByProperty to cover actual behavior
• Expands statvar groups section to include existing variables

Staged at http://bullie.svl.corp.google.com:4000

Next PR will cover similar content for custom entities and enums

[gemini-code-assist]

Summary of Changes

Hello @kmoscoe, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly improves the documentation for Custom Data Commons, particularly focusing on best practices for statistical variable management. The changes aim to provide clearer, more detailed guidance for users on defining, naming, and organizing statistical variables, ensuring better data quality and compatibility for potential contributions to the main Data Commons knowledge graph. It also refines explanations of core concepts like entity types and variable grouping.

Highlights

• Statistical Variable Best Practices: Added comprehensive guidelines on when to reuse existing statistical variables versus creating new ones, emphasizing the importance of reuse for data contribution and accurate linking.
• Naming Conventions: Introduced a new section detailing standard naming conventions for statistical variables, crucial for those planning to contribute their data to base Data Commons.
• Enhanced Entity Type Explanations: Clarified the distinction between populationType and aggregation levels within entity types, providing more detailed guidance for users.
• MCF Variable Definition Guidance: Refined instructions for defining statistical variables in Metadata Content Format (MCF), including a note on when to skip this step and a warning against overriding existing variable definitions.
• Statistical Variable Grouping: Updated the section on defining statistical variable groups, making it optional and adding instructions for assigning existing variables to new custom groups for better discoverability.

Changelog

• custom_dc/config.md
  • Updated the description of groupStatVarsByProperty to provide a more detailed explanation and removed an associated screenshot.
• custom_dc/custom_data.md
  • Modified the link text for defining custom entities from "new custom entities" to "new entities".
  • Expanded the explanation of "Entities and entity types" to differentiate between populationType and aggregation levels.
  • Revised the guidance on statistical variables, stressing the importance of reusing or extending existing variables and the implications for contributing data.
  • Introduced a new section detailing "Naming conventions" for statistical variables, including examples for basic, measurementQualifier, and measurementDenominator cases.
  • Clarified the process for defining statistical variables in MCF, including a note on when to skip this step and a warning against overriding existing variable definitions.
  • Updated the description for populationType to advise on creating new entity types if necessary.
  • Enhanced the statType description by providing more examples of calculated values and a link to the full list of allowable values.
  • Restructured the "Define a statistical variable group" section, making it optional and adding instructions for assigning existing variables to new groups.
  • Adjusted the numbering of subsequent steps in the data preparation guide.
• custom_dc/quickstart.md
  • Removed an unnecessary blank line within a shell command example.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request improves the documentation for custom Data Commons, focusing on best practices for statistical variables (statvars). The changes clarify when to reuse existing statvars, add naming convention guidelines, and provide better examples. I've found a few areas in the documentation that could be further improved for clarity and correctness, including a typo, a broken link, and a couple of confusing or incorrect examples. My suggestions aim to make the documentation more accurate and easier for users to follow.

[beets]

wow, this is a great update. thanks for breaking down all the requirements.

there is currently a limit to the length of dcid's in custom dc. i'll ping that group to see where we are with it

might want to wait for ajai to approve this pr too

[beets]

would be nice if we linked to the pop types for these examples

[kmoscoe]

Not sure I understand what you mean here. Do you mean link to the browser pages for these entities?

[beets]

yes, we could link to the "Person" browser page. i'm also wondering if we have poptypes for the others in the examples (beds in a hospital, price of a commodity, etc). in other words, i thought the reader might be curious about how those examples would be modeled.

[kmoscoe]

The thing is it's a bit confusing: the incoming populationType arcs section shows statvars (https://screenshot.googleplex.com/ASWnrHqVefUfW5r) while it's the domainIncludes section that actually shows the population types: https://screenshot.googleplex.com/BrTds7ghnFBvekP. I think at this point in the doc it's too early to get into these details, which are actually quite confusing.

[beets]

sg to skip then

[kmoscoe]

wow, this is a great update. thanks for breaking down all the requirements.

there is currently a limit to the length of dcid's in custom dc. i'll ping that group to see where we are with it

any update on that?

might want to wait for ajai to approve this pr too