TimeStampProcessing 0.1.3

A package for timestamp-related data processing

TimeStampProcessing

TimeStampProcessing is a Python package designed to simplify and enhance operations involving timestamps and time series data. This package includes a wide range of utilities for parsing, comparing, and manipulating timestamps, which can be particularly useful in time-sensitive data analysis tasks.

Features

• Timestamp Parsing: Parse timestamps and search formatted timestamps in a directory
• Time Comparisons: Easily compare different timestamps to determine order or calculate differences.
• Interval Handling: Generate, merge, and manage lists of time intervals, including finding gaps and overlaps.
• Time Zone Conversions: Convert timestamps between different time zones.
• Time Adjustments: Add or subtract time from timestamps to calculate new times.

Installation

You can install TimeStampProcessing using pip:

pip install TimeStampProcessing

Setup

Import the package once and use the alias tsp to access all functionalities:

import timestampprocessing as tsp

Usage Examples

Each function available in the TimeStampProcessing package is demonstrated below with an example.

Formatting DateTime Objects

The format_datetime function is designed to format a datetime object into a custom string format. This utility is essential for applications requiring date and time display in various formats, such as reporting systems, user interfaces, or logging activities where date and time information needs to be presented in a specific style.

Functionality

This function converts datetime objects into strings based on custom formatting instructions, allowing for flexible presentation of date and time information. It supports a wide range of format options to accommodate different regional formats, special formatting needs, or user preferences.

Parameters

• dt (datetime): The datetime object to format.
• format_str (str): The custom format string where tokens like 'YYYY' or 'YY' for the year, 'MM' or 'M' for the month, 'DD' or 'D' for the day, 'hh' or 'h' for the hour, 'mm' or 'm' for the minute, and 'ss' or 's' for the second are used to specify the format.

Example Usage

Suppose you need to display the current time in a user interface where the date format should include the full year, month, and day, and the time should be in hours and minutes:

import datetime
import timestampprocessing as tsp

# Current datetime
current_datetime = datetime.datetime.now()

# Format the datetime into a more readable format
formatted_date = tsp.format_datetime(current_datetime, "YYYY-MM-DD hh:mm")
print(f"Formatted DateTime: {formatted_date}")

Sorting Dictionary Keys by Datetime Format

The sort_dict_keys function is designed to sort the keys of a dictionary where the keys are strings formatted as datetime. This function is useful for organizing data chronologically when working with time-based key values in dictionaries.

Functionality

This function sorts the keys of a dictionary based on the datetime format provided. It can sort in both ascending and descending order, making it versatile for various data processing needs.

Parameters

• dictionary (dict): A dictionary whose keys are datetime strings that need sorting.
• format (str): The datetime format of the keys, which tells the function how to interpret the datetime strings.
• order (int): Determines the sort order. Use 0 for ascending order or 1 for descending order.

Example Usage

Suppose you have a dictionary with event names as keys and descriptions as values, and you want to sort these events by their datetime keys.

import timestampprocessing as tsp

events = {
    "2023-12-25-15-30-00": "Christmas Party",
    "2023-10-31-19-00-00": "Halloween Bash",
    "2023-11-24-20-00-00": "Thanksgiving Dinner"
}

# Sort the dictionary keys in ascending order
sorted_events = tsp.sort_dict_keys(events, format="%Y-%m-%d-%H-%M-%S", order=0)
print("Events sorted by datetime:")
for event in sorted_events:
    print(f"{event}: {events[event]}")

Calculating Time Difference

The time_difference function calculates the difference between two datetime strings, providing the result as a timedelta object which represents the difference in time between the two specified points.

Functionality

This function is essential for applications requiring time duration calculations between two timestamps, useful in fields such as event planning, logging, and time-series analysis.

Parameters

• datetime_str1 (str): The first datetime string, representing the start time.
• datetime_str2 (str): The second datetime string, representing the end time.
• format1 (str): The datetime format of the first string, specifying how to interpret the datetime string.
• format2 (str): The datetime format of the second string, specifying how to interpret the datetime string.

Example Usage

Suppose you want to calculate the time difference between two specific events:

import timestampprocessing as tsp

# Define datetime strings
start_time = "2023-01-01-10-00-00"
end_time = "2023-01-01-15-00-00"

# Calculate the time difference
time_diff = tsp.time_difference(end_time, start_time, format1="%Y-%m-%d-%H-%M-%S", format2="%Y-%m-%d-%H-%M-%S")
print(f"Time Difference: {time_diff}")

