Addon:DNASegmentMapGramplet

This is a Third-party Addon. The Addon/Plugin system is controlled by the Plugin Manager. Please use carefully on data that is backed up, and help make it better by reporting any issues to the bug tracker. Unless otherwise stated on this page, you can download this addon by following these instructions. Please note that some Addons have prerequisites that need to be installed before they can be used.

DNA Segment Map Gramplet - addon - with DNA information - Relationship View - bottombar - example

The DNA Segment Map Gramplet shows a graphic view of the DNA chromosome segment data for the active user and a set of associated users.

Usage

Undocked DNA Segment Map Gramplet default with no DNA information

You can install the DNA Segment Map Gramplet on the bottombar of one of the People or Relationship category list views.

Initially the DNA Segment Map Gramplet with no DNA information (chromosome data) is empty as 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.

Each person with shared segments will be a separate Association. The Notes in the Association should contain the shared segment info as calculated by the vendor.

There are two default views with an optional hidden third view for this gramplet. The default view is all of the chromosomes with all of the segments, painted in the order of the Association. The second view is a detailed view of a single chromosome, with each associated person having a separate row. The user clicks on the chromosome label (y-axis) to switch to the detailed view and clicks on the background to return to the default view. The optional hidden third view is disabled by default; this third view colors the segment based on the grandparent with separate colors for a common ancestor: maternal grandmother, maternal grandfather, paternal grandmother, and paternal grandfather.

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.
  • The format of the Note is a comma separated list or a tab separated list in the order: Chromosome Number, Start Segment, End Segment, shared length in centiMorgans (cMs), 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). .
  • For Example: 3,56950055,64247327,10.9,1404 Which means; Chromosome Number: 3, Start Segment: 56950055, End Segment: 64247327, shared length in cMs: 10.9, matching SNPs: 1404
  • Valid entries for each are:

Chromosome Number

number between 1-22 or X

Start Segment

The starting number for the segment location.

End Segment

The ending number for the segment location.

Shared length in cMs

The Genetic Distance (otherwise known as the number of centiMorgans) in the segment.

SNP

optional field of the matching SNPs (Single Nucleotide Polymorphism) in the segment.

M/P flag

optional field to override the Maternal or Paternal or Unknown chromosome. Valid entries are M or P or U. Any other data is ignored

Getting the chromosome data

Sites like 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.

DNApainter provides a description of how to get the chromosome data from many of the common sites.

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.

Match Name,Chromosome,Start Location,End Location,Centimorgans,Matching SNPs
MATCH NAME, 1,191870504,201977600,9.505878,2391

GEDmatch

Sample GEDmatch output (see screenshot) that can be cut and paste into the Note. The fields are the same - Chromosome, Start, End, cM, and SNPs. This can be cut/paste from the GEDmatch output directly into the Note for the Association. The header line will be ignored.

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.

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).

<U+FEFF>Name,Match Name,Chromosome,Start Location,End Location,Start RSID,End RSID,Centimorgans,SNPs
User Name,Match Name,2,172775482,208500311,rs116868713,rs9288384,29.8,16512

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.

Chromosome;Start of segment;Length of segment;Number of SNPs;Length in centimorgan (cM);Type of segment
9;14037831;73101159;6804;38.64;half-identical

Ancestry

Ancestry.com does not have a chromosome browser and its data thus lacks some of the information that other vendors provide. An alternative format is therefore used for Ancestry DNA matches.

You can find this information by going to your DNA Matches comparison page and selecting the link to show the popup-page that list the Shared DNA, Unweighted shared DNA and the Longest segment result:

An example of a DNA match where the individuals share 55cM or identical DNA from a recent common ancestor. They also share an additional 17cM of identical DNA not from a common ancestor. Copied from https://support.ancestry.com/s/article/Understanding-Unweighted-Shared-DNA

You and [Name of Match]

Predicted: [predicted relationship]

    Shared DNA: XXXX cM across XX segments
    Unweighted shared DNA: XXXX cM
    Longest segment XXXX cM 

From this information you can create a note with a single line specifying Shared DNA, Unweighted shared DNA and the Longest segment, in that order, separated by tabs or commas, for example screenshot the result would be: 55,72,21

Legend

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(MRCA). 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 of the Legend, edit the config file parameters:

legend-single-chromosome-y-offset=25
legend-swatch-offset-y=0

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 following are capabilities that are currently disabled but can be enabled if user desire. These add complications to the user interface and are deemed not beneficial

The [map] section of the gramplets config file DNASegmentMap.ini has the following options. Remove the comment (double semi-colon) and edit as needed while Gramps is not started. Changes are not reflected until the next time the Gramps is started.

