Greetings,

I have some questions that came up as I added GIFTI surface support in SUMA. The surface I used for testing was
Human.colin.Cerebral.R.FIDUCIAL.TLRC.711-2B.71723.surf.gii
1- What do we do with 'coordframe_id' ?
It seems to conflict with 'dataspace' and 'xformspace'.
2- 'comment', 'orientation', and 'pubmed_id' are not documented. So it is not clear what to do with them. I propose that application-specific metadata be named in an identifiable manner such as: 'caret-comment', 'caret-orientation', etc.
We should also discuss what ought to be done with non-standard metadata and data arrays. In the past we've touched on this issue but with little consideration of the implementation cost.
3-How do we know what to do with the DataArray of intent: NIFTI_INTENT_VECTOR in the surface mentioned above? Its purpose is unknown although I suspect it contains normals. But I can't really do much with it if I did not know what it was for. To follow up on Nick and Rick's thread about data inside surface files, I think we should only include data with a clearly defined intent. Otherwise, we can't tell what to propagate and what not to propagate. If I knew that the DataArray inside a surface file contained normals, then I would know to recompute them if I change the surfaces' geometry. Otherwise, the content of the DataArray would be incorrect with the newly deformed coordinates.
4-Lastly, I propose we use a specific string to state that a certain metadata is of unknown or unspecified value. Something like 'Unknown' perhaps?

cheers,
ziad

Correction to 3: I did not pay attention to 'normal' in the Description of NIFTI_INTENT_VECTOR. I took it to be any kind of vector.
z

1 and 2. Those items you list are from Caret's long existing metadata.
Each of Caret's data files has a "header" that contains name/value
pairs much like GIFTI Metadata. When Caret writes one of its data
types as a GIFTI file, it places its "header" data into the GIFTI
Metadata. As stated in 2.10.1 of the GIFTI Surface Data Format
document, "Metadata elements with names not recognized by the
application software should be preserved or 'passed thru' for use by
other neuroimaging software."

3. Prior to "Intent Codes" GIFTI data arrays had an attribute named
"Category" and one of its values was something like "Normals". When
the decision was made to switch to "Intent Codes", we (I believe Ziad,
Rick, and myself) chose to use NIFTI_INTENT_VECTOR for normal vectors.
As stated in 2.3.4.9 of the GIFTI Surface Data Format document,
NIFTI_INTENT_VECTOR is described as "data consists of three-
dimensional normal vectors". An intent code such as
NIFTI_INTENT_NORMAL_VECTOR would be better, but it does not exist.

4. Would a metadata value element that is empty imply that that the
value is unknown or unspecified?
-----------------------------------
John Harwell

I think preserving unknown MetaData is actually a mistake.


Having extra metadata to use in your local software package is
okay. But the main point of GIFTI is as an exchange format.

Also, having to write a new file B.gii from an existing file A.gii
means having a reason to modify it.

Those 2 points together mean that if the software that wrote file
A.gii gets file B.gii back, they will have no idea what sorts of
changes were done. Therefore, the assumptions it is likely to make
based on the old copied MetaData may be invalid.

For example, suppose Caret creates a dataset that has their own
'orientation' and 'coordframe_id' values set as MetaData. Now AFNI
gets that file and performs some transformations on it, and writes
it back out. Now someone takes it back to Caret.

If AFNI preserves that unknown metadata, it is probably garbage
when it gets back to Caret. From Caret's perspective, who knows
what hideous manipulations were performed in AFNI? At that point,
only agreed upon GIFTI metadata is reliable.

---

So anyway, if certain MetaData is essential for not mis-interpreting
the dataset, then we need to use publicly agreed upon ways of passing
it along.

If that MetaData is not essential and is not understood by the
reading software, then it should be thrown out. It can no longer be
relied on to survive whatever computations are being performed.

My $0.02,

- rick

