Schema patch updates for adhering to Schema Style Guide

[malloryfreeberg]

NB: This is an ongoing Epic that will track individual schema patch updates.

If you open an issue to address any items here, please check them off the list in the Epic and link the issue to the Epic.

Description

As a consumer of the HCA metadata schemas, I would like to be sure that the metadata standards follow a set of consistent formatting and rules. **Acceptance Criteria**

Type

Type:Biomaterial

• [x] cell_line.json
  • [x] add guidelines to date_established field to describe how to enter the date in the correct format
  • [x] add example to catalog_url
  • [x] add second example to supplier
  • [x] add examples to karyotype
  • [x] add user-friendly name to biomaterial_core
  • [x] change user-friendly name of publication to "Publication" (avoid redundant "cell line" words)
  • [x] remove example from genus_species (example will live in the ontology module)
  • [x] remove example from cell_type(example will live in the ontology module)
  • [x] remove example from cell_cycle(example will live in the ontology module)
  • [x] remove example from tissue(example will live in the ontology module)
  • [x] remove example from disease(example will live in the ontology module)
• [x] cell_suspension.json
  • [x] add user-friendly name to biomaterial_core
  • [x] remove example from selected_cell_type(example will live in the ontology module)
  • [x] remove example from genus_species (example will live in the ontology module)
  • [x] move "May be 1 for well-based assays." from description to guidelines for total_estimated_cells field. Also change to "Enter 1 for well-based assays."
  • [x] change "Total estimated cell count" to "Estimated cell count" for total_estimated_cells field
• [x] donor_organism.json
  • [x] add user-friendly name to biomaterial_core
  • [x] remove example from genus_species (example will live in the ontology module)
  • [x] change description to "Whether organism was alive at time of biomaterial collection."
  • [x] move current description to guidelines
  • [x] change user-friendly term for organism_age to "Age"
  • [x] add a second example to organism_age that shows how to enter a range
  • [x] add guidelines to organism_age to indicate that an age range can be entered
  • [x] remove example from organism_age_unit (example will live in the ontology module)
  • [x] change user-friendly term for organism_age_unit to "Age unit"
  • [x] remove example from development_stage (example will live in the ontology module)
  • [x] remove example from diseases (example will live in the ontology module)
  • [x] move "Enter normal if no known diseases." from description to guidelines for diseases
  • [x] add guidelines to gestational_age to indicate that a range can be entered
  • [x] add a second example to gestational_age that shows how to enter a single value
  • [x] remove example from gestational_age_unit (example will live in the ontology module)
  • [x] add a second example to height that shows how to enter a range
  • [x] add guidelines to height to indicate that a range can be entered
  • [x] remove example from height_unit (example will live in the ontology module)
  • [x] add a second example to weight that shows how to enter a range
  • [x] add guidelines to weight to indicate that a range can be entered
  • [x] remove example from weight_unit (example will live in the ontology module)
• [x] imaged_specimen.json
  • [x] add user-friendly name to biomaterial_core
  • [x] move "Must be one of..." part of description in overview_image to guidelines
  • [x] add second example to overview_image
  • [x] change overview_image to overview_images since the field is an array
  • [x] change imaged_slice_thickness to slice_thickness to remove redundant "imaged" word
  • [x] add second example to imaged_slice_thickness
• [x] organoid.json
  • [x] change model_for_organ to model_organ to remove extra word ("for") and be consistent with related term model_organ_part
  • [x] change organoid_age to age to remove redundant word ("organoid")
  • [x] change organoid_age_unit to age_unit to remove redundant word ("organoid")
  • [x] change organoid_size to size to remove redundant word ("organoid")
  • [x] change organoid_size_unit to size_unit to remove redundant word ("organoid")
  • [x] change organoid_morphology to morphology to remove redundant word ("organoid")
  • [x] change organoid_growth_environment to growth_environment to remove redundant word ("organoid")
  • [x] change organoid_stored_oxygen_levels to stored_oxygen_levels to remove redundant word ("organoid")
  • [x] add user-friendly name to biomaterial_core
  • [x] remove example from genus_species (example will live in the ontology module)
  • [x] remove example from model_for_organ (example will live in the ontology module)
  • [x] remove example from model_organ_part (example will live in the ontology module)
  • [x] remove example from organoid_age_unit (example will live in the ontology module)
  • [x] remove example from organoid_size_unit (example will live in the ontology module)
  • [x] add a second example to organoid_morphology
