Metadata-Version: 2.4
Name: samphlyng
Version: 0.1.0
Summary: Finite-population sampling designs and estimators for Python
Author: Ricardo Antunes
Maintainer: Ricardo Antunes
License-Expression: GPL-2.0-or-later
Project-URL: Homepage, https://github.com/Rictunes/samphlyng
Project-URL: Documentation, https://github.com/Rictunes/samphlyng#readme
Project-URL: Repository, https://github.com/Rictunes/samphlyng.git
Project-URL: Issues, https://github.com/Rictunes/samphlyng/issues
Project-URL: Changelog, https://github.com/Rictunes/samphlyng/blob/main/CHANGELOG.md
Project-URL: TeachingSampling Reference, https://doi.org/10.32614/CRAN.package.TeachingSampling
Keywords: survey sampling,finite population,Horvitz-Thompson,probability sampling,statistics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: CREDITS.md
Requires-Dist: numpy>=1.23
Requires-Dist: pandas>=1.5
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: twine>=6; extra == "dev"
Dynamic: license-file

# Samphlyng

[![CI](https://github.com/Rictunes/samphlyng/actions/workflows/ci.yml/badge.svg)](https://github.com/Rictunes/samphlyng/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/samphlyng.svg)](https://pypi.org/project/samphlyng/)
[![Python](https://img.shields.io/pypi/pyversions/samphlyng.svg)](https://pypi.org/project/samphlyng/)
[![License: GPL v2+](https://img.shields.io/badge/license-GPL--2.0%2B-blue.svg)](LICENSE)

Samphlyng é um porte para Python do pacote R
[TeachingSampling](https://cran.r-project.org/package=TeachingSampling). Ele reúne
desenhos probabilísticos, probabilidades de inclusão, estimadores para populações
finitas, calibração e os três conjuntos de dados didáticos originais.

O principal material de referência deste projeto é o **TeachingSampling 4.1.1**,
desenvolvido pelo **Professor Hugo Andres Gutierrez Rojas** e publicado sob GPL
(>= 2). As fórmulas, os desenhos amostrais, os estimadores, os exemplos didáticos
e os conjuntos de dados usados como base para este porte vêm de seu trabalho.
Como este projeto deriva daquele material, Samphlyng também é distribuído sob
GPL-2.0-ou-posterior.

## Instalação

Quando a primeira versão estiver publicada no PyPI:

```bash
python -m pip install samphlyng
```

Diretamente do GitHub:

```bash
python -m pip install "samphlyng @ git+https://github.com/Rictunes/samphlyng.git"
```

Para desenvolvimento, dentro do repositório:

```bash
python -m pip install -e ".[dev]"
```

Execute os testes:

```bash
python -m pytest
```

Para gerar `wheel` e pacote-fonte:

```bash
python -m build
```

## Uso rápido

```python
import numpy as np
import samphlyng as sp

rng = np.random.default_rng(42)

# Amostra aleatória simples sem reposição; índices Python (base zero).
sample = sp.sample_si(N=100, n=10, random_state=rng)

# Inclusões PPS sem reposição e respectivas probabilidades.
x = np.array([52, 60, 75, 100, 50], dtype=float)
selected = sp.sample_pips(n=2, x=x, random_state=42)

# Estimação do total sob amostragem aleatória simples.
y = np.array([10.0, 13.0, 8.0, 15.0, 12.0])
result = sp.estimate_si(N=100, n=5, y=y)
print(result)

# Dados do pacote original.
lucy = sp.load_dataset("Lucy")
print(lucy.head())
```

As funções que devolvem posições usam índices base zero. Nas funções de seleção,
use `one_based=True` para obter os rótulos `1..N` usados no R.

## Equivalência da API

| TeachingSampling (R) | Samphlyng (Python) |
|---|---|
| `Deltakl` | `delta_kl` |
| `Domains` | `domains` |
| `E.1SI` / `E.2SI` | `estimate_one_stage_si` / `estimate_two_stage_si` |
| `E.BE` / `E.PO` | `estimate_bernoulli` / `estimate_poisson` |
| `E.Beta` | `estimate_beta` |
| `E.PPS` / `E.piPS` | `estimate_pps` / `estimate_pips` |
| `E.Quantile` | `estimate_quantile` |
| `E.SI` / `E.WR` / `E.SY` | `estimate_si` / `estimate_wr` / `estimate_systematic` |
| `E.STSI` / `E.STPPS` / `E.STpiPS` | `estimate_stratified_si` / `estimate_stratified_pps` / `estimate_stratified_pips` |
| `E.Trim` / `E.UC` | `trim_weights` / `estimate_ultimate_cluster` |
| `GREG.SI` / `Wk` | `estimate_greg_si` / `greg_weights` |
| `HH` / `HT` | `hansen_hurwitz` / `horvitz_thompson` |
| `IPFP` | `ipfp` |
| `Ik` / `IkRS` / `IkWR` | `inclusion_indicators` / `inclusion_indicators_random_size` / `inclusion_indicators_wr` |
| `OrderWR` | `ordered_support_wr` |
| `Pik` / `Pikl` | `inclusion_probabilities` / `joint_inclusion_probabilities` |
| `PikPPS` / `PikSTPPS` / `PikHol` | `pps_inclusion_probabilities` / `stratified_pps_inclusion_probabilities` / `holmberg_inclusion_probabilities` |
| `S.BE` / `S.PO` | `sample_bernoulli` / `sample_poisson` |
| `S.SI` / `S.WR` / `S.SY` | `sample_si` / `sample_wr` / `sample_systematic` |
| `S.PPS` / `S.piPS` | `sample_pps` / `sample_pips` |
| `S.STSI` / `S.STPPS` / `S.STpiPS` | `sample_stratified_si` / `sample_stratified_pps` / `sample_stratified_pips` |
| `Support` / `SupportRS` / `SupportWR` | `support` / `support_random_size` / `support_wr` |
| `T.SIC` | `cluster_totals` |
| `VarHT` / `VarSYGHT` | `variance_ht` / `variance_estimators` |
| `nk` / `p.WR` | `sample_counts` / `support_probabilities_wr` |

Aliases curtos como `s_si`, `e_si`, `ht`, `hh`, `pik`, `pikl` e
`deltakl` também são exportados.

## Retornos e diferenças intencionais

- Estimadores simples retornam `pandas.DataFrame`, com medidas nas linhas e
  variáveis nas colunas.
- Estimadores estratificados e regressões multivariadas retornam um dicionário
  de `DataFrame`, um por variável de interesse.
- Seletores retornam apenas os índices efetivamente escolhidos; `sample_pps` e
  `sample_pips` retornam também as probabilidades em um `DataFrame`.
- Validações impedem probabilidades inválidas, tamanhos impossíveis e laços
  infinitos em calibração ou aparo de pesos.
- A implementação preserva as fórmulas da versão R, corrigindo ambiguidades de
  indexação e efeitos colaterais entre colunas.

## Dados

```python
sp.list_datasets()
lucy = sp.load_dataset("lucy")
big_lucy = sp.load_dataset("BigLucy")
big_city = sp.load_dataset("BigCity")
```

`load_dataset` sempre devolve uma cópia como `pandas.DataFrame`.

## Licença e atribuição

GPL-2.0-ou-posterior. Consulte `LICENSE`.

### Créditos do material de referência

Este porte Python reconhece e credita expressamente o **Professor Hugo Andres
Gutierrez Rojas**, autor do pacote R TeachingSampling, como responsável pelo
material de referência que fundamenta este projeto. A autoria intelectual do
TeachingSampling, de suas formulações didáticas e dos dados originais permanece
com o Professor Hugo Andres Gutierrez Rojas.

Referência principal:

> Gutierrez Rojas, Hugo Andres. *TeachingSampling: Selection of Samples and
> Parameter Estimation in Finite Population*, versão 4.1.1. CRAN.
> DOI: [10.32614/CRAN.package.TeachingSampling](https://doi.org/10.32614/CRAN.package.TeachingSampling).

Consulte também [CREDITS.md](https://github.com/Rictunes/samphlyng/blob/main/CREDITS.md)
para a atribuição completa. O crédito
como material de referência não implica participação na manutenção ou endosso
deste porte Python pelo autor original.

## Projeto público

- Problemas e solicitações: [GitHub Issues](https://github.com/Rictunes/samphlyng/issues)
- Como contribuir: [CONTRIBUTING.md](https://github.com/Rictunes/samphlyng/blob/main/CONTRIBUTING.md)
- Política de segurança: [SECURITY.md](https://github.com/Rictunes/samphlyng/blob/main/SECURITY.md)
- Histórico de versões: [CHANGELOG.md](https://github.com/Rictunes/samphlyng/blob/main/CHANGELOG.md)
- Processo de publicação: [RELEASING.md](https://github.com/Rictunes/samphlyng/blob/main/RELEASING.md)
