Explorar guías rápidas · Python
Trabajar con fechas y marcas de tiempo
Analiza, compara, filtra, normaliza, localiza, convierte, agrupa y valida fechas y marcas de tiempo en pandas sin introducir errores de zona horaria ni de límites.
En esta página
- Problema
- Respuesta rápida
- Código / comandos
- 1. Analizar una columna datetime
- 2. Analizar explícitamente un formato conocido
- 3. Analizar las marcas de tiempo directamente como UTC
- 4. Comprobar si una columna datetime tiene zona horaria
- 5. Localizar marcas de tiempo naive en la zona horaria del origen
- 6. Convertir marcas de tiempo con zona horaria
- 7. Gestionar de forma deliberada la ambigüedad del horario de verano
- 8. Filtrar un día completo de forma segura
- 9. Filtrar un mes completo de forma segura
- 10. Filtrar marcas de tiempo con zona horaria usando límites coherentes
- 11. Filtrar por la fecha local del negocio
- 12. Extraer componentes de fecha y hora
- 13. Normalizar las marcas de tiempo a medianoche
- 14. Convertir a valores date de Python
- 15. Redondear las marcas de tiempo hacia abajo a un intervalo
- 16. Redondear marcas de tiempo
- 17. Agrupar por día con pd.Grouper
- 18. Agrupar por mes
- 19. Calcular diferencias de tiempo
- 20. Sumar desplazamientos de tiempo
- 21. Ordenar por marca de tiempo
- 22. Obtener la fila más reciente por entidad
- 23. Obtener la marca de tiempo del evento anterior
- 24. Comparar de forma segura marcas de tiempo de distintos orígenes
- 25. Usar merge_asof para joins por fecha de vigencia
- 26. Limitar la distancia temporal de las coincidencias con una tolerancia
- 27. Encontrar fechas no válidas o faltantes después del análisis
- 28. Comprobar el rango de fechas después del análisis
- 29. Comprobar marcas de tiempo duplicadas dentro de una clave de negocio
- Qué significa el resultado
- Qué revisar
- Muchos valores se convierten en NaT
- La marca de tiempo parece desplazada varias horas
- Los totales diarios difieren entre sistemas
- Faltan filas del final del día
- La duración es inesperadamente inferior a un día
- Los cambios de horario de verano producen horas locales ambiguas o inexistentes
- Notas de producción
- Almacena las marcas de tiempo de los eventos en UTC cuando sea posible
- No pierdas la información de zona horaria demasiado pronto
- Los valores solo de fecha y las marcas de tiempo son conceptos distintos
- Los intervalos semiabiertos evitan errores de límite
- El análisis puede ser costoso
- La conversión de zona horaria puede cambiar las fechas de los informes
- La aritmética de calendario difiere de las duraciones fijas
- Errores comunes
- 1. Comparar cadenas de fecha en lugar de marcas de tiempo analizadas
- 2. Usar tz_localize() cuando lo que quieres es tz_convert()
- 3. Marcar marcas de tiempo locales como UTC
- 4. Filtrar hasta 23:59:59
- 5. Usar .dt.date demasiado pronto
- 6. Usar .dt.seconds para duraciones completas
- 7. Ignorar los cambios de horario de verano
- 8. Agrupar por día marcas de tiempo UTC para un informe en hora local del negocio
- 9. Sobrescribir los fallos de análisis sin inspeccionarlos
- Siguiente paso
- Para profundizar
Problema
Las fechas y las marcas de tiempo parecen sencillas hasta que los datos de producción incluyen:
- varios formatos
- valores no válidos
- marcas de tiempo con y sin zona horaria (aware y naive)
- hora UTC y hora local mezcladas
- errores de límite al final del día
- cambios de horario de verano
- informes solo por fecha mezclados con marcas de tiempo precisas de eventos
- joins con datos de referencia que tienen fechas de vigencia
El objetivo es tratar el tiempo de forma explícita para que los filtros, las agrupaciones, las comparaciones, los joins y los informes sigan siendo correctos.
Tienes que responder:
- ¿La columna es realmente de tipo datetime?
- ¿Qué filas no se pudieron analizar?
- ¿Las marcas de tiempo tienen zona horaria o son naive?
- ¿Se conoce la zona horaria del origen?
- ¿Los datos deben almacenarse en UTC?
- ¿Los límites de los rangos de fechas son inclusivos o exclusivos?
- ¿Los periodos de agrupación se basan en UTC o en la hora local del negocio?
Respuesta rápida
Analiza de forma deliberada:
df["event_time"] = pd.to_datetime(
df["event_time"],
errors="coerce",
)
Inspecciona los fallos de análisis:
failed = df.loc[
df["event_time"].isna()
]
Filtra un mes con un intervalo semiabierto:
start = pd.Timestamp("2026-10-01")
end = pd.Timestamp("2026-11-01")
october = df.loc[
(df["event_time"] >= start)
& (df["event_time"] < end)
]
Para datos de producción con zona horaria, normaliza a UTC:
df["event_time"] = pd.to_datetime(
df["event_time"],
utc=True,
errors="coerce",
)
Después, convierte a hora local solo cuando la regla de negocio lo requiera.
Código / comandos
1. Analizar una columna datetime
df["event_time"] = pd.to_datetime(
df["event_time"],
errors="coerce",
)
errors="coerce" convierte los valores no válidos en NaT.
Esto es útil durante la ingesta, porque los valores incorrectos se vuelven visibles en lugar de lanzar un error y detenerlo todo de inmediato.
No sobrescribas la columna de origen antes de inspeccionar los fallos de conversión si el texto original importa para la depuración.
Más seguro durante la investigación:
parsed = pd.to_datetime(
df["event_time"],
errors="coerce",
)
failed = df.loc[
df["event_time"].notna()
& parsed.isna()
]
print(failed)
2. Analizar explícitamente un formato conocido
Si el formato de entrada es estable, especifícalo.
df["event_date"] = pd.to_datetime(
df["event_date"],
format="%Y-%m-%d",
errors="coerce",
)
Para marcas de tiempo:
df["event_time"] = pd.to_datetime(
df["event_time"],
format="%Y-%m-%d %H:%M:%S",
errors="coerce",
)
Los formatos explícitos aclaran la intención y ayudan a detectar cambios inesperados en el origen.
3. Analizar las marcas de tiempo directamente como UTC
df["event_time"] = pd.to_datetime(
df["event_time"],
utc=True,
errors="coerce",
)
Úsalo cuando:
- las marcas de tiempo del origen ya incluyen desplazamientos de zona horaria
- el origen está documentado como UTC
- quieres una representación coherente con zona horaria
Ten cuidado al analizar marcas de tiempo locales naive con utc=True.
Si el texto de origen representa la hora local de reloj, localízalo primero en lugar de fingir que estaba en UTC.
4. Comprobar si una columna datetime tiene zona horaria
print(df["event_time"].dtype)
Ejemplos:
datetime64[ns]
significa sin zona horaria (naive).
datetime64[ns, UTC]
significa con zona horaria, en UTC.
También puedes inspeccionar:
print(df["event_time"].dt.tz)
Para una Series datetime naive, esto devuelve None.
5. Localizar marcas de tiempo naive en la zona horaria del origen
Supón que se sabe que los valores de origen representan la hora local de Nueva York:
df["event_time"] = (
pd.to_datetime(
df["event_time"],
errors="coerce",
)
.dt.tz_localize("America/New_York")
)
Usa tz_localize() cuando las marcas de tiempo sean naive pero se conozca su zona horaria real.
No uses tz_convert() con marcas de tiempo naive.
6. Convertir marcas de tiempo con zona horaria
Una vez que las marcas de tiempo tienen zona horaria:
df["event_time_local"] = (
df["event_time"]
.dt.tz_convert("America/New_York")
)
Usa tz_convert() para representar el mismo instante en otra zona horaria.
El instante en el tiempo sigue siendo el mismo; solo cambia la representación mostrada en hora local de reloj.
7. Gestionar de forma deliberada la ambigüedad del horario de verano
La localización puede encontrarse con horas locales ambiguas o inexistentes.
Ejemplo:
localized = (
pd.to_datetime(df["event_time"], errors="coerce")
.dt.tz_localize(
"America/New_York",
ambiguous="NaT",
nonexistent="NaT",
)
)
Esto es más seguro para la investigación que adivinar en silencio.
Inspecciona las filas afectadas antes de elegir una regla de producción.
8. Filtrar un día completo de forma segura
Para marcas de tiempo precisas, prefiere un intervalo semiabierto.
start = pd.Timestamp("2026-10-04")
end = pd.Timestamp("2026-10-05")
day_rows = df.loc[
(df["event_time"] >= start)
& (df["event_time"] < end)
]
Esto incluye todas las marcas de tiempo del 4 de octubre sin depender de un 23:59:59.999999 artificial.
9. Filtrar un mes completo de forma segura
start = pd.Timestamp("2026-10-01")
end = pd.Timestamp("2026-11-01")
october = df.loc[
(df["event_time"] >= start)
& (df["event_time"] < end)
]
Este patrón es robusto para marcas de tiempo con precisión inferior al segundo.
10. Filtrar marcas de tiempo con zona horaria usando límites coherentes
Si la Series está en UTC con zona horaria:
start = pd.Timestamp(
"2026-10-01",
tz="UTC",
)
end = pd.Timestamp(
"2026-11-01",
tz="UTC",
)
filtered = df.loc[
(df["event_time"] >= start)
& (df["event_time"] < end)
]
No compares marcas de tiempo con zona horaria con límites sin zona horaria.
11. Filtrar por la fecha local del negocio
Supón que las marcas de tiempo se almacenan en UTC, pero los informes deben usar los días naturales de Nueva York.
Convierte antes de derivar la fecha local:
local_time = (
df["event_time"]
.dt.tz_convert("America/New_York")
)
df["local_date"] = local_time.dt.date
Después, filtra:
filtered = df.loc[
df["local_date"]
== pd.Timestamp("2026-10-04").date()
]
Esto importa para los eventos cercanos a la medianoche UTC.
12. Extraer componentes de fecha y hora
df["year"] = df["event_time"].dt.year
df["month"] = df["event_time"].dt.month
df["day"] = df["event_time"].dt.day
df["hour"] = df["event_time"].dt.hour
df["weekday"] = df["event_time"].dt.day_name()
Útil para:
- informes
- ingeniería de características (feature engineering)
- filtrado
- análisis por hora del día
No materialices de forma permanente componentes que puedes derivar a bajo costo, salvo que se necesiten aguas abajo.
13. Normalizar las marcas de tiempo a medianoche
df["event_date"] = (
df["event_time"]
.dt.normalize()
)
En las marcas de tiempo con zona horaria, la zona horaria se conserva.
Úsalo cuando necesites una clave de día de tipo datetime en lugar de objetos date de Python.
14. Convertir a valores date de Python
df["event_date"] = (
df["event_time"]
.dt.date
)
Esto produce objetos date de Python y, por lo general, da una Series de tipo object.
Para operaciones temporales nativas de pandas, .dt.normalize() o .dt.floor("D") suelen conservar un dtype datetime más útil.
15. Redondear las marcas de tiempo hacia abajo a un intervalo
Por hora:
df["event_hour"] = (
df["event_time"]
.dt.floor("h")
)
Por día:
df["event_day"] = (
df["event_time"]
.dt.floor("D")
)
Úsalo para agrupar marcas de tiempo exactas en intervalos de informe.
16. Redondear marcas de tiempo
df["rounded_time"] = (
df["event_time"]
.dt.round("15min")
)
Redondea solo cuando el intervalo más cercano sea de verdad la regla deseada.
Para los intervalos de informe, el redondeo hacia abajo (floor) suele ser más predecible.
17. Agrupar por día con pd.Grouper
daily = (
df.groupby(
pd.Grouper(
key="event_time",
freq="D",
)
)
.agg(
events=("event_id", "count"),
revenue=("revenue", "sum"),
)
.reset_index()
)
Así la clave temporal se mantiene como datetime.
18. Agrupar por mes
monthly = (
df.groupby(
pd.Grouper(
key="event_time",
freq="MS",
)
)
.agg(
events=("event_id", "count"),
revenue=("revenue", "sum"),
)
.reset_index()
)
MS significa frecuencia de inicio de mes.
Usa ME cuando quieras explícitamente etiquetas de fin de mes, en una versión de pandas que admita ese alias.
19. Calcular diferencias de tiempo
df["processing_time"] = (
df["completed_at"]
- df["started_at"]
)
Resultado:
timedelta64[ns]
Convertir a segundos:
df["processing_seconds"] = (
df["processing_time"]
.dt.total_seconds()
)
No uses .dt.seconds cuando necesites la duración completa.
.dt.seconds es solo el componente de segundos dentro del día.
20. Sumar desplazamientos de tiempo
df["expires_at"] = (
df["created_at"]
+ pd.Timedelta(hours=24)
)
Días:
df["next_day"] = (
df["event_time"]
+ pd.Timedelta(days=1)
)
Para desplazamientos que tienen en cuenta el calendario:
df["next_month"] = (
df["event_time"]
+ pd.offsets.MonthBegin(1)
)
Usa desplazamientos de calendario cuando «el mes siguiente» sea lógica de calendario de negocio y no un número fijo de días.
21. Ordenar por marca de tiempo
df = df.sort_values(
["customer_id", "event_time"]
)
Esto es importante antes de:
- rellenar hacia delante (forward fill)
- rellenar hacia atrás (backward fill)
- cálculos móviles
- seleccionar el registro más reciente
- análisis de secuencias
Nunca supongas que el orden de las filas del origen es cronológico.
22. Obtener la fila más reciente por entidad
latest = (
df.sort_values(
["customer_id", "event_time"]
)
.groupby(
"customer_id",
as_index=False,
)
.tail(1)
)
Esto conserva la fila real asociada a la marca de tiempo más reciente.
No uses:
groupby().agg("max")
para reconstruir una fila «más reciente» a partir de columnas no relacionadas.
23. Obtener la marca de tiempo del evento anterior
df = df.sort_values(
["customer_id", "event_time"]
)
df["previous_event_time"] = (
df.groupby("customer_id")["event_time"]
.shift(1)
)
df["seconds_since_previous"] = (
df["event_time"]
- df["previous_event_time"]
).dt.total_seconds()
Útil para:
- reconstrucción de sesiones (sessionization)
- análisis de huecos entre eventos
- cálculos de latencia
- detección de solicitudes repetidas
24. Comparar de forma segura marcas de tiempo de distintos orígenes
Antes de comparar, normaliza ambos lados.
Ejemplo:
left_time = pd.to_datetime(
left["event_time"],
utc=True,
errors="coerce",
)
right_time = pd.to_datetime(
right["event_time"],
utc=True,
errors="coerce",
)
Después, compara o haz merge.
No compares una Series UTC con zona horaria con una Series local naive suponiendo que la diferencia es solo de formato.
25. Usar merge_asof para joins por fecha de vigencia
Ejemplo: asociar a cada evento el último precio vigente antes de ese evento.
events = events.sort_values(
["product_id", "event_time"]
)
prices = prices.sort_values(
["product_id", "effective_time"]
)
result = pd.merge_asof(
events,
prices,
left_on="event_time",
right_on="effective_time",
by="product_id",
direction="backward",
)
Úsalo cuando la igualdad exacta de marcas de tiempo no sea la regla de negocio.
Valida:
- el orden de clasificación
- la coherencia de las zonas horarias
- la clave de entidad
- la dirección
- la tolerancia, si corresponde
26. Limitar la distancia temporal de las coincidencias con una tolerancia
result = pd.merge_asof(
events,
prices,
left_on="event_time",
right_on="effective_time",
by="product_id",
direction="backward",
tolerance=pd.Timedelta("7D"),
)
Esto evita coincidencias con datos de referencia demasiado antiguos.
Usa una tolerancia solo cuando la regla de negocio defina una separación máxima significativa.
27. Encontrar fechas no válidas o faltantes después del análisis
parsed = pd.to_datetime(
df["event_time_raw"],
errors="coerce",
)
invalid = df.loc[
df["event_time_raw"].notna()
& parsed.isna()
]
print(invalid)
Esta es una comprobación crítica de la ingesta.
Una llamada correcta a pd.to_datetime() con errors="coerce" puede seguir ocultando valores de origen incorrectos si no inspeccionas las conversiones forzadas.
28. Comprobar el rango de fechas después del análisis
print(df["event_time"].min())
print(df["event_time"].max())
Úsalo para detectar:
- fechas futuras
- fechas inesperadamente antiguas
- años mal analizados
- desplazamientos de zona horaria
- periodos que faltan en el origen
29. Comprobar marcas de tiempo duplicadas dentro de una clave de negocio
duplicates = df.loc[
df.duplicated(
subset=["customer_id", "event_time"],
keep=False,
)
].sort_values(
["customer_id", "event_time"]
)
print(duplicates)
Una marca de tiempo duplicada puede ser válida.
La pregunta importante es si la clave de negocio y la granularidad de los eventos permiten varias filas en el mismo instante.
Qué significa el resultado
| Concepto | Significado |
|---|---|
datetime64[ns] |
dtype datetime de pandas/NumPy sin zona horaria. |
datetime64[ns, UTC] |
dtype datetime con zona horaria, en UTC. |
pd.Timestamp |
Escalar de pandas que representa una fecha/hora. |
NaT |
Valor datetime/timedelta faltante. |
tz_localize() |
Asigna una zona horaria a marcas de tiempo naive sin cambiar la hora de reloj. |
tz_convert() |
Convierte marcas de tiempo con zona horaria a otra zona horaria conservando el instante. |
Timedelta |
Duración entre marcas de tiempo o desplazamiento de tiempo fijo. |
DateOffset |
Desplazamiento que tiene en cuenta el calendario, como un avance de un mes o de un día hábil. |
floor() |
Redondea hacia abajo hasta un límite temporal. |
normalize() |
Pone la hora del día a medianoche conservando el contexto de fecha y zona horaria. |
Qué revisar
Muchos valores se convierten en NaT
Esto significa que el análisis falló.
Posibles causas:
- cambió el formato
- formatos mezclados
- fechas imposibles
- texto de zona horaria
- datos de origen mal formados
Inspecciona las cadenas originales.
La marca de tiempo parece desplazada varias horas
Probablemente hay una confusión de zona horaria.
Comprueba:
- la zona horaria del origen
- si el origen ya estaba en UTC
- si
tz_localize()ytz_convert()se usaron en el orden correcto
Los totales diarios difieren entre sistemas
Comprueba si los sistemas agrupan por:
- fecha UTC
- fecha local del negocio
- zona horaria del servidor
- zona horaria del usuario
El mismo evento puede pertenecer a días naturales distintos según la zona usada para los informes.
Faltan filas del final del día
Esto suele deberse a filtrar con:
timestamp <= "2026-10-31"
que representa la medianoche al inicio del día.
Usa un intervalo semiabierto que termine en el día o el mes siguiente.
La duración es inesperadamente inferior a un día
Comprueba si el código usó:
timedelta.dt.seconds
en lugar de:
timedelta.dt.total_seconds()
Los cambios de horario de verano producen horas locales ambiguas o inexistentes
Es el comportamiento esperado en las zonas horarias con cambios de horario de verano.
Gestiona la ambigüedad de forma explícita en lugar de adivinar en silencio.
Notas de producción
Almacena las marcas de tiempo de los eventos en UTC cuando sea posible
UTC suele ser la representación canónica más segura para:
- el almacenamiento de eventos
- los sistemas entre regiones
- las API
- el procesamiento distribuido
- los data lakes
Convierte a la hora local del negocio en la frontera de los informes o la presentación, cuando sea necesario.
No pierdas la información de zona horaria demasiado pronto
Convertir marcas de tiempo con zona horaria en marcas de tiempo naive puede volver ambigua su interpretación posterior.
Conserva la zona horaria hasta que la regla de negocio exija explícitamente lo contrario.
Los valores solo de fecha y las marcas de tiempo son conceptos distintos
Ejemplos:
2026-10-04
2026-10-04T15:27:18Z
El primero es una fecha de calendario.
El segundo es un instante en el tiempo.
No los modeles como si fueran intercambiables.
Los intervalos semiabiertos evitan errores de límite
Prefiere:
start <= timestamp < next_start
en lugar de construir manualmente una marca de tiempo máxima de final de día.
Este patrón es más fácil de razonar y funciona con cualquier precisión de marca de tiempo.
El análisis puede ser costoso
En DataFrames grandes:
- analiza una sola vez
- evita conversiones repetidas
- especifica los formatos conocidos cuando corresponda
- selecciona solo las columnas necesarias
- lleva el filtrado por fecha al motor de almacenamiento o de consultas cuando sea posible
La conversión de zona horaria puede cambiar las fechas de los informes
Una marca de tiempo UTC cercana a la medianoche puede pasar al día local anterior tras la conversión.
Convierte siempre antes de derivar las partes de fecha local del negocio.
La aritmética de calendario difiere de las duraciones fijas
Un mes no siempre tiene 30 días.
Usa DateOffset o frecuencias de calendario para las reglas basadas en el calendario.
Usa Timedelta para duraciones transcurridas fijas.
Errores comunes
1. Comparar cadenas de fecha en lugar de marcas de tiempo analizadas
La comparación de cadenas puede parecer que funciona con formatos ISO, pero es frágil y semánticamente incorrecta para la lógica general de fechas.
Analiza primero.
2. Usar tz_localize() cuando lo que quieres es tz_convert()
Usa:
tz_localize -> de marca de tiempo naive a marca de tiempo con zona horaria
tz_convert -> de una zona horaria a otra zona horaria
Resuelven problemas distintos.
3. Marcar marcas de tiempo locales como UTC
Esto cambia el significado de los datos.
Si 08:00 era la hora local de Nueva York, no asignes UTC sin más.
Localiza primero en Nueva York y después convierte a UTC.
4. Filtrar hasta 23:59:59
Esto todavía puede omitir marcas de tiempo con mayor precisión.
Usa el siguiente límite con <.
5. Usar .dt.date demasiado pronto
Convierte las marcas de tiempo en objetos date de Python y pierde la hora del día.
Conserva las marcas de tiempo hasta que de verdad necesites una semántica de solo fecha.
6. Usar .dt.seconds para duraciones completas
.dt.seconds excluye los días completos.
Usa .dt.total_seconds().
7. Ignorar los cambios de horario de verano
Las horas locales pueden ser ambiguas o inexistentes.
Gestiónalas de forma explícita.
8. Agrupar por día marcas de tiempo UTC para un informe en hora local del negocio
Convierte primero a la zona horaria del negocio.
De lo contrario, los eventos cercanos a la medianoche pueden caer en el día de informe equivocado.
9. Sobrescribir los fallos de análisis sin inspeccionarlos
errors="coerce" es útil, pero puede ocultar datos incorrectos si nunca revisas los nuevos valores NaT.
¿Te resultó útil este contenido?
¿Qué podríamos mejorar?
Gracias — esto me ayuda a mejorar Javi Builds.
Mantente al día
Recibe solo las novedades de Javi Builds que realmente te interesan.
Revisa tu bandeja de entrada
Te he enviado un enlace de confirmación. Tu suscripción se activará cuando la confirmes.