Merge ISA-Tab specification with ISA-XLSX changes #72

HLWeil · 2023-09-13T14:31:39Z

Merged all current differences between ISA-Tab and ISA-XLSX as we use it into the base ISA-Tab specification.

Differences are listed here: #71

This is no PR on the main specification but a preliminary PR on a side branch to be able to have a real discussion on the specification of ISA-Tab/ISA-XLSX differences.

@muehlhaus @Freymaurer @Brilator @kMutagene

Please take a look and let me know about inconsistencies, miswordings or missing specification patterns.

Brilator · 2023-09-13T15:05:16Z

ISA-XLSX.md

@@ -1,19 +1,15 @@
-# ISA-Tab format
+# ISA-XLSX format

 For detail on ISA framework terminology, please read the [ISA Abstract Model specification](isamodel.md).


The linked md file does not exist

Naturally 👍

Brilator · 2023-09-13T15:06:27Z

ISA-XLSX.md

-> - `STUDY ASSAYS`
-> - `STUDY PROTOCOLS`
-> - `STUDY CONTACTS`
+The purpose of top-level metadata sheets is aggregating and listing top-level metadata. Each sheet consists of sections consisting of a section header and key-value fields. Section headers MUST be completely written in upper case (e.g. STUDY), field headers MUST have the first letter of each word in upper case (e.g. Study Identifier); with the exception of the referencing label (REF).

 In the following sections, examples of each section block are given beside the specification of each section.

 For a full example of a complete Investigation File, please see [https://git.io/vD1va](https://git.io/vD1va).


this links to an ISA-Tab example that is txt not xlsx

Freymaurer · 2023-09-13T15:06:55Z

ARC specification.md

@@ -127,7 +129,7 @@ Notes:

 ### ISA-XLSX Format

-ISA-XLSX follows the ISA model specification (v1.0) saved in a XLSX format. The XLSX format uses the SpreadsheetML markup language and schema to represent a spreadsheet document. Conceptually, using the terminology of the Spreadsheet ML specification [ISO/IEC 29500-1](https://www.loc.gov/preservation/digital/formats/fdd/fdd000398.shtml#:~:text=The%20XLSX%20format%20uses%20the,a%20rectangular%20grid%20of%20cells.), the document comprises one or more worksheets in a workbook. Every worksheet MUST contain one table object storing the metadata. Comments or auxillary information MAY be stored alongside with table objects in a worksheet.
+https://github.com/nfdi4plants/ARC-specfication/blob/main/ISA-XLSX.md


does not exist

Freymaurer · 2023-09-13T15:10:45Z

ISA-XLSX.md

@@ -22,74 +18,47 @@ experiment; experimental steps (or sequences of events) are described in the Stu
 Investigation file there may be one or more Studies defined with a corresponding Study file; for each Study there may
 be one or more Assays defined with corresponding Assay files.


Maybe specify that one assay can be referenced in multiple studies

Freymaurer · 2023-09-13T15:14:32Z

ISA-XLSX.md

 | Investigation Publication Status Term Source REF       | String                                                                                             | Identifies the controlled vocabulary or ontology that this term comes from. The Source REF has to match one the Term Source Name declared in the in the Ontology Source Reference section. |

-For example, the `INVESTIGATION PUBLICATIONS` section of an ISA-Tab `i_*.txt` file may look as follows:
+For example, the `INVESTIGATION PUBLICATIONS` section of an ISA-XLSX `isa.investigation.xlsx` file may look as follows:

 ```default
 INVESTIGATION PUBLICATIONS


maybe do these blocks as table. As different columns are very difficult to recognize in a code block.

done, although i really do not like the examples from the initial ISA specs. the descriptions are far too large. I get where they come from, their sample should represent a 'real' investigation description. but that huge text block does really not help. I think @HLWeil will adapt the samples anyway.

Freymaurer · 2023-09-13T15:16:33Z

ISA-XLSX.md


-| Characteristics[Organism]   | Term Source REF   | Term Accession Number                                |
+| Characteristics [organism]   | Term Source REF (OBI_0100026)  | Term Accession Number (OBI_0100026) |


do we allow underscore term ids in headers? OBI_0100026

nope, copy error 👍

kMutagene · 2023-09-14T08:50:05Z

I think this is a nice first draft, one addition that i'd like would be internal links in the document. For example in the Study File section, there is this text block:

The Study File MUST contain one Top-Level Metadata sheet. This sheet MUST be named isa_study and MUST contain the following sections:

STUDY

STUDY DESIGN DESCRIPTORS

STUDY PUBLICATIONS

STUDY FACTORS

STUDY ASSAYS

STUDY PROTOCOLS

STUDY CONTACTS

all of the mentioned sections should include a link to their respective specification.

kMutagene · 2023-09-14T08:54:52Z

ISA-XLSX.md

+    - [INVESTIGATION](#investigation)
+      - [Example](#example-1)
+    - [INVESTIGATION PUBLICATIONS](#investigation-publications)
+      - [Example](#example-2)


I do not like how this looks too much, the idea was giving direct links to the samples, but i think this looks weird. other opinions?

Maybe use **Example** instead of #### Example?

HLWeil · 2023-09-14T09:07:01Z

I think this is a nice first draft, one addition that i'd like would be internal links in the document. For example in the Study File section, there is this text block:

The Study File MUST contain one Top-Level Metadata sheet. This sheet MUST be named isa_study and MUST contain the following sections:

STUDY

STUDY DESIGN DESCRIPTORS

STUDY PUBLICATIONS

STUDY FACTORS

STUDY ASSAYS

STUDY PROTOCOLS

STUDY CONTACTS

all of the mentioned sections should include a link to their respective specification.

YES! I think this will make navigating the file much easier. Also for stuff like "Annotation Table sheet" and "Ontology Annotation"

kMutagene · 2023-09-24T07:19:02Z

@HLWeil do you still intend to adapt the examples (e.g. shorter descriptions, other names, etc.)? Otherwise LGTM as far as i can tell

HLWeil · 2023-09-27T09:42:15Z

@HLWeil do you still intend to adapt the examples (e.g. shorter descriptions, other names, etc.)? Otherwise LGTM as far as i can tell

Yes I'm still planning to 😄

HLWeil added 3 commits September 11, 2023 17:31

start incorporating xlsx changes by restructuring headers

472897e

finish up xlsx changes to metadata sheets

e7bc440

Finish up first draft of ISA-XLSX specification

2493d99

Brilator reviewed Sep 13, 2023

View reviewed changes

Freymaurer reviewed Sep 13, 2023

View reviewed changes

HLWeil and others added 2 commits September 14, 2023 09:52

small fixes to xlsx specification

95415ae

render examples as md tables, add TOC

62e234a

kMutagene reviewed Sep 14, 2023

View reviewed changes

HLWeil added 4 commits September 14, 2023 11:21

improve isa-xlsx specification headers

57d416b

add internal links to isa-xlsx specs

bcff861

adjustments to isa-xlsx table of contents

b1c9feb

small fix to isa-xlsx protocol columns section

06453f4

HLWeil requested review from Brilator, kMutagene and Freymaurer September 18, 2023 13:34

HLWeil self-assigned this Oct 4, 2023

HLWeil added the enhancement New feature or request label Oct 4, 2023

HLWeil added 2 commits October 9, 2023 13:00

update examples of isa-xlsx specification

ed9a8ca

small fixes to isa-xlsx specification

da95a0b

HLWeil merged commit c893ec0 into status_quo Oct 9, 2023

HLWeil mentioned this pull request Oct 9, 2023

Metadata section sheets differ in naming #65

Closed

HLWeil deleted the isa_xlsx branch January 12, 2024 08:23

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Merge ISA-Tab specification with ISA-XLSX changes #72

Merge ISA-Tab specification with ISA-XLSX changes #72

HLWeil commented Sep 13, 2023

Brilator Sep 13, 2023

HLWeil Sep 14, 2023

Brilator Sep 13, 2023

Freymaurer Sep 13, 2023

HLWeil Sep 14, 2023

Freymaurer Sep 13, 2023

Freymaurer Sep 13, 2023

kMutagene Sep 14, 2023

Freymaurer Sep 13, 2023

HLWeil Sep 14, 2023

kMutagene commented Sep 14, 2023

kMutagene Sep 14, 2023

HLWeil Sep 14, 2023

HLWeil commented Sep 14, 2023

kMutagene commented Sep 24, 2023

HLWeil commented Sep 27, 2023

		@@ -22,74 +18,47 @@ experiment; experimental steps (or sequences of events) are described in the Stu
		Investigation file there may be one or more Studies defined with a corresponding Study file; for each Study there may
		be one or more Assays defined with corresponding Assay files.


		\| Characteristics[Organism] \| Term Source REF \| Term Accession Number \|
		\| Characteristics [organism] \| Term Source REF (OBI_0100026) \| Term Accession Number (OBI_0100026) \|

Merge ISA-Tab specification with ISA-XLSX changes #72

Merge ISA-Tab specification with ISA-XLSX changes #72

Conversation

HLWeil commented Sep 13, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kMutagene commented Sep 14, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

HLWeil commented Sep 14, 2023

kMutagene commented Sep 24, 2023

HLWeil commented Sep 27, 2023