1 Introduction

Calendars are believed to reflect culture and religious activities. Many daily activities and traditional events are planned with the help of a calendar. They help us gain better access to long-term memory and life history information. Although the Gregorian calendar is followed worldwide for national and international activities, many religions across the world rely on their religious calendar for their cultural and traditional activities.

The VedicDateTime [1] is an R package that provides a platform for the Vedic calendar system. It provides several functionalities to facilitate the conversion between Gregorian and Vedic calendar systems and helps examine its impact in the time series analysis domain. It aims to analyze various natural time series influenced by both sun and moon with the help of a (lunisolar) calendar. It implements five important parts of the Vedic calendar and provides conversion from a Gregorian date or a Julian day to Vedic calendar entities. A few more entities in the Vedic calendar system and related conversions are also available in this package. Researchers can use this package to analyze the time series concerning different time factor s and explore its impact.

In this package, different entities of the Vedic calendar are implemented. This package implements efficient and reliable functions for computing Panchanga’s for a given Gregorian date. Section 2 presents the motivation for this package. A brief introduction to the Vedic calendar and the terminology of the Vedic calendar system is presented in Sect. 3. The package is described, in detail, in Sect. 4.

2 Motivation

Calendars are integral parts of our life and culture. Over time, various calendar systems have been developed in different countries, reflecting their traditions and religious events [2,3,4]. Gregorian, Vedic, Chinese, and Hebrew calendars are some of the existing ones [5]. These calendars follow either the solar cycle, the moon cycle, or both. Various researchers are interested to develop software for these calendar systems. Table 1 shows different software packages available in R and Python for different calendars. In the Gregorian calendar, the number of days in each month of a year is fixed without a justified logic behind it. Whereas, the Vedic calendars are based on the motion of both the sun and moon [6]. The Vedic calendar length corresponds to the solar year, which is the time taken by Earth to revolve around the sun and the months are lunar, which is the time taken by the moon to revolve around the Earth. These lunar months and solar years are well balanced in the Vedic calendar.

Table 1 R and Python packages for different calendar systems

The time factor is an important parameter in time-series analysis. In [15], patterns and trends in univariate time-series data are identified by considering multiple time scales simultaneously. And the authors of [15] claimed that such clustering of time series with different time scales provides insight into both standard and exceptional patterns. In [16], calendar effects on monthly time-series are analyzed. They analyzed the effects of changing months and days of the week and suggested that for effective analysis of time series the calendar effects should be removed. This implies that only the Gregorian calendar is not sufficient to analyze the patterns and trends in the time series.

There exists a great influence of both sun and moon on various behavioral activities on Earth [17], e.g., lunar rhythms are responsible for tidal effects on seas, and major climate fluctuations [18], and the sun is responsible for variations in temperature and wind. These activities are studied and analyzed by forming a time series. For experimental analysis of such natural time series, the time factor generally refers to Gregorian (solar) calendar. However, to analyze the activities that have the impact of the sun and moon both, the time factor must be dependent on the sun and moon both i.e. lunisolar. If the natural time series are formatted using the Vedic (lunisolar) calendar format, then it may be possible to extract both lunar (moon) and solar (sun) based patterns within the time series more efficiently. In [19], Bokde analyzed the time factor of temperature time series using the Gregorian and Vedic calendars. The correlation-based analysis in [19] shows that the Vedic calendar can reveal interesting facts and may improve the time-series analysis accuracies.

Time series are widely used in many fields ranging from weather forecasting, and forecasting financial time series to wind power and speed prediction. Instead of relying only on the Gregorian calendar system, the VedicDateTime package will help researchers to explore a new time factor. As shown in Table 1 various software packages for different calendar systems are available. However, the software package for the Vedic calendar system is not available. So the VedicDateTime package presented in this paper will facilitate the researchers to analyze and compare their results with reference to different time factors.

3 Panchanga of Vedic calendar

