Analysing Solar Eclipse Frequency with a Galaxy Workflow

Author(s) Rita Gautschy avatar Rita Gautschy
Data Provider(s) DaSCH - Swiss National Data and Service Center for the Humanities avatar DaSCH
Tester(s) orcid logoDaniela Schneider avatar Daniela Schneider
Reviewer(s) Saskia Hiltemann avatarDaniela Schneider avatar
Infrastructure Galaxy Switzerland avatar Galaxy SwissDaSCH - Swiss National Data and Service Center for the Humanities avatar DaSCH
Overview
Creative Commons License: CC-BY Questions:
  • How can we identify groups of solar eclipses above a user-defined observable magnitude within a specified time interval?

  • How can runtime parameters make the analysis reusable and reproducible?

Objectives:
  • Import a pre-calculated solar-eclipse dataset into Galaxy.

  • Convert a text file to tab-separated tabular data.

  • Split the eclipse magnitude and time of maximum eclipse fields into observable (mag1 / Tmax1) and theoretical (mag2 / Tmax2) magnitudes.

  • Filter eclipses using a user-defined minimum observable magnitude.

  • Sort eclipse records chronologically.

  • Identify groups of N consecutive eclipses occurring within a user-defined maximum number of years.

  • Remove duplicate eclipse records while retaining one occurrence of each eclipse.

  • Run the analysis reproducibly with workflow parameters.

Requirements:
Time estimation: 45 minutes
Level: Intermediate Intermediate
Supporting Materials:
Published: Sep 21, 2026
Last modification: Sep 21, 2026
License: Tutorial content is licensed under Creative Commons Attribution 4.0 International License. The GTN framework is licensed under MIT
version Revision: 1

Ancient sources contain numerous astronomical observations that can be used to establish absolute dates. Solar eclipses are particularly important in this context. In antiquity, eclipses were often perceived as a threat and bad omen, causing fear and potentially political disturbances. By far not every partial solar eclipse has been noticed by an unprepared observer. Changes in ambient illumination remain relatively inconspicuous until a large part of the solar disk is covered. Even when about three quarters of the Sun’s area is obscured, the reduction in daylight may still pass largely unnoticed with the most dramatic changes in illumination occuring only during the very deep partial phases close to totality. Historical visibility must be understood primarily in terms of the conspicuous environmental effects of a deep eclipse—diminished and altered daylight, unusual shadows, and, near totality, a pronounced twilight-like appearance. These facts make eclipses of high magnitude particularly relevant when considering events that could have attracted widespread attention without advance knowledge of the phenomenon. A series of such high magnitude solar eclipses at a certain location within a limited number of years is a rare phenomenon. Such eclipse series have been interpreted to being the cause of political disturbances.

This tutorial will show you how to identify such sequences of notable eclipses step-by-step based on pre-calculated tables which are available for the following locations relevant for classical antiquity: Alexandria, Amarna, Assur, Athens, Babylon, Jerusalem, Knossos, Mari, Memphis, Rome, and Thebes. The data are deposited in DaSCH’s repository DSP (Gautschy). The dataset contains calculations of notable solar eclipses for the period between 2500 BCE and 1000 CE. It is a solar eclipse canon with identifications of the eclipses recorded in historical sources. Gautschy 2012 discusses two examples of the solar eclipse canon’s application. If you want to know more about the basics of eclipses, Gautschy provides an introduction to eclipse geometry and the underlying calculations.

Agenda

In this tutorial, we will cover:

  1. Analysing Solar Eclipse Frequency with a Galaxy Workflow
    1. The input data
    2. Analysis overview
  2. Step-by-step Analysis
    1. Step 1: Import the eclipse data
    2. Step 2: Convert the text file to tabular data
    3. Step 3: Separate observable and theoretical magnitude
    4. Step 4: Select eclipses above the magnitude threshold
    5. Step 5: Sort the eclipses chronologically
    6. Step 6: Find groups of eclipses
    7. Step 7: Sort chronologically
    8. Step 8: Remove duplicate eclipse rows
    9. Step 9: Sort the final result
  3. Run the analysis as a workflow
    1. Interpreting the result
    2. Explore the parameters
    3. Why use a Galaxy workflow?
  4. Conclusion