Getting First and Last Dates from a Series

The get_first_last_dates function is designed to extract the first and last date from a pandas Series that has a datetime index. This function is particularly useful for time series analysis, where determining the range of data coverage is essential.

Functionality

This function simplifies the process of identifying the start and end points of datasets, facilitating easier assessment of the time span covered by the data.

Parameters

• series (pandas.Series): A pandas Series object equipped with a datetime index.
• format (str): A string specifying the output format for the dates. It should contain placeholders for the year (%04d), month (%02d), and day (%02d).

Example Usage

Consider you have a pandas Series representing daily sales data, and you want to find out the date range covered by this dataset:

import pandas as pd
from timestampprocessing as tsp

# Create a pandas Series with a datetime index
data = {
    pd.Timestamp('2023-01-01'): 100,
    pd.Timestamp('2023-01-02'): 110,
    pd.Timestamp('2023-01-03'): 120
}
series = pd.Series(data)

# Get the first and last date
first_date, last_date = tsp.get_first_last_dates(series)
print(f"First Date: {first_date}, Last Date: {last_date}")

Adding Seconds to a Timestamp

The add_seconds_to_timestamp function allows users to add (or subtract) a specified number of seconds to a given timestamp, effectively modifying the time accordingly. This utility is useful in scenarios where time adjustments are needed, such as scheduling future events or calculating expiration times.

Functionality

This function enhances the flexibility of time manipulation by allowing precise control over time adjustments, supporting both positive and negative adjustments.

Parameters

• timestamp_str (str): The initial timestamp string formatted according to the specified datetime format.
• seconds (int): The number of seconds to add to the timestamp. Negative values will subtract seconds.
• timestamp_format (str): The format of the timestamp string, which dictates how the string is parsed into a datetime object.

Example Usage

Suppose you have a starting timestamp representing the beginning of an event, and you need to find the exact time 30 minutes (1800 seconds) later:

import timestampprocessing as tsp

# Initial timestamp
timestamp_str = "2023-10-01-12-00-00"

# Adding 1800 seconds to the timestamp
new_timestamp = tsp.add_seconds_to_timestamp(timestamp_str, 1800, "%Y-%m-%d-%H-%M-%S")
print(f"New Timestamp: {new_timestamp}")

Checking if One Timestamp is Ahead of Another

The is_time_ahead function determines whether one timestamp occurs chronologically before another. This utility is crucial for applications that require temporal comparisons, such as scheduling systems, logging mechanisms, or any condition-based triggers dependent on time ordering.

Functionality

This function offers a straightforward method to compare two timestamps to assess which one is earlier, aiding in making decisions based on time sequences.

Parameters

• timestamp_str1 (str): The first timestamp string to compare. Typically, this is the timestamp you want to check if it occurs earlier.
• timestamp_str2 (str): The second timestamp string to compare against the first.
• timestamp_format (str): The format in which both timestamp strings are provided. This ensures accurate parsing and comparison.

Example Usage

Assuming you have two events and you need to verify if the first event happens before the second:

import timestampprocessing as tsp

# Define two timestamps
timestamp1 = "2023-10-01-14-00-00"
timestamp2 = "2023-10-01-15-00-00"

# Check if the first timestamp is ahead (earlier) than the second
is_ahead = tsp.is_time_ahead(timestamp1, timestamp2, "%Y-%m-%d-%H-%M-%S")
print(f"Is the first timestamp ahead of the second? {'Yes' if is_ahead else 'No'}")

Checking Leap Year Status

The is_leap_year function determines whether a specified year is a leap year. This utility is crucial for applications that involve date calculations where leap year consideration is necessary, such as calendaring systems, scheduling applications, and any temporal data analysis that spans multiple years.

Functionality

This function checks if a given year qualifies as a leap year based on the Gregorian calendar rules. A leap year has 366 days and occurs every four years, except for years that are divisible by 100 and not divisible by 400.

Parameters

• year (int): The year to check as an integer.

Example Usage

Suppose you are developing a feature that adjusts scheduling for leap years and need to verify if the current year is a leap year:

import timestampprocessing as tsp

# Check if the year 2024 is a leap year
leap_year_status = tsp.is_leap_year(2024)
print(f"Is 2024 a leap year? {'Yes' if leap_year_status else 'No'}")

Calculating Sunrise and Sunset Times

The sunrise_sunset_time function calculates the exact times of sunrise and sunset for a given latitude, longitude, and date. This function is invaluable for applications related to astronomy, meteorology, photography, and any planning activities that depend on daylight hours.

