This is the second part of our task to plot a timeline. You need to begin with a working timeline plotted with hashtags and text (and other elements) marking each year. Your timeline does not need to look exactly like ours (posted here), and you may style it differently, skew it so it isn’t vertical, experiment with its dimensions, plot other shapes besides circles, etc. If you did not succeed with plotting your timeline in the first exercise. be sure to review our posted solution on the DHClass-Hub and make the necessary adjustments to your code before you begin this exercise.

We continue to work with our Digital Mitford collection of TEI-encoded letters in our eXist database: collection('/db/mitford/letters'). After the first exercise, we’ll have plotted the line on the left with the circles (or your variation on this) inside to record comparative counts of letters per year. You will also have created and saved your work in the eXist database to view it in a browser.

Our task

With part 2 of this assignment, we want to plot a span of time when Mitford corresponded with the artist Benjamin Robert Haydon, based on the letters we have encoded in our eXist database. We do not actually have firm dates for this correspondence yet until we have coded more letters, but we can at least plot a timeline based on what we know from the letters currently in the database. To write good XQuery that we can use in the future, it is best if we write variables that will always retrieve the earliest and latest dates, whatever they are. And of course, once we plot this graphic for one historic person in our project, we can continue with plotting dates for other people as well, just by altering the variable that identifies a person Mitford corresponded with. For now, our immediate task is to plot and label one timespan, and if we can code this to represent the letters to Benjamin Haydon, we can apply the same code to anyone else we care to look up. Here is a sample output to give you an idea of what we are trying to produce: this is a plot of a time-span.

Work within the XQuery script that produced your timeline for the first part of this exercise. You will be adding to it to plot a second, shorter line next to the first one you drew, and positioned so that its dates align with the dates on the original timeline. You can label this line to identify Haydon, and output the dates of the first and last letter we have in the collection addressed to him, at the top and bottom of your new line. To begin, here are two global variables that will locate the letters to Haydon and their dates (formatted as yyyy-mm-dd in the TEI headers of our files:

declare variable $HaydonLetters := $letterFiles[descendant::tei:titleStmt/tei:title/tei:persName/@ref="#Haydon"];
declare variable $HaydonDates :=$HaydonLetters//tei:teiHeader//tei:msDesc//tei:head/tei:date/@when/string();

Thinking about how to code the new line

The challenge in this assignment involves the need to convert dates in yyyy-mm-dd format into simpler numbers that we can use to plot our lines. In the previous assignment, we did that step-by-step, thus:

  1. We retrieved only the years in the collection: Tokenize the date, and take only the yyyy part of it, as the first token before the hyphen (-).
  2. We used the max() and min() functions, and subtracted the minumum (or earliest) year from the maximum (or latest) year, to give us a variable holding a simple number of years that represents how long a period is represented in our database of letters. We used that number multiplied by 365 to help measure out and plot our line.
  3. After that we worked inside the time span, divided it with a for loop into a set of integers, so that for each unit year in the span of years, we output a hashmark, as well as a circle (or other shape), and some text elements to help label the timeline.

Here our goal, in a way, is comparatively simple. Do we need to write this within a for loop? We considered this when we first experimented with with this plot, and soon realized that was not what we needed to do. We are not outputting anything per unit year this time. We are simply marking a single span of years, but we do need to plot it so it aligns with our master timeline, so that if the first Haydon letter is dated, say, on February 13, 1819, our line should begin at just the right point for February 13 in our lineup of 365 days (pixels) in between each year.

Because each year on our plot is divided from the others by 365 pixels, we created room for ourselves to plot things with specific dates in the midranges. How do we do that? We need to work with date functions and take our full dates more seriously than we did in the first assignment. We need to actually begin plotting from the "y" location that corresponds to the specific day of the year of the minimum (earliest) and maximum (latest) letter from Mitford to Haydon.

Of course you will begin by declaring some new global variables that will identify the earliest and latest letter to Haydon, and convert those values into integers (with xs:integer). But then we will need to do something new:

  1. Calculate where the year should be positioned in relation to the master timeline. We did this by subtracting the minimum year of the main timeline from the minimum year of the Haydon line and multiplying by 365. That will give us the literal distance in SVG coordinates (or pixels) from the starting point of the master timeline to begin plotting the Haydon line, but it will only give us the year, so we need something more.
  2. Since we spaced 365 pixels between each date, we now can use that information. If we have converted the minimum start year to a position in our SVG coordinate system, we would need to add to it the number of days from the start of the year. There is an XPath function for that, which you may have seen before in a homework exercise in this course: format-date(). Read about this in the Michael Kay book, pp. 781-788 or online from the WWW consortium here. (At the time Kay wrote his book, this function was not available in XQuery but it is now!) There are so many different ways to format dates, but one of them, just the one we need, tells you how to output the number of a day in a 365-day year (so that for February 15, it will output 46, as it is the 46th day of a 365-day year, and for 23 March, it will output the number 83, for the 83rd day of the year). Be careful to write this unusual function correctly with its distinctive picture string argument inside single quotes and square brackets, like this: 
    format-date($yourDateVariable, '[?]')
    We discovered that we need to convert that date to an integer in order to use it for calculation later, since it output a number formatted as a string.
  3. Calculate a value to plot on the SVG to represent (the earliest year point) + (the day of the year), each part of which must be converted at some point into integers.
  4. Do the same to calculate the latest date.
  5. Plot your SVG line with the appropriate coordinates to start and end it, based on the variables you have calculated. Position it in your code (and in the output) so it is plotted right next to your main timeline, so we can see how the Haydon correspondence sits in relationship to all of the correspondence. Label it with SVG text elements.

Voila! You have prepared a timeline and learned how to convert dates into points on graphics in SVG coordinate space! Copy and paste your XQuery code into a text file, name it according to our standard homework conventions, and upload it to Courseweb.