Time Navigation

Bitmapist makes it easy to navigate through time-based event data using the next(), prev(), and delta() methods. These are available on all time-based event classes (HourEvents, DayEvents, WeekEvents, MonthEvents, YearEvents) and return a new event object for the adjusted time period.

This allows you to easily build reports that compare different time periods or iterate backward or forward in time.

prev() - Go Back One Period

The prev() method returns an event object for the immediately preceding time period.

from bitmapist import MonthEvents

# Get events for the current month
this_month = MonthEvents('active')

# Get events for last month
last_month = this_month.prev()

print(f"Users active this month: {len(this_month)}")
print(f"Users active last month: {len(last_month)}")

next() - Go Forward One Period

The next() method returns an event object for the immediately following time period.

from bitmapist import DayEvents

# Get events for today
today = DayEvents('signup')

# Get events for tomorrow
tomorrow = today.next()

print(f"Signups today: {len(today)}")
print(f"Signups tomorrow: {len(tomorrow)}") # Likely 0 unless events are pre-marked

delta() - Jump Through Time

For larger jumps, the delta(value) method allows you to move forward or backward by a specified number of periods. Use a positive integer to move forward and a negative integer to move backward.

Example: Monthly Retention for the Last Year

This example iterates backward through the last 12 months to calculate retention.

from bitmapist import MonthEvents

print("Monthly Retention Report:")
current_month = MonthEvents('active')

for i in range(12):
    # Go back `i` months from the current month
    target_month = current_month.delta(-i)

    # Go back one more month to get the prior period
    previous_month = target_month.prev()

    # Perform a bitwise AND to find retained users
    retained_users = previous_month & target_month

    if len(previous_month) > 0:
        retention_rate = (len(retained_users) / len(previous_month)) * 100
        print(f"- Month {target_month.year}-{target_month.month:02d}: {retention_rate:.2f}% retention from prior month")
    else:
        print(f"- Month {target_month.year}-{target_month.month:02d}: No data for prior month")

This uniform API across all time-based event classes makes your analytics code clean, reusable, and easy to understand.