276
edits
Changes
From Gramps
m
<nowiki>
<code>
</code>
</nowiki>
Draft of updates based on PR 600
{{languages|Addon:DNASegmentMapGramplet}}
{{Third-party plugin}}
The {{man label|DNA Segment Map Gramplet}} shows a graph.
==Usage==
The purpose of this gramplet is to view DNA segment data for the active user and a set of associated users. Once the user has done an autosomal DNA test and uploaded their data to one of the vendors (GEDmatch or FamilyTreeDNA, for example), the vendor can calculate the shared DNA segments with others in their system. These list of people with their shared segments are input to this gramplet for visualization.
You can install the {{man label|DNA Segment Map Gramplet}} on the bottombar of one of the people or relationship category list views.
===Create a DNA Association===
To specify shared DNA segments between 2 people,
* Create an Association for one person (Person A) with another Person (Person B) of the type DNA.
* Add a Citation to the Association to reference the vendor which provided the segment info. This is not used by the gramplet, but is useful since different vendors will produce slightly different segment info. And some Associated Persons might have data from multiple vendors. In these cases, having a second Association is useful.
* Create a Note in the Association or attached to a Citation in the Association with the shared DNA segment data. By default the config ''include-citation-notes'' is True (1) and both the Association Note and the Citation Note may contain DNA segment data. If this config is set to False (0), then only the Association Note will be read for DNA segment data.** The format of the Note is a comma separated list or a tab separated list in the orderbelow. If the list contains tabs, but cannot be parsed to these fields, the line is ignored: <code>[https://wikipedia.org/wiki/Chromosome#Human_chromosomes Chromosome Number], Start Segment, End Segment, shared length in [[Genealogy_Glossary#centimorgan|centiMorgans]] (cMs), [https://wikipedia.org/wiki/Single-nucleotide_polymorphism SNP] (optional), M or P or U (unknown) to override the Maternal Paternal chromosome as determined by the closest genetic connection in the tree (optional). </code>.
** For Example: <code>3,56950055,64247327,10.9,1404</code> Which means; Chromosome Number: 3, Start Segment: 56950055, End Segment: 64247327, shared length in cMs: 10.9, matching SNPs: 1404</code>
** Valid entries for each are:
{{-}}
====Getting the chromosome data ====
Sites like [https://www.gedmatch.com/login1.php GEDmatch] make this shared chromosome data available. Direct copy from the GEDmatch results page (with header and tab separators) will work. There can be additional Associations between Person A and Person C (et cetera) as known.
Add the kit number or other unique info as an Attribute to the Associated Person. For example, create an Attribute 'GEDmatch kit' to contain the GEDmatch kit number. Or 'DNAkit' for the FTDNA kit number. These are not used by the gramplet but good for reference.
The sites that have DNA segment data and formats are covered below. ===== FamilyTreeDNA =====FamilyTreeDNA provides a download CSV file. Sample format starting at field 2 is set for copy into this gramplet. <pre>Match Name,Chromosome,Start Location,End Location,Centimorgans,Matching SNPsMATCH NAME, 1,191870504,201977600,9.505878,2391</pre> ===== GEDmatch =====GEDmatch provides a cut-paste option for data. The format is set for copy into this gramplet. The gramplet will accept either comma or period as the thousands separator.{| class="wikitable"|-| Chr||B37 Start Pos'n||B37 End Pos'n||Centimorgans (cM)||SNPs||Segment threshold||Bunch limit||SNP Density Ratio|-| 6||67,249,077||91,039,808||15.6||978||191||114||0.1|} ===== MyHeritage =====MyHeritage provides a download CSV. The fields need to be adjusted (remove the 1st, 2nd, 6th and 7th fields).<pre><U+FEFF>Name,Match Name,Chromosome,Start Location,End Location,Start RSID,End RSID,Centimorgans,SNPsUser Name,Match Name,2,172775482,208500311,rs116868713,rs9288384,29.8,16512</pre> ===== Geneanet =====Geneanet provides a download CSV that needs to be adjusted. Fields 4 (Number of SNPs) and 5 (Length in centimorgan) need switched and field 6 removed. Semicolon delimeter needs replaced with comma.<pre>Chromosome;Start of segment;Length of segment;Number of SNPs;Length in centimorgan (cM);Type of segment9;14037831;73101159;6804;38.64;half-identical</pre> ====Legend====
[[File:Addon-DNA-SegmentMap-legend.png|thumb|338px|right|[ {{man label|Legend with rollover tooltip]]
* For each Chromosome: the top portion is the Paternal side and the bottom portion is the Maternal side.
* The chromosome segment side (Paternal or Maternal) is determined from the Most Recent Common Ancestor. If there is no common ancestor, both sides are used.
* The color code for each associated person in the DNA segment map is consistent but not user-specified. The first Association will always be the same color.
* To change the location or size of the Legend, edit the config file parameters:
<pre>
legend-single-chromosome-y-offset=25
legend-swatch-offset-y=0
legend-char-height=12
</pre>
====Navigation====
* The Legend on the right side lists each associated person who has a mapped segment. Hovering over the legend items will show a tooltip for possible action. Primary button click will change the active person. Secondary button click will open the Person Editor for the associated person.
* Hovering over the Y-axis chromosome labels will show a tooltip for possible action. Primary button click will switch view to single chromosome of the label clicked. To return to full view, click on the background in the single chromosome view.
* Hovering over a segment provides detail on the segments at that location. If there are multiple segments overlapping, all will have details.
====Configuration====
The config file for this gramplet has the following options. Remove the comment (double semi-colon) and edit as needed. Changes are not reflected until the next time the gramps is started.
[map]
;;chromosome-build=37
;;include-citation-notes=1
;;legend-char-height=12
;;legend-single-chromosome-y-offset=25
;;legend-swatch-offset-y=0
;;maternal-background=(0.833926, 0.845825, 0.92, 1.0);;paternal-background=(0.926833, 0.825845, 0.92, 1.0)
;;show-centromere=0
;;show_associate_id=1
* Chromosome Build: choose the specific build for the chromosomes. Options are 36, 37, 38.
* Include Citation Notes: whether to use the Association's Citation Notes for DNA segment data. Default is true (1). If set to false (0), then only the Association Note will be parsed for DNA segment data.
* Legend Character Height: size of the lines in the legend block. Default is 12. To make the legend include more lines, lower this number. 6 is still very readable.
* Legend Single Chromosome Y offset: Adjust the height of the legend for the single chromosome view. This may be needed if more than 12 people share the chromosome.
* Legend Swatch Offset: Offset for the color swatch in the legend. Should be 5 for Windows systems. 0 works for Linux and Mac
* Show Associate ID: To remove the ID on the legend and tooltip, set to 0. Otherwise leave as 1 to print the Associate ID.
====Single Chromosome View====To view just a single chromosome, click on the chromosome number. This view has each association as a different row, helping to see overlapping areas. To return to the standard view, click on the background area. ====DNA Example data====
To reproduce the illustration with the [[Example.gramps]] dataset, create two records in the Associations tab in the Person Editor for Luther Robinson(I0656).
{{-}}
==== Example ====
[[File:Addon-DNA-Note-Example.png|thumb|600px|right]]
Create an Association of type DNA as described in the [[Gramps_{{man version}}_Wiki_Manual_-_Entering_and_editing_data:_detailed_-_part_1#Associations|Association]] page to Person A. Add a Note with the DNA shared segment data. Set the Note private if you do not want the data printed in reports.
{{-}}
=== Reference Info ======= Untested Areas ====
There are areas in the DNA test that are generally not tested as they are not reliable indicators of a match. If you want to visualize these areas, create a dummy person and add an association with the following DNA segments.
</pre>
==== Centromere Areas ====
Machines have difficulties to read the area around the centromere. There are less SNPs to read, therefore there is higher probability of false positive matches. For example, if you have a match exactly around the centromere, then it is most probably a false positive match. If you want to visualize these areas, edit the config file as described above and set show-centromere to 1. The area of the centromere id dependent on the Build (36, 37, or 38). For example, the list for Build 37 (the most common) is
show-centromere=1
</pre>
== To Do ==
== Issues ==
* If the Chromosome Number is not in the range (1, 2, ..., 22, X) it is ignored.
* If there are multiple paths to a common ancestor, the closest found is used.
* If there are overlapping segments within a maternal/paternal view of a chromosome, only the front (last drawn) will be pickable. The tooltip will still provide the details of the hidden segments. Changing the order of Associations (using the up-arrow and down-arrow) to have the closer relatives before further relatives will fix this. To see overlapping segments, select a single chromosome.
== See also ==
* DNA Segment Map gramplet #550 (GitHub pre-release [https://github.com/gramps-project/addons-source/pull/550])
* [[Addon:SyncAssociation]] - For every Association, if there is not a reciprocal Association then it will be created. That is, where Person John Smith has a DNA Association (with an Association Note) to Person Jane Jones, then if Jane Jones does not have a corresponding DNA Association to John Smith, it will be created which shares the Note.
[[Category:Plugins]]
[[Category:Addons]]