Functionality

This function leverages the astral library to determine the sunrise and sunset times based on geographic coordinates and a specific date. It's perfect for scheduling events that align with daylight, understanding light conditions for photography shoots, or any use case requiring precise knowledge of daylight hours.

Parameters

• latitude (float): The latitude of the location for which you want to calculate sunrise and sunset times. Positive values are north of the equator; negative values are south.
• longitude (float): The longitude of the location for which you want to calculate sunrise and sunset times. Positive values are east of the Prime Meridian; negative values are west.
• date_str (str): The date for which to calculate the times, formatted as 'YYYY-MM-DD'.

Example Usage

Suppose you are planning a photography event and need to know the sunrise and sunset times to capture the best natural lighting:

import timestampprocessing as tsp

# Latitude and longitude for New York City
latitude = 40.7128
longitude = -74.0060

# Calculate sunrise and sunset times for October 1st, 2023
date_str = '2023-10-01'
sunrise, sunset = tsp.sunrise_sunset_time(latitude, longitude, date_str)
print(f"Sunrise: {sunrise}")
print(f"Sunset: {sunset}")

Converting UTC Time to Central Time

The convert_utc_to_central function is designed to convert a given UTC timestamp into Central Time (CT). This utility is particularly valuable for applications involving users or operations across different time zones, ensuring that time-sensitive data is correctly adjusted to local times.

Functionality

This function transforms a timestamp from Coordinated Universal Time (UTC) to Central Standard Time (CST) or Central Daylight Time (CDT), depending on daylight saving times.

Parameters

• timestamp_str (str): The timestamp string in UTC that needs to be converted.
• timestamp_format (str): The format of the timestamp string, which dictates how the string is parsed into a datetime object.

Example Usage

Suppose you have a UTC timestamp that represents the start time of an international virtual meeting, and you need to convert this time to Central Time for participants in that zone:

import timestampprocessing as tsp

# UTC timestamp
utc_timestamp = "2023-12-15-18-00-00"

# Convert UTC to Central Time
central_time = tsp.convert_utc_to_central(utc_timestamp, "%Y-%m-%d-%H-%M-%S")
print(f"Central Time: {central_time}")

Adjusting Timestamps

The adjust_timestamp function allows for the addition or subtraction of a specified number of seconds to or from a timestamp. This functionality is crucial for applications that need to manipulate time values dynamically, such as scheduling, reminders, or adjusting event times based on various conditions.

Functionality

This function is versatile in its ability to both advance and roll back timestamps, making it a valuable tool for time-sensitive operations where precise time adjustments are necessary.

Parameters

• timestamp_str (str): The timestamp string to be adjusted.
• interval_seconds (int): The number of seconds to add (positive value) or subtract (negative value).
• check_before (bool): A boolean flag that indicates whether to subtract (True) or add (False) the interval to the timestamp.
• timestamp_format (str): The format of the timestamp string, which ensures accurate parsing and formatting.

Example Usage

Suppose you are managing a project timeline and need to extend a deadline by 2 hours due to unforeseen circumstances:

import timestampprocessing as tsp

# Original timestamp of the deadline
deadline = "2023-11-01-15-00-00"

# Adjust the deadline by adding 7200 seconds (2 hours)
new_deadline = tsp.adjust_timestamp(deadline, 7200, False, "%Y-%m-%d-%H-%M-%S")
print(f"Adjusted Deadline: {new_deadline}")

Finding Closest Timestamps

The find_closest_timestamps function is designed to identify the closest timestamps before and after a given reference time that are multiples of a specified interval. This utility is particularly useful in time series analysis, event logging, or scheduling where aligning events to fixed intervals is required.

Functionality

This function calculates the nearest timestamps around a given reference point based on a regular time interval. It helps in aligning timestamps to a grid, which is useful for generating reports, setting up event triggers, or any application requiring standardized time intervals.

Parameters

• timestamp_str (str): The reference timestamp string around which to find the closest timestamps.
• interval_seconds (int): The interval in seconds to use for finding the closest timestamps.
• timestamp_format (str): The format of the timestamp string, ensuring it is parsed and formatted correctly.

Example Usage

Assuming you need to schedule tasks that should run closest to regular 15-minute intervals, and you receive a timestamp that doesn't exactly align:

import timestampprocessing as tsp

# Given timestamp that doesn't align with a 15-minute schedule
timestamp_str = "2023-08-01-12-07-35"