[map]
;;chromosome-build=37
;;chromosome-x-scale=1.4
;;chromosome-y-scale=1
;;grandparent-view=0
;;include-citation-notes=0
;;legend-char-height=12
;;legend-single-chromosome-y-offset=0
;;legend-swatch-offset-y=0
;;maternal-background=(0.996, 0.8, 0.941, 1.0)
;;output-folder=''
;;output-visual-segments=0
;;paternal-background=(0.722, 0.808, 0.902, 1.0)
;;show-centromere=1
;;show_associate_id=0

• Chromosome Build: choose the specific build for the chromosomes. Options are 36, 37, 38.
• 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
• Maternal Background Color: RGB values for the background of the Maternal Chromosome
• Paternal Background Color: RGB values for the background of the Paternal Chromosome
• Show Centromere: If 1, do not paint the background area for the centromere. This area is dependent on the Build.
• Show Associate ID: To remove the ID on the legend and tooltip, set to 0. Otherwise leave as 1 to print the Associate ID.

Views

This gramplet has two views with an optional hidden third view:

• Chromosome Segment Map for <PersonName> View (default)
• Single Chromosome View
• Visual Phasing View - (optional hidden third view)

Chromosome Segment Map for <PersonName> View

Undocked DNA Segment Map Gramplet example with tooltip

The default view shows all 23 chromosomes; with all of the segments, painted in the order of the Association.
DNA Segments are positions on chromosomes where a DNA relative is related to the active person.

Segment Map
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
X

Single Chromosome View

"DNA Segment Map" Gramplet - addon - detached - "Single Chromosome View" with DNA information example

To view just a single chromosome, click on the chromosome number column. 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.

Visual Phasing View

Visual Phasing View for Grandparent View 2

Visual phasing is a methodology for assigning segments to specific grandparents. This technique can be employed when parents are not available for testing.

This view is disabled by default. To enable, edit the config file. The specific config options are:

• grandparent-view

   0 (default) to disable
   1 Visual phasing with 4 grandparents
   2 Visual phasing with 4 grandparents and 8 great-grandparents

• output-visual-segments

   0 (default) to disable
   1 Print the segment info assigned to the grandparent/great-grandparent from the view. The file is named grampsID.tsv and is a tab-separated file.

• output-folder

   ' ' (default) print the file in the user Home directory
   'dir-name' print the file in the specified folder

If the segment file cannot be printed in the output folder, a warning is generated. The segment file is the same format as the Note so can be cut-paste into the grandparent/great-grandparent if desired.

To view with coloring based on grandparent/great-grandparent, enable in the config and then click on the background outside of any drawn graphics or legend. The DNA segment will be painted one of 4/12 colors, depending on the grandparent/great-grandparent found in the path of the tree. The maternal side has 2 color options (maternal grandfather or maternal grandmother). The paternal side has 2 color options (paternal grandmother or paternal grandfather).

Legend for Grandparent View

For the great-grandparent view, there are an additional 8 colors

Legend for Great-Grandparent View

First cousins or closer are not displayed. If there is no known path based on the tree, the segment is not displayed.

Click again on the background to reset to standard view.

DNA Example data

To reproduce the illustration (for default view of all the chromosomes with all of the segments) with the Example.gramps dataset.

In the "Person Editor" for 'Luther Robinson (I0656) create two records in the Associations tab:

---

(1.) Record one is DNA type, adding an association with Robert F. Garner (I1123).

The Note under this association contains the following text. The last two fields with the Person names are ignored.

Chromosome,Start Location,End Location,Centimorgans,Matching SNPs,Name,Match Name
3,56950055,64247327,10.9,375,Luther Robinson, Robert F. Garner
11,25878681,35508918,9.9,396
12,129481599,133491098,12.4,304
15,35444614,64710827,33.3,1212
1,48053426,68837810,24.6,3413
1,72956037,87857969,13.4,2035
3,69656569,74563488,9.0,974
6,6179882,15400114,18.5,1994  

---

(2.) Record two is also DNA type, adding an association with Maude Garner (I0651).

The Note under this association contains the following text:

1,30578594,38686908,11.2,334
1,236520701,249210707,29.7,685
3,14446545,24339734,12.3,458
3,128688499,140766208,11.4,447
4,76585823,114118650,33.7,1317
4,163973796,190915650,49.1,1422
6,4737179,9181572,10.3,279
6,39128976,49586285,15.8,510
6,150564916,156389148,10.2,415
7,18915133,37547290,25.8,1038
7,93557588,116296896,20.2,821
7,141636563,156148608,30.9,787
8,2808265,6919748,10.7,436
8,12568161,42652859,38.7,1556
8,49039681,71454529,20.3,742
8,71990280,99554231,21.9,917
9,78958599,122204804,55.7,2014
10,5608202,10769007,10.4,333
10,19365648,38434090,19.6,775
11,26722523,37020611,11.8,447
12,66412457,94422155,24.4,1035
13,19234747,23899627,8.7,270
13,74422984,91183468,14.2,506
14,23902753,33048583,15.5,392
14,88816167,106020366,37.8,947
15,23727655,27246462,8.2,229
16,22836249,32137965,12.6,413
16,46644903,54620503,11.7,360
17,13905,6613192,18.9,419
17,25567080,44187492,19.7,694
17,44790203,72115774,39.7,1223
18,18714991,47726830,27.9,1071
18,69454453,77894844,23.5,481
19,1993444,11174625,28.1,567
19,54545531,59087479,12.7,335
20,9879166,26225145,24.3,788
20,30221104,43975451,13.5,489
21,14670124,18743733,10.8,201

---

DNA match row data must be in a specific CSV order The data may include a header but the Gramplet does not require one. Headers are to make the rows more readable by humans. The rows do not need to be sequentially ordered by the chromosome identifier (1 to 22 and X).

Example

Create an Association of type DNA as described in the 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. (For this example use the DNA Example data above.)

Save the Association.

Add more associations as known. Each would be associated to a different person and have a different Note. Since the Associations are drawn in order, it is generally better to have them in order of closest relative to furthest relative to avoid obscuring a distant relative (smaller segment) by a close relative (larger segment). Use the up-arrow and down-arrow to change the order of the Association.

Add the DNA Segment Map Gramplet to the Relationship View's bottom bar. Select the DNA Segment Map tab. The segment map will be color coded by associated person. For each Chromosome the top portion is the P (Paternal) side and the M (Maternal) side is the bottom portion. If the chromosome segment side (Paternal or Maternal) is unknown, the segment will cover both the top and bottom portions of the chromosome and be 50% transparent.

Hovering the cursor over a known segment will pop up the name of the associated person and the length (in cMs) of the shared segment.

Clicking on the Y-axis label for the 6th chromosome, a detailed single Chromosome View is shown. Click on the background to return to the complete view.

Reference Info

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. 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

1	121500000	128900000
2	90500000	96800000
3	87900000	93900000
4	48200000	52700000
5	46100000	50700000
6	58700000	63300000
7	58000000	61700000
8	43100000	48100000
9	47300000	50700000
10	38000000	42300000
11	51600000	55700000
12	33300000	38200000
13	16300000	19500000
14	16100000	19100000
15	15800000	20700000
16	34600000	38600000
17	22200000	25800000
18	15400000	19000000
19	24400000	28600000
20	25600000	29400000
21	10900000	14300000
22	12200000	17900000
X	58100000	63000000

To view and visualize these centromere areas for all chromosomes, edit the config file as described below and set show-centromere to 1.

show-centromere=1

See also:

• Centromere - From Wikipedia, the free encyclopedia

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.

13,1,19020094,0,0
14,1,19067948,0,0
15,1,20004965,0,0
21,1,9922017,0,0
22,1,16055121,0,0

Issues

• Issues on the bug tracker tagged DNASegmentMapGramplet
  • detached help button & addon listing wiki button link to https://gramps-project.org/wiki/index.php?title=Addon:DNASegmentMap

• 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. All of the paths are printed in the tooltip.
• To create a segment map for Person A, you need to add associations to Person A. There is no reciprocal relationship for Person B - that is, there is no segment map for Person B, only for Person A. You can execute the Addon:SyncAssociation addon to create any missing reciprocal relationships.
• Color code for each associated person in the map is consistent but not user-specified. The first Association will always be the same color.
• 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.
• When the user has no DNA data, have the gramplet still show a blank chromosome chart & legend with a message link to this page?
• Legend with rollover tooltip does not work (win 10)

Future feature To Do

• Add user config to specify the Association Type. Currently, the Association Type of DNA is used for this gramplet. It could be made user-controllable.

History

• DNA Segment Map gramplet Pull Request #550 (GitHub pre-release) Jun 25, 2023
• Updated DNA gramplet ready for review, Discourse forum discussion on the DNAgramplet; 15th of October, 2020

See also

• DNA Matches gramplet addon presents the users with a table of people whose DNA has a match with the currently selected person.
• Sync Association addon tool - 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.
• Add Types to the SyncAssociation tool
• Introduction to Associations in Gramps
• Roles, Relationships & Associations
• Genetics
• Visual Phasing: An Example (Series of 5 parts), By The Genetic Genealogist, 21st November 2016