Stream: genomics
Topic: Proposal for new extension - Genomics File
Kevin Power (Oct 20 2021 at 19:28):
For FHIR-32415, I have drafted a new Genomics File extension and associated guidance in a branch, published here:
http://build.fhir.org/ig/HL7/genomics-reporting/branches/kp-file-attachments/general.html#file-attachments
Any and all feedback is welcome.
Arthur Hermann (Oct 22 2021 at 19:56):
Excellent work Kevin! Thanks... A minor suggestion - currently says: It should be noted that the Genomic File extension is not an appropriate way to send a copy of the report.... I suggest a change to: It should be noted that the Genomic File extension is not an appropriate way to send a copy of the report (e.g. A PDF or other document containing the written report)
Kevin Power (Oct 22 2021 at 20:44):
@Arthur Hermann - Done.
Arthur Hermann (Oct 25 2021 at 22:46):
@Jamie Jones I moved this to Zulip to ensure that others can see this discussion. Jaime is referring to JIRA https://jira.hl7.org/browse/FHIR-32415 Referencing BAM, CRAM, VCF (and other standard genomic files).
He stated: I drafted a potential rework of text for this section today on https://docs.google.com/document/d/19vFe9UD4_XRsa5c0ykcS8P-RmpNBDDeGP0jSFg5UuyM/edit, please take a look. I don't mention the new extension there because I'm not sure we need it, but could add that part back in/after if we feel it helps. I think Liz's comments from before about presentedForm should probably still go in.
For those trying to catch-up on this issue - there are many comments in the JIRA and a number of linked google docs with drafts...
@Jamie Jones , @Kevin Power - there is so much discussion going on regarding this issue, and there have been so many changes in the text with continuing comments from members of the WG - that I strongly belive we should bring this to the entire WG (either a Monday or Tuesday meeting), sum up where we stand, and what questions remain to be debated. Then determine who we would like to resolve those outstanding questions... thoughts?
Kevin Power (Oct 25 2021 at 22:51):
@Arthur Hermann - I have it on the agenda for tomorrow.
Kevin Power (Oct 25 2021 at 22:55):
For anyone else reviewing now, I would only review the current draft on my branch here and compare it to Jamie's potential rework of text linked above. In short, Jamie writes better than I, and he proposed not adding a new extension on DiagnosticReport but using the built in attribute (DocumentReference.context.related) to link from the Genomics File to the Genomics Report. That is probably the key question to answer tomorrow.
Kevin Power (Oct 26 2021 at 16:18):
From the call today, seems like we have a key decision to make - how should our profiling/guidance discuss the appropriate way(s) to link the report and the file. And I say way(s), as we might want to use multiple of these:
- New extension (genomics-file) specifically discussing how to associate files files to the report
- Update guidance to use existing extension (supporting-information) discussing that it can be used to associate files to the report
- Use DocumentReference.context.related to refer from the file to the report
We probably need guidance for #3 no matter what. It is built into DocumentReference, so we should talk about it.
In addition, we could choose #1 or #2 or use neither and only rely on #3 to relate the files to the report.
My vote is #1 and #3.
Arthur Hermann (Oct 27 2021 at 15:58):
@Kevin Power I agree with how you have categorized this issue. I also agree with going with #1 and #3, but obviously am still willing to be convinced otherwise if someone provides compelling reasons.
Bret H (Oct 27 2021 at 16:01):
#3 is a given, #1 is useful for the variant profile to refer to the genomics data file. It's tidy and is a nice to have a specific call out for the files (somewhat easier to discover).
Kevin Power (Oct 27 2021 at 17:11):
@Bret H - I will say the plan was to only have the new extension (#1) from our GenomicsReport profile, not from our Observation profiles. Is that still OK or do you think differently?
Bret H (Oct 27 2021 at 19:22):
@Kevin Power sure, but there's nothing to stop one from using related reference in the observation, if they want. right?
Kevin Power (Oct 27 2021 at 19:35):
Nothing to stop them, no. Implementers are free to use extensions where ever they want. I was just saying our guidance was planning to focus on the usage of that extension from GenomicsReport. If we feel reference the file from any/all of our Observation profiles, perhaps we should add the extension and update our guidance? Personally, I am not sure it is necessary, but what do others think?
Bret H (Oct 27 2021 at 19:38):
I think keeping the extension only on diagnostic report is fine. If someone has a use case and uses related reference in observation, I do not think it goes beyond the intended scope of that element. I see no harm in only talking about diagnostic report and the extension and leaving the possibility for reference in an observation as a related resource. Might be redundant but not hurtful.
Kevin Power (Oct 27 2021 at 22:21):
@Jamie Jones @Patrick Werner - Thoughts on the options 1,2,3 above? I think we all agree on #3, so maybe the question now is just do we do #1, #2, or neither?
Jamie Jones (Oct 27 2021 at 22:26):
I still like supportingInfo for linking DocRef to Genomics Reports. We can just be sure to call out VCF DocRefs as one type of resource that may be included as relevant info
Kevin Power (Oct 27 2021 at 22:30):
OK, then in that case, someone else is going to need to weigh in (as it seems Jamie and I are just on different pages on this one :smile:)
Bret H (Oct 27 2021 at 22:50):
new extension: CON - adding another potentially overlapping extension. Which could lead to confusion as to where to put information. PRO - easier to find. more specific.
use supportingInfo: CON - files are potentially grouped with more clinically actionable information. PRO - not adding an other extension. have one less place to look for information.
Ouch, it's like a devil's triangle....but I still think the content.type (in the DocRef, not the mime type in the attatchment data type) should get a good label to make sure it is known what is in the specific docRef.
From current definitions you can see where it might be confusing.
Related Artifact
Captures citations, evidence and other supporting documentation for the observation or report
Supporting Information
Additional information relevant to interpreting/understanding the report
I'm already on the books for liking specificity, a named extension would be more specific. This is almost like grouper. Philosophically who does the element serve. The systems that are really smart will be checking the linked resources in Supporting Information to do something meaningful with them. But I could see systems shoving the reference to the genetics file deep in a comment section in the EMR. OR, if they weigh the supporting information element as of high import the reference to the genetics file might be cluttering the screen when someone reviews the result.
Thinking outside the EMR use case. The genetics reference could be useful to some applications which need the genetics file for action.
Kevin Power (Oct 27 2021 at 22:53):
This is really the only guidance in the IG I can find for SupportingInformation (which is probably bad), but given it is what we have, I still don't feel like pointing at a genomics file is appropriate given this guidance:
Orders can point to other sources of information used to support the analysis performed as part of genomic testing. Genomic reports can refer to this the information that was considered as part of the report - whether provided as part of the order or made available subsequently by the patient or clinicians or otherwise retrieved. The figure above shows these relationships through the extension supportingInfo, which can be to various Observations, FamilyMemberHistory records (including records that comply with Family member history for genomics analysis and RiskAssessments.
I can SupportingInformation pointing at DocumentReferences, but to me it is more like other documents that were used as input to the analysis, like perhaps previous lab reports or clinical notes that might inform the lab. But perhaps that view of SupportingInformation is too narrow and that is why I don't really like it?
Kevin Power (Oct 29 2021 at 16:26):
Just so we don't lose momentum, tagging a few folks to comment on the question of "New Extension (Genomics File)", "Use Current Extension (Supporting Information)", or even "Do not add a new extension"
@Patrick Werner @Bob Dolin @Liz Amos @Mullai Murugan @Lloyd McKenzie
Lloyd McKenzie (Oct 29 2021 at 17:45):
Why does the extension have a context of 'element' - is it really supposed to appear anywhere?? My leaning is to actually use DiagnosticReport.media and ask for the definition to be broadened. It's a similar use-case - point to a big thing managed elsewhere that we want to talk about elsewhere in the report...
Kevin Power (Oct 29 2021 at 18:09):
Lloyd McKenzie said:
Why does the extension have a context of 'element' - is it really supposed to appear anywhere??
I will admit, I have no idea. When we moved over to FSH, at some point someone added this to an extension, and then it copied/pasted to others:
```* ^context[0].type = #element
Kevin Power (Oct 29 2021 at 18:50):
Lloyd McKenzie said:
My leaning is to actually use DiagnosticReport.media and ask for the definition to be broadened. It's a similar use-case - point to a big thing managed elsewhere that we want to talk about elsewhere in the report...
The current definition (in R4 and R5) seems to be too narrow:
A list of key images associated with this report. The images are generally created during the diagnostic process, and may be directly of the patient, or of treated specimens (i.e. slides of interest).
We have made a request to broaden this definition, but until then, it feels like we would be choosing an attribute just because it has the datatype we need. That feels wrong to me.
Kevin Power (Oct 29 2021 at 20:19):
Not to mention, that in R4, DR.media is a Media data type, which even furthers my stance that there is a misalignment:
A photo, video, or audio recording acquired or used in healthcare. The actual content may be inline or provided by direct reference.
When R5 is published, and a future release of our IG is based on R5, we will likely revisit.
Kevin Power (Oct 29 2021 at 20:27):
Oh, and I added a fix for our extensions here (after doing some research to know what you are talking about :smile:). At least I think I did the right fix.
http://build.fhir.org/ig/HL7/genomics-reporting/branches/kp-file-attachments/index.html
Lloyd McKenzie (Oct 29 2021 at 21:36):
Let's fix it in R5 and use the interversion extension mechanism
Jamie Jones (Oct 29 2021 at 21:37):
So would this be an extension on DR.media to reference a DocRef? Or just an Attachment (or is there another proposal?)
Kevin Power (Oct 29 2021 at 21:52):
Lloyd McKenzie said:
Let's fix it in R5 and use the interversion extension mechanism
I should have mentioned I did log a request to O&O: FHIR-34068 (so, it is not really ours, meaning CG, to fix) - That is currently waiting on @John David Larkin Nolen
If I understand what you are saying @Lloyd McKenzie - you mean apply whatever fix will be applied in R5 in our IG somehow? I am not sure what that looks like.
Lloyd McKenzie (Oct 29 2021 at 23:47):
There are rules here for using extensions to pre-adopt content from a newer version in an old version. I'm suggesting we'd simply do that once R5 supports what we need.
Kevin Power (Oct 30 2021 at 18:57):
Thanks Lloyd. @John David Larkin Nolen - Any chance you have an update on FHIR-34068?
John David Larkin Nolen (Nov 02 2021 at 14:55):
Yes...I think the best way is to widen the definition of media to handle this. I'll run this past the OO on FHIR peeps this week.
Bret H (Nov 02 2021 at 15:12):
As long as we have a single place to use ,and where we can communicate in the message what kind of genomics file it is, any spot seems great.
Kevin Power (Nov 05 2021 at 22:41):
Just to not lose track of this, wanted to tag a few people and see if they are OK putting this change on hold for now, and instead do this (based on Lloyd's suggestion above):
- wait until the definition of DiagnosticReport.media' is broadened in R5 (seems to have tentative approval from O&O)
- pre-adopt from our IG after R5 release (so, in our STU3 release)
This feels like the best long term answer to me honestly, but it likely prevents getting this covered in the STU2 release. Unless in STU2 we make a short term change (which feels weird to me).
@Jamie Jones @Patrick Werner @Liz Amos @Arthur Hermann @Bret H
Bret H (Nov 06 2021 at 16:23):
@Kevin Power can we get a promise from O&O? Also, We could stretch the current definition if it is in line with the next version, I think, as we do not currently have a place. It would be our guidance saying to use the DiagnosticReport.media for the specific genomic data formatted files (such as CRAM, BAM, SAM, VCF...) and acknowledge that the R5 definition is being used.
to be honest, I think people will be happier to have a place for the files that is inline with R5 then have us stick tightly to a definition which is broadend. We do not have a specified spot for those files today, so I don't see any harm.
Bret H (Nov 06 2021 at 16:26):
as a note: https://www.hl7.org/fhir/media.html allows for a lot a room to tell the recipient what the file is. Wonder if we want to provide specific guidance on how to specify that a genomics data file is included?
Bret H (Nov 06 2021 at 16:29):
to be clarify: I vote to go ahead and guide folks to DiagnosticReport.media.attatchment. With a code in media.type indicating a genomics data file format.
Bret H (Nov 06 2021 at 16:30):
of course, media.modality is pretty useful too
Kevin Power (Nov 06 2021 at 16:34):
My biggest problem with the R4 is that it is an Attachment only, not a DocRef. Meaning it doesn’t exist on its own, it is contained within the report
Arthur Hermann (Nov 06 2021 at 17:48):
This is slightly off track - but what are our plans for balloting STU2? I may have missed that in a meeting, but I am not aware of any dates that we are tracking to? Are we planning to take all of the changes we have been working on, including the changes to Variant that Jamie has been working on, and ballot them as STU2? This will help us "clean up" the current situation for this issue, but until R5 is published won't really solve it. But knowing when we plan on balloting will help me understand our current plans... also do we have any idea at all as to when R5 would be published?
Bret H (Nov 06 2021 at 18:31):
good point Kevin. However, that's what operations are for : ^ ) It would be a specific, specialized use case where someone would want the genomic data file formats on their own. By forcing context with a diagnostic report, as a devil's advocate, it ensures that the file has the context that biased the bioinformatic/variant scientist workflows used to produce the file. I think it not likely at this time that an unbiased survey of genome would be communicated. For example, with more common short-sequencing NGS pipelines can be adjusted to improve detection of repeats, and there are coverage versus quality filters that can be adjusted based on the desired regions to call. For VCF files you'll only see the regions targeted by the specific pipeline. However (in favor of sending alone), if the specific pipeline metadata were included, as has been advocated, the context would be clarified well enough that the file by itself could be fully comprehended by the receiving system.
Kevin Power said:
My biggest problem with the R4 is that it is an Attachment only, not a DocRef. Meaning it doesn’t exist on its own, it is contained within the report
Bret H (Nov 06 2021 at 18:32):
Arthur Hermann said:
This is slightly off track - but what are our plans for balloting STU2? I may have missed that in a meeting, but I am not aware of any dates that we are tracking to? Are we planning to take all of the changes we have been working on, including the changes to Variant that Jamie has been working on, and ballot them as STU2? This will help us "clean up" the current situation for this issue, but until R5 is published won't really solve it. But knowing when we plan on balloting will help me understand our current plans... also do we have any idea at all as to when R5 would be published?
I am curious too. I think one of the co-chairs sent me a document of the changes to be expected. Probably need to survey the FHIR subgroup to see if we've got everything documented.
Kevin Power (Nov 06 2021 at 20:36):
Regarding timelines, we have already balloted STU2 (in May 2021) and we are working through ballot reconciliation (resolving the issues from the ballot comments) before we can release STU2 as a standard. I believe we are trying to target end of year to complete ballot rec then start the publishing process. If we can stick to that I hope we can release STU2 by 2022 Q1.
Kevin Power (Nov 06 2021 at 20:41):
@Bret H - Fair points about the metadata and everything that goes into creating the file, but given we have nothing standardized and computable on DiagosticReport either (as of today) then forcing everyone through DR is still an unnecessary extra step (in my opinion anyway). But if we will use DR.media in the long term, I think we can put up with the shortcomings it has for now.
Lloyd McKenzie (Nov 06 2021 at 23:13):
Attachment can just be a url pointing elsewhere. Also, so long as OO has signed off on the change to the definition, you should be fine to use it.
Kevin Power (Nov 06 2021 at 23:30):
We still have to wait for R5 though right?
Lloyd McKenzie (Nov 07 2021 at 21:18):
No. You can point to extensions that are in the draft. Though there is a risk to doing that.
Kevin Power (Nov 08 2021 at 14:19):
What does it look like to point to the draft? The guidance provided above doesn't address that - what do you use for the 'version'?
http://hl7.org/fhir/current/StructureDefinition/extension-DiagnosticReport.media
But even if we do that, I assume we would need to change the URL once R5 is released, so something like this?
http://hl7.org/fhir/5.0/StructureDefinition/extension-DiagnosticReport.media
Jamie Jones (Nov 08 2021 at 15:37):
Personally, I'd push to pre-adopt the R5 change as it suits out need, even before the O&O documentation around 'media' is updated to clearly be the right spot.
Kevin Power (Nov 08 2021 at 15:41):
So, the R5 change you are talking about is the change of data type of .media (from Attachment to Reference(DocumentReference) ) ?
Jamie Jones (Nov 08 2021 at 15:43):
That's what enables the use case (discovering a VCF from a genomics report)
Kevin Power (Nov 08 2021 at 15:44):
Do it now (so pre-adopt from current build)? Or, wait until R5 is released?
Kevin Power (Nov 08 2021 at 18:17):
OK, problem. DR.media.link in R4 is 1..1 - so if we do the extension on DiagnosticReport.media.extensions, we would be forcing people to use DR.media.link as well as the extension. That doesn't seem good.
Jamie Jones (Nov 08 2021 at 18:32):
@Lloyd McKenzie It seems due to cardinality restrictions in base DR, we would need to pre-adopt the whole DR.media element in order for it to validate without a Reference(Media). Is that an option?
Lloyd McKenzie (Nov 08 2021 at 18:36):
Ah. Yeah. That's not going to work with the inter-version extension mechanism. FHIR-I has actually agreed to a new extension that could be used, but I'm pretty sure it hasn't been created yet. So you may be out of luck for now. Sorry for misleading :(
Kevin Power (Nov 08 2021 at 19:13):
Welp, now I see these as our options (in no particular order):
-
Go with the extension for now, but perhaps add to our STU note that this approach will change to DR.media once we upgrade our IG to R5. (and we can continue to haggle if this is a new extension as in the branch, or just use 'SupportingInformation' and update our guidance)
-
Update our guidance to use DR.media even now, since it aligns with our long term vision, and just deal with the short comings.
-
Decide this isn't worth solving for now, and we wait until we upgrade to IG to be built on R5 and use the DR.media attribute once it aligns to our use cases.
Jamie Jones (Nov 08 2021 at 19:17):
For what it's worth I like #1. Folks can use our extension much like how they will eventually be able to use DR.media.link. wonder if we should draft it as a complex extension to include the comment string
Kevin Power (Nov 08 2021 at 19:29):
Jamie Jones said:
wonder if we should draft it as a complex extension to include the comment string
I proposed they use DocumentReference.description?
Arthur Hermann (Nov 08 2021 at 19:31):
I too like option 1 for now.. although the details as your new comments show, need to be fully worked out.....
Kevin Power (Nov 08 2021 at 20:00):
If we stick with option 1, I still vote for new extension. Anyone want to weigh in if they like that or to leverage the existing SupportingInformation extension?
Bret H (Nov 08 2021 at 20:18):
I propose using the current DR.media link with R4 and note that the resource - media may change for the better in R5.
Kevin Power (Nov 08 2021 at 20:24):
Bret H said:
I propose using the current DR.media link with R4 and note that the resource - media may change for the better in R5.
@Bret H - Not sure what you mean by note that the resource - media may change for the better in R5? In R5, DiagnosticReport.media.link will change from Reference(Media) to Reference(DocumentReference).
Jamie Jones (Nov 08 2021 at 20:25):
Bret H
Media IS a valid R4 resource and Media.type IS extensible but I feel strange pointing to something that is not a 'may' change but a 'will' change--the whole resource is being sunsetted in R5
Bret H (Nov 08 2021 at 20:37):
Ok. So, Document Reference.refererence will be the specific element used. But for R5 it is to be DiagnosticReport.media.link.Document Reference. content.attatchment?
For R4 how about DiagnosticReport.presentedFrom.attachement? It would skip a lot of intervening links. Of course the metadata won't be there but that's not going to be fully solved in R5 anyway for those that needed it: attachment https://www.hl7.org/fhir/datatypes.html#Attachment
Document Reference: https://www.hl7.org/fhir/documentreference.html
Is the Genomics Report profile of Diagnostic Report going away in an R4 version? or just from R5 onward?
Jamie Jones (Nov 08 2021 at 20:38):
Presentedform is tricky because implementers will likely try to render it and it's not going to work
Bret H (Nov 08 2021 at 20:39):
Good. how about the other question on R4 content? is Genomic Report going from R4? @Jamie Jones @Kevin Power
Kevin Power (Nov 08 2021 at 20:43):
I am not sure what you are asking @Bret H -- GenomicsReport profile will remain for quite some time. Do you mean the new extension we would add (would it go away once we uplift the IG to R5?). If so, I think the answer to that is yes.
Bret H (Nov 08 2021 at 20:51):
Nope. You can't focus on R5 and R4 at the same time in this case. I revise my position. Do not give any guidance till R5, but do point folks towards Document Reference - just don't connect to for them. If an implementer need to connect Document Reference to a specific report, they could use at least two ways (both of which would be deprecated uses and not fully compatible with R5). Rather than use guidance that get's broken just mention Document Reference (with attachment) as a way of communicating VCF, BAM and SAM location for R4.
But don't give an express way to connect with Diagnostic Report. It'll be a compromise, but if implementers get so far as to use Document Reference for exchanging VCF, BAM and SAM file locations (or, saint's preserve us, files), they will only need to adjust how they connect with Diagnostic Report in R5.
Kevin Power (Nov 08 2021 at 20:58):
I suppose I didn't have this as a bullet item, but I should have (which this aligns with what Bret is saying)
- Do not have a reference from DR to DocRef, only use (DocRef.context.related to refer to GenomicsReport): http://hl7.org/fhir/R4/documentreference-definitions.html#DocumentReference.context.related
Kevin Power (Nov 09 2021 at 13:50):
So, the new list of options:
- Go with an extension for now, but add to our STU note that this approach will change to DR.media once we upgrade our IG to R5.
- If extension, we need to decide between a new extension or use 'SupportingInformation' and update our proposed guidance
- Do not have a reference from DR to DocRef, only use (DocRef.context.related to refer to GenomicsReport) and update our proposed guidance: http://hl7.org/fhir/R4/documentreference-definitions.html#DocumentReference.context.related
@ Bob Milius - This might be good to discuss in today's meeting.
Jamie Jones (Nov 09 2021 at 13:55):
Let's not forget to also highlight the option to use the relatedArtifact extension with type=justification, for the folks who don't want to inflate the file to its own resource and want to "inline it" within the report
Kevin Power (Nov 09 2021 at 14:07):
Are you suggesting that as an alternative, or as "the way" ?
Jamie Jones (Nov 09 2021 at 14:14):
Currently it's the cleanest way to get an Attachment in, and it gets around the mimetype issue
Kevin Power (Nov 09 2021 at 14:17):
I like clean for sure, and at first I thought the same. However, the more I read about RelatedArtifact, it just doesn't feel right. How RelatedArtifact is used feels different that what we need.
Even if we consider this, is justification really the right code?
The target artifact is a summary of the justification for the knowledge resource including supporting evidence, relevant guidelines, or other clinically important information. This information is intended to provide a way to make the justification for the knowledge resource available to the consumer of interventions or results produced by the knowledge resource.
Bret H (Nov 09 2021 at 17:03):
So vote next week to include/merge the new extension with guidance on use?
including use (DocRef.context.related to refer to GenomicsReport) and update our proposed guidance: http://hl7.org/fhir/R4/documentreference-definitions.html#DocumentReference.context.related
I think Kevin's got that in the branch for the topic.
Kevin Power (Nov 09 2021 at 17:04):
Correct @Bret H
Bret H (Nov 09 2021 at 17:06):
glad I'm on target
Arthur Hermann (Nov 09 2021 at 17:36):
Kevin Power said:
I like clean for sure, and at first I thought the same. However, the more I read about RelatedArtifact, it just doesn't feel right. How RelatedArtifact is used feels different that what we need.
Even if we consider this, is justification really the right code?
The target artifact is a summary of the justification for the knowledge resource including supporting evidence, relevant guidelines, or other clinically important information. This information is intended to provide a way to make the justification for the knowledge resource available to the consumer of interventions or results produced by the knowledge resource.
Sorry - don't want to confuse things.. but does the path we plan on taking address your concerns noted above @Kevin Power ?
Arthur Hermann (Nov 09 2021 at 17:37):
LOL - I may have lost track of just what is being proposed!! :grinning:
Kevin Power (Nov 09 2021 at 17:37):
@Arthur Hermann - Yes, because we won't use RelatedArtifact now.
Kevin Power (Nov 09 2021 at 17:38):
We will go forward with the proposal found described by this guidance:
http://build.fhir.org/ig/HL7/genomics-reporting/branches/kp-file-attachments/general.html#file-attachments
Bret H (Nov 09 2021 at 17:40):
looks great but might want to strike "Another approach to avoid for attaching files is the DiagnosticReport.media attribute. Its definition focuses on "Key images associated with this report" which does not align well with this use case." if diagnosticReport.media definition will be changing in R5
Kevin Power (Nov 09 2021 at 17:41):
Ahh yea, I will rework that a bit before my next meeting.
Kevin Power (Nov 09 2021 at 18:53):
OK, I had to rush a bit due to other conflicts, but I have pushed up changes here:
http://build.fhir.org/ig/HL7/genomics-reporting/branches/kp-file-attachments/general.html#attaching-genomic-files
I incorporated some of the suggestions from @Jamie Jones as well. So, I would suggest everyone re-read this section and make sure it sounds good.
Arthur Hermann (Nov 09 2021 at 19:39):
@Kevin Power do you happen to have the previous text for this section? I am finding that some of the content is much less clear than it was previously so I am doing some editing. But I would like to see the phrasing that was used in the previous version.
Kevin Power (Nov 09 2021 at 19:53):
Sorry @Arthur Hermann - On my local device, I can back-out the latest change and share the previous text here. Give me 10 mins. I did try to merge in Jamie's updates with mine, and likely didn't do very well.
Kevin Power (Nov 09 2021 at 20:02):
File Attachments
This approach to file attachments needs to be carefully reviewed and considered. There are many potential issues and the Work Group welcomes feedback.
The Genomics File extension can be used to transmit the contents of, or links to, files that were produced as part of the testing process. Common examples are VCF, BAM, CRAM, and other similar files. Using the Genomics Document Reference profile provides the advantage of allowing a file to have its own existence and makes queries like "find all VCF files for this patient" possible by directly querying the DocumentReference resource. The extension provides an easy way to identify the file that is associated to a given report.
There are many considerations for these kinds of files, but one of the most recognized is file size. Many can be quite large, so size must be carefully considered. The GenomicsDocumentReference resource has different options to evaluate for your use case. The document content can be embedded directly in the resource using DocumentReference.content.attachment.data. In this case, the servers receiving the files may have size constraints per resource or per transaction which may limit your options. Alternatively, the file can be referenced by a URL using DocumentReference.content.attachment.url. The URL will likely point to an online resource that is not the FHIR server, perhaps referring directly to a cloud resource that hosts the file. In this case, servers may have constraints that limits access to resources outside the organization, which would prevent the receiving system from accessing the data. This approach also introduces authorization concerns, where the FHIR server would need to understand the authorization mechanism used to protect the file.
Implementers should also consider how the files were generated - what pipelines were used, what tools and applications were used in those pipelines, specific settings, and more. All of these must be carefully evaluated to ensure appropriate use of those files in downstream processes. The DocumentReference.description might be helpful for sending systems to provide some guidance on how the file was generated. However, a fully computable approach has yet to be described.
It should be noted that the Genomic File extension is not an appropriate way to send a copy of the report (e.g., PDF or other document containing the written report). Instead, use DiagnosticReport.presentedForm. Also note the Genomic File extension is different than the Genomics Artifact extension, which is used to reference citations, evidence and other supporting documentation for the observation or report. Another approach to avoid for attaching files is the DiagnosticReport.media attribute. Its definition focuses on "Key images associated with this report" which does not align well with this use case.
While a full, detailed discussion of an implementation is outside the scope of this IG, these and other factors affect how these files should be handled. In a future release, this IG may include a profile of DocumentReference or other artifacts to provide more specific guidance.
Kevin Power (Nov 09 2021 at 20:17):
@Arthur Hermann ^^^ previous text ^^^
Arthur Hermann (Nov 09 2021 at 22:41):
Here is my edit of the text.... I have a word doc with tracking on, if you would like me to attach it here. Please not two sections which begin with "AH note". These are sections I could not resolve.
In a future release, the file attachments guidance below, will be changed to utilize upcoming FHIR R5 updates to the DiagnosticReport.media backbone element. The attribute will refer to DocumentReference instead of Media, and this guidance will then be updated. This approach to file attachments needs to be carefully reviewed and considered. There are many potential issues and the Work Group welcomes feedback.
There are use cases in genomics where a deeper level of data than that provided by the variant profile is warranted, thus, specifications such as VCF, BAM, CRAM, and MAF have been developed. Best practices in exchanging these files along with the metadata necessary to make use of them through a FHIR API remains a complicated and open issue. See operations for a description of an experimental alternative workflow.
While in future versions of FHIR other resources or options might be preferred, currently, DocumentReference is a good candidate as a means to provide access to genomic data formats (AH QUESTION: We call them data formats here and specifications in paragraph above – which should we use?) such as VCF, BAM, CRAM and MAF. As opposed to the files just mentioned: attachments which are individually useful (such as clinical notes) would likely be sent in FHIR using the DocumentReference resource, which allows the file and its captured metadata (e.g. within the DocumentReference.context element) to be discovered via search queries.
(AH NOTE: - This paragraph was originally the key point of this section, but is now a bit lost – and I can’t harmonize the earlier draft with this current draft. It DEFINITELY needs work however, as I can’t easily make sense of it …. To many references to “objects” without enough clear text providing the context) The Genomics File extension can be used to transmit the contents of, or links to, files that were produced as part of the testing process The Genomics File extension can be used to reference files from the GenomicsReport. Also provided is the Genomics Document Reference profile which provides guidance for the genomic file itself.
When sending genomic files there are many considerations. For example, it is not unusual for files to be gigabytes in size. The DocumentReference resource has different options to evaluate for your use case. If embedded directly using using DocumentReference.content.attachment.data, servers receiving the files may have size constraints per resource or per transaction which may limit your options. Instead of sending a large data file, the file can be referenced by a URL and title using the using DocumentReference.content.attachment.url element. This can point to an online resource that hosts the file or from where the file can be accessed. For genomic files, the host is likely not the FHIR server providing the DocumentReference data instance. Be aware that use of DocumentReference to provide access to files through URLs introduces authorization requirements that are out of scope of this Implementation Guide.
For receivers to make use of these files, many facets of the generation of the genomic files will be needed, such as what pipelines, tools, and settings were used. The intended downstream use case must be carefully evaluated to ensure appropriate file preparation. The DocumentReference.description might be helpful for a sending system to provide guidance on how the file was generated. A fully computable approach for this issue has yet to be defined.
It should be noted that the Genomic File extension is not an appropriate way to send a copy of the report (e.g., PDF or other document containing the written report). Instead, use DiagnosticReport.presentedForm. Also note the Genomic File extension is different than the Genomics Artifact extension, which is used to reference citations, evidence and other supporting documentation for the observation or report. In this release, another approach to avoid for attaching files is the DiagnosticReport.media attribute. Its definition focuses on "Key images associated with this report" which does not align well with this use case. However, as noted in the STU note above, this will be changing in a future release.
A full, detailed implementation discussion, is outside the scope of this IG. In a future release, this IG may include other profiles or artifacts along with more specific guidance.
Arthur Hermann (Nov 09 2021 at 22:43):
Here is the word doc with tracking on
text-for-IG.docx
Kevin Power (Nov 09 2021 at 22:44):
Yea, this is my fault @Arthur Hermann - I tried to slam it through and didn't review closely enough. I will see about doing some cleanup tonight.
Arthur Hermann (Nov 09 2021 at 22:48):
Kevin Power said:
Yea, this is my fault Arthur Hermann - I tried to slam it through and didn't review closely enough. I will see about doing some cleanup tonight.
Please don't appologize Kevin!! We are all thankful for the tremendous work you are putting in to this and other efforts!
Kevin Power (Nov 10 2021 at 15:24):
@Arthur Hermann - I pushed up some changes, please review.
Arthur Hermann (Nov 10 2021 at 15:24):
Ok will do.. thanks
Arthur Hermann (Nov 10 2021 at 15:54):
Looks great @Kevin Power ! I few minor typos and change suggested below. Then from my perspective this section is clear and reads well. Others should review as well
First Sentence (in pink area) : In a future release, th genomic file --Correct the spelling of "the"
third sentence of actual entry: e metadata necessary to make use of them through a FHIR API remains a ----- --add a comma after API
When sending these genomic files, implementers should utilize the Genomics Document Reference profile which is used for sending meaningful metadata about the file.
--Change to: When sending these genomic files, implementers should utilize the Genomics Document Reference profile to send meaningful metadata about the file.
Arthur Hermann (Nov 10 2021 at 16:06):
(deleted)
Kevin Power (Nov 10 2021 at 21:56):
@Arthur Hermann - Updates made, please double check me.
Arthur Hermann (Nov 10 2021 at 22:36):
@Kevin Power I found a few more typos - sigh... is there someplace I could edit this and you could just push up the changes? if not, I will do as I did previously and note the typos I found..
Kevin Power (Nov 10 2021 at 22:42):
@Arthur Hermann - Sorry my writing sucks :frown: Probably easiest is to do your word doc approach w/track changes on again.
Arthur Hermann (Nov 10 2021 at 22:52):
I think we are almost done - so let's try these changes... then I will review once more.. but think I have caught everything.. of course it would be great to have other reviewers..
The guidance below to file attachments needs to be carefully reviewed and considered. There are potential issues and the Work Group welcomes feedback.
---- change to: The guidance below for file attachments
this approach allows the files to have their own existence and enables queries to find them possible via the DocumentReference resource.
--- delete word "possible"
in this release, another approach to avoid for attaching files is the DiagnosticReport.media attribute.
---change to: An approach which sould be avoided for attaching files (at least for this current release and guidance) is the DiagnosticReport.media attribute.
Kevin Power (Nov 10 2021 at 23:08):
@Arthur Hermann - I just pushed up these changes and am waiting on the build ( it should be available in 5-10 minutes ).
Sorry to treat you like Grammerly :smile:
Kevin Power (Nov 10 2021 at 23:09):
... although that is a pretty cool nickname :smile:
Kevin Power (Nov 10 2021 at 23:27):
Build complete @Arthur Hermann
Arthur Hermann (Nov 10 2021 at 23:45):
Sorry! I missed one last type - all else looks good to me - others should review as well please!!
To enabling linking the report to those files - change to enable
Kevin Power (Nov 11 2021 at 16:14):
@Arthur Hermann - Fixed that one.
Kevin Power (Nov 15 2021 at 17:45):
Anyone else have a bit to review over the next couple of days? I would like to get this one voted on next week if possible.
@Jamie Jones @Liz Amos @Bret H @Bob Dolin
Bob Dolin (Nov 15 2021 at 21:57):
@Kevin Power to be sure, can you repost the link to the material you want reviewed?
Kevin Power (Nov 15 2021 at 22:30):
Bret H (Nov 15 2021 at 23:03):
I think the guidance should go after http://build.fhir.org/ig/HL7/genomics-reporting/branches/kp-file-attachments/general.html#genomic-implications that is after the implications section.
There's a lot of good information there. this working group certainly strives to help out implementers. :grinning:
Kevin Power (Nov 15 2021 at 23:05):
Since the extension is on the GenomicsReport profile, I kept it with the rest of the GenomicsReport guidance. What is your thinking @Bret H ?
Bret H (Nov 15 2021 at 23:14):
That's a fair point. But here's my reasoning: 1) the files are very accessory, 2) the other parts do link from the Report and are key artifacts of the IG and implementation (will likely be more used).
Kevin Power (Nov 15 2021 at 23:16):
Fair points as well. I think I still propose keeping it where it is, but if others agree with Bret, I can be convinced.
Mullai Murugan (Nov 16 2021 at 00:51):
@Kevin Power @Bret H I kind of prefer where it is i.e. right after GenomicsReport considering the extension is used on GenomicsReport and since the potential R5 reference is calling out DiagnosticReport as well. @Kevin Power I would like to propose a verbiage change to the first sentence to kind of make it more general - thinking about the eMERGE use of bed files - how about "There are use cases in genomics where a deeper level of data than that provided by the GenomicsReport or variant profile is warranted. These use cases might be best served by including files such as VCF, BAM, CRAM, MAF and BED to the GenomicsReport." (or similar language)
Kevin Power (Nov 16 2021 at 15:44):
@Mullai Murugan - I made some changes to that first paragraph, and it is building now.
Jamie Jones (Nov 16 2021 at 15:51):
Kevin Power said:
Anyone else have a bit to review over the next couple of days? I would like to get this one voted on next week if possible.
Jamie Jones Liz Amos Bret H Bob Dolin
I think it looks pretty darn good as it is now! Only thing we may want to add is a warning that genomic files will likely be compressed (when their url is accessed) and may have unexpected or missing mime types
Bret H (Nov 16 2021 at 17:01):
I still am hesitant with the placement - there's a lot of text and it gives weight to the concept of including the files. It is a prominent place. Let me re-read. perhaps I just need another sentence.
Bret H (Nov 16 2021 at 17:03):
Yeah. my problem is that attaching genomics files to me is a note about an addendum item - whereas the observations are more critical to discuss (and to be read - although one should read the entire specification...)
Arthur Hermann (Nov 16 2021 at 17:04):
@Kevin Power - I tried adding Jamie's comment to this section.. see what you think:
When sending genomic files there are many considerations. For example, it is not unusual for files to be gigabytes in size. The DocumentReference resource has different options to evaluate for your use case. If embedded directly using using DocumentReference.content.attachment.data, servers receiving the files may have size constraints per resource or per transaction which may limit your options. Another issue to be aware of, is that these files will likely be compressed and may not have a defined mime type.
Then a paragraph break and continue the rest as is...
Arthur Hermann (Nov 16 2021 at 17:05):
Oh sorry - missed that Jaime said when using a URL... let me try again @Kevin Power
Bret H (Nov 16 2021 at 17:05):
To me it is the subject for an end note. could we put a single sentence with a link further down the page? Or maybe ::add something like "While most use cases will be satisfied by using genomic Observations <link to Observation anchor>, for those cases where a deeper..." with the opening sentence. @Kevin Power ? @Mullai Murugan ? what do you think?
Arthur Hermann (Nov 16 2021 at 17:08):
@Kevin Power maybe this will work (for including Jaime's comment):
Instead of sending a large data file, the file can be referenced by a URL and title using the using DocumentReference.content.attachment.url element. This can point to an online resource that hosts the file or from where the file can be accessed. For genomic files, the host is likely not the FHIR server providing the DocumentReference data instance. Be aware that that these files will likely be compressed and may not have a defined mime type. Also be aware that use of DocumentReference to provide access to files through URLs introduces authorization requirements that are out of scope of this Implementation Guide.
Kevin Power (Nov 16 2021 at 17:14):
Actually, I think Jamie's comments would apply to both approaches (contents embedded versus via URL)?
Kevin Power (Nov 16 2021 at 17:22):
Meaning, if the sender includes a base64 encoded file in DocumentReference.content.attachment.data, that might also be compressed and may not have a defined mime type.
Kevin Power (Nov 16 2021 at 18:03):
I would actually propose adding this to the end of 3rd paragraph:
... Be aware that use of DocumentReference to provide access to files through URLs introduces authorization requirements that are out of scope of this Implementation Guide. With either of these approaches, it is important to note the files might be compressed. The mime types for these genomic files will vary, or possibly be missing. The senders of the data should include as much metadata as possible to enabled the receiver to appropriately handle the files.
Arthur Hermann (Nov 16 2021 at 18:32):
Sound great!
Kevin Power (Nov 16 2021 at 18:42):
@Bret H - I am also updating the first sentence:
While this implementation guide strives to provide structured genomic data via a variety of <a href="#observations">observations</a>, there are use cases that warrant a deeper level of data than this guide allows.
Kevin Power (Nov 16 2021 at 18:50):
Just pushed up the change, should build in about 5 minutes or so
Bret H (Nov 16 2021 at 18:51):
thanks!
Kevin Power (Nov 16 2021 at 19:15):
OK, changes requested from @Jamie Jones and @Bret H made and built.
Kevin Power (Nov 23 2021 at 17:07):
To close out this thread, I have officially merged this with master, so all of these changes are now here:
http://build.fhir.org/ig/HL7/genomics-reporting/general.html
Last updated: Apr 12 2022 at 19:14 UTC
