hdtimelines

hdtimelines

A Python package for creating graphical timelines of historical data using Plotly

Github: https://github.com/dh3968mlq/hdtimelines

Documentation: https://hdtimelines.readthedocs.io/en/

PyPI: https://pypi.org/project/hdtimelines/

An app that uese this package: https://timeflows.uk/

Some starter datasets (.csv): https://github.com/dh3968mlq/historicaldate-data

Uses the historicaldate package for dates:

• Dates in input files are in a natural readable format, such as '25 Dec 1066'
• Dates can be uncertain (e.g. 'circa 1028') and can be BC (e.g. '525 BC')
• It is possible to specify start and end dates of persistent events, such as a wars or monarchs' reigns, and/or birth and death dates of persons

In the timeline display:

To create a timeline:

• Install this package: pip install hdtimelines
• Download sample data from https://github.com/dh3968mlq/historicaldate-data, and/or
• Create .csv files of data (see below for column names and date formats)
• Create and run a Python program, similar to below, or see sample timeline code in the timelines folder in this repository

Sample code:

# Sample code for a timeline of British monarchs and Prime Ministers
# The folder that historicaldate-data has been downloaded to...
dataroot = "/svol1/pishare/users/pi/repos/timelines2/historicaldate-data" 

from hdtimelines import pltimeline
import pandas as pd

df1 = pd.read_csv(f"{dataroot}/data/History/Europe/English and British Monarchs.csv",
               na_filter=False)
df2 = pd.read_csv(f"{dataroot}/data/History/Europe/British Prime Ministers.csv",
               na_filter=False)

pltl = pltimeline.plTimeLine()
pltl.add_topic_from_df(df1, title="English and British Monarchs")
pltl.add_topic_from_df(df2, title="British Prime Ministers") 
pltl.show() # Show in a browser, or...
pltl.write_html("/home/pi/example_timeline.html")

Input file format

Dataframes passed to add_topic_from_df have one row per event or life, and specific column names. label must be present, together with either hdate or both of hdate_birth and hdate_death. All other columns are optional.

Column	Usage
label	Event label, appears on the timeline
description	Extended description, used for hovertext
hdate	Date of event, or start date if it is a persistent event
hdate_end	End date of a persistent event
hdate_birth	A person's birth date
hdate_death	A person's date of death, defaults to alive if hdate_birth is present
htext_end	Hover text linked to the marker drawn at hdate_end
color (or colour)	Colour to draw the event or life
url	hyperlink, active by clicking on the displayed label
rank	An integer, use together with max_rank to control which rows are displayed
min_xrange_years	An integer. The event is displayed only if the displayed date range is greater than min_xrange_years
max_xrange_years	An integer. The event is displayed only if the displayed date range is less than or equal to max_xrange_years

Date formats

Date formats are described in detail at https://historicaldate.readthedocs.io/en/

In brief:

• Two core formats are supported by default:
  • 25 Dec 1066 (and variants)
  • 1066-12-25
• Additional non-default formats available:
  • 25/12/1066
  • 12/25/1066
  • Dec 25 1066
• Imprecise dates, such as '1066' or 'circa 1066' are allowed
• BC dates are supported such as '385 BC'
• Ongoing events and lives are supported by setting hdate_end or hdate_death to 'ongoing'. A blank value of hdate_death isinterprested as meaning a person is still alive.

Changes

New in 0.1.1

max_xrange_years, min_xrange_years

New in 0.1.0

Released to PyPI and documentation on readthedocs

New in 0.0.7

Split from historicaldate package (https://github.com/dh3968mlq/historicaldate)

New in 0.0.6

add_event_set renamed to add_topic_from_df

New in 0.0.5

• BC dates can now be displayed on timelines (xmode=years)
• X-axis (date axis) labels moved to top

New in 0.0.4

add_event_set() now updates yaxes to fit the displayed data

New method plTimeLine().fit_xaxis(self, mindate=None, maxdate=None) that fits the X axis either to the data or to a specified range of dates

X axis date labels moved to top of display

Study range filtering added, parameters study_range_start and study_range_end of the add_event_set method. Event sets lying entirely outside the study range are not displayed.

Filtering on the value of a rank column in input data, parameter max_rank of the add_event_set method.

New in 0.0.3

• New English Football timeline code (english_football.py)
• New hover_datetype parameter to add_event_set
• New htext_end column supported