• [x] specimen_from_organism.json
  • [x] add user-friendly name to biomaterial_core
  • [x] remove example from genus_species (example will live in the ontology module)
  • [x] remove example from organ (example will live in the ontology module)
  • [x] move "Blood and connective tissue are considered organs." from example to guidelines for organ
  • [x] move comment in organ field to guidelines
  • [x] remove example from organ_part (example will live in the ontology module)
  • [x] move comment in organ_part field to guidelines
  • [x] move "Enter normal if no known diseases" from description to guidelines for diseases field
  • [x] remove example from diseases (example will live in the ontology module)
  • [x] move ", in date-time format, yyyy-mm-ddThh:mm:ssZ." from description to guidelines for collection_time

Type:File

• [x] reference_file.json
  • [x] add second example to reference_version
  • [x] add user-friendly name to file_core
  • [x] add second example to ncbi_taxon_id
  • [x] add guidelines to ncbi_taxon_id to describe where to find valid taxon IDs
  • [x] remove example from genus_species (example will live in the ontology module)
  • [x] change assembly_type description to "The assembly type of the genome reference."
  • [x] change reference_type description to "The type of the reference."
• [x] sequence_file.json
  • [x] add user-friendly name to file_core
  • [x] change description of read_index to "The sequencing read this file represents."
  • [x] add guidelines to read_index field to indicate that if a sequencing experiment is single-end, enter "read1".
  • [x] remove "Can be from the DDBJ, NCBI, or EMBL-EBI. Accession must start with DRR, SRR, or ERR." from description for insdc_run
  • [x] add guidelines to insdc_run: "Accession can be from the DDBJ, NCBI, or EMBL-EBI and must start with DRR, SRR, or ERR.".
  • [x] move "Technical replicates are sequence files generated from the same sequencing library. Leave blank if files are biological replicates." to guidelines for technical_replicate_group
• [x] supplementary_file.json
  • [x] add user-friendly name to file_core
  • [x] add examples to file_description
  • [x] move "This could include information about how the file was generated." to guidelines for file_description

Type:Project

• [x] project.json
  • [x] add second example to supplementary_links
  • [x] add user-friendly name to project_core
  • [x] move part of description to guidelines for insdc_project: "Accession can be from the DDBJ, NCBI, or EMBL-EBI and must start with DRP, SRP, or ERP."
  • [x] move part of description to guidelines for geo_series: "Accession must start with GSE."
  • [x] add guidelines for array_express_investigation: "Accession must start with E-."
  • [x] move part of description to guidelines for insdc_study: "Accession can be from the DDBJ, NCBI, or EMBL-EBI and must start with PRJE, PRJN, or PRJD."
  • [x] change user-friendly term for funders to "Funding sources(s)" to remove redundancy ("Project")

Type:Protocol

• [x] analysis_protocol.json
  • [x] remove "Must be a child term of..." from description for protocol_type
  • [x] add examples to computational_method
  • [x] add user-friendly name to protocol_core
• [x] aggregate_generation_protocol.json
  • [x] add second example to aggregate_cell_uniformity
  • [x] add user-friendly term to protocol_core
  • [x] fix typo in description for aggregate_formation_method
• [x] collection_protocol.json
  • [x] add user-friendly term to protocol_core
  • [x] reword collection_method description
  • [x] remove example from collection_method (example will live in the ontology module)
  • [x] add type to protocol_reagents.items
• [x] differentiation_protocol.json
  • [x] add second example for target_pathway
  • [x] add user-friendly term to protocol_core
  • [x] remove "Differentiation" from beginning of description for 'differentiation_methodandsmall_molecules`
  • [x] separate examples with semi colons
  • [x] add type to reagents.items
• [x] dissociation_protocol.json
  • [x] add user-friendly term to protocol_core
  • [x] remove example from dissociation_method (example will live in the ontology module)
  • [x] add type to protocol_reagents.items
• [x] enrichment_protocol.json
  • [x] add user-friendly term to protocol_core
  • [x] change description for markers to "A list of markers used to enrich for or against certain cells."
  • [x] add guidelines for markers to indicate that markers should be space-delimited and include + or - depending on if the markers were enriched for or against. Should this be an array field since it can accept more than 1 value?
  • [x] add example to markers
  • [x] remove example from enrichment_method (example will live in the ontology module)
• [x] ipsc_induction_protocol.json
  • [x] add user-friendly term to protocol_core
  • [x] add examples to ipsc_induction_method
  • [x] add type to protocol_reagents.items
  • [x] fix typo in schema title
  • [x] add second example to pluripotency_test
