aiskillstore/marketplace

Requisitos para los Archivos de Salida

Todos los archivos de Excel

Fuente profesional

• Use una fuente consistente y profesional (p. ej., Arial, Times New Roman) para todos los archivos, a menos que el usuario indique lo contrario.

Cero errores de fórmula

• Cada modelo de Excel DEBE entregarse con CERO errores de fórmula (#REF!, #DIV/0!, #VALUE!, #N/A, #NAME?).

Preservar plantillas existentes (al actualizar plantillas)

• Estudie y respete EXACTAMENTE el formato, estilo y convenciones existentes al modificar archivos.
• Nunca imponga formatos estandarizados en archivos que ya tienen patrones establecidos.
• Las convenciones de la plantilla existente SIEMPRE anulan estas directrices.

Modelos financieros

Estándares de codificación de colores

A menos que el usuario o la plantilla existente indiquen lo contrario.

Convenciones de colores estándar de la industria

• Texto azul (RGB: 0,0,255): Entradas fijas y números que el usuario cambiará para escenarios.
• Texto negro (RGB: 0,0,0): TODAS las fórmulas y cálculos.
• Texto verde (RGB: 0,128,0): Enlaces que extraen datos de otras hojas dentro del mismo libro.
• Texto rojo (RGB: 255,0,0): Enlaces externos a otros archivos.
• Fondo amarillo (RGB: 255,255,0): Supuestos clave que requieren atención o celdas que deben actualizarse.

Estándares de formato numérico

Reglas de formato requeridas

• Años: Formatear como cadenas de texto (p. ej., "2024" no "2.024").
• Moneda: Usar formato $#,##0; especificar SIEMPRE las unidades en los encabezados ("Ingresos ($mm)").
• Ceros: Usar formato numérico para mostrar todos los ceros como "-", incluidos los porcentajes (p. ej., "$#,##0;($#,##0);-").
• Porcentajes: Predeterminado a formato 0,0% (un decimal).
• Múltiplos: Formatear como 0,0x para múltiplos de valoración (EV/EBITDA, P/U).
• Números negativos: Usar paréntesis (123) no signo menos -123.

Reglas de construcción de fórmulas

Ubicación de supuestos

• Coloque TODOS los supuestos (tasas de crecimiento, márgenes, múltiplos, etc.) en celdas de supuestos separadas.
• Use referencias a celdas en lugar de valores fijos en las fórmulas.
• Ejemplo: Use =B5*(1+$B$6) en lugar de =B5*1,05.

Prevención de errores en fórmulas

• Verifique que todas las referencias a celdas sean correctas.
• Compruebe errores de desfase en rangos.
• Asegure la consistencia de las fórmulas en todos los períodos de proyección.
• Pruebe con casos límite (valores cero, números negativos).
• Verifique que no haya referencias circulares no intencionadas.

Requisitos de documentación para valores fijos

• Comente o incluya información en celdas adyacentes (si está al final de la tabla). Formato: "Fuente: [Sistema/Documento], [Fecha], [Referencia específica], [URL si aplica]".
• Ejemplos:
  • "Fuente: 10-K de la empresa, FY2024, Página 45, Nota de Ingresos, [URL de SEC EDGAR]"
  • "Fuente: 10-Q de la empresa, Q2 2025, Anexo 99.1, [URL de SEC EDGAR]"
  • "Fuente: Terminal Bloomberg, 15/08/2025, AAPL US Equity"
  • "Fuente: FactSet, 20/08/2025, Pantalla de Estimaciones de Consenso"

Creación, edición y análisis de archivos XLSX

Descripción general

Un usuario puede pedirle que cree, edite o analice el contenido de un archivo .xlsx. Dispone de diferentes herramientas y flujos de trabajo para distintas tareas.

Requisitos importantes

LibreOffice necesario para el recálculo de fórmulas: Puede asumir que LibreOffice está instalado para recalcular valores de fórmulas usando el script scripts/recalc.py. El script configura automáticamente LibreOffice en la primera ejecución, incluso en entornos aislados donde los sockets Unix están restringidos (gestionado por scripts/office/soffice.py).

Lectura y análisis de datos

Análisis de datos con pandas

Para análisis de datos, visualización y operaciones básicas, use pandas, que ofrece potentes capacidades de manipulación de datos:

import pandas as pd

# Leer Excel
df = pd.read_excel('archivo.xlsx')  # Predeterminado: primera hoja
todas_hojas = pd.read_excel('archivo.xlsx', sheet_name=None)  # Todas las hojas como diccionario

# Analizar
df.head()      # Vista previa de datos
df.info()      # Información de columnas
df.describe()  # Estadísticas

# Escribir Excel
df.to_excel('salida.xlsx', index=False)

Flujos de trabajo con archivos Excel

CRÍTICO: Use fórmulas, no valores fijos

Siempre use fórmulas de Excel en lugar de calcular valores en Python y fijarlos. Esto asegura que la hoja de cálculo siga siendo dinámica y actualizable.

❌ INCORRECTO - Fijar valores calculados

# Mal: Calcular en Python y fijar el resultado
total = df['Ventas'].sum()
hoja['B10'] = total  # Fija 5000

# Mal: Calcular tasa de crecimiento en Python
crecimiento = (df.iloc[-1]['Ingresos'] - df.iloc[0]['Ingresos']) / df.iloc[0]['Ingresos']
hoja['C5'] = crecimiento  # Fija 0,15

# Mal: Cálculo de promedio en Python
promedio = sum(valores) / len(valores)
hoja['D20'] = promedio  # Fija 42,5

✅ CORRECTO - Usar fórmulas de Excel

# Bien: Dejar que Excel calcule la suma
hoja['B10'] = '=SUM(B2:B9)'

# Bien: Tasa de crecimiento como fórmula de Excel
hoja['C5'] = '=(C4-C2)/C2'

# Bien: Promedio usando función de Excel
hoja['D20'] = '=AVERAGE(D2:D19)'

Esto aplica a TODOS los cálculos: totales, porcentajes, ratios, diferencias, etc. La hoja de cálculo debe poder recalcularse cuando los datos de origen cambien.

Flujo de trabajo común

1. Elegir herramienta: pandas para datos, openpyxl para fórmulas/formato.
2. Crear/Cargar: Crear nuevo libro o cargar archivo existente.
3. Modificar: Añadir/editar datos, fórmulas y formato.
4. Guardar: Escribir en archivo.
5. Recalcular fórmulas (OBLIGATORIO SI USA FÓRMULAS): Usar el script scripts/recalc.py

   python scripts/recalc.py salida.xlsx
   

6. Verificar y corregir errores:
   • El script devuelve JSON con detalles de errores.
   • Si status es errors_found, revise error_summary para tipos y ubicaciones específicos.
   • Corrija los errores identificados y recalcule de nuevo.
   • Errores comunes a corregir:
     • #REF!: Referencias a celdas no válidas.
     • #DIV/0!: División por cero.
     • #VALUE!: Tipo de dato incorrecto en fórmula.
     • #NAME?: Nombre de fórmula no reconocido.

Crear nuevos archivos Excel

# Usando openpyxl para fórmulas y formato
from openpyxl import Workbook
from openpyxl.styles import Font, PatternFill, Alignment

wb = Workbook()
hoja = wb.active

# Añadir datos
hoja['A1'] = 'Hola'
hoja['B1'] = 'Mundo'
hoja.append(['Fila', 'de', 'datos'])

# Añadir fórmula
hoja['B2'] = '=SUM(A1:A10)'

# Formato
hoja['A1'].font = Font(bold=True, color='FF0000')
hoja['A1'].fill = PatternFill('solid', start_color='FFFF00')
hoja['A1'].alignment = Alignment(horizontal='center')

# Ancho de columna
hoja.column_dimensions['A'].width = 20

wb.save('salida.xlsx')

Editar archivos Excel existentes

# Usando openpyxl para preservar fórmulas y formato
from openpyxl import load_workbook

# Cargar archivo existente
wb = load_workbook('existente.xlsx')
hoja = wb.active  # o wb['NombreHoja'] para una hoja específica

# Trabajar con múltiples hojas
for nombre_hoja in wb.sheetnames:
    hoja = wb[nombre_hoja]
    print(f"Hoja: {nombre_hoja}")

# Modificar celdas
hoja['A1'] = 'Nuevo Valor'
hoja.insert_rows(2)  # Insertar fila en posición 2
hoja.delete_cols(3)  # Eliminar columna 3

# Añadir nueva hoja
nueva_hoja = wb.create_sheet('NuevaHoja')
nueva_hoja['A1'] = 'Datos'

wb.save('modificado.xlsx')

Recálculo de fórmulas

Los archivos Excel creados o modificados con openpyxl contienen fórmulas como cadenas de texto, pero no valores calculados. Use el script proporcionado scripts/recalc.py para recalcular las fórmulas:

python scripts/recalc.py <archivo_excel> [segundos_timeout]

Ejemplo:

python scripts/recalc.py salida.xlsx 30

El script:

• Configura automáticamente la macro de LibreOffice en la primera ejecución.
• Recalcula todas las fórmulas en todas las hojas.
• Escanea TODAS las celdas en busca de errores de Excel (#REF!, #DIV/0!, etc.).
• Devuelve JSON con ubicaciones y recuentos de errores detallados.
• Funciona tanto en Linux como en macOS.

Lista de verificación de fórmulas

Verificaciones rápidas para asegurar que las fórmulas funcionan correctamente:

Verificación esencial

• Probar 2-3 referencias de muestra: Verificar que extraen los valores correctos antes de construir el modelo completo.
• Mapeo de columnas: Confirmar que las columnas de Excel coinciden (p. ej., columna 64 = BL, no BK).
• Desfase de filas: Recordar que las filas de Excel están indexadas desde 1 (fila 5 de DataFrame = fila 6 de Excel).

Errores comunes

• Manejo de NaN: Verificar valores nulos con pd.notna().
• Columnas al extremo derecho: Los datos fiscales a menudo están en columnas 50+.
• Múltiples coincidencias: Buscar todas las ocurrencias, no solo la primera.
• División por cero: Verificar denominadores antes de usar / en fórmulas (#DIV/0!).
• Referencias incorrectas: Verificar que todas las referencias a celdas apunten a las celdas previstas (#REF!).
• Referencias entre hojas: Usar el formato correcto (Hoja1!A1) para enlazar hojas.

Estrategia de prueba de fórmulas

• Empezar pequeño: Probar fórmulas en 2-3 celdas antes de aplicarlas de forma general.
• Verificar dependencias: Comprobar que todas las celdas referenciadas en las fórmulas existen.
• Probar casos límite: Incluir valores cero, negativos y muy grandes.

Interpretación de la salida de scripts/recalc.py

El script devuelve JSON con detalles de errores:

{
  "status": "success",           // o "errors_found"
  "total_errors": 0,              // Número total de errores
  "total_formulas": 42,           // Número de fórmulas en el archivo
  "error_summary": {              // Solo presente si se encuentran errores
    "#REF!": {
      "count": 2,
      "locations": ["Hoja1!B5", "Hoja1!C10"]
    }
  }
}

Mejores prácticas

Selección de librerías

• pandas: Ideal para análisis de datos, operaciones masivas y exportación de datos simple.
• openpyxl: Ideal para formato complejo, fórmulas y características específicas de Excel.

Trabajar con openpyxl

• Los índices de celda comienzan en 1 (fila=1, columna=1 se refiere a la celda A1).
• Use data_only=True para leer valores calculados: load_workbook('archivo.xlsx', data_only=True).
• Advertencia: Si se abre con data_only=True y se guarda, las fórmulas se reemplazan con valores y se pierden permanentemente.
• Para archivos grandes: Use read_only=True para lectura o write_only=True para escritura.
• Las fórmulas se preservan pero no se evalúan; use scripts/recalc.py para actualizar los valores.

Trabajar con pandas

• Especifique tipos de datos para evitar problemas de inferencia: pd.read_excel('archivo.xlsx', dtype={'id': str}).
• Para archivos grandes, lea columnas específicas: pd.read_excel('archivo.xlsx', usecols=['A', 'C', 'E']).
• Maneje fechas correctamente: pd.read_excel('archivo.xlsx', parse_dates=['columna_fecha']).

Directrices de estilo de código

IMPORTANTE: Al generar código Python para operaciones de Excel:

• Escriba código Python mínimo y conciso sin comentarios innecesarios.
• Evite nombres de variables verbosos y operaciones redundantes.
• Evite declaraciones print innecesarias.

Para los propios archivos Excel:

• Añada comentarios a las celdas con fórmulas complejas o supuestos importantes.
• Documente las fuentes de datos para valores fijos.
• Incluya notas para cálculos clave y secciones del modelo.