# Finding the closest timestamps before and after the given time
lower, upper = tsp.find_closest_timestamps(timestamp_str, 900, "%Y-%m-%d-%H-%M-%S")
print(f"Closest Lower Timestamp: {lower}")
print(f"Closest Upper Timestamp: {upper}")

Checking Time Interval Overlap

The is_time_overlap function determines whether two specified time intervals overlap. This utility is crucial for scheduling systems, resource allocation tasks, and any application where it's necessary to avoid conflicts between events scheduled in the same timeframe.

Functionality

This function checks if the periods defined by two pairs of start and end times overlap, providing a boolean result. This is particularly useful in planning and logistics, where overlapping times can lead to conflicts or resource overbooking.

Parameters

• event_start (str): The start time of the first interval.
• event_end (str): The end time of the first interval.
• interval_start (str): The start time of the second interval.
• interval_end (str): The end time of the second interval.
• timestamp_format (str, optional): The format of the timestamp strings, if not already datetime objects.

Example Usage

Assume you need to determine if a new meeting time conflicts with an already scheduled meeting:

import timestampprocessing as tsp

# Scheduled meeting time
scheduled_start = "2023-10-05-09-00-00"
scheduled_end = "2023-10-05-10-00-00"

# New meeting time proposal
new_meeting_start = "2023-10-05-09:30-00"
new_meeting_end = "2023-10-05-10:30-00"

# Check if the new meeting overlaps with the scheduled one
overlap = tsp.is_time_overlap(scheduled_start, scheduled_end, new_meeting_start, new_meeting_end)
print(f"Do the meeting times overlap? {'Yes' if overlap else 'No'}")

Generating Time Range Histogram Data

The get_time_range_histogram_data function creates a histogram of the number of events that overlap with each interval in a specified time range. This utility is particularly useful for analyzing the distribution and frequency of events over time, such as in traffic flow management, resource usage monitoring, or attendance tracking.

Functionality

This function calculates how many events occur within predefined intervals throughout a day or other time period. It's valuable for statistical analysis and planning, providing insights into peak times or identifying potential scheduling conflicts.

Parameters

• entries (list of dict): A list of dictionaries, each representing an event with start and end times.
• start_counting_time (str): The start time for counting events in the format "H-M-S", typically "00-00-00" for starting at midnight.
• end_counting_time (str): The end time for counting events in the format "H-M-S", typically "23-59-59" for ending at midnight.
• interval (int): The interval in minutes for which to count overlapping events.

Example Usage

Suppose you want to analyze traffic flow by counting the number of cars that pass a checkpoint every 30 minutes:

import timestampprocessing as tsp

# Sample data representing car passing times
entries = [
    {'start_time': '2023-07-01-12-00-00', 'end_time': '2023-07-01-12-05-00'},
    {'start_time': '2023-07-01-12-15-00', 'end_time': '2023-07-01-12-20-00'},
    {'start_time': '2023-07-01-12-25-00', 'end_time': '2023-07-01-12-35-00'}
]

# Generate a histogram for the 12 PM to 1 PM range with 30-minute intervals
histogram_data = tsp.get_time_range_histogram_data(entries, '12-00-00', '13-00-00', 30)
print("Histogram of traffic flow:")
for interval, count in histogram_data.items():
    print(f"{interval}: {count} cars passed")

Finding Missing Timestamps in a Directory

The find_missing_timestamps function is designed to identify gaps or missing timestamps in a sequence of files within a directory, typically used for monitoring data completeness in time-series data collected at regular intervals, such as sensor data or surveillance footage.

Functionality

This function scans through files in a specified directory, each named with a timestamp, and checks for expected intervals between timestamps. It's particularly useful for ensuring data integrity and completeness in automated data collection systems.

Parameters

• base_dir (str): The base directory containing timestamped files.
• start_time (str): The start time for checking files in the format "H-M", which determines when the expected sequence begins each day.
• end_time (str): The end time for checking files in the format "H-M", which marks when the expected sequence should end each day.
• interval (int): The expected interval in seconds between files, used to determine what counts as a missing timestamp.
• file_end (str): The file extension or ending pattern to identify relevant files in the directory.

Example Usage

Suppose you are monitoring a weather station that saves sensor readings every 15 minutes, and you need to verify data completeness for a particular day:

import timestampprocessing as tsp

# Path to the directory containing sensor data files
base_dir = "/path/to/sensor/data"