In order to understand how VedicDateTime package works, the concepts related to the Vedic calendar must be clear. Ayanamsha and Panchanga are important entities in this calendar system. In order to explain how the Vedic calendar works, some basic facts from astronomy must be recalled. As we all know, the Earth revolves anti-clockwise around the sun in an elliptical orbit. And the time taken by the earth to arrive at one vernal equinox from the other vernal equinox after one revolution is called a tropical year. At the end of the tropical year, if we consider the position of the earth with respect to a fixed star in the zodiac, the earth appears to lie 50.26 s of celestial longitude to the west of its original position. In order to arrive at the same position with respect to a fixed star of the zodiac, the time taken is called a sidereal year. This is the result of the precession of the earth’s axis due to its wobble in a clockwise direction. The precession of the equinoxes increases by 50.2 s every year. The distance between the Vernal equinox and the 1st point of Aries (Mesha) on the fixed zodiac is progressively increasing. The distance at any given point of time is called Ayanamsha.

Fig. 1
figure 1

(1a) Panchanga and (1b) Tithi of Vedic calendar

The Panchanga means ‘five arms’, it consists of the five most important parts, i.e., Tithi, Vaara, Nakshatra, Yoga, and Karana [20]. The five arms of Panchanga are shown in Fig. 1a. The calculations of these five entities are based on either moon or sun or both. The first arm, the Vaara or the day of the week is based on the sun alone; Tithi and Karana are based on the moon alone; Nakshatra and Yoga are based upon both moon and sun. This makes the Vedic calendar a true lunisolar calendar. A brief description of these five entities is listed below.

  1. 1.

    Tithi: A lunar day is termed as tithi. The moon illuminates because it reflects part of the light received from the sun. The different phases of the moon are due to the relative positions of the sun and the moon with respect to the Earth. When the moon traverses 12\(^{\circ }\) in longitude relative to the sun, a tithi is completed. In one month, fifteen tithis are in the waxing phase (known as Shukla paksha) of he moon while the end tithi is the full moon day (called Purnima). The remaining fifteen tithis are in the waning phase (known as Krishna paksha) with the end of tithi being the new moon day Amavasya). These phases together constitute a lunar month, which is of thirty tithis. Names are associated with each of these tithis. Thirty tithis or phases of the moon in a lunar month are hown in Fig. 1b.

  2. 2.

    Vara: As in the Gregorian calendar, vaara is the day of the week. The names of the seven varas are derived from the names of the seven Grahas i.e. planets which are considered as heir lords. The varas and their corresponding names as per the Gregorian calendar are presented in Table 2.

  3. 3.

    Nakshatra: As per Vedic terminology, nakshatra or constellation means a sky map or a star map. There are a total of 27 nakshatras and each of them has a specific name. The Moon resides in each of these constellations for a day [21]. Figure 2 shows the location of nakshatras and zodiac. The position of any planet or star in the sky is fixed with reference to the zodiac. And the earth is encircled by zodiacs so it covers 360 degrees. This 360 degrees span is equally divided into a span of 13 degrees 20 min, each one starting from zero Aries, and each nakshtra is placed on it [22] as shown in Fig. 2. Each nakshatra spans 13 degrees 20 min where the moon resides for one day. Therefore, the absolute longitude of the moon is used to calculate the nakshatra of the day. The location of nakshatra with respect to zodiacs is shown in Fig. 2.

  4. 4.

    Yoga: There are 27 yogas, each of them measuring 13 degrees and 20 min of the arc. Yoga is the sum of sidereal (Nirayana) longitudes of sun and moon in the multiples of 13 degrees 20 min. When the sidereal longitudes of the sun and moon are added and they are divided by 13 degrees 20 min, the quotient plus one gives the respective yoga.

  5. 5.

    Karana: A Karana is half of a tithi or when the moon traverses 6\(^{\circ }\) in longitude relative to the sun. In 30 tithis of a lunar month, there are 60 Karanas or half-tithis.

Table 2 Names of varas as per Vedic calendar and their corresponding names in the Gregorian calendar
Fig. 2
figure 2

Location of Nakshatra as per Vedic calendar

4 Introduction to R package VedicDateTime

