Skip to content

Make the home page look finished below the fold #52

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Paururo merged 4 commits into from
Aug 30, 2026
Merged

Make the home page look finished below the fold #52

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
22979d0
Show the figures on the home page instead of counting them
Paururo Aug 30, 2026
65be512
End the home page rather than letting it run out
Paururo Aug 30, 2026
c78fa4a
Give the landing page a gutter it keeps on a phone
Paururo Aug 30, 2026
ecf5dee
Say in the closing block only what the footer does not
Paururo Aug 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
124 changes: 102 additions & 22 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -349,23 +349,52 @@ stack. A phylogeny is a track and so are its sample traits. A circular
chromosome and a world map are containers of their own, because a sequence with
no ends cannot be drawn as a line without inventing one.

<div class="track-gallery">
<a class="track-card" href="plots/reads-molecules/">
<img src="assets/figures/example-pileup.svg" alt="A read pileup with mismatches, insertions, deletions and spliced alignments" width="920" height="474" loading="lazy">
<span><strong>Reads</strong><small>Pileups and single molecules</small></span>
</a>
<a class="track-card" href="plots/annotation-coordinates/">
<img src="assets/figures/example-ideogram.svg" alt="A chromosome ideogram with its bands and a highlighted region" width="900" height="276" loading="lazy">
<span><strong>Annotation</strong><small>Ideograms, genes and coordinates</small></span>
</a>
<a class="track-card" href="plots/variation-association/">
<img src="assets/figures/example-association.svg" alt="Association statistics above a genotype matrix" width="940" height="349" loading="lazy">
<span><strong>Variation</strong><small>Association scans and genotypes</small></span>
</a>
<a class="track-card" href="plots/comparisons-alignments/">
<img src="assets/figures/example-synteny.svg" alt="A dotplot with synteny ribbons between two genomes" width="900" height="438" loading="lazy">
<span><strong>Comparisons</strong><small>Dotplots, synteny and alignments</small></span>
</a>
<a class="track-card" href="plots/phylogeny-clades/">
<img src="assets/figures/example-phylo-layouts.svg" alt="The same phylogeny drawn rectangular, circular and unrooted" width="1402" height="1232" loading="lazy">
<span><strong>Phylogeny</strong><small>Three projections of one tree</small></span>
</a>
<a class="track-card" href="plots/signal-sequence/">
<img src="assets/figures/example-methylation.svg" alt="Methylation calls across the origin of replication" width="880" height="198" loading="lazy">
<span><strong>Signal</strong><small>Coverage, methylation and squiggles</small></span>
</a>
<a class="track-card" href="plots/evolution-surveillance/">
<img src="assets/figures/example-circular.svg" alt="A circular chromosome with its rings" width="688" height="688" loading="lazy">
<span><strong>Circular</strong><small>Sequences with no ends</small></span>
</a>
<a class="track-card" href="plots/">
<img src="assets/figures/example-maps.svg" alt="Cases drawn on a world map beside a phylogeny" width="1402" height="974" loading="lazy">
<span><strong>Maps</strong><small>Where the samples came from</small></span>
</a>
</div>

<details class="track-overview">
<summary>Thirty-six track types, twenty-two panels, one sheet</summary>
<summary>All thirty-six on one sheet</summary>
<img src="assets/figures/gallery.svg" loading="lazy" alt="A gallery of genomic plots on one sheet of twenty-two panels in three columns: a genomic stack, a read pileup, sequence logos, association statistics with a genotype matrix, a dotplot and synteny ribbons, a multiple sequence alignment, variable sites with a phylogeny, a tree, windowed statistics read against a baseline, a circular chromosome, raw nanopore signal, one locus compared across three genomes, Dam methylation across the E. coli origin of replication, an association scan across a whole draft assembly, structural variants as arcs between their breakpoints, the six reading frames, two trees face to face, a human imprinting control region read one molecule at a time, a coding sequence ruled in codons, one molecule aligned in three pieces, SARS-CoV-2 lineage deletions painted onto a phylogeny, and transcription units from start site to terminator" width="3472" height="1908">
</details>

Twenty-eight of the thirty-six are reachable from the command line. Twenty-seven
of those have a file to read; the twenty-eighth is the coordinate ruler, which
needs none. Trees drawn with metadata, maps and the selection views are
library only. Where the library ends and the command begins is worth saying out
loud, because it is the boundary readers walk into.

The count is thirty-six because three were removed. Every track has to answer
one question, *does drawing it read the shared scale*, and three that could not
were taken out rather than kept for the sake of a longer list.
Twenty-eight of the thirty-six are reachable from the command line; the rest are
library only, which is a boundary worth saying out loud because it is the one
readers walk into. The count is thirty-six because three were removed: every
track has to answer *does drawing it read the shared scale*, and three that
could not were taken out rather than kept for the sake of a longer list.
[Extending](how-it-works/extending.md) has that test and what a new track owes.
A library that says what it threw out is easier to believe than one that says
how much it has.

</section>

Expand All @@ -377,12 +406,59 @@ Several tracks encode a claim rather than a picture, and what they do when the
data does not support the claim is what makes them worth having. The refusals
are the interesting part.