# Finding missing timestamps
missing_ts = tsp.find_missing_timestamps(base_dir, '00-00', '23-45', 900, '-data.log')
print("Missing timestamps:")
for date, timestamps in missing_ts.items():
    print(f"{date}: {timestamps}")

Comparing Timestamp Order

The compare_timestamp_order function assesses the chronological order of two timestamps. This utility is crucial for systems where event sequence validation is necessary, such as in workflow management, event logging, or conditional process triggering based on time criteria.

Functionality

This function compares two given timestamps to determine if one occurs before the other. It is designed to support both strict (exclusive) and non-strict (inclusive) comparisons, making it versatile for various use cases where precision in time ordering impacts the logic flow.

Parameters

• time1 (str): The first timestamp string to compare, typically representing the start or earlier time.
• time2 (str): The second timestamp string to compare, typically representing the end or later time.
• include (bool): Specifies whether the comparison is inclusive (True) of the exact timestamp or strictly before (False).

Example Usage

Suppose you need to determine if a task started on time based on scheduled and actual start times:

import timestampprocessing as tsp

# Scheduled and actual start times of a task
scheduled_start = "10-00-00"
actual_start = "10-00-00"

# Check if the task started on or before the scheduled time
on_time = tsp.compare_timestamp_order(actual_start, scheduled_start, include=True)
print(f"Did the task start on time? {'Yes' if on_time else 'No'}")

Finding Missing Timestamp Ranges

The find_missing_ranges function identifies ranges of missing timestamps in a sequence, based on provided lists of missing timestamps for each day. It is particularly useful in applications requiring continuous monitoring or data collection, such as environmental sensing, healthcare monitoring, or manufacturing process control.

Functionality

This function analyzes a dictionary of missing timestamps and calculates contiguous missing ranges, helping users understand prolonged gaps in data collection or event logging.

Parameters

• missing_timestamps (dict): A dictionary with days as keys and lists of missing timestamps (in strings) as values. Each list should contain timestamps where data is absent.
• start_time (str): The start time for the day, indicating when monitoring or data collection begins.
• end_time (str): The end time for the day, indicating when monitoring or data collection ends.
• interval (int): The interval in seconds, used to determine the threshold for grouping close timestamps into a single range.

Example Usage

Suppose you are managing a telemetry system that collects data every minute, and you need to identify any significant data collection gaps over a specific day:

import timestampprocessing as tsp

# Example missing timestamps reported by the system
missing_timestamps = {
    '2023-10-01': ['2023-10-01-00:15:00', '2023-10-01-00:16:00', '2023-10-01-05:00:00', '2023-10-01-05:01:00']
}

# Find missing ranges considering a 60-second interval for closeness
missing_ranges = tsp.find_missing_ranges(missing_timestamps, '00-00-00', '23-59-59', 60)
for day, ranges in missing_ranges.items():
    print(f"Day: {day}")
    for start, end in ranges:
        print(f"Missing from {start} to {end}")

Generating Timestamps

The generate_timestamps function is designed to create a list of timestamps at specified second intervals between a given start and end time. This utility is especially useful for applications that require scheduled tasks, simulations, or time-series analysis where consistent time intervals are necessary.

Functionality

This function generates a series of timestamps, ensuring that events or data points are evenly spaced over a defined period. It's valuable for setting up simulations, scheduling in industrial automation, or any scenario where precise timing between events is crucial.

Parameters

• start (str): The start time in 'YYYY-MM-DD HH:MM:SS' format.
• end (str): The end time in 'YYYY-MM-DD HH:MM:SS' format.
• interval_seconds (int): The interval in seconds between each generated timestamp.

Example Usage

Suppose you are setting up a simulation that requires data points every 30 minutes over a 24-hour period starting from midnight:

import timestampprocessing as tsp

# Define the start and end times
start = "2023-10-01 00:00:00"
end = "2023-10-02 00:00:00"

# Generate timestamps at 30-minute intervals
timestamps = tsp.generate_timestamps(start, end, 1800)  # 1800 seconds = 30 minutes
print("Generated Timestamps:")
for timestamp in timestamps:
    print(timestamp)

Finding Non-Missing Timestamp Ranges

The find_non_missing_timestamps function identifies continuous ranges of time that are not covered by the specified missing ranges. This utility is crucial for applications where it is important to understand when data or events are consistently present, such as in operational monitoring, quality control processes, or in ensuring compliance with expected service or operational standards.

Functionality

This function calculates the intervals within a total specified range that are not accounted for by a list of known missing periods. It's invaluable for filling gaps in schedules, ensuring coverage in surveillance or monitoring systems, and optimizing operational plans based on availability.

