# Synteny by ancestral linkage group (sponge, comb jelly, jellyfish)

:::caution JBrowse v5 beta

The tutorials target the JBrowse v5 beta, and the v4.3.0 release
on the [download page](https://jbrowse.org/jb2/download/) lacks some of what they show. To install the
beta of JBrowse Web, run `npm install -g @jbrowse/cli@next`, then
`jbrowse create jbrowse2 --branch v5.0.0-beta.17`. Desktop beta builds are coming soon.

:::

Certain sets of genes have stayed on the same chromosome together since before
animals existed, and those sets have names.
[odp](https://github.com/conchoecia/odp) writes, for every pair of genomes it
compares, a table of their orthologs with the set each one belongs to and a
color for it. A sponge keeps each set on one chromosome; a comb jelly spreads
each over several. We:

- load the jellyfish-sponge table as a synteny track, each ortholog colored by
  its set
- open it as a dotplot, with one genome's chromosomes sorted by where their
  orthologs sit on the other
- stack the genomes in a linear synteny view, with ribbons colored by set

## Prerequisites

- A web browser, to fetch two files from Dryad by hand
- `python3`
- `samtools`
- `curl` and `tar`
- `node`, for the [JBrowse CLI](https://jbrowse.org/jb2/docs/cli)
- A running JBrowse instance (the [web quickstart](https://jbrowse.org/jb2/docs/quickstart_web) or the
  [desktop quickstart](https://jbrowse.org/jb2/docs/quickstart_desktop))

<!-- TUTORIAL_INSTALL samtools,node,jbrowse-cli START -->

```bash
# Debian/Ubuntu
sudo apt install samtools nodejs
# or conda, which has every tool above
conda install -c bioconda -c conda-forge samtools nodejs
# any platform
npm install -g @jbrowse/cli
```

<!-- TUTORIAL_INSTALL samtools,node,jbrowse-cli END -->

## Download the data

The genomes and the ortholog tables are the Dryad deposit behind Schultz et al.
2023, released CC0.

Dryad has no direct download URL, so download the two tarballs by hand. The
[build script](#reproduce-it-end-to-end) fetches the _Ephydatia_ assembly.

| What it is                                                                             | File                                                                                                       |
| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Both tarballs, `genomes.tar.gz` and `supplementary_information.tar.gz`                 | [dryad.dncjsxm47](https://datadryad.org/dataset/doi:10.5061/dryad.dncjsxm47)                               |
| The _Ephydatia_ assembly, which a script in the deposit fetches from the original host | [Emu_genome_v1.fa.gz](https://bitbucket.org/EphydatiaGenome/ephydatiagenome/downloads/Emu_genome_v1.fa.gz) |

## The linkage-group label in the ortholog table

Simakov et al. 2022 named a set of gene families the BCnS linkage groups. A gene
belongs to one group or to none. odp searches every proteome it is given against
a database of the groups' protein models and writes the group each ortholog was
assigned as a column beside it, which a synteny track can read. Your own genomes
need odp's table with its `gene_group` and `color` columns, written when odp
runs with `plot_LGs: True`, and a `.chrom` file per genome.

The dotplot uses two genomes and the stack at the end adds more:

| Code   | Species                                | Used in           |
| ------ | -------------------------------------- | ----------------- |
| `RES`  | jellyfish _Rhopilema esculentum_       | dotplot and stack |
| `EMU`  | freshwater sponge _Ephydatia muelleri_ | dotplot and stack |
| `HCA`  | comb jelly _Hormiphora californensis_  | stack only        |
| `BIN`  | comb jelly _Bolinopsis microptera_     | stack only        |
| `BFL`  | amphioxus _Branchiostoma floridae_     | stack only        |
| `CLAa` | cladorhizid sponge                     | stack only        |

odp's group database was built from a set of genomes, some of them on this page:
the jellyfish, _Ephydatia_ and amphioxus. The comb jellies and the cladorhizid
took no part in it. odp compares genomes two at a time, so the deposit holds one
table per pair, each listing every reciprocal best protein hit between its two
genomes.

A table's row is the gene pair, the group, where each gene sits, and the color:

```text
rbh                    EMU_gene      RES_gene       gene_group  EMU_scaf  EMU_pos  RES_scaf  RES_pos   ...  color
rbh2way_EMU_RES_964    Em0019g38a    mRNA.RE04286   A1a         EMU19     180964   RES2      13815510  ...  #C23D51
rbh2way_EMU_RES_4123   Em0019g57a    mRNA.RE14076   None        EMU19     290216   RES8      13037026  ...  #000000
```

Gene intervals come from odp's `.chrom` files, since the table's position column
holds one coordinate per gene and would make every feature one base long:

<!-- from: scripts/build_odp_linkage_groups_synteny.sh -->

```bash
curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/rbh_to_blocks.py
# --species sets the column order, anchor first, which the track then follows
# --chrom gives each species' genes their real start and stop
# --attributes names the columns that pass through after the gene ids
python3 rbh_to_blocks.py EMU_RES_xy_reciprocal_best_hits.coloredby_BCnS_LGs.plotted.rbh \
  -o RES_EMU.blocks --bed-dir RES_EMU \
  --species RES EMU --chrom RES=RES.chrom EMU=EMU.chrom \
  --attributes gene_group color break_FET
```

`rbh_to_blocks.py` prints how many of each genome's gene ids its `.chrom`
placed. An ortholog from outside the BCnS families gets `.` in the group column,
which the browser draws in grey.

A `.blocks` row is the gene ids across the two genomes, then the attribute
columns:

```text
mRNA.RE04286  Em0019g38a  A1a  #C23D51  0.0000
mRNA.RE14076  Em0019g57a  .    #000000  1.8213
```

## Loading the jellyfish and sponge assemblies

We'll load the two genomes of the dotplot. The genome FASTA needs a `.fai`
beside it (`samtools faidx`), and its sequence names must match the table's
scaffold columns. The stack adds four more assemblies the same way, one block
each.

```json addassembly
{
  "name": "RES",
  "displayName": "Rhopilema (jellyfish)",
  "uri": "RES.fa"
}
```

```json addassembly
{
  "name": "EMU",
  "displayName": "Ephydatia (sponge)",
  "uri": "EMU.fa"
}
```

## Loading the jellyfish-sponge table as a synteny track

`attributeColumns` exposes the last three columns of the `.blocks` file:

- `gene_group` becomes a color-by mode named after it.
- `color` holds the palette odp chose for each group, so the menu leaves it out
  of the modes.
- `break_FET` is odp's test of the row's chromosome pair, which the stack below
  reads as opacity.

```json addtrack
{
  "type": "SyntenyTrack",
  "trackId": "RES_EMU",
  "name": "RES vs EMU orthologs, colored by BCnS linkage group",
  "assemblyNames": ["RES", "EMU"],
  "adapter": {
    "type": "MCScanBlocksAdapter",
    "uri": "RES_EMU.blocks.gz",
    "blockAssemblies": ["RES", "EMU"],
    "bedLocations": ["RES_EMU.RES.bed.gz", "RES_EMU.EMU.bed.gz"],
    "attributeColumns": ["gene_group", "color", "break_FET"]
  }
}
```

The build script adds one such track per pair.

## Dotplot of jellyfish against sponge, colored by linkage group

We'll open the jellyfish-against-sponge table as a dotplot, then:

- Pick **gene_group** under **Color by value** on the palette button in the view
  header. The legend comes up with it.
- Choose **Re-order chromosomes** on the view menu to sort the vertical genome's
  chromosomes by where their orthologs land along the horizontal one, which
  turns one block per group into a diagonal.

As a session, the same dotplot with the sponge's unplaced scaffolds left off its
axis. In [grammar-of-graphics](https://jbrowse.org/jb2/docs/config_guides/mark_display) terms, the
session's `encoding.color` is a color scale, a `field` mapped to colors:

```json session config=https://jbrowse.org/demos/odp_linkage_groups/config.json
{
  "defaultSession": {
    "name": "Ancestral linkage groups",
    "views": [
      {
        "type": "DotplotView",
        "displayName": "Rhopilema (jellyfish) vs Ephydatia (sponge)",
        "views": [
          { "assembly": "RES" },
          { "assembly": "EMU", "displayedRegionNames": ["EMU*"] }
        ],
        "tracks": ["RES_EMU"],
        "encoding": { "color": "gene_group" },
        "autoDiagonalize": true,
        "lineWidth": 4,
        "height": 860
      }
    ]
  }
}
```

<Figure caption="Jellyfish against sponge as a dotplot, each ortholog colored by its linkage group." src="/img/linkage_groups/alg_dotplot_res_emu.png" />

Inside a block the points fill the square, because gene order along each
chromosome has shuffled. Each gene stays on its chromosome.

## Stacking the genomes, ribbons colored by linkage group

Figure 1d of Schultz et al. 2023 stacks the same tables, one row per genome,
with ribbons between neighbours colored by group. A linear synteny view does
that with one pair's track per band. The build script loads the pairs in the
paper's order, two comb jellies over the jellyfish, amphioxus and two sponges,
and the session below sets what the figure needs.

odp tests each pair of chromosomes for more shared orthologs than chance
(Fisher's exact test, corrected for the number of pairs, in the `break_FET`
column). Like the paper's figure, the stack draws orthologs on a chromosome pair
under 0.05 at opacity 0.8 and the rest at 0.15. That is an `encoding.opacity`
scale, which maps the `break_FET` field, cut at 0.05, to a `scale.range` of two
opacities.

Each setting in the session has a menu route except `render` and the
`encoding.opacity` mapping:

- `autoDiagonalize` sorts each row against its neighbour, working outward from
  `diagonalizeAnchorRow`. Rows count from 0, so 2 is the jellyfish, where each
  group sits on one chromosome. **Rows → Re-order chromosomes** on the view menu
  runs the same sort and asks for that row.
- `filter` drops the alignments with no `gene_group`, which **Hide unlabelled
  rows** on the palette menu writes.
- `mark` is **Curved lines** on the sliders button.
- `render.antialias` turns off the fade a whole-genome view applies to sub-pixel
  ribbons, since their colors are what the figure shows. It has no menu item.
- `encoding.opacity` is the scale above. **Opacity** on the sliders button
  scales both opacities together; the mapping itself has no menu item.

```json session config=https://jbrowse.org/demos/odp_linkage_groups/config.json
{
  "defaultSession": {
    "name": "Ancestral linkage groups, six genomes",
    "views": [
      {
        "type": "LinearSyntenyView",
        "displayName": "Comb jellies, jellyfish, amphioxus, sponges",
        "views": [
          { "assembly": "BIN", "displayedRegionNames": ["BIN*"] },
          { "assembly": "HCA", "displayedRegionNames": ["HCA*"] },
          { "assembly": "RES", "displayedRegionNames": ["RES*"] },
          { "assembly": "BFL", "displayedRegionNames": ["BFL*"] },
          { "assembly": "EMU", "displayedRegionNames": ["EMU*"] },
          { "assembly": "CLAa", "displayedRegionNames": ["CLA*_hapA"] }
        ],
        "tracks": [
          ["BIN_HCA"],
          ["RES_HCA"],
          ["RES_BFL"],
          ["BFL_EMU"],
          ["EMU_CLAa"]
        ],
        "encoding": {
          "color": "gene_group",
          "opacity": {
            "field": "break_FET",
            "scale": {
              "type": "threshold",
              "domain": [0.05],
              "range": [0.8, 0.15]
            }
          }
        },
        "filter": [{ "field": "gene_group", "valid": true }],
        "autoDiagonalize": true,
        "diagonalizeAnchorRow": 2,
        "mark": { "interpolate": "bump" },
        "render": { "antialias": false },
        "levelHeights": [130, 130, 130, 130, 130],
        "collapseEmptyRows": true
      }
    ]
  }
}
```

<Figure caption="The genomes in the paper's order, ribbons colored by linkage group, solid on significantly paired chromosomes and faint elsewhere." src="/img/linkage_groups/alg_stack.png" />

Amphioxus and _Ephydatia_ helped build the group database, so the bundles
running through them are expected. The cladorhizid sponge took no part, and in
the bottom band the groups still run to it as bundles. The second band is mostly
faint because _Hormiphora_ spreads each group over several chromosomes, none
holding even half of it.

## Reproduce it end to end

Download `genomes.tar.gz` and `supplementary_information.tar.gz` from
[the Dryad page](https://datadryad.org/dataset/doi:10.5061/dryad.dncjsxm47) into
`~/Downloads` first, since Dryad has no direct download URL. The script needs
the tools under [Prerequisites](#prerequisites) and works in three steps:

1. Unpack the genomes and pair tables the page uses from the two tarballs, and
   fetch the _Ephydatia_ assembly, which the deposit does not redistribute, from
   its original host.
2. Convert each pair's odp table into a `.blocks` table and two BEDs, taking
   each gene's extent from the `.chrom` files and keeping the group, color and
   `break_FET` columns.
3. Write the assemblies, one track per pair, and the dotplot session.

```bash
curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/build_odp_linkage_groups_synteny.sh
DRYAD_DIR=~/Downloads bash build_odp_linkage_groups_synteny.sh
```

For your own genomes, point the conversion at the tables odp writes under
`synteny_analysis/step2-figures/synteny_coloredby_BCnS_LGs/`.

## See also

- **Tutorial:** [Synteny from an ortholog table (grape, peach, cacao)](https://jbrowse.org/jb2/docs/tutorials/multiway_synteny_grape_peach_cacao)
- **Tutorial:** [Synteny visualization (OrthoFinder orthogroups)](https://jbrowse.org/jb2/docs/tutorials/orthofinder_synteny)
- **Tutorial:** [Pangenome (HPRC) part 2: haplotypes against each other](https://jbrowse.org/jb2/docs/tutorials/pangenome_hprc_haplotypes)
- **User guide:** [Linear synteny view](https://jbrowse.org/jb2/docs/user_guides/linear_synteny_view)

## External links

- odp, the oxford dot plot toolkit: https://github.com/conchoecia/odp

## Citations

- Schultz et al. (2023).
  [Ancient gene linkages support ctenophores as sister to other animals](https://doi.org/10.1038/s41586-023-05936-6)
- Simakov et al. (2022).
  [Deeply conserved synteny and the evolution of metazoan chromosomes](https://doi.org/10.1126/sciadv.abi5884)