The VedicDateTime package provides functions to convert Gregorian date-time to Vedic date-time based on the calculations of the Panchanga. These functions rely on the gregorian_to_jd( ) function, which converts a Gregorian date to a Julian day. The package includes functions such as tithi, vaara, nakshatra, yoga, and karana. These functions require the input parameters of the date (Julian day number) and the location (latitude, longitude, and time zone).

  1. 1.

    \(\underline{\mathtt {tithi( )}}\)

    figure a

    The function calculates the tithi (a phase of the moon) for a given Julian day and place. The tithi at sunrise is determined by the difference between lunar and solar longitudes divided by 12. The fractional part of the tithi indicates the remaining degrees to the next tithi, which helps determine when that tithi ends. The time required to complete the remaining degrees is found using Inverse Lagrange’s interpolation with lunar and solar longitudes at 0.25 day intervals from sunrise. The resulting tithi and its ending time are added to the output vector.

    figure c

    In Listing 2, the first number in the output represents a specific tithi. There are 30 tithis in total, and in this case, the number 20 represents Krishna Paksha Panchami. The following three numbers indicate the time at which this tithi ends (20 h, 55 min, and 35 s). Sometimes, two tithis can occur on a given date. In such cases, the tithi of the next day is checked to determine if the current tithi is skipped. If it is skipped, the skipped tithi is included in the output along with its ending time.

    figure d

    For the given input parameters in Listing 3, the tithi( ) function returns 8 numbers as output. The first 4 numbers represent the first tithi and its ending time, while the next 4 numbers represent the second tithi and its ending time. If the timings exceed 24:00, it means that they indicate a time past midnight. To determine the tithi name associated with a tithi number, get_tithi_name(jd, place) function is used. The tithi calculation process is illustrated in a flow chart (Fig. 3a).

  2. 2.

    \(\underline{\mathtt {Vaara( )}}\) Vaara is the day of the week, very similar to the day in the Gregorian calendar. There are seven vaaras in one week. Vaara of a Julian day is calculated as follows.

    figure e
    figure f

    The output of Listing 5 is 1, which is ’Ravivara’ as per the Vedic calendar. The name associated with the Julian day is obtained using get_vaara_name( ) function as shown in Listings 6 and 7.

    figure g
    figure h
  3. 3.

    \(\underline{\mathtt {nakshatra( )}}\): The function calculates the Nakshatra of a given day based on the moon’s position. It involves determining the moon’s sidereal longitude by subtracting the Ayanamsa (related to the precession of equinoxes) from its tropical(Sayana) longitude. The Ayanamsa used is the Lahiri Ayanamsa. The sunrise for the specified date and location is obtained using the Swiss Ephemeris, providing a Julian day number. To calculate the Nakshatra, the Nirayana longitude of the moon is computed by subtracting the Ayanamsa from its Sayana longitude. This Nirayana longitude is then multiplied by 27 and divided by 360 to obtain the Nakshatra as a decimal number. The ending time of the current Nakshatra is determined by checking for the starting time of the next Nakshatra using Lagrange’s inverse interpolation of Nirayana lunar longitudes at 0.25 intervals of the day. The Nakshatra and its ending time are added to the output vector. In some cases, two Nakshatras may occur on a given date. To account for skipped Nakshatras, the function checks the Nakshatra of the next day. If a Nakshatra is skipped, it is included in the output along with its ending time. This process is summarized in the flowchart shown in Fig. 3b.

    figure i
    figure j

    In Listing 9, the first number represents the number associated with the respective nakshatra. 25 represents Purvabhadrapada. This nakshatra ends on the next day at 0 h, 24 min, and 1 s, which is represented by the rest of the numbers.

  4. 4.

    \(\underline{\mathtt {yoga( )}}\): There are 27 yogas, each of them measures 13 degrees, 20 min of an arc. To calculate yoga, the sidereal longitudes of the sun and moon are added and divided by 13 degrees 20 min. The quotient of the division plus one gives the number which denotes the respective Yoga as shown in Listing 11.

    figure k
    figure l

    For given input parameters, yoga( ) returns a number associated with the respective yoga and the remaining three numbers the time at which yoga ends.

  5. 5.

    \(\underline{\mathtt {karana( )}}\): There are four fixed karanas that occur only once in a lunar month and the remaining seven karanas recur eight times during the rest of the lunar month. For a given date and place, firstly tithi is calculated, and then, using tithi, the corresponding karanas are calculated as shown in Listing 13.

    figure m
    figure n

    For given input parameters, karana( ) returns two numbers associated with the respective two karanas. The names of the karana are obtained using get_karana_name( ) as shown in Listing 14.

    figure o
