timestamp_stats

timestamp_stats

TimestampStatistics

TimestampStatistics(
    dataframe: DataFrame, time_column: str = "systime"
)

Bases: Base

Provides class methods to calculate statistics on timestamp columns in a pandas DataFrame. The default column for calculations is 'systime'.

count_null classmethod

count_null(
    dataframe: DataFrame, time_column: str = "systime"
) -> int

Returns the number of null (NaN) values in the timestamp column.

Parameters:

Name	Type	Description	Default
dataframe	DataFrame	Input DataFrame.	required
time_column	str	Name of the timestamp column to analyze. Default "systime".	'systime'

Returns:

Type	Description
int	Number of missing timestamps.

count_not_null classmethod

count_not_null(
    dataframe: DataFrame, time_column: str = "systime"
) -> int

Returns the number of non-null (valid) timestamps in the column.

Parameters:

Name	Type	Description	Default
dataframe	DataFrame	Input DataFrame.	required
time_column	str	Name of the timestamp column to analyze. Default "systime".	'systime'

Returns:

Type	Description
int	Number of valid timestamps.

earliest_timestamp classmethod

earliest_timestamp(
    dataframe: DataFrame, time_column: str = "systime"
) -> pd.Timestamp

Returns the earliest timestamp in the column.

Parameters:

Name	Type	Description	Default
dataframe	DataFrame	Input DataFrame.	required
time_column	str	Name of the timestamp column to analyze. Default "systime".	'systime'

Returns:

Type	Description
Timestamp	The earliest timestamp; NaT when there is none.

latest_timestamp classmethod

latest_timestamp(
    dataframe: DataFrame, time_column: str = "systime"
) -> pd.Timestamp

Returns the latest timestamp in the column.

Parameters:

Name	Type	Description	Default
dataframe	DataFrame	Input DataFrame.	required
time_column	str	Name of the timestamp column to analyze. Default "systime".	'systime'

Returns:

Type	Description
Timestamp	The latest timestamp; NaT when there is none.

timestamp_range classmethod

timestamp_range(
    dataframe: DataFrame, time_column: str = "systime"
) -> pd.Timedelta

Returns the time range (difference) between the earliest and latest timestamps.

Parameters:

Name	Type	Description	Default
dataframe	DataFrame	Input DataFrame.	required
time_column	str	Name of the timestamp column to analyze. Default "systime".	'systime'

Returns:

Type	Description
Timedelta	Latest minus earliest timestamp; NaT when there is none.

most_frequent_timestamp classmethod

most_frequent_timestamp(
    dataframe: DataFrame, time_column: str = "systime"
) -> pd.Timestamp | None

Returns the most frequent timestamp in the column.

Parameters:

Name	Type	Description	Default
dataframe	DataFrame	Input DataFrame.	required
time_column	str	Name of the timestamp column to analyze. Default "systime".	'systime'

Returns:

Type	Description
Timestamp | None	The most frequent timestamp (the earliest on a tie), or None when the column holds no timestamp.

count_most_frequent_timestamp classmethod

count_most_frequent_timestamp(
    dataframe: DataFrame, time_column: str = "systime"
) -> int

Returns the count of the most frequent timestamp in the column.

Parameters:

Name	Type	Description	Default
dataframe	DataFrame	Input DataFrame.	required
time_column	str	Name of the timestamp column to analyze. Default "systime".	'systime'

Returns:

Type	Description
int	Occurrences of the most frequent timestamp; 0 when there is none.

year_distribution classmethod

year_distribution(
    dataframe: DataFrame, time_column: str = "systime"
) -> pd.Series

Returns the distribution of timestamps per year.

Parameters:

Name	Type	Description	Default
dataframe	DataFrame	Input DataFrame.	required
time_column	str	Name of the timestamp column to analyze. Default "systime".	'systime'

Returns:

Type	Description
Series	Series of timestamp counts indexed by year, most frequent first.

month_distribution classmethod

month_distribution(
    dataframe: DataFrame, time_column: str = "systime"
) -> pd.Series

Returns the distribution of timestamps per month.

Parameters:

Name	Type	Description	Default
dataframe	DataFrame	Input DataFrame.	required
time_column	str	Name of the timestamp column to analyze. Default "systime".	'systime'

Returns:

Type	Description
Series	Series of timestamp counts indexed by month number (1-12), most frequent first.

weekday_distribution classmethod