Analysing Solar Eclipse Frequency with a Galaxy Workflow

Solar eclipses can be relevant to historical and chronological investigations. For example, one may ask whether several conspicuous eclipses occurred within a relatively short period of time. In antiquity, eclipses were often perceived as a bad omen, as signs of the dissatisfaction of the gods with a ruler. Therefore, an unusual sequence of remarkable eclipses could have had drastic consequences.

In this tutorial, we use pre-calculated solar-eclipse data and a Galaxy workflow to answer a configurable question:

Which eclipses with an observable magnitude at or above a chosen threshold belong to a group of N consecutive eclipses occurring within at most X years?

The published workflow is parameterised. Instead of fixing a particular threshold, number of eclipses, or time interval in the workflow, you can supply these values at runtime.

The input data

The source data are pre-calculated lists of solar eclipses for locations relevant to classical antiquity, covering 2500 BCE to 1000 CE available in DaSCH’s DSP repository. Files can be fetched from DSP or first downloaded there and uploaded from the local computer.

Examples of suitable input files are:

Input files are expected to have the following structure:

Y M D Type deltaT mag Tbeg Tmax Tend SR SS

The original text file contains the following columns:

Column Meaning
Y Year
M Month
D Day
Type Eclipse type
deltaT Delta T
mag Two magnitude values separated by /
Tbeg Start time
Tmax Two times of maximum eclipse values separated by /
Tend End time
SR Local time of sunrise
SS Local time of sunset

The mag and Tmax fields contain two values. This workflow separates the two mag and Tmax values into:

  • mag1: the maximum magnitude actually observable at the selected location.
  • mag2: the theoretical maximum magnitude; the Sun may still or already be below the horizon when this value is reached.
  • Tmax1: time when maximum magnitude actually observable at the selected location occurs.
  • Tmax2: time of theoretical maximum magnitude; the Sun may still or already be below the horizon at this point in time.

For this analysis, mag1 is the relevant magnitude. Tmax1 and Tmax2 are not used further.

Relevant columns for the workflow are:

  • Column 1: Y(year; years are in astronomical notation including a historically non-existent year 0, year -1919 corresponds to 1920 BCE)
  • Column 2: M (month)
  • Column 3: D (day)
  • Column 6: mag (maximum magnitude of the solar eclipse)

Analysis overview

This analysis consists of nine processing stages:

  1. Upload / import the eclipse data.
  2. Convert the original text file to tab-separated data.
  3. Split mag and Tmax into mag1, mag2, Tmax1 and Tmax2.
  4. Select eclipses whose observable magnitude meets the user-defined threshold.
  5. Sort the selected eclipses chronologically.
  6. Find groups of N consecutive eclipses occurring within X years.
  7. Sort the eclipses chronologically.
  8. Remove duplicate eclipse rows while retaining one occurrence.
  9. Sort the final result chronologically.
Visulisation of the workflow. Open image in new tab

Figure 1: Visulisation of the workflow

Step-by-step Analysis

In the next sections, we will walk you through this analysis step by step.

In the final section, we will show you how you can speed up this analysis by using the workflow.

Step 1: Import the eclipse data

You can upload data in various ways. Here are some examples:

Hands On: Data Upload
  1. Create a new history for this tutorial

    To create a new history simply click the new-history icon at the top of the history panel:

    UI for creating new history

  2. Import the desired .txt eclipse file from your local computer, or retrieve it directly from the DaSCH repository:

    https://ingest.dasch.swiss/projects/0868/assets/0V3H7UR6naZ-rOIyKnuP8An/original
    

    As an alternative to uploading the data from a URL or your computer, the files may also have been made available from a shared data library:

    1. Go into Libraries (left panel)
    2. Navigate to the correct folder as indicated by your instructor.
      • On most Galaxies tutorial data will be provided in a folder named GTN - Material –> Topic Name -> Tutorial Name.
    3. Select the desired files
    4. Click on Add to History galaxy-dropdown near the top and select as Datasets from the dropdown menu
    5. In the pop-up window, choose

      • “Select history”: the history you want to import the data to (or create a new one)
    6. Click on Import

    • Copy the link location
    • Click galaxy-upload Upload at the top of the activity panel

    • Select galaxy-wf-edit Paste/Fetch Data
    • Paste the link(s) into the text field

    • Press Start

    • Close the window

    Galaxy upload link

