Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

4.8 KB
Raw Blame
/* Copyright 2026 Marimo. All rights reserved. */

import type { StringFieldDef } from "vega-lite/types_unstable/channeldef.js";
import { Logger } from "@/utils/Logger";
import type { BinValue, BinValues } from "../types";

const READABLE_TIME_FORMAT = "%-I:%M:%S %p"; // e.g., 1:02:30 AM (no leading zero on hour)

/**
 * True when a bin has finite, non-null start/end suitable for quantitative /
 * temporal encodings. Rejects nulls and NaN (all-NaN hist garbage).
 */
export function isValidBinValue(value: BinValue): boolean {
  const { bin_start, bin_end } = value;
  if (bin_start == null || bin_end == null) {
    return false;
  }
  // Reject NaN and ±Infinity; they break quantitative/temporal encodings.
  if (typeof bin_start === "number" && !Number.isFinite(bin_start)) {
    return false;
  }
  if (typeof bin_end === "number" && !Number.isFinite(bin_end)) {
    return false;
  }
  return true;
}

export function getPartialTimeTooltip(
  values: BinValues,
): Partial<StringFieldDef<string>> {
  if (values.length === 0) {
    return {};
  }

  // Find first valid bin. `isValidBinValue` guarantees a non-null, finite
  // start, so only bail when no valid bin exists (nullish, not falsy — a
  // numeric `0` / epoch timestamp is a legitimate value).
  const value = values.find((v) => isValidBinValue(v))?.bin_start;
  if (value == null) {
    return {};
  }

  // If value is a year (2019, 2020, etc), we return empty as it bugs out when we return a time unit
  if (typeof value === "number" && value.toString().length === 4) {
    return {};
  }

  // If value is just time (00:00:00, 01:00:00, etc)
  if (typeof value === "string" && value.length === 8) {
    return {
      type: "temporal",
      timeUnit: "hoursminutesseconds",
      format: READABLE_TIME_FORMAT,
    };
  }

  // If value is a date (2019-01-01, 2020-01-01, etc)
  if (typeof value === "string" && value.length === 10) {
    return {
      type: "temporal",
      timeUnit: "yearmonthdate",
    };
  }

  // If value is a datetime (2019-01-01 00:00:00, 2020-01-01 00:00:00, 2023-05-15T01:00:00 etc)
  if (typeof value === "string" && value.length === 19) {
    const minimumValue = value; // non-null value
    const maximumValue = values[values.length - 1].bin_end;

    try {
      const minimumDate = new Date(minimumValue);
      const maximumDate = new Date(maximumValue as string);
      const timeDifference = maximumDate.getTime() - minimumDate.getTime();

      // If time difference is less than 1 day, we use hoursminutesseconds
      if (timeDifference < 1000 * 60 * 60 * 24) {
        return {
          type: "temporal",
          timeUnit: "hoursminutesseconds",
          format: READABLE_TIME_FORMAT,
        };
      }
    } catch (error) {
      Logger.debug("Error parsing date", error);
    }

    return {
      type: "temporal",
      timeUnit: "yearmonthdatehoursminutes",
    };
  }

  Logger.debug("Unknown time unit", value);

  return {
    type: "temporal",
    timeUnit: "yearmonthdate",
  };
}

/**
 * Calculate the bin step for a given set of values.
 * If the bin step is too small for a large range, it can crash the browser.
 *
 * @param values - The values to calculate the bin step for.
 * @returns The bin step.
 */
export function calculateBinStep(values: BinValues) {
  if (values.length === 0) {
    return 1;
  }

  const validValues = values.filter(isValidBinValue);

  if (validValues.length === 0) {
    return 1;
  }

  // Check the data types
  const firstStart = validValues[0].bin_start;
  const firstEnd = validValues[0].bin_end;

  // If values are strings or dates, we need to convert them to numbers
  let min: number;
  let max: number;

  // Use first and last values since binValues are sorted
  if (typeof firstStart === "number" && typeof firstEnd === "number") {
    const firstValue = validValues[0];
    const lastValue = validValues[validValues.length - 1];
    min = firstValue.bin_start as number;
    max = lastValue.bin_end as number;
  } else if (typeof firstStart === "string" || typeof firstEnd === "string") {
    // String data (likely dates) - convert to timestamps
    const firstValue = validValues[0];
    const lastValue = validValues[validValues.length - 1];
    const firstStart = new Date(firstValue.bin_start as string).getTime();
    const lastEnd = new Date(lastValue.bin_end as string).getTime();
    min = firstStart;
    max = lastEnd;
  } else {
    // Date objects - use first and last values since they're sorted
    const firstValue = validValues[0];
    const lastValue = validValues[validValues.length - 1];
    min = (firstValue.bin_start as Date).getTime();
    max = (lastValue.bin_end as Date).getTime();
  }

  const range = max - min;

  // Handle edge case where range is 0
  if (range === 0) {
    return 1;
  }

  const numBins = validValues.length;
  const step = range / numBins;

  // Ensure minimum step size
  return Math.max(step, 1);
}