Metadata-Version: 2.4
Name: pysinda
Version: 0.1.1
Summary: API Client for DataSINDA - INPE
Author-email: COENE INPE <datasinda.coene@inpe.br>
License-Expression: MIT
License-File: LICENSE
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Requires-Dist: numpy>=1.21.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: requests>=2.25.0
Description-Content-Type: text/markdown

# pySINDA Client Library

A library client `pySINDA` facilita a interação com a API do SINDA (Sistema Nacional de Dados Ambientais) para coletar e analisar dados de Plataformas de Coleta de Dados (PCDs). 

Esta biblioteca foi redesenhada para ser modular, eficiente e totalmente integrada com fluxos de ciência de dados e análise exploratória (EDA) usando Pandas e NumPy.

## Instalação

```bash
pip install pysinda
```

## Configuração

Para usar o cliente, você deve usar a chave de API fornecida pelo DataSINDA. O cliente `SindaClient` também 'utiliza variáveis de ambiente para evitar a exposição de credenciais no código:

- `SINDA_API_KEY`: Chave de autenticação (API Key) da API.

Você também pode passar a chave de API como parâmetro para o cliente `SindaClient`:

```python
client = SindaClient(api_key="sua_api_key")
```

## Uso Básico

```python
from pysinda import SindaClient

# Instanciando o cliente (carrega chave de API da variável de ambiente)
client = SindaClient()

# Ou passando os parâmetros explicitamente
client = SindaClient(api_key="sua_api_key")
```

---

## SindaClient Reference

A classe única `SindaClient` unifica todas as operações disponíveis na API do SINDA. A maioria dos métodos de dados suporta o parâmetro opcional `to_df=True` para retornar um DataFrame do Pandas diretamente.

### Métodos de Listagem de PCDs

#### `get_all(to_df=False)`
Retorna a lista completa com todas as PCDs e seus metadados.

#### `get_all_resumed(to_df=False)`
Retorna uma lista contendo apenas os campos principais das PCDs (`id`, `numero`, `ativo`, `proprietario`, `latitude`, `longitude`, `estado`, `cidade`).

#### `get_complete_pcds(to_df=False)`
Retorna a lista de PCDs que possuem todos os metadados principais preenchidos.

#### `get_incomplete_pcds(to_df=False)`
Retorna a lista de PCDs que possuem algum metadados principal ausente.

#### `get_pcds_by_owner(owner, to_df=False)`
Filtra a lista de PCDs pelo nome do proprietário (case-insensitive).

#### `get_pcds_by_state(state, to_df=False)`
Filtra a lista de PCDs pelo estado (sigla ou nome por extenso).

#### `get_public_pcds(to_df=False)`
Recupera a lista de todas as PCDs públicas.

#### `get_private_pcds(to_df=False)`
Recupera a lista de todas as PCDs de acesso privado.

### Métodos de Dados e Metadados de uma PCD

#### `get_pcd(idPCD, to_df=False)`
Recupera informações rápidas da PCD associada ao ID informado.

#### `get_period_availability(idPCD)`
Obtém o período de disponibilidade dos dados temporais no banco. Retorna um dicionário contendo as chaves `dataInicial` e `dataFinal`.

#### `get_sensors(idPCD)`
Retorna a lista dos sensores habilitados para a respectiva PCD.

#### `get_pcd_metadata(idPCD)`
Retorna os metadados completos da PCD.

#### `get_metadata_resumed(idPCD)`
Retorna um resumo dos metadados da PCD.

#### `get_owner(idPCD)`
Obtém os detalhes do proprietário cadastrado da PCD.

#### `is_private(idPCD)`
Verifica se os dados daquela PCD específica são privados.

#### `get_data(idPCD, data_inicial, data_final, to_df=False)`
Recupera a série temporal de medições dos sensores para o intervalo de datas solicitado.
*Nota:* Consultas maiores que 365 dias são automaticamente divididas em requisições anuais e agrupadas de forma transparente.

---

## Módulo de Análise de Dados (Analytics)

A biblioteca oferece funções integradas para o tratamento, controle de qualidade e análise exploratória rápida das séries temporais das PCDs.

```python
from pySINDA import SindaClient, clean_data, resample_time_series, compute_wind_components

client = SindaClient()
# Recupera dados brutos como DataFrame
df = client.get_data(idPCD=30847, data_inicial="2023-01-01", data_final="2023-02-01", to_df=True)

# 1. Trata outliers e interpola dados nulos
df_cleaned = clean_data(df, time_col='Data', fill_method='interpolate', outlier_threshold=3.0)

# 2. Decompõe velocidade e direção do vento em vetores U e V
df_wind = compute_wind_components(df_cleaned, speed_col='VelocidadeVento', dir_col='DirecaoVento')

# 3. Faz o resample para médias diárias
df_daily = resample_time_series(df_wind, time_col='Data', rule='D', agg='mean')
```

### Funções Disponíveis

#### `clean_data(df, time_col='Data', fill_method='interpolate', outlier_threshold=3.0)`
Identifica outliers estatísticos (baseado em Z-score) substituindo-os por `NaN`. Em seguida, preenche valores ausentes utilizando o método escolhido (`'interpolate'`, `'ffill'`, `'bfill'` ou `None`).

#### `detect_outliers(df, columns=None, threshold=3.0)`
Retorna um DataFrame booleano indicando quais posições contêm valores atípicos (Z-score acima do limite especificado).

#### `resample_time_series(df, time_col='Data', rule='D', agg='mean')`
Agrupa a série temporal de acordo com a frequência informada (ex: `'D'` para dia, `'H'` para hora, `'ME'` para mês) e calcula a agregação (ex: `'mean'`, `'sum'`, `'max'`, `'min'`).

#### `summarize_time_series(df, time_col='Data')`
Retorna um relatório geral contendo intervalo de datas, quantidade total de registros e porcentagens de valores ausentes e estatísticas básicas de cada sensor.

#### `compute_wind_components(df, speed_col, dir_col)`
Calcula as componentes zonais (U) e meridionais (V) do vento a partir da direção (em graus) e velocidade do vento. Ideal para análises meteorológicas e rosas dos ventos.

#### `plot_time_series(df, time_col='Data', variables=None)`
Plota subplots temporais para as variáveis numéricas do DataFrame de maneira automatizada. *(Requer matplotlib instalado)*.