Be sure to choose a source file whose pre-calculated lower magnitude limit does not exclude eclipses you want to investigate. For example, a study threshold of 0.85 requires a source list calculated with a threshold of 0.8 or lower.

Once you click start, your upload should begin. It will first turn orange while in progress, then turn green once it is successfully uploaded. After this step you should have one file in your History.

Step 2: Convert the text file to tabular data

The original .txt file is converted into a tab-separated format suitable for subsequent Galaxy tools by changing the spaces/whitespaces to tabs. The output is a tabular dataset.

Hands On: Convert the file
  1. Convert delimiters to TAB with the following parameters:
    • param-file “Convert all”: Whitespaces
    • “in Dataset”: origin (Input dataset) tool
  2. Click “Run Tool”.

    Comment:

    The original .txt file is converted into a tab-separated format suitable for subsequent Galaxy tools by changing the spaces/whitespaces to tabs. The output is a tabular dataset.

Step 3: Separate observable and theoretical magnitude

The original mag and Tmax columns contain two values separated by /. A [Replace text] step splits the mag field and creates the columns mag1 and mag2. The two Tmax values correspond to the two mag values, they are split as well, but not used further during the workflow.

Hands On: Separate observable and theoretical magnitude
  1. Replace Text in entire line ( Galaxy version 9.5+galaxy3) with the following parameters:
    • param-file “File to process”: Convert on dataset 1 (output of Convert delimiters to TAB tool)
    • In “Replacement”:
      • param-repeat “Replacement”
        • “Find pattern”: mag
        • “Replace with:”: mag1\tmag2
      • param-repeat “Insert Replacement”
        • “Find pattern”: Tmax
        • “Replace with:”: Tmax1\tTmax2
      • param-repeat “Insert Replacement”
        • “Find pattern”: /
        • “Replace with:”: \t

    Regular expressions are a standardized way of describing patterns in textual data. They can be extremely useful for tasks such as finding and replacing data. They can be a bit tricky to master, but learning even just a few of the basics can help you get the most out of Galaxy.

    Finding

    Below are just a few examples of basic expressions:

    Regular expression Matches
    abc an occurrence of abc within your data
    (abc|def) abc or def
    [abc] a single character which is either a, b, or c
    [^abc] a character that is NOT a, b, nor c
    [a-z] any lowercase letter
    [a-zA-Z] any letter (upper or lower case)
    [0-9] numbers 0-9
    \d any digit (same as [0-9])
    \D any non-digit character
    \w any alphanumeric character
    \W any non-alphanumeric character
    \s any whitespace
    \S any non-whitespace character
    . any character
    \. literal . (period)
    {x,y} between x and y repetitions
    ^ the beginning of the line
    $ the end of the line

    Note: you see that characters such as *, ?, ., + etc have a special meaning in a regular expression. If you want to match on those characters, you can escape them with a backslash. So \? matches the question mark character exactly.

    Examples

    Regular expression matches
    \d{4} 4 digits (e.g. a year)
    chr\d{1,2} chr followed by 1 or 2 digits
    .*abc$ anything with abc at the end of the line
    ^$ empty line
    ^>.* Line starting with > (e.g. Fasta header)
    ^[^>].* Line not starting with > (e.g. Fasta sequence)

    Replacing

    Sometimes you need to capture the exact value you matched on, in order to use it in your replacement, we do this using capture groups (...), which we can refer to using \1, \2 etc for the first and second captured values. If you want to refer to the whole match, use &.

    Regular expression Input Captures
    chr(\d{1,2}) chr14 \1 = 14
    (\d{2}) July (\d{4}) 24 July 1984 \1 = 24, \2 = 1984

    An expression like s/find/replacement/g indicates a replacement expression, this will search (s) for any occurrence of find, and replace it with replacement. It will do this globally (g) which means it doesn’t stop after the first match.

    Example: s/chr(\d{1,2})/CHR\1/g will replace chr14 with CHR14 etc.

    You can also use replacement modifier such as convert to lower case \L or upper case \U. Example: s/.*/\U&/g will convert the whole text to upper case.

    Note: In Galaxy, you are often asked to provide the find and replacement expressions separately, so you don’t have to use the s/../../g structure.

    There is a lot more you can do with regular expressions, and there are a few different flavours in different tools/programming languages, but these are the most important basics that will already allow you to do many of the tasks you might need in your analysis.

    Tip: RegexOne is a nice interactive tutorial to learn the basics of regular expressions.

    Tip: Regex101.com is a great resource for interactively testing and constructing your regular expressions, it even provides an explanation of a regular expression if you provide one.

    Tip: Cyrilex is a visual regular expression tester.