<ul class="k-refusal-list" markdown>
<li markdown>A tanglegram is two phylogenies. Handed one file it would draw the tree against itself, which has no crossings, and no crossings is what a perfect result looks like. So it is refused by name: `karyon: a tanglegram track is drawn from two files, and --against names the second`. The two other tracks that take a second file are refused the same way.</li>
<li markdown>A homology join that matched nothing would draw every gene in every genome outlined as having no counterpart, which reads as a discovery. It is refused instead, and the message names the first gene that found no match, since the names in a search result and the names in an annotation are routinely not the same strings.</li>
<li markdown>`--identity` says whether a column is a percentage or a fraction. Left out it is worked out from the values, and a file whose values are all at or below one could be either, so it is refused by name rather than guessed at. Read the wrong way round, every ribbon in the figure becomes a perfect match and nothing fails.</li>
<li markdown>Nought reads is not nought per cent. `modkit` writes a row for a position it could not call, with nought in every count, and passed through that is a mark on the baseline saying the cytosine is unmodified, which is a measurement. The position was not measured. Those rows are skipped and counted.</li>
</ul>
<div class="k-block-grid k-refusals-grid" markdown>

<div class="k-block" markdown>

### A tanglegram is two trees

<p class="k-claim"><code>a tanglegram track is drawn from two files, and --against names the second</code></p>

Handed one file it would draw the tree against itself, which has no crossings,
and no crossings is what a perfect result looks like. The two other tracks that
take a second file are refused the same way.

</div>

<div class="k-block" markdown>

### A join that matched nothing

<p class="k-claim">names the first gene that found no match</p>

A homology join with no hits would outline every gene in every genome as having
no counterpart, which reads as a discovery. The names in a search result and the
names in an annotation are routinely not the same strings, so it says which one
it looked for.

</div>

<div class="k-block" markdown>

### A scale it cannot infer

<p class="k-claim"><code>--identity</code> says whether a column is a percentage or a fraction</p>

Left out it is worked out from the values, and a file whose values are all at or
below one could be either. Read the wrong way round, every ribbon in the figure
becomes a perfect match and nothing fails, so it is refused by name rather than
guessed at.

</div>

<div class="k-block" markdown>

### Nought reads is not nought per cent

<p class="k-claim">skipped, and counted</p>

`modkit` writes a row for a position it could not call, with nought in every
count. Passed through, that is a mark on the baseline saying the cytosine is
unmodified, which is a measurement. The position was not measured.

</div>

</div>

All four are the same bug, and it has a name here: **a value given for the
absence of a value**. It is the class this crate is written against, and it is
Expand Down Expand Up @@ -532,10 +608,14 @@ when a figure leans on them.
</ul>

[Citation](about/citation.md) has the whole list, the specifications behind
every format the readers take included. Written by **Paula Ruiz-Rodriguez** and
**Mireia Coscolla**, I²SysBio, University of Valencia-CSIC, FISABIO Joint
Research Unit Infection and Public Health, Valencia, Spain. Released under
[MIT](https://github.com/PathoGenOmics-Lab/karyon/blob/main/LICENSE).
every format the readers take included.

<div class="k-colophon" markdown>

Built at I²SysBio, University of Valencia-CSIC, and the FISABIO Joint Research
Unit Infection and Public Health, Valencia, Spain.

</div>

</section>

Expand Down
45 changes: 38 additions & 7 deletions docs/stylesheets/landing.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,11 @@
.md-content__inner:has(.k-hero) {
max-width: 62rem;
margin-inline: auto;
/* A floor under the gutter. `margin-inline: auto` wins over Material's own
side margin and resolves to nothing on a narrow screen, so without this
every paragraph, heading and card on the page sat flush against both
bezels of a phone. */
padding-inline: 0.8rem;
}

/* -------------------------------------------------------------------------
Expand Down Expand Up @@ -536,13 +541,15 @@
The refusals and the shelf
------------------------------------------------------------------------- */

.md-typeset .k-refusal-list {
padding-left: 1.1rem;
}

.md-typeset .k-refusal-list > li {
margin-bottom: 0.6rem;
line-height: 1.65;
/* The four refusals were a bulleted list of dense paragraphs directly under a
section built out of blocks, which made the page look as though it had given
up halfway down. They are the same kind of thing as the pieces above them, so
they are set the same way. */
.md-typeset .k-refusals-grid .k-claim code {
font-size: 0.72rem;
background: none;
padding: 0;
color: inherit;
}

.md-typeset .k-shelf {
Expand Down Expand Up @@ -607,6 +614,30 @@
line-height: 1.55;
}

/* The page used to end by running out: the last thing on it was one paragraph
with the citation link, the authors, two institutions and the licence run
together. A closing block is not more of the page, it is the page saying it
has finished. It carries only what the footer underneath does not, which is
where the work was done: the footer already gives the authors and the
licence, and saying either of them twice two lines apart is worse than not
closing the page at all. */
.md-typeset .k-colophon {
margin: 2rem 0 0;
padding-top: 1.1rem;
border-top: 1px solid var(--md-default-fg-color--lighter);
}

.md-typeset .k-colophon p {
margin: 0 0 0.35rem;
color: var(--md-default-fg-color--light);
font-size: 0.72rem;
line-height: 1.6;
}

.md-typeset .k-colophon p:last-child {
margin-bottom: 0;
}

/* -------------------------------------------------------------------------
Narrow pages
------------------------------------------------------------------------- */
Expand Down