weekday_distribution(
    dataframe: DataFrame, time_column: str = "systime"
) -> pd.Series

Returns the distribution of timestamps per weekday.

Parameters:

Name	Type	Description	Default
dataframe	DataFrame	Input DataFrame.	required
time_column	str	Name of the timestamp column to analyze. Default "systime".	'systime'

Returns:

Type	Description
Series	Series of timestamp counts indexed by weekday (0=Monday, 6=Sunday), most frequent first.

hour_distribution classmethod

hour_distribution(
    dataframe: DataFrame, time_column: str = "systime"
) -> pd.Series

Returns the distribution of timestamps per hour of the day.

Parameters:

Name	Type	Description	Default
dataframe	DataFrame	Input DataFrame.	required
time_column	str	Name of the timestamp column to analyze. Default "systime".	'systime'

Returns:

Type	Description
Series	Series of timestamp counts indexed by hour (0-23), most frequent first.

most_frequent_day classmethod

most_frequent_day(
    dataframe: DataFrame, time_column: str = "systime"
) -> int | None

Returns the most frequent day of the week (0=Monday, 6=Sunday).

Parameters:

Name	Type	Description	Default
dataframe	DataFrame	Input DataFrame.	required
time_column	str	Name of the timestamp column to analyze. Default "systime".	'systime'

Returns:

Type	Description
int | None	The most frequent weekday (0=Monday; the smallest on a tie), or None when there is no timestamp.

most_frequent_hour classmethod

most_frequent_hour(
    dataframe: DataFrame, time_column: str = "systime"
) -> int | None

Returns the most frequent hour of the day (0-23).

Parameters:

Name	Type	Description	Default
dataframe	DataFrame	Input DataFrame.	required
time_column	str	Name of the timestamp column to analyze. Default "systime".	'systime'

Returns:

Type	Description
int | None	The most frequent hour (0-23; the smallest on a tie), or None when there is no timestamp.

average_time_gap classmethod

average_time_gap(
    dataframe: DataFrame, time_column: str = "systime"
) -> pd.Timedelta

Returns the average time gap between consecutive timestamps.

Parameters:

Name	Type	Description	Default
dataframe	DataFrame	Input DataFrame.	required
time_column	str	Name of the timestamp column to analyze. Default "systime".	'systime'

Returns:

Type	Description
Timedelta	Mean gap between consecutive timestamps (in time order); NaT for fewer than 2 timestamps.

median_timestamp classmethod

median_timestamp(
    dataframe: DataFrame, time_column: str = "systime"
) -> pd.Timestamp

Returns the median timestamp in the column.

Parameters:

Name	Type	Description	Default
dataframe	DataFrame	Input DataFrame.	required
time_column	str	Name of the timestamp column to analyze. Default "systime".	'systime'

Returns:

Type	Description
Timestamp	The median timestamp; NaT when there is none.

standard_deviation_timestamps classmethod

standard_deviation_timestamps(
    dataframe: DataFrame, time_column: str = "systime"
) -> pd.Timedelta

Returns the standard deviation of the time differences between consecutive timestamps.

Parameters:

Name	Type	Description	Default
dataframe	DataFrame	Input DataFrame.	required
time_column	str	Name of the timestamp column to analyze. Default "systime".	'systime'

Returns:

Type	Description
Timedelta	Standard deviation of the gaps between consecutive timestamps; NaT for fewer than 3 timestamps.

timestamp_quartiles classmethod

timestamp_quartiles(
    dataframe: DataFrame, time_column: str = "systime"
) -> pd.Series

Returns the 25th, 50th (median), and 75th percentiles of the timestamps.

Parameters:

Name	Type	Description	Default
dataframe	DataFrame	Input DataFrame.	required
time_column	str	Name of the timestamp column to analyze. Default "systime".	'systime'

Returns:

Type	Description
Series	Series of the 25th, 50th and 75th percentile timestamps, indexed by quantile.

days_with_most_activity classmethod

days_with_most_activity(
    dataframe: DataFrame,
    time_column: str = "systime",
    n: int = 3,
) -> pd.Series

Returns the top N days with the most timestamp activity.

Parameters:

Name	Type	Description	Default
dataframe	DataFrame	Input DataFrame.	required
time_column	str	Name of the timestamp column to analyze. Default "systime".	'systime'
n	int	Number of days to return. Default 3.	3

Returns:

Type	Description
Series	Series of timestamp counts indexed by calendar date, most active first.