diff --git a/.github/CSV_TEMPLATES/README.md b/.github/CSV_TEMPLATES/README.md new file mode 100644 index 0000000..0c63fb3 --- /dev/null +++ b/.github/CSV_TEMPLATES/README.md @@ -0,0 +1,227 @@ +# CSV Template System for GitHub Issue Forms + +A simple system for generating GitHub issue templates from CSV field definitions and Python data files. Creates CMIP7-compliant Essential Model Documentation (EMD) forms. + +## How It Works + +Each template consists of two files: + +``` +templates/ +├── template_name.csv # Field definitions +├── template_name.py # Configuration and CV data +└── ... +``` + + + +## CSV Field Structure + +Each CSV defines form fields with these columns: + +| Column | Description | Example | +|--------|-------------|---------| +| `field_order` | Order of fields (1, 2, 3...) | `5` | +| `field_type` | Type of form field | `dropdown`, `input`, `textarea`, `multi-select`, `markdown` | +| `field_id` | Unique identifier | `component_name` | +| `label` | Display label | `Component Name` | +| `description` | Help text (supports `\n` for line breaks) | `Enter the name\nRequired for CMIP7` | +| `data_source` | Data source from Python file | `realms`, `licenses`, `none` | +| `required` | Required field | `true`, `false` | +| `placeholder` | Placeholder text | `e.g., ECHAM6.3` | +| `options_type` | How to format options | `dict_keys`, `list`, `dict_multiple` | +| `default_value` | Default selection | `0` | + +## Field Types + +### `input` - Text Input +Single-line text entry. + +```csv +3,input,name,Name,The name of your model,none,true,"e.g., CESM2",, +``` + +### `textarea` - Multi-line Text +Large text area for descriptions. + +```csv +5,textarea,description,Description,Scientific model overview,none,true,"Describe scientific basis",, +``` + +### `dropdown` - Single Select +Choose one option from a list. + +```csv +4,dropdown,license,License,Select the model license,licenses,true,,dict_keys, +``` + +### `multi-select` - Multiple Select +Choose multiple options from a list. + +```csv +6,multi-select,components,Components,Select all model components,realms,true,,dict_multiple, +``` + +### `markdown` - Instructions +Formatted text (no user input). + +```csv +1,markdown,header,Header,"# Instructions\n\nPlease complete all required fields.",none,false,,, +``` + +## Options Types + +Controls how dropdown options are generated from Python data: + +### `dict_keys` - Dictionary Keys +Uses keys from dictionary data. + +```python +'licenses': { + 'MIT': {'id': 'MIT', 'validation-key': 'MIT'}, + 'GPL': {'id': 'GPL', 'validation-key': 'GPL'} +} +``` +→ Options: `["MIT", "GPL"]` + +### `list` - Simple List +Uses list items directly. + +```python +'priorities': ['High', 'Medium', 'Low'] +``` +→ Options: `["High", "Medium", "Low"]` + +### `dict_multiple` - Multi-Select Dictionary +For multi-select fields using dictionary keys. + +```python +'realms': { + 'atmosphere': {'id': 'atmosphere'}, + 'ocean': {'id': 'ocean'} +} +``` +→ Multi-select options: `["atmosphere", "ocean"]` + +### `hardcoded` - Hardcoded Options +Uses predefined options from Python file. + +```python +'status_options': ['Active', 'Inactive'] +``` +→ Options: `["Active", "Inactive"]` + +### `list_with_na` - List with "Not applicable" +Adds "Not applicable" as first option. + +→ Options: `["Not applicable", "option1", "option2"]` + +### `dict_with_extra` - Dictionary + Extras +Dictionary keys plus hardcoded additional options. + +→ Options: `["CV_option1", "CV_option2", "Open Source", "Proprietary"]` + +## Python Configuration Files + +Structure for template configuration: + +```python +# Required template configuration +TEMPLATE_CONFIG = { + 'name': 'Display Name', + 'description': 'Template description', + 'title': '[EMD] Template Title', + 'labels': ['emd-submission', 'category'], + 'issue_category': 'category' # Usually matches last label +} + +# Data for form options +DATA = { + 'cv_name': { + 'option1': {'id': 'option1', 'validation-key': 'option1'}, + 'option2': {'id': 'option2', 'validation-key': 'option2'} + }, + 'simple_list': ['item1', 'item2'], + 'field_id_options': ['Choice A', 'Choice B'] # For hardcoded options +} +``` + +## CMIPLD Integration + +For controlled vocabularies from the WCRP universe: + +```python +import cmipld +from cmipld.utils.ldparse import * + +DATA = { + # Load from universal repository + 'realms': name_multikey_extract( + cmipld.get('universal:realm/graph.jsonld')['@graph'], + ['id','validation-key','ui-label'],'validation-key' + ), + + # Add custom "none" option + loaded data + 'calendars': { + 'no-calendar': {'id': 'no-calendar', 'validation-key': 'no-calendar'}, + ** name_multikey_extract( + cmipld.get('universal:model-calendar/graph.jsonld')['@graph'], + ['id','validation-key','ui-label'],'validation-key' + ) + }, + + # Hardcoded data for CVs not in universal repo + 'grid_descriptors': ['N48', 'N96', 'ORCA1', 'T63'] +} +``` + +## Generation Commands + +```bash + + +# Generate all templates +python per_file_generator.py + +# Custom directories +python per_file_generator.py -t ./templates -o ./github_templates + +``` + +## Generated Output Format + +Creates GitHub-compliant YAML: + +```yaml +name: Model Component Submission +description: Submit metadata for a model component +title: "[EMD] Model Component Submission" +labels: ["emd-submission", "component"] +body: + - type: input + id: name + attributes: + label: Name + description: The name of your component + placeholder: "e.g., ECHAM6.3" + validations: + required: true + + - type: dropdown + attributes: + multiple: true + label: Components + description: | + Select all model components. + Select all that apply. + options: + - "atmosphere" + - "ocean" + - "land" +``` + +## Adding New Templates + +1. **Create CSV file**: `templates/my_template.csv` +2. **Create Python file**: `templates/my_template.py` +3. **Run generator**: `python per_file_generator.py` diff --git a/.github/CSV_TEMPLATES/templates/new_component.csv b/.github/CSV_TEMPLATES/templates/new_component.csv index c430c37..ab31c4e 100644 --- a/.github/CSV_TEMPLATES/templates/new_component.csv +++ b/.github/CSV_TEMPLATES/templates/new_component.csv @@ -1,6 +1,6 @@ field_order,field_type,field_id,label,description,data_source,required,placeholder,options_type,default_value 1,markdown,instructions,Instructions,"# Model Component Documentation\n\nThis template documents individual components of your climate model as required for CMIP7 participation. Each component description enables traceability across different models, supports scientific evaluation, and is mandatory for publishing model data to ESGF. The information you provide helps the climate modeling community understand your component's scientific basis, track how components are shared between institutions, and ensure proper attribution in research studies.",none,false,,, -2,dropdown,component,Component,"Select the process that this model component simulates.\n\nMANDATORY field from Model component process CV.",realms,true,,dict_keys, +2,dropdown,component,Component,"Select the process that this model component simulates.\n\nMANDATORY field from Model component process CV.\n\nIf your component type is not listed, you can register a new entry at: https://github.com/WCRP-CMIP/WCRP-universe/tree/main/realm",realms,true,,dict_keys, 3,input,name,Name,"The name of the model component.\n\nMANDATORY field.",none,true,"e.g., ECHAM6.3, NEMO3.6",, 4,input,family,Family,"The name of the family of models that the model component belongs to.\n\nMANDATORY field.",none,true,"e.g., ECHAM, NEMO, CLM",, 5,textarea,description,Description,"A scientific overview of the model component.\n\nMANDATORY field.",none,true,"Provide a scientific overview summarizing key processes simulated, scientific basis, and MIP-relevant details.",, @@ -8,14 +8,14 @@ field_order,field_type,field_id,label,description,data_source,required,placehold 7,textarea,reference_1_citation,Reference 1 - Citation,"Human-readable citation for the primary component reference.\n\nMANDATORY field.",none,true,"Author(s). (Year). Title. Journal/Report.",, 8,input,reference_1_doi,Reference 1 - DOI,"The persistent identifier (DOI) for the primary component reference.\n\nMANDATORY field.",none,true,https://doi.org/...,, 9,input,code_base,Code Base,"A URL (preferably DOI) for the source code.\n\nMANDATORY field. Set to 'private' if not publicly available.",none,true,"https://github.com/org/repo/tree/v1.2.3 or 'private'",, -10,multi-select,embedded_in,Embedded In,"Select the model component(s) in which this component is embedded.\n\nSelect all that apply.\n\nOPTIONAL field from Model component process CV.",realms,false,,dict_multiple, -11,multi-select,coupled_with,Coupled With,"Select the model component(s) to which this component is coupled.\n\nSelect all that apply.\n\nOPTIONAL field from Model component process CV.",realms,false,,dict_multiple, +10,multi-select,embedded_in,Embedded In,"Select the model component(s) in which this component is embedded.\n\nSelect all that apply.\n\nOPTIONAL field from Model component process CV.\n\nIf your component type is not listed, you can register a new entry at: https://github.com/WCRP-CMIP/WCRP-universe/tree/main/realm",realms,false,,dict_multiple, +11,multi-select,coupled_with,Coupled With,"Select the model component(s) to which this component is coupled.\n\nSelect all that apply.\n\nOPTIONAL field from Model component process CV.\n\nIf your component type is not listed, you can register a new entry at: https://github.com/WCRP-CMIP/WCRP-universe/tree/main/realm",realms,false,,dict_multiple, 12,markdown,horizontal_grid_header,Native Horizontal Grid,"## Native Horizontal Grid\n\nMANDATORY compound object describing the component's horizontal grid.",none,false,,, -13,dropdown,horizontal_grid,Grid,"The horizontal grid type.\n\nMANDATORY field from Native horizontal grid Type CV.",horizontal_grid_types,true,,dict_keys, +13,dropdown,horizontal_grid,Grid,"The horizontal grid type.\n\nMANDATORY field from Native horizontal grid Type CV.\n\nIf your grid type is not listed, you can register a new entry at: https://github.com/WCRP-CMIP/WCRP-universe/tree/main/native-horizontal-grid-type",horizontal_grid_types,true,,dict_keys, 14,textarea,horizontal_description,Description (Optional),"Free-text description of the horizontal grid.\n\nOPTIONAL field.",none,false,"Additional horizontal grid details if needed",, 15,dropdown,horizontal_grid_mapping,Grid Mapping,"The coordinate reference system of the horizontal coordinates.\n\nMANDATORY field from Grid Mapping CV.",grid_mappings,true,,list, -16,dropdown,horizontal_region,Region,"The portion of the globe where horizontal grid calculations are performed.\n\nMANDATORY field from Region CV.",horizontal_regions,true,,dict_keys, -17,dropdown,horizontal_temporal_refinement,Temporal Refinement,"How the distribution of grid cells varies with time.\n\nMANDATORY field from Temporal refinement CV.",temporal_refinements,true,,dict_keys, +16,dropdown,horizontal_region,Region,"The portion of the globe where horizontal grid calculations are performed.\n\nMANDATORY field from Region CV.\n\nIf your region is not listed, you can register a new entry at: https://github.com/WCRP-CMIP/WCRP-universe/tree/main/native-horizontal-grid-region",horizontal_regions,true,,dict_keys, +17,dropdown,horizontal_temporal_refinement,Temporal Refinement,"How the distribution of grid cells varies with time.\n\nMANDATORY field from Temporal refinement CV.\n\nIf your temporal refinement type is not listed, you can register a new entry at: https://github.com/WCRP-CMIP/WCRP-universe/tree/main/native-horizontal-grid-temporal-refinement",temporal_refinements,true,,dict_keys, 18,dropdown,horizontal_arrangement,Arrangement,"Grid arrangement of orthogonal physical quantities.\n\nMANDATORY field from Arrangement CV.",grid_arrangements,true,,list, 19,input,horizontal_resolution_x,Resolution X,"Horizontal resolution in X direction (float).\n\nOPTIONAL field.",none,false,"e.g., 1.25",, 20,input,horizontal_resolution_y,Resolution Y,"Horizontal resolution in Y direction (float).\n\nOPTIONAL field.",none,false,"e.g., 0.9375",, @@ -27,9 +27,9 @@ field_order,field_type,field_id,label,description,data_source,required,placehold 26,input,horizontal_truncation_number,Truncation Number,"Truncation number for spectral grids.\n\nOPTIONAL integer field.",none,false,"e.g., 63",, 27,input,horizontal_resolution_range_km,Resolution Range (km),"Minimum and maximum resolution in km.\n\nMANDATORY field as [float,float].\n\nFormat: min, max",none,true,"e.g., 57.0, 290",, 28,input,horizontal_mean_resolution_km,Mean Resolution (km),"Mean resolution in km.\n\nMANDATORY float field.",none,true,"e.g., 234.5",, -29,dropdown,horizontal_nominal_resolution,Nominal Resolution,"Nominal resolution characterizing the grid.\n\nMANDATORY field from Nominal resolution CV.",nominal_resolutions,true,,list, +29,dropdown,horizontal_nominal_resolution,Nominal Resolution,"Nominal resolution characterizing the grid.\n\nMANDATORY field from Nominal resolution CV.\n\nIf your resolution is not listed, you can register a new entry at: https://github.com/WCRP-CMIP/WCRP-universe/tree/main/resolution",nominal_resolutions,true,,list, 30,markdown,vertical_grid_header,Native Vertical Grid,"## Native Vertical Grid\n\nMANDATORY compound object describing the component's vertical grid.",none,false,,, -31,dropdown,vertical_coordinate,Coordinate,"The coordinate type of the vertical grid.\n\nMANDATORY field from Coordinate CV.",vertical_coordinates,true,,dict_keys, +31,dropdown,vertical_coordinate,Coordinate,"The coordinate type of the vertical grid.\n\nMANDATORY field from Coordinate CV.\n\nIf your coordinate type is not listed, you can register a new entry at: https://github.com/WCRP-CMIP/WCRP-universe/tree/main/native-vertical-grid-coordinate",vertical_coordinates,true,,dict_keys, 32,textarea,vertical_description,Description (Optional),"Free-text description of the vertical grid.\n\nOPTIONAL field.",none,false,"Additional vertical grid details if needed",, 33,input,vertical_n_z,N z,"Number of grid cells in Z direction.\n\nOPTIONAL integer field. Must be omitted if n_z_range is set.",none,false,"e.g., 70",, 34,input,vertical_n_z_range,N z Range,"Minimum and maximum number of Z grid cells for variable resolution.\n\nOPTIONAL field as [integer,integer]. Must be omitted if n_z is set.\n\nFormat: min, max",none,false,"e.g., 5, 15",, diff --git a/.github/ISSUE_TEMPLATE/new_component.yml b/.github/ISSUE_TEMPLATE/new_component.yml index 63be2d2..e3e92c5 100644 --- a/.github/ISSUE_TEMPLATE/new_component.yml +++ b/.github/ISSUE_TEMPLATE/new_component.yml @@ -18,6 +18,8 @@ body: Select the process that this model component simulates. MANDATORY field from Model component process CV. + + If your component type is not listed, you can register a new entry at: https://github.com/WCRP-CMIP/WCRP-universe/tree/main/realm options: - "aerosol" - "atmos" @@ -119,6 +121,8 @@ body: Select all that apply. OPTIONAL field from Model component process CV. + + If your component type is not listed, you can register a new entry at: https://github.com/WCRP-CMIP/WCRP-universe/tree/main/realm options: - "aerosol" - "atmos" @@ -139,6 +143,8 @@ body: Select all that apply. OPTIONAL field from Model component process CV. + + If your component type is not listed, you can register a new entry at: https://github.com/WCRP-CMIP/WCRP-universe/tree/main/realm options: - "aerosol" - "atmos" @@ -164,6 +170,8 @@ body: The horizontal grid type. MANDATORY field from Native horizontal grid Type CV. + + If your grid type is not listed, you can register a new entry at: https://github.com/WCRP-CMIP/WCRP-universe/tree/main/native-horizontal-grid-type options: - "no-horizontal-grid" - "cubed-sphere" @@ -233,6 +241,8 @@ body: The portion of the globe where horizontal grid calculations are performed. MANDATORY field from Region CV. + + If your region is not listed, you can register a new entry at: https://github.com/WCRP-CMIP/WCRP-universe/tree/main/native-horizontal-grid-region options: - "antarctica" - "global" @@ -249,6 +259,8 @@ body: How the distribution of grid cells varies with time. MANDATORY field from Temporal refinement CV. + + If your temporal refinement type is not listed, you can register a new entry at: https://github.com/WCRP-CMIP/WCRP-universe/tree/main/native-horizontal-grid-temporal-refinement options: - "adaptive" - "dynamically-stretched" @@ -394,6 +406,8 @@ body: Nominal resolution characterizing the grid. MANDATORY field from Nominal resolution CV. + + If your resolution is not listed, you can register a new entry at: https://github.com/WCRP-CMIP/WCRP-universe/tree/main/resolution options: - "0.5 km" - "10000 km" @@ -428,6 +442,8 @@ body: The coordinate type of the vertical grid. MANDATORY field from Coordinate CV. + + If your coordinate type is not listed, you can register a new entry at: https://github.com/WCRP-CMIP/WCRP-universe/tree/main/native-vertical-grid-coordinate options: - "no-vertical-grid" - "air-potential-temperature"