The resulting table has the structure:

Y M D Type deltaT mag1 mag2 Tbeg Tmax1 Tmax2 Tend SR SS

Step 4: Select eclipses above the magnitude threshold

Hands On: Select eclipses above the magnitude threshold

The workflow uses a Filter step to select all eclipses with a magnitude greater or equal to a user-supplied Magnitude threshold.

  1. Filter data with the following parameters:
    • param-file “Filter *“: Replace Text on dataset (output of Replace Text in entire line tool)
    • “With following condition”: c6>=0.8
    • “Number of header lines to skip”: 1
    Comment: About the parameters

    You have to set the number of header lines to 1 in order to skip the header. The condition states that the value in column 6 of the file has to be greater than or equal to 0.8

Question
  1. What has to change in the condition if the import file has no header?
  2. What has to change in the condition if column 7 would contain the magnitudes and not column 6?
  1. In “Number of header lines to skip”: 0
  2. In “With following condition”: c7>=0.8

Step 5: Sort the eclipses chronologically

The remaining eclipses must be in chronological order before consecutive groups can be identified.

Hands On: Sort the eclipses chronologically
  1. Sort data in ascending or descending order with the following parameters:
    • param-file “Sort Dataset”: Filter on dataset (output of Filter tool)
    • “on column”: c1
    • “everything in”: Ascending order
    • In “Column selection”:
      • param-repeat “Insert Column selection”
        • “on column”: c2
        • “everything in”: Ascending order
      • param-repeat “Insert Column selection”
        • “on column”: c3
        • “everything in”: Ascending order
    • “Number of header lines to skip”: 1
    Comment:

    The configured numeric ascending sorts in this order:

    1. Column 1: Year (Y),
    2. Column 2: Month (M),
    3. Column 3: Day (D).

    The header line is skipped. This produces a chronologically ordered sequence of eclipses satisfying the magnitude criterion.

Step 6: Find groups of eclipses

This is the central analytical step of the workflow. You have to supply as input:

  • Number of eclipses (N)
  • Maximum interval in years (X)

Both are connected to variables in a Text reformatting with awk step.

For each possible sequence of N consecutive eclipses, the workflow compares the year of the Nth eclipse with the year of the first eclipse:

year[N] - year[1] <= X

If the condition is satisfied, all eclipses in that group are returned.

Hands On: Find groups of eclipses
  1. Text reformatting - with awk ( Galaxy version 9.5+galaxy3) with the following parameters:
    • param-file “File to process”: Sort in dataset (output of Sort tool)
    • “AWK Program”:

      BEGIN { OFS="\t"
        n = VAR1
        years = VAR2
      }
      NR == 1 {
       next
      }
      {
        year[NR-1] = $1
        line[NR-1] = $0
        count = NR-1
      }
      END {
        for (i=1; i<=count-n+1; i++) {
          if (year[i+n-1] - year[i] <= years) {
            for (j=i; j<=i+n-1; j++) {
              print line[j]
            }
          }
        }
      }
      
    • In ”+ Insert variables”: 3
    • In ”+ Insert variables”: 10
    Comment: What counts as a group?

    With 3 (N) and 10 (years), the workflow examines every three consecutive eclipses in the magnitude-filtered chronological list.

    A group qualifies when the year difference between its first and third eclipse is no more than ten years. There may be overlapping groups because an eclipse can belong to more than one qualifying group.

    For example, if eclipses A-B-C qualify and B-C-D also qualify, B and C are emitted twice by the group-selection step. This is intentional: the group-selection step first identifies all qualifying windows. The next steps will collapse repeated eclipse rows.

