Metadata-Version: 2.4
Name: fiscalpy
Version: 0.0.16
Summary: Paquete para la limpieza de datos fiscales en Colombia
Author-email: Carlos Ortiz <cjortizb@javeriana.edu.co>
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# FiscalPY

Funciones para limpieza de datasets fiscales en Colombia (por ahora solo incluye territorial y presupuesto general de la nación).

## Instalación

```bash
pip install fiscalpy
```

## ¿Cómo usarla?

### Presupuesto nacional

Para la limpieza del presupuesto nacional, se cuenta con dos funciones `limpieza_gastos_pgn` y `limpieza_ingresos_pgn`. Es importante que los datos provengan directamente de la página del Ministerio de Hacienda y Crédito Público de Colombia, y que la primera fila de los datasets sea la que da los nombres a las columnas.

Para emplearlo:

```
from fiscalpy import limpieza_gastos_pgn, limpieza_ingresos_pgn
import pandas as pd

gastos = pd.read_excel('gastos.xlsx')
rentas = pd.read_excel('rentas.xlsx')

gastos_limpios = limpieza_gastos_pgn(gastos)
rentas_limpias = limpieza_ingresos_pgn(gastos)
```

El resultado en cada caso son datasets normalizados, preparados para análisis descriptivo, tanto estadístico como gráfico.

### Territorial

Se tienen tres funciones: `limpieza_ingresos_territoriales`, `limpieza_gastos_territoriales`, `columnas_ingresos_territoriales`

```python
from fiscalpy import limpieza_ingresos_territoriales, limpieza_gastos_territoriales
```

Tanto la función de `limpieza_ingresos_territoriales` como de `limpieza_gastos_territoriales` soportan la normalización de los datos de ingresos y gastos, de ejecución y de programación, de las entidades territoriales. Lo primero que se debe hacer es importar los datasets con ayuda de `pandas`. Asegúrese de que la importación se realice de manera correcta o la función no se ejecutará correctamente.

Una vez se hayan importando los datos se puede utilizar la función apropiada para cada caso:

```python
import pandas as pd
from fiscalpy import limpieza_ingresos_territoriales

df = pd.read_excel('datos_ejecucion_2025.xlsx')

norm_data = limpieza_ingresos_territoriales(df, tipo='ejecucion')
```

En el argumento `tipo` de cada función se debe especificar si se está trabajando con datos de ejecución o con datos de programación.

La función de `columnas_ingresos_territoriales` permite generar tres columnas para las columnas de ingreso que agregan la información a partir de tres criterios. El primero agrega la información en tres categorías:

- Recursos propios
- Transferencias
- Recursos de capital

La segunda agrega la información en cuatro categorías:

- Ingresos tributarios
- Ingresos no tribugtarios
- Transferencias
- Recursos de capital

La tercera agrega la información teniendo en cuenta las fuentes de ingresos más relevantes tanto para municipios como para departamentos.

## Contratación

Existe una función `datos_abiertos` que permite extraer información de todo tipo de la página datos.gov.co. La función permite hacer filtros de diferentes tipos:

```md
    Parameters
    ----------
    dataset_id : str
        ID Socrata del dataset, por ejemplo "abcd-1234".

    token : str
        App token de Socrata.

    filtros : dict, optional
        Diccionario de filtros.

    **kwargs :
        Filtros simples adicionales.

    Operadores permitidos
    ---------------------
    eq          =
    ne          !=
    gt          >
    gte         >=
    lt          <
    lte         <=
    in          IN (...)
    not_in      NOT IN (...)
    between     BETWEEN ... AND ...
    not_between NOT BETWEEN ... AND ...
    like        LIKE
    not_like    NOT LIKE
    is_null     IS NULL
    not_null    IS NOT NULL
    """
```

Un ejemplo simple de su uso sería:

```python

dataset_id = 'jbjy-vk9h'
token = "socrata-token"
filtros = {
    "nit_entidad" : {"in" : ["900948953"]},
    "fecha_de_firma": {
        "gte": date(2022, 1, 1),
        "lt": date(2023, 1, 1)
    },}

df = datos_abiertos(
    dataset_id,
    token,
    filtros=filtros
)
```

Esta función traería los contratos desde el dataset de SECOP II - Contratos electrónicos de la Agencia Nacional de Tierras entre el 1ro de enero de 2022 y el 1ro de enero de 2023. Es necesario obtener un token de Socrata para agilizar las descargas.