Parameters

• total_start (datetime): The start datetime of the total range to be examined.
• total_end (datetime): The end datetime of the total range to be examined.
• missing_ranges (list of tuples): A list of tuples, each containing the start and end datetimes of a missing range.
• interval_seconds (int): The granularity in seconds for checking the presence within the total range, affecting the precision of the identified non-missing ranges.

Example Usage

Suppose you are managing a factory that operates 24/7, and you have identified certain periods when equipment was down. You need to determine when the equipment was operational:

import timestampprocessing as tsp
from datetime import datetime

# Define the overall operational period
total_start = datetime(2023, 10, 1)
total_end = datetime(2023, 10, 2)

# List known downtimes
downtimes = [
    (datetime(2023, 10, 1, 2, 0), datetime(2023, 10, 1, 3, 0)),
    (datetime(2023, 10, 1, 5, 0), datetime(2023, 10, 1, 6, 0))
]

# Find operational periods
operational_periods = tsp.find_non_missing_timestamps(total_start, total_end, downtimes)
print("Operational Periods:")
for start, end in operational_periods:
    print(f"From {start} to {end}")

Merging Close or Overlapping Time Ranges

The merge_close_ranges function is designed to merge time ranges that are close to each other or overlapping, based on a specified threshold. This is particularly useful in scenarios where you need to consolidate event durations that may have small gaps or overlaps between them.

Functionality

This function takes a list of time range tuples (each tuple consists of a start and an end datetime) and a merge_threshold, which is a timedelta object specifying how close the time ranges need to be to consider them for merging.

Parameters

• missing_ranges (list of tuples): List of tuples, where each tuple contains start and end datetime objects representing individual time ranges.
• merge_threshold (timedelta): A timedelta object that specifies the maximum gap between ranges that should be considered for merging. Ranges closer than this threshold will be merged together.

Returns

• list of tuples: Returns a list of tuples, where each tuple represents a merged time range.

Example Usage

Here's how you can use the merge_close_ranges function to merge time ranges that are within two seconds of each other:

from datetime import datetime, timedelta
import timestampprocessing as tsp

# Example list of time ranges
time_ranges = [
    (datetime(2021, 7, 15, 12, 0, 0), datetime(2021, 7, 15, 12, 30, 0)),
    (datetime(2021, 7, 15, 12, 30, 1), datetime(2021, 7, 15, 13, 0, 0)),
    (datetime(2021, 7, 15, 14, 0, 0), datetime(2021, 7, 15, 14, 30, 0))
]

# Setting the merge threshold to 2 seconds
merge_threshold = timedelta(seconds=2)

# Merging close or overlapping ranges
merged_ranges = tsp.merge_close_ranges(time_ranges, merge_threshold)

for start, end in merged_ranges:
    print(f"Range from {start} to {end}")

Interpolating Timestamp Values

The interp_ts_vals function calculates interpolated values at specific times based on linear interpolation between two known data points. This function is ideal for applications such as data imputation, sensor data analysis, and financial forecasting where precise intermediate values are needed between two known data points.

Functionality

This function employs linear interpolation to estimate values at a given timestamp, based on the values at two bounding timestamps. It is particularly useful for filling gaps in datasets, enhancing the granularity of sparse data, or any situation where data points are missing or expected at times between recorded values.

Parameters

• start_time (str): The start time as a string in any recognizable datetime format, representing the first data point.
• end_time (str): The end time as a string in any recognizable datetime format, representing the second data point.
• start_value (float): The data value at the start time.
• end_value (float): The data value at the end time.
• current_time (str): The time at which the value needs to be interpolated, formatted as a string in the same format as the start and end times.

Example Usage

Suppose you have sensor data measuring temperature every hour, but you need to estimate the temperature at a half-hour mark:

import timestampprocessing as tsp

# Known temperature readings at 1:00 PM and 2:00 PM
start_time = '2023-07-01 13:00:00'
end_time = '2023-07-01 14:00:00'
start_value = 22.0  # Temperature in degrees Celsius
end_value = 24.0    # Temperature in degrees Celsius

# Time for which you need an estimated temperature
current_time = '2023-07-01 13:30:00'

# Interpolate the temperature at 1:30 PM
interpolated_value = tsp.interp_ts_vals(start_time, end_time, start_value, end_value, current_time)
print(f"Interpolated Temperature at {current_time}: {interpolated_value:.2f}°C")