Step 7: Sort chronologically

The grouping destroyed the chronological order and some eclipses are listed more than once. The list needs to be sorted to be prepared for the following step.

Hands On: Sort chronologically
  1. Sort data in ascending or descending order with the following parameters:
    • param-file “Sort Dataset”: Text reformatting on dataset (output of Text reformatting tool)
    • “on column”: c1
    • “everything in”: Ascending order
    • In “Column selection”:
      • param-repeat “Insert Column selection”
        • “on column”: c2
        • “everything in”: Ascending order
      • param-repeat “Insert Column selection”
        • “on column”: c3
        • “everything in”: Ascending order
    • “Number of header lines to skip”: 0
    Comment: About the output

    The configured numeric ascending sorts in this order:

    1. Column 1: Year (Y),
    2. Column 2: Month (M),
    3. Column 3: Day (D).

    This produces a chronologically ordered sequence of eclipses. Some of them are listed more than once. No header line needs to be skipped because the Text reformatting tool eliminated the header.

Step 8: Remove duplicate eclipse rows

A Unique step removes repeated rows if the list is sorted well.

Hands On: Remove duplicates
  1. Unique occurrences of each record ( Galaxy version 9.5+galaxy3) with the following parameters:
    • param-file “File to scan for unique values *“: Sort on dataset (output of Sort tool)
    • “Avoid comparing the first N fields *“: 0
    Comment: About the output

    This produces a list with each eclipse only occuring once, but not in chronological order.

Step 9: Sort the final result

Because the duplicate-removal step does not preserve chronological order, the result is sorted once more.

Hands On: Sort chronologically
  1. Sort data in ascending or descending order with the following parameters:
    • param-file “Sort Dataset”: Unique on dataset (output of Unique tool)
    • “on column”: c1
    • “everything in”: Ascending order
    • In “Column selection”:
      • param-repeat “Insert Column selection”
        • “on column”: c2
        • “everything in”: Ascending order
      • param-repeat “Insert Column selection”
        • “on column”: c3
        • “everything in”: Ascending order
    • “Number of header lines to skip”: 0 We have already used this tool in a previous step with similar parameters. You can redo all the input steps by step, or you can rerun the earlier sort tool:
  1. Expand one of the output datasets of the tool (by clicking on it)
  2. Click re-run galaxy-refresh the tool

This is useful if you want to run the tool again but with slightly different paramters, or if you just want to check which parameter setting you used.

That way, you can save some clicks. But make sure to select the output of Unique and set “Number of header lines to skip” to 0.

Comment: Details about the sorting

The configured numeric ascending sorts in this order:

  1. Column 1: Year (Y)
  2. Column 2: Month (M)
  3. Column 3: Day (D). This produces the final dataset which is a chronological list of eclipses that satisfy the magnitude threshold and belong to at least one qualifying group

Run the analysis as a workflow

Suppose you now want to repeat this analysis with different input data or parameter settings. You would not want to repeat all these steps again by hand. For this, we can use the workflow.

The tutorial Extracting Workflows from Histories shows you how you can create a workflow from your own History. For variables to be flexible as in our workflow you need to extract your input parameters - how to achieve that is explained in the tutorial Using Workflow Parameters.

When you run the solar eclipse frequency workflow, you need to upload a file with the source data and to supply the following three values at runtime:

Workflow parameter Example Meaning
Minimum magnitude 0.8 Minimum observable magnitude (mag1)
Number of eclipses 3 Number of consecutive eclipses, N
Maximum interval in years 10 Maximum span between the first and Nth eclipse, X

But first, we must import the workflow into Galaxy:

Hands On: Importing and launching a GTN workflow
Launch Solar eclipse Frequency Workflow (View on GitHub, Download workflow) workflow.
  1. Click on galaxy-workflows-activity Workflows in the Galaxy activity bar (on the left side of the screen, or in the top menu bar of older Galaxy instances). You will see a list of all your workflows
  2. Click on galaxy-upload Import at the top-right of the screen
  3. Paste the following URL into the box labelled “Archived Workflow URL”: https://training.galaxyproject.org/training-material/topics/digital-humanities/tutorials/solar-eclipse-frequency/workflows/solar-eclipse-frequency.ga
  4. Click the Import workflow button

