fn_registry/python/functions/datascience/profile_datetime.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, params, output, tested, tests, test_file_path, file_path

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	params	output	tested	tests	test_file_path	file_path
profile_datetime	function	py	datascience	1.0.0	pure	def profile_datetime(values: list) -> dict	Perfil minimo de una columna fecha/datetime para la cabecera del capitulo TIMESERIES de AutomaticEDA. Acepta datetime.date, datetime.datetime y strings ISO mezclados, parsea defensivamente e ignora lo no parseable (nunca lanza). Devuelve rango (min/max ISO), n, n_distinct, span_days, frecuencia inferida (daily/weekly/monthly/quarterly/yearly/irregular/unknown) a partir del paso mediano entre fechas distintas, is_regular (pasos ~constantes), n_gaps (huecos en la rejilla) y median_step_days. Solo stdlib (datetime + statistics).	statistics timeseries datetime profiling frequency eda automatic_eda python				false		datetime statistics	name desc values lista de valores fecha. Acepta datetime.date, datetime.datetime y strings ISO ('2021-06-28', '2021-06-28T00:00:00', '2021-06-28 12:00:00'). None, vacios y no parseables se ignoran; tz-aware se normaliza a naive. Si values es None o no iterable se trata como lista vacia.	dict SIEMPRE presente con: 'min'/'max' (ISO date YYYY-MM-DD o None), 'n' (valores parseables), 'n_distinct' (fechas unicas), 'span_days' (float o None), 'freq' (daily|weekly|monthly|quarterly|yearly|irregular|unknown), 'is_regular' (bool), 'n_gaps' (int), 'median_step_days' (float o None) y 'note' (str). Con <2 valores o una sola fecha distinta: freq='unknown', is_regular=False, n_gaps=0, median_step_days=None y nota. Nunca lanza.	true	test_serie_diaria_regular_golden test_serie_mensual_freq_monthly test_serie_con_hueco_cuenta_gaps test_strings_iso_mezclados_con_datetime test_lista_vacia_y_none_devuelve_unknown test_valores_no_parseables_ignorados test_span_days_correcto test_una_sola_fecha_es_coherente	python/functions/datascience/profile_datetime_test.py	python/functions/datascience/profile_datetime.py

Ejemplo

from datascience import profile_datetime
from datetime import date, datetime, timedelta

# Serie diaria regular de 30 dias
fechas = [date(2021, 1, 1) + timedelta(days=i) for i in range(30)]
res = profile_datetime(fechas)
res["freq"]              # -> "daily"
res["is_regular"]        # -> True
res["n_gaps"]            # -> 0
res["min"], res["max"]   # -> ("2021-01-01", "2021-01-30")
res["span_days"]         # -> 29.0

# Acepta strings ISO mezclados con objetos datetime/date; ignora lo no parseable
profile_datetime(["2021-06-28", datetime(2021, 6, 29, 12), "basura", None])["n"]   # -> 2

# Columna vacia o sin fechas validas
profile_datetime([])["freq"]   # -> "unknown" + note "datos insuficientes"

Cuando usarla

Cuando construyes la cabecera del capitulo TIMESERIES de un EDA y necesitas caracterizar la columna de fecha antes de modelar: que rango cubre, cada cuanto llegan los datos (frecuencia), si la cadencia es regular y si hay huecos en la rejilla temporal. Es el complemento de fecha al perfil numerico/categorico del TableProfile (cierra el datetime{}=None pendiente). Pasale la columna de fechas en bruto (tal cual venga de la BD: dates, datetimes o strings ISO) y usa freq + is_regular + n_gaps para decidir si conviene resamplear, rellenar huecos o desestacionalizar mas adelante.

Gotchas

• Es pura y stdlib-only, pero la inferencia de freq es heuristica por bandas sobre el paso mediano entre fechas distintas (se deduplica antes de medir). Cualquier paso fuera de las bandas conocidas (incluido sub-diario, p.ej. datos horarios) cae en "irregular": no hay banda hourly.
• El analisis de frecuencia/regularidad/huecos necesita >=2 fechas distintas. Con 0-1 valores parseables o una sola fecha unica, freq="unknown", median_step_days=None y n_gaps=0, pero min/max/span_days siguen siendo coherentes si hay al menos una fecha.
• min/max se reportan como ISO date (YYYY-MM-DD); la hora se conserva internamente para calcular span_days y median_step_days (que pueden ser fraccionarios con datetimes sub-diarios) pero no aparece en min/max.
• Los datetime con zona horaria se normalizan a naive (se descarta el tzinfo) para poder mezclarlos con fechas naive sin que las restas lancen; esto puede desplazar la fecha en datetimes con offset grande. Para EDA es despreciable.
• is_regular usa tolerancia ±25% sobre el paso mediano y umbral del 80% de los pasos dentro de banda; series de "primero de mes" (deltas 28-31) salen regulares.
• n_gaps solo se calcula cuando freq es una rejilla regular conocida; con freq "irregular" o "unknown" siempre es 0.