On 1 and 2: It looks like we ought to revisit what should be done about non-standard metadata and, by extension, non-standard data arrays (with undefined NIFTI_INTENT) that might come up in surface files. We also add AFNI-specific meta-data into GIFTI files but we are not expecting them to be preserved through an exchange.

On 3: So are these normals defined once the surface is in xformspace or in dataspace? For the caret surfaces we have, where xform is identity, this does not matter. But in the general case, the meaning is ambiguous.

On 4: This is related to a previous discussion and is more of a stylistic issue. But to my mind, an empty value is like an uninitialized variable. So I opted to use 'Unknown' in my implementation and I gather this does not violate GIFTI edicts.

>
>
> By: Richard Reynolds
>
> I think preserving unknown MetaData is actually a mistake.
>
>
> Having extra metadata to use in your local software package is
> okay. But the main point of GIFTI is as an exchange format.
>

I guess you can call GIFTI an exchange format. However, our intent
with Caret, and I believe the intent of others, is to replace our
"proprietary" file formats and use GIFTI as the standard file format
for Caret. Our vision is that a user can have ONE SET of files and
switch between neuroimaging software applications without having to do
any file format conversions.

> Also, having to write a new file B.gii from an existing file A.gii
> means having a reason to modify it.
>
> Those 2 points together mean that if the software that wrote file
> A.gii gets file B.gii back, they will have no idea what sorts of
> changes were done. Therefore, the assumptions it is likely to make
> based on the old copied MetaData may be invalid.
>
> For example, suppose Caret creates a dataset that has their own
> 'orientation' and 'coordframe_id' values set as MetaData. Now AFNI
> gets that file and performs some transformations on it, and writes
> it back out. Now someone takes it back to Caret.

Any of the caret specific metadata items that have GIFTI counterparts
will not be added to GIFTI data files written by Caret once the GIFTI
standard is finalized.

> If AFNI preserves that unknown metadata, it is probably garbage
> when it gets back to Caret. From Caret's perspective, who knows
> what hideous manipulations were performed in AFNI? At that point,
> only agreed upon GIFTI metadata is reliable.
>

Not necessarily. One item we sometimes place in metadata is a PubMed
Identifier that identifies the journal article that is the source of
the data. Even if this data is manipulated, the PubMed Identifier is
still pertains to the data.

> ---
>
> So anyway, if certain MetaData is essential for not mis-interpreting
> the dataset, then we need to use publicly agreed upon ways of passing
> it along.
>
> If that MetaData is not essential and is not understood by the
> reading software, then it should be thrown out. It can no longer be
> relied on to survive whatever computations are being performed.
>>
>
> My $0.02,
>
> - rick
>

First, and I believe this was decided at the in-person meeting in
D.C., unrecognized metadata should be passed thru as stated in the
GIFTI Format Document. Second, we should allow the users to add
metadata if they desire to do so, and, in this case, it is important
that it be preserved.

John Harwell

>
>
> By: Ziad Saad
>
> On 1 and 2: It looks like we ought to revisit what should be done
> about non-standard
> metadata and, by extension, non-standard data arrays (with undefined
> NIFTI_INTENT)
> that might come up in surface files. We also add AFNI-specific meta-
> data into
> GIFTI files but we are not expecting them to be preserved through an
> exchange.
>

I think we should preserve unrecognized metadata and this is explained
in my recent reply to Rick.

> On 3: So are these normals defined once the surface is in xformspace
> or in dataspace?
> For the caret surfaces we have, where xform is identity, this does
> not matter.
> But in the general case, the meaning is ambiguous.
>

Do we need normals in the surface file ? We could eliminate them from
surfaces and let the data consumer calculate them.

> On 4: This is related to a previous discussion and is more of a
> stylistic issue.
> But to my mind, an empty value is like an uninitialized variable.
> So I opted
> to use 'Unknown' in my implementation and I gather this does not
> violate GIFTI
> edicts.
>

We need to decide if empty metadata values are invalid because this
could be added to the GIFTI XML Schema.