Table 3 Five arms of Panchanag in Vedic calendar

The remaining functions available in VedicDateTime package are listed in Table 3.

Fig. 3
figure 3

Flowchart of (a) Tithi and (b) Nakshatra calculation

Table 4 Functions in VedicDateTime Package

5 Demonstration of case studies using VedicDateTime

This section demonstrates the applicability of the VedicDateTime package to analyze the effects of calendar seasonality on economic output and regressor on industrial production of India pre and post-Diwali festival. Calendars have an enormous effect on economic, social, and cultural behaviours but nowhere it is more profound than a country or region’s economic output indicators such as industrial output, CPI, stock-market transaction, and import exports. But in a globalized world, all of the economic time series is modelled around the Gregorian calendar system. In a country like India, with multiple regions and festivals from multiple religions as well, a single calendar will not be sufficient to model various seasonal components. For example, during the festival month of Diwali, the consumer consumption rate is usually higher and industrial output is generally lower. In this section, we present two case studies where the VedicDateTime package is used to dig for more insights from the data (Table 4).

5.1 Effects of calendar seasonality on economic output

Calendar has an enormous effect on economic, social, and cultural behaviors but nowhere it is profound than a country or region’s economic output indicators such as industrial output, CPI, stock-market transaction, import–exports but in a globalized world, all of the economic time-series modelling is modeled around Gregorian calendar system. In a country like India with multiple regions and festivals from multiple religions as well, a single calendar will not be sufficient to model various seasonal components. For example, during the festival month of Diwali, the consumer consumption rate is usually higher and during the month, industrial output is generally lower (Table 5).

There have been significant work published already to identify and remove multiple lagged seasonality from time-series [23] considering technical papers published from the US Bureau of Census [24]. There also have been significant work done to identify and remove seasonality, especially concerning religious festival based on the Gregorian calendar by the Bank of Spain [25]. Similar work has been presented for lunar [26] and luni-solar [27] based calendar system and also in the context of Indian seasonality effect present [28,29,30].

We have performed a comparative study to understand calendar seasonality creeping in while modelling seasonal decomposition on time-series objects, especially on econometric data sets. To understand if any methodologies can be obtained and to provide a better, quantitative analysis of the seasonality, we used India’s Industrial output data after the year 2000 and modelled holiday seasonality with Diwali dates corresponding to that. To understand the effect of seasonality, dates corresponding to India’s industrial production data are converted into Vedic calendar dates using [1]. The following are the steps to convert the time series from the Gregorian calendar into the Vedic calendar (details available in supplementary material: Doc1).

  • Step 1: View India Industrial Production (IIP) Data from [31]

  • Step 2: Convert Gregorian dates of India Industrial Production (IIP) data to Julian dates.

  • Step 3: Select the desired location for the date conversion.

  • Step 4: Convert Julian dates to Vedic calendar dates.

With this conversion, there will be two different time-series objects of India’s industrial production output, one with Gregorian calendar dates and another with Vedic calendar dates. Both time series are modelled and in both the cases, a seasonal decomposition was observed visible along the red line, and [32] was used for seasonality decomposition. Due to the change in the type of calendar, missing values were omitted to keep the frequency of the time series the same for both calendar systems. VedicDateTime [1] was used for all the conversions related to date and time-series objects in this comparative study.

5.2 Regressors of Diwali on industrial production of India

Diwali is the most important festival of India and its timing distorts the monthly time-series of industrial production heavily. Generally, Diwali is celebrated in the month of October according to the Gregorian Calendar but that is not fixed. However, as per the Vedic calendar, Diwali happens to be on the last day of the seventh masa, i.e., Ashwin and it is fixed unless two tithis appear on the same day. Depending on which month Diwali is celebrated, the industrial production index also changes. The standard software packages for seasonal adjustment [32, 33] (developed by the U.S. Census Bureau) or Tramo Seats [34] (developed by the Bank of Spain) have a built-in adjustment procedure for Easter holiday, but not for Diwali. However, all packages allow for the inclusion of user-defined variables. Seasonal is an interface to [32] wherein we can include Diwali dates. The impact of Diwali on industrial production in India is analyzed using the VedicDateTime package. First, Diwali dates are converted into VedicDateTime compatible date-time through the following steps.

  • Step 1: View the Diwali holidays.

  • Step 2: Convert Gregorian dates of Diwali holidays into Julian dates.

  • Step 3: Select the desired location for the date conversion.

  • Step 4: Convert Julian dates to Vedic calendar dates.

