Metadata-Version: 2.1
Name: TimeStampProcessing
Version: 0.1.3
Summary: A package for timestamp-related data processing
Home-page: http://github.com/yourusername/TimeStampProcessing
Author: Wei Wang
Author-email: wwang487@wisc.edu
License: MIT
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown

# 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:

```bash
pip install TimeStampProcessing
```

## Setup
Import the package once and use the alias tsp to access all functionalities:
```python
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:

```python
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.

```python
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:

```python
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:

```python
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:

```python
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:

```python
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:

```python
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:

```python
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:

```python
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:

```python
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:

```python
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:

```python
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:

```python
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:

```python
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:

```python
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:

```python
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:

```python
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:

```python
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:

```python
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:

```python
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")
```



