Package: tempun
tempunCitationVojtěch Kaše. (2022). tempun (Version v0.2). Zenodo.http://doi.org/10.5281/zenodo.4650989Descriptiontempunis a Python 3 package to deal with temporal uncertainty in historical & archaeological datasets. Dating of historical artifacts (e.g. inscriptions, books etc.) is typically expressed by means of adating intervalduring which it is assumed that the artifact was produced. Commonly, the production itself was much shorter than the interval and did not take more than one year. Therefore, the interval rather expressesuncertaintyconcerning the actual date of production. The question is how to analyze temporal trends in data revealing such temporal uncertainty.A way forward is to use the interval to extractprobabilityof production of the artifact. All dates (years) outside of the dating interval have probalityp=0; all dates within the interval have probability somehow proportional to the duration of the interval, while the sum of  probabilities for all years within the interval has to be equal to 1. This probality has to follow certaindistribution. The package works with uniform or trapezoidal distribution. With uniform distribution, each year within the interval has an equal probality to be the year of production of the artifact.We can use the intervals and the probalities associatiated with them to randomly assign individual dates (years) to each artifact within our dataset. In other words, we canmodelorsimulatethe date.  We can do this repeatedly, i.e. to each artifact assign a certain number ofrandom dates.  This is in the core of aMonte Carlo Simulation(MCS) approach. In the package, it is implemented by means ofmodel_date()function.Having the random dates, we can proceed to do the analysis. For instance, we can recombine these dates intomultiple time seriesand to compare between them. The package includes a bunch of functions developed for this purpose.Getting startedThe package can be installed viapip:pipinstalltempunTo be sure that you have the latest version, usepip install tempun --ignore-installed. To install it directly from Jupyter, use!pip install tempun.In Python, import the package:importtempun## Documentation (in progress)model_date()This function requires at least two parameters:startstopIf bothstartandstopare numbers, model_date(start, stop) returns a random number within the range starting withstartand ending withstop.Ifstopis not a valid number or contains an empty value,startis interpreted as defining a NOT BEFORE date (the so called ante quem*)Ifstartis not a valid number or contains an empty value,stopis interpreted as defining a NOT AFTER date (the so calledpost quem)Ifstartandstopare identical, the function returns the same number as well.There are three optional parameters:size=1: how many random numbers you want to get; by default, size=1, i.e. only one number is returnedb: bending pointbdefining shape of the trapezoidal distribution; by default,b=0, i.e. uniform distribution; set to 0.1 to get trapezoidal distributionscale:  scale of the half-uniform distribution used to model ante quem and post quem; by default scale=25The function returns an individual number (if size=1; i.e. by default) or a list of numbers of length equal to size# example 1: only start and stop>>>tempun.model_date(-340,-330)-337# example 2: size specified (returns a list of numbers of given size>>>tempun.model_date(-340,-330,10)[-334,-333,-332,-336,-332,-338,-333,-336,-333,-331]# example 3: model post quem (with default scale)>>>tempun.model_date(114,"",10,antepost=False)[114,114,114,114,114,114,114,114,114,114]>>>tempun.model_date(114,"",10,antepost=True)[123,143,123,149,123,155,125,115,128,132]get_simulation_variants()>>>get_simulation_variants(random_dates_lists)timeblocksplot_from_random()>>>timeblocksplot_from_randoms(random_dates_lists,timeblocks=None,ax=None,color="black",random_size=None,**kwargs)kdeplot_from_randoms()>>>kdeplot_from_randoms(random_dates_lists,ax=None,color="black",random_size=None,**kwargs)timeblocksplot_from_randoms()>>>timeblocksplot_from_randoms(random_dates_lists,timeblocks=None,ax=None,color="black",random_size=None,**kwargs)Version history0.2.2 - minor bugs fixing0.2.1 - minor bugs fixing0.2 - numerous improvements and simplifications (some new features not compatible with previous versions...)0.1.6 - minor improvements0.1.5 -antepostargument added, defaultFalse0.1.4 - seed argument in model date0.1 - first version