Add DNA docs

Author: DavidMStraub

docs/user-guide/chromosome-browser.md

@@ -0,0 +1,9 @@
+# Chromosome Browser
+
+The chromosome browser is a tool to visualize a person's DNA matches. It shows the DNA segments shared with other people in the tree as colored bars on the chromosomes.
+
+You can find it under the “Chromosome Browser” tab in the DNA view.
+
+For each chromosome, the upper (light blue) bar represents the copy inherited from the father, the lower (light red) bar the one inherited from the mother. The shared segments are shown as colored bars on top of these. If the side (paternal or maternal) is not known, the segment spans both bars and is shown with hatch marks.
+
+Clicking on the name of a match in the legend, only this person's shared segments are shown.

docs/user-guide/dna-matches.md

@@ -0,0 +1,46 @@
+# Working with DNA matches
+
+DNA matches are segments of DNA that agree between to individuals, identified by the presence of markers, so-called SNPs (the acronym for single nucleotide polymorphisms, pronounced “snips”).
+
+To obtain this data, you need access to a DNA test that is uploaded to a matching database that allows to view DNA segment match data (e.g. MyHeritage, Gedmatch, FamilytreeDNA). Gramps Web does not perform the matching itself, as it only has access to the data you upload.
+
+## Entering DNA match data
+
+To enter DNA match data, you need [edit permissions](../install_setup/users.md) as the data is stored as a note in the Gramps database. The DNA view, accessible from the main menu, provides a convenient way to enter this data in the right format.
+
+To enter a new match, click on the + button in the lower right. In the dialog that opens, select the two individuals. Note that the “First person” and the “Second person” are treated differently: the match is stored as an association from the first to the second person. Only the first person will be selectable for the DNA match view and chromosome browser. Typically, the first person is the one whose DNA test you have access to and the second person is a more distant relative.
+
+If the second person is not in the database, you need to create it first by using the “Create person” button in the top right corner of the user interface. Once you have created the person, you can return to the DNA match view and select the newly created person.
+
+Next, paste the raw data into the text field. The data should be a comma or tab separated table of matches, typically containing the chromosome number, the start and end position of the match, the number of SNPs in the match and the lenght of the match in units of centimorgans (cM). You can also drag and drop a file with the match data into the text field.
+
+A minimal example of such a table is:
+
+```csv
+Chromosome,Start Location,End Location,Centimorgans,SNPs
+6,6358001,18115715,19.6,7424
+7,150135758,154205894,10.9,2816
+```
+
+If the format is valid, a preview is shown below the text field as a table. 
+
+Finally, click on the “Save” button to store the match in the database.
+
+## Viewing DNA match data
+
+The DNA match view has a dropdown that allows to select each person in the database that has an associated DNA match. Once a person is selected, the DNA match data is shown in a table below the dropdown. It shows the name of the person the match is associated with, the relation to the person selected in the dropdown (automatically determined from the Gramps database), the total length of shared DNA in centimorgans (cM), the number of shared segments, and the length of the largest of these segments.
+
+When you click on an individual match, it opens a detail page showing all the segments and whether the match is on the maternal or paternal side. This information can be either entered manually (by providing a `P` for paternal or `M` for maternal in a column named `Side` in the raw data) or automatically determined by Gramps based on the most recent common ancestor.
+
+## Editing a match
+
+You can edit a match by clicking on the pencil button in the bottom right in the match detail view. This opens a similar dialog as when creating a new match, but with the data pre-filled. Note that you can change the raw data, but not the individuals associated with the match – you need to delete the match and create a new one if you want to change the individuals.
+
+## Working with match data in Gramps Desktop
+
+The DNA match data is stored as a note in the Gramps database. The format is compatible with the 
+[DNA Segment Map Addon](https://gramps-project.org/wiki/index.php/Addon:DNASegmentMapGramplet)
+available for Gramps Desktop. Its wiki page contains more details about how to obtain the data, how to interpret it, and how to enter the data in Gramps.
+
+!!! info
+    Gramps Web API v2.8.0 introduced some changes to the accept a broader range of raw DNA match data, which is not yet available in the Gramps Desktop Addon. The Gramps Desktop Addon will be updated in the future to support the same formats as well.

docs/user-guide/dna.md

@@ -1,13 +1,9 @@
-# DNA segment map
+# Using Gramps Web for DNA genealogy
 
-!!! warning
-    This page is outdated as of Gramps Web v25.1.0 released in January 2025. It will be updated soon.
+There are three branches of DNA genealogy dependending on the type of DNA used:
 
+- Autosomal chromosomes (numbered 1–22) are inherited from father and mother, so the probability of inheriting a piece of DNA from a given ancestor reduces exponentially with the number of generations. This makes them useful for finding degrees of separation with relatives when there is a relatively recent (few generations) common ancestor.
+- The Y chromosome is only passed on from father to son, so it can be used to trace the paternal lineage.
+- Mitochondrial DNA is passed on from mother to daughter, so it can be used to trace the maternal lineage.
 
-The DNA segment map view, accessible under the "DNA" tab in the person view, shows DNA matches with other people in the tree as segments highlighted on the person's chromosomes.
-
-This feature does not rely on raw DNA data being uploaded to Gramps Web, but on the segment match data directly, which can be obtained from websites like Gedmatch or MyHeritage.
-
-The DNA segment map is based on the [Gramplet Addon](https://gramps-project.org/wiki/index.php/Addon:DNASegmentMapGramplet) that provides the same functionality in Gramps Desktop. Its wiki page contains more details about how to obtain the data, how to interpret it, and how to enter the data in Gramps.
-
-The data is added as notes attached to associations (or attached to association citations), which is possible directly in Gramps Web.
+At present, Gramps Web provides tools to work with [matches from autosomal DNA tests](dna-matches.md). To obtain this data, you need access to a DNA test that is uploaded to a matching database that allows to view DNA segment match data (e.g. MyHeritage, Gedmatch, FamilytreeDNA). Gramps Web does not perform the matching itself, as it only has access to the data you upload.

mkdocs.yml

@@ -40,13 +40,13 @@ nav:
         - Tag people in photos:  user-guide/tagging.md
         - Use the blog:  user-guide/blog.md
         - Manage tasks:  user-guide/tasks.md
+      - DNA: 
+        - Overview: user-guide/dna.md
+        - DNA matches: user-guide/dna-matches.md
+        - Chromosome browser: user-guide/chromosome-browser.md
       - Revision history:  user-guide/revisions.md
-      # - DNA: 
-      #   - Overview: user-guide/dna.md
-      #   - DNA matches: user-guide/dna-matches.md
-      #   - Chromosome browser: user-guide/chromosome-browser.md
       - Advanced features:
-        - DNA:  user-guide/dna.md
+        # - DNA:  user-guide/dna.md
         - GQL filters:  user-guide/gql.md
         - AI chat: user-guide/chat.md
   - Developers: