From 3f82f5e553939a0baf188666d01b81c891e91e12 Mon Sep 17 00:00:00 2001 From: Thomas Sibley Date: Tue, 16 Jan 2024 16:38:37 -0800 Subject: [PATCH 1/5] =?UTF-8?q?guides/versions:=20Correct=20wont=20?= =?UTF-8?q?=E2=86=92=20won't=20typo?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/guides/versions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/guides/versions.rst b/src/guides/versions.rst index 6b6b3c6c..96f01286 100644 --- a/src/guides/versions.rst +++ b/src/guides/versions.rst @@ -100,7 +100,7 @@ able to provide this functionality. When files are "deleted" from a versioned bucket, the normal behaviour is to preserve the file but add a `delete marker `__. When looking back at versions over time, we interpret the intended behaviour of -a delete marker as removing the then-latest file from history, so it wont be +a delete marker as removing the then-latest file from history, so it won't be available via any ``@YYYY-MM-DD`` value. .. image:: ../images/delete-markers.png From fc9bf3ee59022401148717c0b0188871d6e9dd89 Mon Sep 17 00:00:00 2001 From: Thomas Sibley Date: Tue, 16 Jan 2024 16:38:59 -0800 Subject: [PATCH 2/5] guides/versions: Drop leading / from dataset path/name to be internally-consistent --- src/guides/versions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/guides/versions.rst b/src/guides/versions.rst index 96f01286..e7f7c83f 100644 --- a/src/guides/versions.rst +++ b/src/guides/versions.rst @@ -110,7 +110,7 @@ What about if the URL changed over time? ---------------------------------------- We've often changed the URL which (core) datasets appear at, for instance we -recently changed the URL for `/dengue/denv1 +recently changed the URL for `dengue/denv1 `__ to `dengue/denv1/genome `__, with the former now redirecting to the latter. The result of this is that the earliest available From 354cfb99662a4bd826895f56f047196902ab1c1b Mon Sep 17 00:00:00 2001 From: Thomas Sibley Date: Tue, 16 Jan 2024 16:40:04 -0800 Subject: [PATCH 3/5] guides/versions: Move up higher in the TOC and thus sidebar This "Viewing previous versions" guide seems worth being more prominent than managing an installation or contributing guides. I also think this is more of an explanatory document than how-to guide, which suggests it belongs under our "About" section instead, but I'll discuss that with the team first. --- src/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/index.rst b/src/index.rst index 0f2b7dcf..68d1dad4 100644 --- a/src/index.rst +++ b/src/index.rst @@ -68,9 +68,9 @@ team and other Nextstrain users provide assistance. For private inquiries, Bioinformatics Sharing analyses Communicating scientific insights + Viewing previous versions Managing an installation Contributing - Viewing previous versions .. toctree:: :maxdepth: 1 From ed13d925b2034ac43a3e1bd87f700a96ab5dbb5d Mon Sep 17 00:00:00 2001 From: Thomas Sibley Date: Tue, 16 Jan 2024 16:55:43 -0800 Subject: [PATCH 4/5] guides/versions: Use "snapshots" (instead of "versions") and "analyses" MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The document already used the term "snapshot" a bit, and I think it's less ambiguous/overloaded than "version" so use it consistently. "Analyses" is already in use in other document and section titles, so use that term in those contexts. I didn't update the source document file names here, but maybe I should… --- src/guides/versions.rst | 16 ++++++++-------- src/index.rst | 2 +- src/learn/about.rst | 4 ++-- 3 files changed, 11 insertions(+), 11 deletions(-) diff --git a/src/guides/versions.rst b/src/guides/versions.rst index e7f7c83f..ea192ac3 100644 --- a/src/guides/versions.rst +++ b/src/guides/versions.rst @@ -1,6 +1,6 @@ -================================= -Viewing previous versions of data -================================= +========================= +Viewing previous analyses +========================= .. contents:: Sections in this document @@ -36,7 +36,7 @@ will load the dataset that was the latest available at that particular date. Tanglegrams to compare changes ------------------------------ -Using tanglegrams allows us to easily view two different versions of the same +Using tanglegrams allows us to easily view two different snapshots of the same dataset side-by-side. Using the above examples we can view the latest dataset against the one from the middle of 2023 via the URL `flu/seasonal/h3n2/ha/6y:flu/seasonal/h3n2/ha/6y@2023-07-01 @@ -48,7 +48,7 @@ expansion of clade 2a.3a.1 over the past 6 months: :alt: Tanglegram of flu/seasonal/h3n2/ha/6y:flu/seasonal/h3n2/ha/6y@2023-07-01 Over time, the data shown by this URL link will start to change as we update the -latest version, but by versioning both datasets we can preserve this exact view +latest snapshot, but by dating both datasets we can preserve this exact view into the data: `flu/seasonal/h3n2/ha/6y@2024-01-03:flu/seasonal/h3n2/ha/6y@2023-07-01 `__. @@ -57,7 +57,7 @@ into the data: SARS-CoV-2 datestamped datasets ------------------------------- -Prior to the functionality described here we exposed dated versions of some of +Prior to the functionality described here we exposed dated snapshots of some of our datasets by including the YYYY-MM-DD in the URL without the ``@`` character, i.e. the date string was part of the dataset name. This functionality is now superseded by the new URL syntax described here, and we may stop producing these @@ -117,7 +117,7 @@ to the latter. The result of this is that the earliest available ``dengue/denv1/genome`` dataset is from 2024-01-03, despite DENV1 datasets being available since January 2019. -We have plans to expose these versions - see `this issue +We have plans to expose these snapshots - see `this issue `__ for progress here. @@ -139,6 +139,6 @@ meta+tree JSONs in the case of v1 datasets). How far back does this go? -------------------------- -The oldest versioned dataset `is a H3N2 dataset from August 2018 +The oldest dataset snapshot `is a H3N2 dataset from August 2018 `__. While Nextstrain datasets existed before then, we didn't have versioning enabled. diff --git a/src/index.rst b/src/index.rst index 68d1dad4..82013a20 100644 --- a/src/index.rst +++ b/src/index.rst @@ -68,7 +68,7 @@ team and other Nextstrain users provide assistance. For private inquiries, Bioinformatics Sharing analyses Communicating scientific insights - Viewing previous versions + Viewing previous analyses Managing an installation Contributing diff --git a/src/learn/about.rst b/src/learn/about.rst index 88f61b47..0f8580d3 100644 --- a/src/learn/about.rst +++ b/src/learn/about.rst @@ -25,8 +25,8 @@ snapshots of evolving pathogen populations such as `SARS-CoV-2 We use interactive visualizations to enable exploration of curated datasets and analyses which are continually updated when new genomes are available. This offers a powerful pathogen surveillance tool to virologists, epidemiologists, -public health officials, and community scientists. In many cases old versions of -these analyses are able to be easily accessed, see :doc:`viewing previous versions +public health officials, and community scientists. In many cases old snapshots of +these analyses are able to be easily accessed, see :doc:`viewing previous analyses ` for more. .. rubric:: Open-source software From 528c9a31d181f3c036c0e16a63cf4e38513d979c Mon Sep 17 00:00:00 2001 From: Thomas Sibley Date: Tue, 16 Jan 2024 17:06:04 -0800 Subject: [PATCH 5/5] =?UTF-8?q?guides/versions=20=E2=86=92=20guides/snapsh?= =?UTF-8?q?ots:=20Update=20source=20paths=20to=20match=20document=20terms?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- redirects.yml | 4 ++++ src/guides/{versions.rst => snapshots.rst} | 4 ++-- ...ete-markers.png => snapshots-delete-markers.png} | Bin ...egram-h3n2.jpg => snapshots-tanglegram-h3n2.jpg} | Bin src/index.rst | 2 +- src/learn/about.rst | 2 +- 6 files changed, 8 insertions(+), 4 deletions(-) rename src/guides/{versions.rst => snapshots.rst} (98%) rename src/images/{delete-markers.png => snapshots-delete-markers.png} (100%) rename src/images/{versions-tanglegram-h3n2.jpg => snapshots-tanglegram-h3n2.jpg} (100%) diff --git a/redirects.yml b/redirects.yml index 7c8798ea..59be9d20 100644 --- a/redirects.yml +++ b/redirects.yml @@ -190,3 +190,7 @@ - type: page from_url: /reference/style.html to_url: /reference/documentation-style-guide.html + +- type: page + from_url: /guides/versions.html + to_url: /guides/snapshots.html diff --git a/src/guides/versions.rst b/src/guides/snapshots.rst similarity index 98% rename from src/guides/versions.rst rename to src/guides/snapshots.rst index ea192ac3..da0c3758 100644 --- a/src/guides/versions.rst +++ b/src/guides/snapshots.rst @@ -44,7 +44,7 @@ against the one from the middle of 2023 via the URL Here's a screenshot of this taken in early January 2024, allowing us to see the expansion of clade 2a.3a.1 over the past 6 months: -.. image:: ../images/versions-tanglegram-h3n2.jpg +.. image:: ../images/snapshots-tanglegram-h3n2.jpg :alt: Tanglegram of flu/seasonal/h3n2/ha/6y:flu/seasonal/h3n2/ha/6y@2023-07-01 Over time, the data shown by this URL link will start to change as we update the @@ -103,7 +103,7 @@ When looking back at versions over time, we interpret the intended behaviour of a delete marker as removing the then-latest file from history, so it won't be available via any ``@YYYY-MM-DD`` value. -.. image:: ../images/delete-markers.png +.. image:: ../images/snapshots-delete-markers.png What about if the URL changed over time? diff --git a/src/images/delete-markers.png b/src/images/snapshots-delete-markers.png similarity index 100% rename from src/images/delete-markers.png rename to src/images/snapshots-delete-markers.png diff --git a/src/images/versions-tanglegram-h3n2.jpg b/src/images/snapshots-tanglegram-h3n2.jpg similarity index 100% rename from src/images/versions-tanglegram-h3n2.jpg rename to src/images/snapshots-tanglegram-h3n2.jpg diff --git a/src/index.rst b/src/index.rst index 82013a20..42f4f74e 100644 --- a/src/index.rst +++ b/src/index.rst @@ -68,7 +68,7 @@ team and other Nextstrain users provide assistance. For private inquiries, Bioinformatics Sharing analyses Communicating scientific insights - Viewing previous analyses + Viewing previous analyses Managing an installation Contributing diff --git a/src/learn/about.rst b/src/learn/about.rst index 0f8580d3..7fcfab03 100644 --- a/src/learn/about.rst +++ b/src/learn/about.rst @@ -27,7 +27,7 @@ analyses which are continually updated when new genomes are available. This offers a powerful pathogen surveillance tool to virologists, epidemiologists, public health officials, and community scientists. In many cases old snapshots of these analyses are able to be easily accessed, see :doc:`viewing previous analyses -` for more. +` for more. .. rubric:: Open-source software