.

datacards/overview.py

@@ -34,6 +34,16 @@ def overview_page():
     st.session_state.card_dict["overview"] = st.session_state.card_dict.get(
         "overview", {}
     )
+    with st.expander("Where to find the data and its documentation", expanded=True):
+        key_pref = ["overview", "what"]
+        st.session_state.card_dict["overview"]["what"] = st.session_state.card_dict[
+            "overview"
+        ].get("what", {})
+        make_text_area(
+            label="Provide a summary of this dataset in 3-4 sentences.",
+            key_list=key_pref + ["dataset"],
+            help="[free text]",
+        )
     with st.expander("Where to find the data and its documentation", expanded=False):
         key_pref = ["overview", "where"]
         st.session_state.card_dict["overview"]["where"] = st.session_state.card_dict[

formatting/format_as_md.py

@@ -1,6 +1,7 @@
 import argparse
 import json
 import pathlib
+import os
 
 parser = argparse.ArgumentParser(
     description="Format the output of the data card tool as .md for the hub."
@@ -72,6 +73,6 @@ def construct_md(data_card_data: dict, text_by_key: dict):
 
 if __name__ == "__main__":
     data_card_data = read_json_file(args.input_path)
-    text_by_key = read_json_file("key_to_question.json")
+    text_by_key = read_json_file(os.path.join(os.path.dirname(__file__), "key_to_question.json"))
     data_card_md_string = construct_md(data_card_data, text_by_key)
     save_md_file(args.output_path, data_card_md_string)

formatting/key_to_question.json

@@ -1,189 +1,952 @@
 {
-    "overview": {
-      "section-title": "Dataset Overview",
-      "where": {
-        "section-title": "Where to find the data and its documentation",
-        "website": "What is the webpage for the dataset (if it exists)?",
-        "data-url": "What is the link to where the original dataset is hosted?",
-        "paper-url": "What is the link to the paper describing the dataset (open access preferred)?",
-        "paper-bibtext": "Provide the BibTex-formatted reference for the dataset. Please use the correct published version (ACL anthology, etc.) instead of google scholar created Bibtex.",
-        "contact-name": "If known, provide the name of at least one person the reader can contact for questions about the dataset.",
-        "contact-email": "If known, provide the email of at least one person the reader can contact for questions about the dataset.",
-        "has-leaderboard": "Does the dataset have an active leaderboard?",
-        "leaderboard-url": "Provide a link to the leaderboard.",
-        "leaderboard-description": "Briefly describe how the leaderboard evaluates models."
-      },
-      "languages": {
-        "section-title": "Languages and Intended Use",
-        "is-multilingual": "Is the dataset multilingual?",
-        "language-dialects": "What dialects are covered? Are there multiple dialects per language?",
-        "language-names": "What languages/dialects are covered in the dataset?",
-        "language-speakers": "Whose language is in the dataset?",
-        "license": "What is the license of the dataset?",
-        "task-other": "What is the primary task?",
-        "intended-use": "What is the intended use of the dataset?",
-        "license-other": "What is the 'other' license of the dataset?",
-        "task": "What primary task does the dataset support?",
-        "communicative": "Provide a short description of the communicative goal of a model trained for this task on this dataset."
-      },
-      "credit": {
-        "section-title": "Credit",
-        "organization-type": "In what kind of organization did the dataset curation happen?",
-        "organization-names": "Name the organization(s).",
-        "creators": "Who created the original dataset? List the people involved in collecting the dataset and their affiliation(s).",
-        "funding": "Who funded the data creation?",
-        "gem-added-by": "Who contributed to the data card and adding the dataset to GEM? List the people+affiliations involved in creating this data card and who helped integrate this dataset into GEM."
-      },
-      "structure": {
-        "section-title": "Structure",
-        "data-fields": "List and describe the fields present in the dataset.",
-        "structure-description": "How was the dataset structure determined?",
-        "structure-labels": "How were the labels chosen?",
-        "structure-example": "Provide a JSON formatted example of a typical instance in the dataset.",
-        "structure-splits": "Describe and name the splits in the dataset if there are more than one.",
-        "structure-splits-criteria": "Describe any criteria for splitting the data, if used. If there are differences between the splits (e.g., if the training annotations are machine-generated and the dev and test ones are created by humans, or if different numbers of annotators contributed to each example), describe them here.",
-        "structure-outlier": "What does an outlier of the dataset in terms of length/perplexity/embedding look like?"
+  "overview": {
+    "section-title": "Dataset Overview",
+    "where": {
+      "section-title": "Where to find the Data and its Documentation",
+      "website": {
+        "title": "Webpage",
+        "info": "What is the webpage for the dataset (if it exists)?",
+        "flags": [
+          "quick"
+        ],
+        "scope": "telescope"
+      },
+      "data-url": {
+        "title": "Download",
+        "info": "What is the link to where the original dataset is hosted?",
+        "flags": [
+          ""
+        ],
+        "scope": "telescope"
+      },
+      "paper-url": {
+        "title": "Paper",
+        "info": "What is the link to the paper describing the dataset (open access preferred)?",
+        "flags": [
+          ""
+        ],
+        "scope": "telescope"
+      },
+      "paper-bibtext": {
+        "title": "BibTex",
+        "info": "Provide the BibTex-formatted reference for the dataset. Please use the correct published version (ACL anthology, etc.) instead of google scholar created Bibtex.",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      },
+      "contact-name": {
+        "title": "Contact Name",
+        "info": "If known, provide the name of at least one person the reader can contact for questions about the dataset.",
+        "flags": [
+          "quick"
+        ],
+        "scope": "periscope"
+      },
+      "contact-email": {
+        "title": "Contact Email",
+        "info": "If known, provide the email of at least one person the reader can contact for questions about the dataset.",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      },
+      "has-leaderboard": {
+        "title": "Has a Leaderboard?",
+        "info": "Does the dataset have an active leaderboard?",
+        "flags": [
+          ""
+        ],
+        "scope": "telescope"
+      },
+      "leaderboard-url": {
+        "title": "Leaderboard Link",
+        "info": "Provide a link to the leaderboard.",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      },
+      "leaderboard-description": {
+        "title": "Leaderboard Details",
+        "info": "Briefly describe how the leaderboard evaluates models.",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
       }
     },
-    "gem": {
-      "section-title": "Dataset in GEM",
-      "rationale": {
-        "section-title": "Rationale",
-        "contribution": "What does this dataset contribute toward better generation evaluation and why is it part of GEM?",
-        "sole-task-dataset": "Do other datasets for the high level task exist?",
-        "sole-language-task-dataset": "Does this dataset cover other languages than other datasets for the same task?",
-        "distinction-description": "What else sets this dataset apart from other similar datasets in GEM?",
-        "model-ability": "What aspect of model ability can be measured with this dataset?"
-      },
-      "curation": {
-        "section-title": "GEM Additional Curation",
-        "has-additional-curation": "Has the GEM version of the dataset been modified in any way (data, processing, splits) from the original curated data?",
-        "modification-types": "What changes have been made to he original dataset?",
-        "modification-description": "For each of these changes, described them in more details and provided the intended purpose of the modification",
-        "has-additional-splits": "Does GEM provide additional splits to the dataset?",
-        "additional-splits-description": "Describe how the new splits were created",
-        "additional-splits-capacicites": "What aspects of the model's generation capacities were the splits created to test?"
-      },
-      "starting": {
-        "section-title": "Getting Started",
-        "research-pointers": "Getting started with in-depth research on the task. Add relevant pointers to resources that researchers can consult when they want to get started digging deeper into the task.",
-        "technical-terms": "Technical terms used in this card and the dataset and their definitions"
+    "languages": {
+      "section-title": "Languages and Intended Use",
+      "is-multilingual": {
+        "title": "Multilingual?",
+        "info": "Is the dataset multilingual?",
+        "flags": [
+          "quick"
+        ],
+        "scope": "telescope"
+      },
+      "language-dialects": {
+        "title": "Covered Dialects",
+        "info": "What dialects are covered? Are there multiple dialects per language?",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      },
+      "language-names": {
+        "title": "Covered Languages",
+        "info": "What languages/dialects are covered in the dataset?",
+        "flags": [
+          "quick"
+        ],
+        "scope": "telescope"
+      },
+      "language-speakers": {
+        "title": "Whose Language?",
+        "info": "Whose language is in the dataset?",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      },
+      "license": {
+        "title": "License",
+        "info": "What is the license of the dataset?",
+        "flags": [
+          "quick"
+        ],
+        "scope": "telescope"
+      },
+      "task-other": {
+        "title": "Primary Task",
+        "info": "What is the primary task?",
+        "flags": [
+          "quick"
+        ],
+        "scope": "periscope"
+      },
+      "intended-use": {
+        "title": "Intended Use",
+        "info": "What is the intended use of the dataset?",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
+      },
+      "license-other": {
+        "title": "Add. License Info",
+        "info": "What is the 'other' license of the dataset?",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      },
+      "task": {
+        "title": "Primary Task",
+        "info": "What primary task does the dataset support?",
+        "flags": [
+          ""
+        ],
+        "scope": "telescope"
+      },
+      "communicative": {
+        "title": "Communicative Goal",
+        "info": "Provide a short description of the communicative goal of a model trained for this task on this dataset.",
+        "flags": [
+          "quick"
+        ],
+        "scope": "periscope"
+      }
+    },
+    "credit": {
+      "section-title": "Credit",
+      "organization-type": {
+        "title": "Curation Organization Type(s)",
+        "info": "In what kind of organization did the dataset curation happen?",
+        "flags": [
+          ""
+        ],
+        "scope": "telescope"
+      },
+      "organization-names": {
+        "title": "Curation Organization(s)",
+        "info": "Name the organization(s).",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      },
+      "creators": {
+        "title": "Dataset Creators",
+        "info": "Who created the original dataset? List the people involved in collecting the dataset and their affiliation(s).",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
+      },
+      "funding": {
+        "title": "Funding",
+        "info": "Who funded the data creation?",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
+      },
+      "gem-added-by": {
+        "title": "Who added the Dataset to GEM?",
+        "info": "Who contributed to the data card and adding the dataset to GEM? List the people+affiliations involved in creating this data card and who helped integrate this dataset into GEM.",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
       }
     },
+    "structure": {
+      "section-title": "Dataset Structure",
+      "data-fields": {
+        "title": "Data Fields",
+        "info": "List and describe the fields present in the dataset.",
+        "flags": [
+          ""
+        ],
+        "scope": "telescope"
+      },
+      "structure-description": {
+        "title": "Reason for Structure",
+        "info": "How was the dataset structure determined?",
+        "flags": [
+          "quick"
+        ],
+        "scope": "microscope"
+      },
+      "structure-labels": {
+        "title": "How were labels chosen?",
+        "info": "How were the labels chosen?",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
+      },
+      "structure-example": {
+        "title": "Example Instance",
+        "info": "Provide a JSON formatted example of a typical instance in the dataset.",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      },
+      "structure-splits": {
+        "title": "Data Splits",
+        "info": "Describe and name the splits in the dataset if there are more than one.",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      },
+      "structure-splits-criteria": {
+        "title": "Splitting Criteria",
+        "info": "Describe any criteria for splitting the data, if used. If there are differences between the splits (e.g., if the training annotations are machine-generated and the dev and test ones are created by humans, or if different numbers of annotators contributed to each example), describe them here.",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
+      },
+      "structure-outlier": {
+        "title": "",
+        "info": "What does an outlier of the dataset in terms of length/perplexity/embedding look like?",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
+      }
+    }
+  },
+  "gem": {
+    "section-title": "Dataset in GEM",
+    "rationale": {
+      "section-title": "Rationale for Inclusion in GEM",
+      "contribution": {
+        "title": "Why is the Dataset in GEM?",
+        "info": "What does this dataset contribute toward better generation evaluation and why is it part of GEM?",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
+      },
+      "sole-task-dataset": {
+        "title": "Similar Datasets",
+        "info": "Do other datasets for the high level task exist?",
+        "flags": [
+          ""
+        ],
+        "scope": "telescope"
+      },
+      "sole-language-task-dataset": {
+        "title": "Unique Language Coverage",
+        "info": "Does this dataset cover other languages than other datasets for the same task?",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      },
+      "distinction-description": {
+        "title": "Difference from other GEM datasets",
+        "info": "What else sets this dataset apart from other similar datasets in GEM?",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
+      },
+      "model-ability": {
+        "title": "Ability that the Dataset measures",
+        "info": "What aspect of model ability can be measured with this dataset?",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      }
+    },
+    "curation": {
+      "section-title": "GEM-Specific Curation",
+      "has-additional-curation": {
+        "title": "Modificatied for GEM?",
+        "info": "Has the GEM version of the dataset been modified in any way (data, processing, splits) from the original curated data?",
+        "flags": [
+          ""
+        ],
+        "scope": "telescope"
+      },
+      "modification-types": {
+        "title": "GEM Modifications",
+        "info": "What changes have been made to he original dataset?",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      },
+      "modification-description": {
+        "title": "Modification Details",
+        "info": "For each of these changes, described them in more details and provided the intended purpose of the modification",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
+      },
+      "has-additional-splits": {
+        "title": "Additional Splits?",
+        "info": "Does GEM provide additional splits to the dataset?",
+        "flags": [
+          ""
+        ],
+        "scope": "telescope"
+      },
+      "additional-splits-description": {
+        "title": "Split Information",
+        "info": "Describe how the new splits were created",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      },
+      "additional-splits-capacicites": {
+        "title": "Split Motivation",
+        "info": "What aspects of the model's generation capacities were the splits created to test?",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      }
+    },
+    "starting": {
+      "section-title": "Getting Started with the Task",
+      "research-pointers": {
+        "title": "Pointers to Resources",
+        "info": "Getting started with in-depth research on the task. Add relevant pointers to resources that researchers can consult when they want to get started digging deeper into the task.",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
+      },
+      "technical-terms": {
+        "title": "Technical Terms",
+        "info": "Technical terms used in this card and the dataset and their definitions",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
+      }
+    }
+  },
+  "results": {
+    "section-title": "Previous Results",
     "results": {
       "section-title": "Previous Results",
-      "results": {
-        "section-title": "Previous Results",
-        "model-abilities": "What aspect of model ability can be measured with this dataset?",
-        "metrics": "What metrics are typically used for this task?",
-        "other-metrics-definitions": "Definitions of other metrics",
-        "original-evaluation": "List and describe the purpose of the metrics and evaluation methodology (including human evaluation) that the dataset creators used when introducing this task.",
-        "has-previous-results": "Are previous results available?",
-        "current-evaluation": "What evaluation approaches have others used?",
-        "previous-results": "What are the most relevant previous results for this task/dataset?"
+      "model-abilities": {
+        "title": "Measured Model Abilities",
+        "info": "What aspect of model ability can be measured with this dataset?",
+        "flags": [
+          ""
+        ],
+        "scope": "telescope"
+      },
+      "metrics": {
+        "title": "Metrics",
+        "info": "What metrics are typically used for this task?",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      },
+      "other-metrics-definitions": {
+        "title": "Other Metrics",
+        "info": "Definitions of other metrics",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
+      },
+      "original-evaluation": {
+        "title": "Proposed Evaluation",
+        "info": "List and describe the purpose of the metrics and evaluation methodology (including human evaluation) that the dataset creators used when introducing this task.",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
+      },
+      "has-previous-results": {
+        "title": "Previous results available?",
+        "info": "Are previous results available?",
+        "flags": [
+          ""
+        ],
+        "scope": "telescope"
+      },
+      "current-evaluation": {
+        "title": "Other Evaluation Approaches",
+        "info": "What evaluation approaches have others used?",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      },
+      "previous-results": {
+        "title": "Relevant Previous Results",
+        "info": "What are the most relevant previous results for this task/dataset?",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
+      }
+    }
+  },
+  "curation": {
+    "section-title": "Dataset Curation",
+    "original": {
+      "section-title": "Original Curation",
+      "rationale": {
+        "title": "Original Curation Rationale",
+        "info": "Original curation rationale",
+        "flags": [
+          ""
+        ],
+        "scope": "telescope"
+      },
+      "communicative": {
+        "title": "Communicative Goal",
+        "info": "What was the communicative goal?",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      },
+      "is-aggregated": {
+        "title": "Sourced from Different Sources",
+        "info": "Is the dataset aggregated from different data sources?",
+        "flags": [
+          ""
+        ],
+        "scope": "telescope"
+      },
+      "aggregated-sources": {
+        "title": "Source Details",
+        "info": "List the sources (one per line)",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
       }
     },
-    "curation": {
-      "section-title": "Dataset Curation",
-      "original": {
-        "section-title": "Original Curation",
-        "rationale": "Original curation rationale",
-        "communicative": "What was the communicative goal?",
-        "is-aggregated": "Is the dataset aggregated from different data sources?",
-        "aggregated-sources": "List the sources (one per line)"
-      },
-      "language": {
-        "section-title": "Language Data",
-        "obtained": "How was the language data obtained?",
-        "found": "If found, where from?",
-        "crowdsourced": "If crowdsourced, where from?",
-        "created": "If created for the dataset, describe the creation process.",
-        "machine-generated": "If text was machine-generated for the dataset, provide a link to the generation method if available (N/A otherwise).",
-        "producers-description": "What further information do we have on the language producers?",
-        "topics": "Does the language in the dataset focus on specific topics? How would you describe them?",
-        "validated": "Was the text validated by a different worker or a data curator?",
-        "pre-processed": "How was the text data pre-processed? (Enter N/A if the text was not pre-processed)",
-        "is-filtered": "Were text instances selected or filtered?",
-        "filtered-criteria": "What were the selection criteria?"
-      },
-      "annotations": {
-        "section-title": "Structured Annotations",
-        "origin": "Does the dataset have additional annotations for each instance?",
-        "rater-number": "What is the number of raters",
-        "rater-qualifications": "Describe the qualifications required of an annotator.",
-        "rater-training-num": "How many annotators saw each training example?",
-        "rater-test-num": "How many annotators saw each test example?",
-        "rater-annotation-service-bool": "Was an annotation service used?",
-        "rater-annotation-service": "Which annotation services were used?",
-        "values": "Purpose and values for each annoation",
-        "quality-control": "Quality control measures?",
-        "quality-control-details": "Describe the quality control measures that were taken."
-      },
-      "consent": {
-        "section-title": "Consent",
-        "has-consent": "Was there a consent policy involved when gathering the data?",
-        "consent-policy": "What was the consent policy?",
-        "consent-other": "What other downstream uses of the data did the original data creators and the data curators consent to?",
-        "no-consent-justification": "If not, what is the justification for reusing the data?"
-      },
-      "pii": {
-        "section-title": "Private Identifying Information (PII)",
-        "has-pii": "Does the source language data likely contain Personal Identifying Information about the data creators or subjects?",
-        "no-pii-justification": "Provide a justification for selecting `no PII` above.",
-        "pii-categories": "What categories of PII are present or suspected in the data?",
-        "is-pii-identified": "Did the curators use any automatic/manual method to identify PII in the dataset?",
-        "pii-identified-method": "Describe the method used to identify PII in the dataset.",
-        "is-pii-replaced": "Was the PII pseudonymized/handled somehow?",
-        "pii-replaced-method": "Describe the methods that were used to process the PII."
-      },
-      "maintenance": {
-        "section-title": "Maintenance",
-        "has-maintenance": "Does the original dataset have a maintenance plan?",
-        "description": "Describe the original dataset's maintenance plan.",
-        "contact": "Provide contact information of a person responsible for the dataset maintenance",
-        "contestation-mechanism": "Does the maintenance plan include a contestation mechanism allowing individuals to request removal fo content?",
-        "contestation-description": "Describe the contestation mechanism",
-        "contestation-link": "Provide the form link or contact information"
+    "language": {
+      "section-title": "Language Data",
+      "obtained": {
+        "title": "How was Language Data Obtained?",
+        "info": "How was the language data obtained?",
+        "flags": [
+          ""
+        ],
+        "scope": "telescope"
+      },
+      "found": {
+        "title": "Where was it found?",
+        "info": "If found, where from?",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      },
+      "crowdsourced": {
+        "title": "Where was it crowdsourced?",
+        "info": "If crowdsourced, where from?",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      },
+      "created": {
+        "title": "Creation Process",
+        "info": "If created for the dataset, describe the creation process.",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
+      },
+      "machine-generated": {
+        "title": "Generation Method Link",
+        "info": "If text was machine-generated for the dataset, provide a link to the generation method if available (N/A otherwise).",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      },
+      "producers-description": {
+        "title": "Language Producers",
+        "info": "What further information do we have on the language producers?",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
+      },
+      "topics": {
+        "title": "Topics Covered",
+        "info": "Does the language in the dataset focus on specific topics? How would you describe them?",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      },
+      "validated": {
+        "title": "Data Validation",
+        "info": "Was the text validated by a different worker or a data curator?",
+        "flags": [
+          ""
+        ],
+        "scope": "telescope"
+      },
+      "pre-processed": {
+        "title": "Data Preprocessing",
+        "info": "How was the text data pre-processed? (Enter N/A if the text was not pre-processed)",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      },
+      "is-filtered": {
+        "title": "Was Data Filtered?",
+        "info": "Were text instances selected or filtered?",
+        "flags": [
+          ""
+        ],
+        "scope": "telescope"
+      },
+      "filtered-criteria": {
+        "title": "Filter Criteria",
+        "info": "What were the selection criteria?",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      }
+    },
+    "annotations": {
+      "section-title": "Structured Annotations",
+      "origin": {
+        "title": "Additional Annotations?",
+        "info": "Does the dataset have additional annotations for each instance?",
+        "flags": [
+          "quick"
+        ],
+        "scope": "telescope"
+      },
+      "rater-number": {
+        "title": "Number of Raters",
+        "info": "What is the number of raters",
+        "flags": [
+          ""
+        ],
+        "scope": "telescope"
+      },
+      "rater-qualifications": {
+        "title": "Rater Qualifications",
+        "info": "Describe the qualifications required of an annotator.",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      },
+      "rater-training-num": {
+        "title": "Raters per Training Example",
+        "info": "How many annotators saw each training example?",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      },
+      "rater-test-num": {
+        "title": "Raters per Test Example",
+        "info": "How many annotators saw each test example?",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      },
+      "rater-annotation-service-bool": {
+        "title": "Annotation Service?",
+        "info": "Was an annotation service used?",
+        "flags": [
+          ""
+        ],
+        "scope": "telescope"
+      },
+      "rater-annotation-service": {
+        "title": "Which Annotation Service",
+        "info": "Which annotation services were used?",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      },
+      "values": {
+        "title": "Annotation Values",
+        "info": "Purpose and values for each annotation",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
+      },
+      "quality-control": {
+        "title": "Any Quality Control?",
+        "info": "Quality control measures?",
+        "flags": [
+          ""
+        ],
+        "scope": "telescope"
+      },
+      "quality-control-details": {
+        "title": "Quality Control Details",
+        "info": "Describe the quality control measures that were taken.",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
+      }
+    },
+    "consent": {
+      "section-title": "Consent",
+      "has-consent": {
+        "title": "Any Consent Policy?",
+        "info": "Was there a consent policy involved when gathering the data?",
+        "flags": [
+          ""
+        ],
+        "scope": "telescope"
+      },
+      "consent-policy": {
+        "title": "Consent Policy Details",
+        "info": "What was the consent policy?",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
+      },
+      "consent-other": {
+        "title": "Other Consented Downstream Use",
+        "info": "What other downstream uses of the data did the original data creators and the data curators consent to?",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
+      },
+      "no-consent-justification": {
+        "title": "Justification for Using the Data",
+        "info": "If not, what is the justification for reusing the data?",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
+      }
+    },
+    "pii": {
+      "section-title": "Private Identifying Information (PII)",
+      "has-pii": {
+        "title": "Contains PII?",
+        "info": "Does the source language data likely contain Personal Identifying Information about the data creators or subjects?",
+        "flags": [
+          "quick"
+        ],
+        "scope": "telescope"
+      },
+      "no-pii-justification": {
+        "title": "Justification for no PII",
+        "info": "Provide a justification for selecting `no PII` above.",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      },
+      "pii-categories": {
+        "title": "Categories of PII",
+        "info": "What categories of PII are present or suspected in the data?",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      },
+      "is-pii-identified": {
+        "title": "Any PII Identification?",
+        "info": "Did the curators use any automatic/manual method to identify PII in the dataset?",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      },
+      "pii-identified-method": {
+        "title": "PII Identification Details",
+        "info": "Describe the method used to identify PII in the dataset.",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
+      },
+      "is-pii-replaced": {
+        "title": "Any Anonymization?",
+        "info": "Was the PII pseudonymized/handled somehow?",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      },
+      "pii-replaced-method": {
+        "title": "Anonymization Details",
+        "info": "Describe the methods that were used to process the PII.",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
+      }
+    },
+    "maintenance": {
+      "section-title": "Maintenance",
+      "has-maintenance": {
+        "title": "Any Maintenance Plan?",
+        "info": "Does the original dataset have a maintenance plan?",
+        "flags": [
+          ""
+        ],
+        "scope": "telescope"
+      },
+      "description": {
+        "title": "Maintenance Plan Details",
+        "info": "Describe the original dataset's maintenance plan.",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
+      },
+      "contact": {
+        "title": "Maintainer Contact Information",
+        "info": "Provide contact information of a person responsible for the dataset maintenance",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      },
+      "contestation-mechanism": {
+        "title": "Any Contestation Mechanism?",
+        "info": "Does the maintenance plan include a contestation mechanism allowing individuals to request removal fo content?",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      },
+      "contestation-description": {
+        "title": "Contestation Mechanism Details",
+        "info": "Describe the contestation mechanism",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
+      },
+      "contestation-link": {
+        "title": "Contestation Form Link",
+        "info": "Provide the form link or contact information",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      }
+    }
+  },
+  "context": {
+    "section-title": "Broader Social Context",
+    "previous": {
+      "section-title": "Previous Work on the Social Impact of the Dataset",
+      "is-deployed": {
+        "title": "Usage of Models based on the Data",
+        "info": "Are you aware of cases where models trained on the task featured in this dataset ore related tasks have been used in automated systems?",
+        "flags": [
+          ""
+        ],
+        "scope": "telescope"
+      },
+      "described-risks": {
+        "title": "Social Impact Observations",
+        "info": "Did any of these previous uses result in observations about the social impact of the systems? In particular, has there been work outlining the risks and limitations of the system? Provide links and descriptions here.",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
+      },
+      "changes-from-observation": {
+        "title": "Changes as Consequence of Social Impact",
+        "info": "Have any changes been made to the dataset as a result of these observations?",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      }
+    },
+    "underserved": {
+      "section-title": "Impact on Under-Served Communities",
+      "helps-underserved": {
+        "title": "Addresses needs of underserved Communities?",
+        "info": "Does this dataset address the needs of communities that are traditionally underserved in language technology, and particularly language generation technology? Communities may be underserved for exemple because their language, language variety, or social or geographical context is underepresented in NLP and NLG resources (datasets and models).",
+        "flags": [
+          ""
+        ],
+        "scope": "telescope"
+      },
+      "underserved-description": {
+        "title": "Details on how Dataset Addresses the Needs",
+        "info": "Describe how this dataset addresses the needs of underserved communities.",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
       }
     },
-    "context": {
-      "section-title": "Broader Social Context",
-      "previous": {
-        "section-title": "Previous Work on the Social Impact of the Dataset",
-        "is-deployed": "Are you aware of cases where models trained on the task featured in this dataset ore related tasks have been used in automated systems?",
-        "described-risks": "Did any of these previous uses result in observations about the social impact of the systems? In particular, has there been work outlining the risks and limitations of the system? Provide links and descriptions here.",
-        "changes-from-observation": "Have any changes been made to the dataset as a result of these observations?"
-      },
-      "underserved": {
-        "section-title": "Impact on Under-Served Communities",
-        "helps-underserved": "Does this dataset address the needs of communities that are traditionally underserved in language technology, and particularly language generation technology? Communities may be underserved for exemple because their language, language variety, or social or geographical context is underepresented in NLP and NLG resources (datasets and models).",
-        "underserved-description": "Describe how this dataset addresses the needs of underserved communities."
-      },
-      "biases": {
-        "section-title": "Discussion of Biases",
-        "has-biases": "Are there documented social biases in the dataset? Biases in this context are variations in the ways members of different social categories are represented that can have harmful downstream consequences for members of the more disadvantaged group.",
-        "bias-analyses": "Provide links to and summaries of works analyzing these biases.",
-        "speaker-distibution": "Does the distribution of language producers in the dataset accurately represent the full distribution of speakers of the language world-wide? If not, how does it differ?"
+    "biases": {
+      "section-title": "Discussion of Biases",
+      "has-biases": {
+        "title": "Any Documented Social Biases?",
+        "info": "Are there documented social biases in the dataset? Biases in this context are variations in the ways members of different social categories are represented that can have harmful downstream consequences for members of the more disadvantaged group.",
+        "flags": [
+          ""
+        ],
+        "scope": "telescope"
+      },
+      "bias-analyses": {
+        "title": "Links and Summaries of Analysis Work",
+        "info": "Provide links to and summaries of works analyzing these biases.",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
+      },
+      "speaker-distibution": {
+        "title": "Are the Language Producers Representative of the Language?",
+        "info": "Does the distribution of language producers in the dataset accurately represent the full distribution of speakers of the language world-wide? If not, how does it differ?",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      }
+    }
+  },
+  "considerations": {
+    "section-title": "Considerations for Using the Data",
+    "pii": {
+      "section-title": "PII Risks and Liability",
+      "risks-description": {
+        "title": "Potential PII Risk",
+        "info": "Considering your answers to the PII part of the Data Curation Section, describe any potential privacy to the data subjects and creators risks when using the dataset.",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
       }
     },
-    "considerations": {
-      "section-title": "Considerations for Using the Data",
-      "pii": {
-        "section-title": "PII Risks and Liability",
-        "risks-description": "Considering your answers to the PII part of the Data Curation Section, describe any potential privacy to the data subjects and creators risks when using the dataset."
-      },
-      "licenses": {
-        "section-title": "Licenses",
-        "dataset-restrictions": "Based on your answers in the Intended Use part of the Data Overview Section, which of the following best describe the copyright and licensing status of the dataset?",
-        "dataset-restrictions-other": "You selected `other` for the dataset licensing status, please elaborate here:",
-        "data-copyright": "Based on your answers in the Language part of the Data Curation Section, which of the following best describe the copyright and licensing status of the underlying language data?",
-        "data-copyright-other": "You selected `other` for the source data licensing status, please elaborate here:"
-      },
-      "limitations": {
-        "section-title": "Known Technical Limitations",
-        "data-technical-limitations": "Describe any known technical limitations, such as spurrious correlations, train/test overlap, annotation biases, or mis-annotations, and cite the works that first identified these limitations when possible.",
-        "data-unsuited-applications": "When using a model trained on this dataset in a setting where users or the public may interact with its predictions, what are some pitfalls to look out for? In particular, describe some applications of the general task featured in this dataset that its curation or properties make it less suitable for.",
-        "data-discouraged-use": "What are some discouraged use cases of a model trained to maximize the proposed metrics on this dataset? In particular, think about settings where decisions made by a model that performs reasonably well on the metric my still have strong negative consequences for user or members of the public."
+    "licenses": {
+      "section-title": "Licenses",
+      "dataset-restrictions": {
+        "title": "Copyright Restrictions on the Dataset",
+        "info": "Based on your answers in the Intended Use part of the Data Overview Section, which of the following best describe the copyright and licensing status of the dataset?",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      },
+      "dataset-restrictions-other": {
+        "title": "Copyright Restriction - Elaboration",
+        "info": "You selected `other` for the dataset licensing status, please elaborate here:",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
+      },
+      "data-copyright": {
+        "title": "Copyright Restrictions on the Language Data",
+        "info": "Based on your answers in the Language part of the Data Curation Section, which of the following best describe the copyright and licensing status of the underlying language data?",
+        "flags": [
+          ""
+        ],
+        "scope": "periscope"
+      },
+      "data-copyright-other": {
+        "title": "Source Data Copyright Restriction - Elaboration",
+        "info": "You selected `other` for the source data licensing status, please elaborate here:",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
+      }
+    },
+    "limitations": {
+      "section-title": "Known Technical Limitations",
+      "data-technical-limitations": {
+        "title": "Technical Limitations",
+        "info": "Describe any known technical limitations, such as spurrious correlations, train/test overlap, annotation biases, or mis-annotations, and cite the works that first identified these limitations when possible.",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
+      },
+      "data-unsuited-applications": {
+        "title": "Unsuited Applications",
+        "info": "When using a model trained on this dataset in a setting where users or the public may interact with its predictions, what are some pitfalls to look out for? In particular, describe some applications of the general task featured in this dataset that its curation or properties make it less suitable for.",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
+      },
+      "data-discouraged-use": {
+        "title": "Discouraged Use Cases",
+        "info": "What are some discouraged use cases of a model trained to maximize the proposed metrics on this dataset? In particular, think about settings where decisions made by a model that performs reasonably well on the metric my still have strong negative consequences for user or members of the public.",
+        "flags": [
+          ""
+        ],
+        "scope": "microscope"
       }
     }
-  }
+  }
+}

formatting/reformat_json.py

@@ -0,0 +1,148 @@
+import argparse
+import json
+import pathlib
+import os
+
+parser = argparse.ArgumentParser(
+    description="Format the output of the data card tool as .md for the hub."
+)
+parser.add_argument("--input_path", "-i", type=pathlib.Path, required=False)
+parser.add_argument("--output_path", "-o", type=pathlib.Path, required=False)
+args = parser.parse_args()
+
+
+def read_json_file(json_path: pathlib.Path):
+    """Load a json file and return it as object."""
+    with open(json_path, "r") as f:
+        data = json.load(f)
+    return data
+
+
+def save_file(json_path: pathlib.Path, json_obj: str):
+    """Takes a string and saves it as .md file."""
+    with open(json_path, "w") as f:
+        f.write(json.dumps(json_obj, indent=2))
+
+
+def construct_json(dataset_name: str, data_card_data: dict, text_by_key: dict):
+  """Constructs the json file
+
+  This function iterates through text_by_key and extracts all answers from
+  the data_card_data object. It uses the levels of hierarchy as indicator for
+  the heading indentation and does not change the order in which anything
+  appears.
+
+  Args:
+      data_card_data: Output from the data card tool
+      text_by_key: configuration defined in key_to_question.json
+
+  Returns:
+      data_card_md_string: json content
+  """
+
+  try:
+    website_link = data_card_data["overview"]["where"]["website"]
+  except KeyError:
+    website_link = ""
+  try:
+    paper_link = data_card_data["overview"]["where"]["paper-url"]
+  except KeyError:
+    paper_link = ""
+  try:
+    authors = data_card_data["overview"]["credit"]["creators"]
+  except KeyError:
+    authors = ""
+
+  new_json = {
+      "name": dataset_name,
+      "summary": "Placeholder",
+      "sections": [
+      ],
+  }
+
+  if website_link:
+    new_json["website"] = website_link
+  if paper_link:
+    new_json["paper"] = paper_link
+  if authors:
+    new_json["authors"] = authors
+
+
+  total_questions = 0
+  total_words = 0
+
+  for main_key, main_content in text_by_key.items():
+    l2_data = {
+              "title": main_content["section-title"],
+              "level": 2,
+              "subsections": []
+    }
+    if main_key not in data_card_data:
+      continue
+    for second_key, second_content in main_content.items():
+      if second_key == "section-title":
+        continue
+      l3_data = {
+                      "title": second_content["section-title"],
+                      "level": 3,
+                      "fields": []
+      }
+      for final_key, final_content in second_content.items():
+        if final_key == "section-title":
+          continue
+        try:
+          total_questions += 1
+          answer = data_card_data[main_key][second_key].get(final_key, "N/A")
+        except:
+          print(main_key, second_key, final_key)
+          print("==="*50)
+          print(data_card_data)
+        # Skip empty answers.
+        if isinstance(answer, str):
+          if answer.lower() == "n/a":
+            continue
+        if not answer:
+          continue
+
+        if isinstance(answer, list):
+          answer = ", ".join([f"`{a}`" for a in answer])
+
+        json_answer = {
+          "title": final_content["title"],
+          "level": 4,
+          "content": answer,
+          "flags": final_content["flags"],
+          "info": final_content["info"],
+          "scope": final_content["scope"],
+        }
+        total_words += len(answer.split())
+        l3_data["fields"].append(json_answer)
+      l2_data["subsections"].append(l3_data)
+    new_json["sections"].append(l2_data)
+  print(f"Total questions {total_questions}")
+  print(f"total words: {total_words}")
+  return new_json, total_words
+
+
+
+
+if __name__ == "__main__":
+
+  text_by_key = read_json_file(
+      os.path.join(os.path.dirname(__file__), "key_to_question.json")
+  )
+  total_words_across_everything = 0
+  for dataset in os.listdir("../../../GEMv2"):
+    data_card_path = f"../../../GEMv2/{dataset}/{dataset}.json"
+    if os.path.exists(data_card_path):
+      print(f"Now processing {dataset}.")
+      new_path = f"datacards/{dataset}.json"
+      data_card_data = read_json_file(data_card_path)
+      data_card_json, total_cur_words = construct_json(dataset, data_card_data, text_by_key)
+      total_words_across_everything += total_cur_words
+      save_file(new_path, data_card_json)
+    else:
+      print(f"{dataset} has no data card!")
+  print(total_words_across_everything)
+  # data_card_json = construct_json(data_card_data, text_by_key)
+  # save_file(args.output_path, data_card_json)