• [x] library_preparation_protocol.json
  • [x] add user-friendly term to protocol_core
  • [x] remove example from input_nucleic_acid_molecule (example will live in the ontology module)
  • [x] remove example from library_construction_approach (example will live in the ontology module)
  • [x] add guidelines for end_bias to indicate common usage (e.g. "full length" for SS2)
  • [x] add guidelines for strand to indicate common usage (e.g. "second" for 10X v2)
  • [x] remove example from library_preamplification_method (example will live in the ontology module)
  • [x] remove example from cdna_library_amplification_method (example will live in the ontology module)
• [x] sequencing_protocol.json
  • [x] change approach to method in sequencing_approach description and user-friendly
  • [x] add user-friendly term to protocol_core
  • [x] remove "Should be a child term..." from instrument_manufacturer_model
  • [x] remove example from instrument_manufacturer_model (example will live in the ontology module)
  • [x] add second example for local_machine_name
  • [x] change description of paried_end to "Whether the sequenced molecule was sequenced from both ends."

Type:Process

• [x] process.json
  • [x] add user-friendly term to process_core
  • [x] change user-friendly term for insdc_experiment to "INSDC experiment accession"
  • [x] add a second example to length_of_time that shows how to enter a range
  • [x] add guidelines to length_of_time to indicate that an age range can be entered
  • [x] remove example from length_of_time_unit (example will live in the ontology module)
  • [x] remove example from process_type (example will live in the ontology module)
  • [x] add example for deviation_from_protocol
• [x] analysis_process.json
  • [x] add examples to reference_bundle
  • [x] confirm whether "files or string values" are acceptable for inputs
  • [x] add examples to input_bundles
  • [x] add user-friendly name to process_core
  • [x] remove "Must be a child term of..." from description for process_type
  • [x] move "these can be files..." to guidelines for inputs
  • [x] add type attributes to inputs.items
  • [x] add type attributes to tasks.items
  • [x] change tasks description to "Information about steps in the workflow.".
  • [x] change outputs description to "Output files generated by the pipeline run."
  • [x] change user-friendly name of outputs to "Output files"
  • [x] add examples to timestamp_start_utc
  • [x] add examples to timestamp_stop_utc
  • [x] add guidelines to timestamp_start_utc to show how to fill out date-time format
  • [x] add guidelines to timestamp_stop_utc to show how to fill out date-time format
  • [x] change description of analysis_run_type to "Whether the analysis ran or was copied forward as an optimization."
  • [x] add example to analysis_run_type: "Should be one of: run, copy-forward."

Module

Module:Biomaterial

• [x] cell_morphology.json
  • [x] add guidelines to percent_cell_viability, percent_necrosis, cell_size
  • [x] add example to cell_size and cell_viability_method
  • [x] remove example from cell_size_unit (example will live in the ontology module)
• [x] death.json
  • [x] add example to cause_of_death
  • [x] add guidelines to cause_of_death, cold_perfused, normothermic_regional_perfusion, time_of_death, hardy_scale, and organ_donation_death_type
  • [x] change description of cold_perfused to "Whether perfusion with cold fluid was used to help preserve tissues before heart stopped."
  • [x] change description for normothermic_regional_perfusion to "Whether entire body was perfused with oxygenated blood."
• [x] familial_relationship.json
  • [x] add guidelines for parent
  • [x] add guidelines for child
  • [x] add guidelines for sibling
• [x] growth_conditions.json
  • [x] add example to growth_medium, culture_environment, drug_treatment, and feeder_layer_type
  • [x] add guidelines for drug_treatment and passage_number
• [x] human_specific.json
  • [x] move "using ontology terms from EMBL-EBI's Ancestry Ontology" from description to guidelines for ethnicity and add how to enter more than 1 ethnicity
  • [x] remove example from ethnicity (example will live in the ontology module)
• [x] medical_history.json
  • [x] add guidelines for alcohol_history, medication, and smoking_history
  • [x] add example for alcohol_history and medication
• [x] mouse_specific.json
  • [x] remove example from strain (example will live in the ontology module)
• [x] preservation_storage.json
  • [x] add second example for storage_method
  • [x] remove example from storage_time_unit (example will live in the ontology module)
  • [x] add guidelines for preservation_method to say "Enter 'fresh' if not preserved."
  • [x] add second example for preservation_method