>

John Harwell

Yes, my opinion disagrees with what the group decided and was
therefore put in the GIFT Format document, that's okay.

Note that I am not talking to you explicitly John, I am stating
my opinion because I think it may be worth consideration by the
group. Again, I am hoping others will reply, too.

---

While there may be many cases where it is appropriate to carry
a specific MD value along, it is equally important to think of
the cases where it is not.

As another random example, consider the case of computing an
EPI time series, where the result is computed from the EPI data
masked by the intersection of 2 different atlas-based ROIs, and
the union or intersection of 5 statistical datasets, where they
exceed some threshold.

That would be 8 different datasets as input, and of 3 different
types. What MetaData should be in the output? Should it be the
union of all MD from all 8 inputs, or perhaps subject to unique
Name=Value pairs, or uniq Names? If Names should be unique, as
makes sense, which Value should be applied, while the other 7
are thrown out? After a few operations, a dataset could have
many hundreds of MD pairs in it, easily.

Also, how many of these identifiers will be meaningless, or even
misleading in the output dataset?

If 4 of these datasets have PubMed Identifiers, should the output
have one? Should it have all 4?

This does not seem very clear cut to me, and it does not seem
quite appropriate to simply pass any MetaData through.

- rick

Rick,

As you point out, there certainly are cases where metadata should not
be "passed through". Do you think adding an optional attribute to the
metadata element ( ) that would request data be
passed through would be helpful?

John

>
> By: Richard Reynolds
>
> Yes, my opinion disagrees with what the group decided and was
> therefore put in the GIFT Format document, that's okay.
>
> Note that I am not talking to you explicitly John, I am stating
> my opinion because I think it may be worth consideration by the
> group. Again, I am hoping others will reply, too.
>
> ---
>
> While there may be many cases where it is appropriate to carry
> a specific MD value along, it is equally important to think of
> the cases where it is not.
>
> As another random example, consider the case of computing an
> EPI time series, where the result is computed from the EPI data
> masked by the intersection of 2 different atlas-based ROIs, and
> the union or intersection of 5 statistical datasets, where they
> exceed some threshold.
>
> That would be 8 different datasets as input, and of 3 different
> types. What MetaData should be in the output? Should it be the
> union of all MD from all 8 inputs, or perhaps subject to unique
> Name=Value pairs, or uniq Names? If Names should be unique, as
> makes sense, which Value should be applied, while the other 7
> are thrown out? After a few operations, a dataset could have
> many hundreds of MD pairs in it, easily.
>
> Also, how many of these identifiers will be meaningless, or even
> misleading in the output dataset?
>
> If 4 of these datasets have PubMed Identifiers, should the output
> have one? Should it have all 4?
>
> This does not seem very clear cut to me, and it does not seem
> quite appropriate to simply pass any MetaData through.
>
- rick

As you point out, there certainly are cases where metadata should not

be "passed through". Do you think adding an optional attribute to the

metadata element ( ) that would request data be

passed through would be helpful?


John,
There is certainly an advantage to allowing certain non-standard (NSmeta) metadata to pass through but the issue is complex and merits that the whole group consider it. Flagging NSmeta as pass through would help in some cases.
Another idea might be to have a tool to pass certain metadata from one dset or surface to another. This way, users who jump from one application to the next can simply reattach relevant NSmeta using some GIFTI 'refit' tool. One can also imagine allowing metadata matching by regexp methods to make such commands easy to run. So after a complicated sequence of processing, you can just add NSmeta using something like: gifti_tool -copy_missing_meta 'caret_*' source.gii target.gii . I'll encourage the rest of the group to chime in.


Regarding the surface normals, I whole heartedly agree with your suggestion that normals be kept out of the surface file. We actually compute the normals on the fly. But others might insist on having them and if that's the case we'll need to sort out how the coordinate transform relates to the normals. That's another detail the whole group should consider.

cheers,
ziad