Next, a time series based on Gregorian dates is converted into Vedic calendar dates (explained in Sect. 5.1). For comparative analysis and better seasonal adjustment, the time series includes pre and post-festival industrial production. The seasonal package allows users to add user-defined regressors to remove seasonality from a time series. We have added both pre and post-Diwali production time series in the main seasonal adjustment. X-13ARIMA-SEATS is used to adjust for the festival seasonal component. Experimental analysis (presented in supplementary material: Doc3B) shows that the seasonal co-efficient shows a minor decline during pre and post-Diwali season across the time series. We have observed an unadjusted vs adjusted seasonal plot and it can be concluded that seasonal adjustment based on the Diwali season removes distortion from the time series (details are available in the supplementary material: Figure 5 in Doc 3B). The amount of distortion present in the series can be seen in Figure 6 in Doc 3B.

6 Conclusions

In conclusion, this paper introduces VedicDateTime, a pioneering open-source framework that implements the Vedic lunisolar calendar and facilitates conversions to and from Gregorian dates. This innovative tool presents a unique avenue for researchers to delve into time-series analyses from a fresh perspective, particularly in contexts influenced by both solar and lunar cycles. Significantly, this study serves to underscore the relevance and potential of alternative calendar systems in fields where the Gregorian calendar has been the primary reference point. The Vedic calendar, due to its lunisolar nature, offers an untapped wellspring of insights for research fields influenced by both celestial bodies.

Our explorations took the form of two case studies focusing on the economic outputs of India. The first study utilized the VedicDateTime package to investigate calendar seasonality’s effects on economic output, while the second examined the impact of the Diwali festival on India’s industrial production. In both scenarios, the VedicDateTime package emerged as a valuable tool, providing new insights and reinforcing the need for a nuanced understanding of calendar systems and their impacts. These case studies demonstrate that VedicDateTime offers practical solutions for modelling and understanding the complexity of time-series data in contexts where multiple calendar systems and cultural factors come into play. It makes the seasonal decomposition and adjustment process more comprehensive and culturally sensitive, thereby allowing for more accurate forecasting and analysis. As we navigate an increasingly globalized world, it’s critical that our analytical tools evolve to reflect the diverse cultural, regional, and temporal complexities at play. VedicDateTime represents a significant stride in this direction, offering an innovative tool for researchers keen to incorporate these considerations into their work.

7 Limitations and future scopes

Future iterations of the VedicDateTime package will build on this foundation, with plans to incorporate a visualization feature that will allow for enhanced user interaction and interpretation of data. As it stands, VedicDateTime opens up an exciting new chapter in time-series analysis, bridging the gap between different calendar systems and providing fresh perspectives in the process.

At present, the VedicDateTime R package, while offering robust functionality for date conversions and time-series analysis, does not incorporate built-in tools for data visualization within the Vedic calendar framework. This limits the user’s ability to directly and visually interact with and analyze their data in a Vedic calendar context. As part of our future roadmap, we intend to surmount this limitation by infusing the package with a dynamic visualization feature. This development is aimed at enabling users to graphically interact with the Vedic calendar and its corresponding Gregorian dates/times within a single, intuitive interface. This visual augmentation is projected to provide a holistic and tangible representation of the data. It will not only enhance the understanding of the Vedic time series but will also elucidate trends and patterns which may otherwise remain obscured in the raw data. By doing so, we aim to further augment the potential and usability of the VedicDateTime package in time-series analysis.

Another future scope of work is to add native R datetime object support for VedicDateTime library while dealing with calendar conversation which will provide generic class support (S4 class) to manipulate VedicDateTime objects as native R datetime objects which can include operation on such objects such as addition, time-delta and time-zone awareness which is currently missing.

8 Current code v0.1.7

Table 5 Code metadata