• [x] state_of_specimen.json
  • [x] add two examples for gross_description
  • [x] move "Must be of format JPEG, TIFF, or PNG." from description to guidelines for gross_image
  • [x] add second example to microscopic_description
  • [x] move "Must be of format JPEG, TIFF, or PNG." from description to guidelines for microscopic_image

Module:Ontology

• [x] add two examples to all fields

Module:Process

• [x] purchased_reagents.json
  • [x] add second example to retail_name
  • [x] add second example to manufacturer
  • [x] move formatting text from description to guidelines for expiry_date
  • [x] change example to include jus the value for kit_titer
• [x] insdc_experiment.json
  • [x] move from description to guidelines for insdc_experiment: "Accession can be from the DDBJ, NCBI, or EMBL-EBI and must start with DRX, SRX, or ERX."
• [x] barcode.json
  • [x] add guidelines for barcode_offset: "Enter 0 for beginning of read." (and remove from description)
  • [x] fix whitespace in white_list_file
  • [x] remove "if known" from whilte_list_file description
  • [x] change comment to guidelines for whilte_list_file
• [x] 10x.json
  • [x] fix indentation of all fields
  • [x] change schema description to be: "Information specific to 10x experiments."
• [x] plate_based_sequencing.json
  • [x] change user-friendly name of plate_id to "Plate ID"
  • [x] move "Should be unique for the plate." from description to guidelines for well_id
  • [x] change description for cell_quality to "Quality of well if imaged..."
  • [x] change user-friendly term of cell_quality to "Well quality"

Module:Project

• [x] contact.json
  • [x] move "Format: first name, middle name or initial, last name." text from example to guidelines
  • [x] add second example to contact_name that doesn't have a middle initial
  • [x] remove "Enter valid email" from description for email
  • [x] remove "Enter a valid phone number" from phone description
  • [x] add "Include country code" to guidelines for phone
  • [x] add second example to institution
  • [x] add second example to laboratory
  • [x] add guidelines to address currently in description
  • [x] change description for corresponding_contributor to be "Whether the individual is a primary point of contact for the project.
  • [x] add second example to project_role
• [x] funder.json
  • [x] remove "Approximately 30 words." from description and move to guidelines
  • [x] add second example to funder_name
• [x] publication.json
  • [x] move "in 'surname initials' format." from description to guidelines for authors
  • [x] add example to publication_url
  • [x] remove ", preferably not behind a paywall," from description for publication_url

Module:Protocol

• [x] channel.json
• [x] target.json

Core

Core:Biomaterial

• [x] add example for genotype
• [x] change description for biosd_biomaterial to "A DDBJ, NCBI, or EMBL-EBI BioSample accession."
• [x] add guidelines for biosd_biomaterial: "Accession must start with SAMD, SAMN, or SAME."
• [x] change description for insdc_biomaterial to "An INSDC (International Nucleotide Sequence Database Collaboration) sample accession."
• [x] add guidelines for insdc_biomaterial: "Accession can be from the DDBJ, NCBI, or EMBL-EBI and must start with DRS, SRS, or ERS."

Core:File

• [x] add example for file_format
• [x] add example for checksum
• [x] add guidelines for filename to say that the file extension should be included
• [x] add examples to file_name

Core:Process

• [x] add example for process_location
• [x] add example for operator

Core:Project

• [x] move description text to guidelines for project_short_name
• [x] add to guidelines for project_short_name that value should have no spaces and be less than xx characters
• [x] move description text to guidelines for project_title
• [x] move description text to guidelines for project_description

Core:Protocol

• [x] remove " that need not be unique" from protocol_name description
• [x] add guidelines to protocol_id

[zperova]

😱

[zperova]

@malloryfreeberg are we going to break this up by type/by module issues? I am hesitant to start commenting here on things as this will be one unbearably long Issue. I am happy to do it, btw.

[malloryfreeberg]

are we going to break this up by type/by module issues

Dear God, yes :)

Maybe we break them up by schema + kind of update. E.g. one ticket for updating all examples in donor_organism schema. We can decide as we go, but in general we shouldn't have too many individual updates lumped into one branch/PR.

[malloryfreeberg]

@zperova can you take care of the imaging_protocol.json and imaging_preparation_protocol.json updates? I haven't yet spelled out the updates for the latter, so that will need to be done.

Paris has offered suggestions for some of the imaging_protocol field examples:

• immersion_medium_type
  • glycerin
  • methylene iodide
  • synthetic oil
  • paraffin oil
  • cedarwood oil
  • water
  • bromonaphthalene
• tile_size_y
  • -100
• tile_size_x
  • -100