Below is a short video demonstrating how to import a workflow from GitHub using this procedure:

Video: Importing a workflow from URL

Now we can run it:

  1. Click on galaxy-workflows-activity Workflows in the Galaxy activity bar (on the left side of the screen, or in the top menu bar of older Galaxy instances). You will see a list of all your workflows
  2. Click on galaxy-upload Import at the top-right of the screen
  3. Provide your workflow
    • Option 1: Paste the URL of the workflow into the box labelled “Archived Workflow URL”
    • Option 2: Upload the workflow file in the box labelled “Archived Workflow File”
  4. Click the Import workflow button

Below is a short video demonstrating how to import a workflow from GitHub using this procedure:

Video: Importing a workflow from URL

Hands On: Run the workflow
  1. Run the workflow with the following parameters:
    • Select the eclipse data file as the workflow dataset input.
    • Enter 0.8 for Magnitude threshold.
    • Enter 3 for Number of eclipses.
    • Enter 10 for Maximum interval in years.
    • Run the workflow.
    1. Click on galaxy-workflows-activity Workflows on the Activity Bar on the left.
    2. At the top of the resulting page you will have the option to switch between the My workflows, Workflows shared with me and Public workflows tabs.
    3. Select the tab you want to see all workflows in that category
    4. Search for your desired workflow.

      Select workflow

    5. Click on the workflow name: a pop-up window opens with a preview of the workflow.
    6. To run it directly: click workflow-run Run (top-right). This will take you to the workflow run form.
    7. Configure the workflow
      • Send results to a new history: if enabled, will send the results to a new history instead of your current active history. You can provide a name for the new history here as well.
      • Re-use jobs with identical parameters. This will check if any identical jobs have already been run before, and save compute time and energy by re-using the previous results. Great to use if you previously ran (part of) this workflow on the same data already.
    8. Set the workflow parameters (e.g. input data)

    9. Recommended: click Import (left of Run) to make your own local copy under Workflows / My Workflows.

    10. Click on workflow-run Run Workflow in the upper right corner to start the workflow.
    11. You will now see the workflow invocation page showing the progress of your workflow. This page can always be accessed via galaxy-panelview Workflow invocations on the Activity bar (left-hand menu).
      • If you sent the results to a new history, you can view this history by clicking on the galaxy-histories-activity history link in the top left corner of the workflow invocation page.

Interpreting the result

The workflow returns all eclipses with mag1 at or above the threshold that are members of at least one group of N consecutive qualifying eclipses occurring within the specified maximum interval.

The result should not be interpreted as evidence that historical observers actually saw, recorded, or interpreted every eclipse. The workflow identifies astronomical configurations in the pre-calculated dataset; historical interpretation requires appropriate contextual evidence.

Explore the parameters

The main advantage of the workflow is that the research question can be changed without editing the workflow.

Hands On: Experiment
  1. Run the workflow several times with different parameters.

For example, compare:

Minimum magnitude N Maximum interval
0.8 3 10
0.8 4 20
0.9 3 20

Consider:

  • How does raising the magnitude threshold affect the number of qualifying eclipses?
  • How does increasing N change the result?
  • How sensitive are the results to the chosen time interval?
  • Are particular periods repeatedly selected under different parameter combinations?

Why use a Galaxy workflow?

The workflow makes several parts of the analysis explicit:

  • the source dataset,
  • the transformations applied to the data,
  • the definition of observable magnitude used for filtering,
  • the chronological sorting,
  • the mathematical criterion used to define an eclipse group,
  • and the user-selected analytical parameters.

This makes the procedure easier to inspect, rerun, share, and modify than an analysis in which these operations are performed manually.

Conclusion

You have built and run a parameterised Galaxy workflow for astronomical chronology. Starting with a pre-calculated eclipse list, the workflow converts and restructures the data, selects eclipses by observable magnitude, identifies temporally concentrated groups, removes overlapping duplicates, and produces a chronologically sorted result.

Because the three scientific criteria are runtime parameters, the same workflow can be reused to investigate different hypotheses without changing its internal structure.