SOP for analyzing contributor use cases

1. Create user narrative (describe workflow)
2. Map project to data model
3. Extract identifier requirements
4. Collect data locations
5. Collect project metadata
6. Define development tasks
7. Technical implementation of tasks
8. Evaluation

1. Create user narrative (describe workflow)

This is a description of what they will be doing or have done, including:

• Timeline
• Processes involved in the project (analysis types)
• Transitions (e.g., from private to public, unpublished to published)
• Data types
• Which data need to be kept long term and which can be discarded

SOP:

• Get description of project and data from contributor.
• Review and request any additional information needed to clarify.
• Save description to wiki.
• Contributor can edit the description directly on the wiki.
• See examples at [Data-Sources-Use-Cases] (https://github.com/identifier-services/IDservices_assessment/wiki/Data-Soureces-Use-Cases).

2. Map project to data model

Visually map the project-specific workflow. This can be done by the contributor or the contributor and curator together.

• Should be done using VUE. Use the genomic-entities.vue (ADD LINK) file as a guide, but only include the entities you need.
• All use cases will include a project (generally a single project per use case).
• Most use cases will include one or more datasets, specimens, and data of some sort.
• If the master file is missing entities, add them to your map, and file an issue requesting new entities
• Save final workflow as casename_workflow.vue and casename_workflow.pdf in the testcase_workflow_diagrams folder.
• See [maize example] (https://github.com/identifier-services/IDservices_assessment/blob/master/docs/testcase_workflow_diagrams/maize_diverse_workflow.pdf).
• Ramona to update master file as needed.

3. Extract identifier requirements

This step maps instances of the project entities (e.g., data files, specimens, processes) to the workflow, specifies how many instances of each entity there are, and determines what kind of IDs are needed for each entity type.

• Use [entity_mapping_template.xlsx] (https://github.com/identifier-services/IDservices_assessment/blob/master/docs/test_case_mappings/entity_mapping_template.xlsx) spreadsheet to map test case to entities in the data model.
• Save template as casename_entities.xlsx in the same folder.
• Edit the Excel file to remove column D and rows 1-3. Save file as casename_entities.csv in same folder.

4. Collect data locations

• Create a text file with the locations (URIs) of any elements of the dataset.
• If the same object has multiple locations, specify that here.
• Save the text file as casename_file_locations.txt in the file_locations folder.

5. Collect metadata

• Contributor provides dataset metadata for any DOIs using the [DOI DataCite template] (https://github.com/identifier-services/IDservices_assessment/blob/master/docs/metadata_files/DOI_datacite_metadata.csv).
• Contributor provides any other metadata as CSV file(s).
• If any of the specimens have external identifiers, please supply those in the metadata folder, in the file with the specimen metadata.
• There can be separate metadata files for each type of entity (specimen, process, data) or it can all be in one file, as in [this example] (https://github.com/identifier-services/IDservices_assessment/blob/master/docs/metadata_files/maize_diverse_metadata.csv).
• Once portal is in place, metadata can be collected via the portal.

6. Define development tasks

• Curator works with developers to review use case and determine use case requirements
• We will need to develop focused use cases for interaction with the UI or API. These are quite different than the contributors' use cases.
• Examples will be available on [this page] (https://github.com/identifier-services/IDservices_assessment/wiki/Use-cases-for-development-team).
• This will be specified as a YAML document and stored in the portal repo.

7. Technical implementation of tasks

• Developers integrate requirements from use case into the ID Services framework.
• Requirements should be identified in issues, so they can be closed when complete.

8. Evaluation

• Developers and curators review implementation, adjust as necessary
• Contributor reviews implementation

Evaluation should be based on the following:

• Are data and metadata accessible?
• Does the data model make it easier for the contributor to manage their data?
• Do identifier resolve?
• Are multiple copies of the same dataset correctly linked?
• Is metadata sufficient?
• How do the different identifier types function for the different entity types?

--There probably will be more and different criteria as we move forward.