memga 1.1.0__tar.gz

memga-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sérgio Augusto Faria Salles
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

memga-1.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: memga
+Version: 1.1.0
+Summary: Multiple Choice Method (MEM): select a set of alternatives that complement each other, by exhaustive search or a genetic algorithm
+Author: Henrique Rego Monteiro da Hora
+Author-email: Sérgio Augusto Faria Salles <safsalles@hotmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/safsalles/portfolio-ds/tree/main/mem-ga
+Project-URL: Issues, https://github.com/safsalles/portfolio-ds/issues
+Keywords: multicriteria,decision-making,genetic-algorithm,selection,mem
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.0
+Requires-Dist: matplotlib>=3.8
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Dynamic: license-file
+
+# mem-ga
+
+*Leia em: [English](README.en.md)*
+
+O Método de Escolha Múltipla (MEM) escolhe um conjunto de alternativas que se completam, em vez de pegar as melhores uma a uma. Serve para montar equipes, carteiras, comitês, qualquer escolha em que o grupo importa mais que cada parte.
+
+Este repositório traz o método como um pacote Python, `memga`, com:
+
+- as duas regras de nota: a da tese que propôs o MEM (`media`) e a adaptação da minha dissertação (`minimo`), com a mesma interface;
+- duas buscas: testar todas as combinações, para problemas pequenos, e um algoritmo genético (MEM-GA), para os grandes;
+- vagas por grupo (por exemplo, 2 analistas e 1 gestor), complementação e pesos calculados dos dados, e um gráfico de radar.
+
+Dois exemplos fictícios de recrutamento mostram o uso: um pequeno, para acompanhar a conta, e um grande, com 300 candidatos. A aplicação em futebol, com os dados do Brasileirão 2017, fica na pasta vizinha, [football-analytics](../football-analytics/README.md).
+
+## Instalação
+
+Do PyPI:
+
+```bash
+pip install memga
+```
+
+Para mexer no código, na pasta `mem-ga`:
+
+```bash
+pip install -e ".[test]"
+python -m pytest
+```
+
+## Uso
+
+A função `memga()` faz tudo: monta a regra, roda a busca e compara com a escolha tradicional. Os dois exemplos fictícios vêm dentro do pacote.
+
+```python
+from memga import memga, load_example
+
+# 2 de 8 candidatos, testando todas as duplas
+print(memga(load_example("small"), size=2))
+
+# Equipe de 4 entre 300, com vagas por grupo, pelo algoritmo genético
+resultado = memga(
+    load_example("large"), method="ga", tau=0.54,
+    quotas={"analyst": 2, "engineer": 1, "manager": 1}, seed=1,
+)
+print(resultado.team, resultado.score)
+# ('P007', 'P038', 'P192', 'P276') 0.6785714285714286
+```
+
+Os argumentos principais são `method` (`"exhaustive"` ou `"ga"`), `rule` (`"mean"`, a da tese, ou `"minimum"`), `tau`, `quotas` e `config` (um `GAConfig`). Sem `rule`, a busca exaustiva usa `"mean"` e o algoritmo genético usa `"minimum"`. O resultado traz `team`, `score`, `ranking` (na busca exaustiva), `history` (no algoritmo genético) e `traditional`.
+
+Para usar os módulos separadamente, a partir da pasta `mem-ga`:
+
+```python
+from memga.busca import run_ga
+from memga.problema import load_problem
+from memga.regras import build_rule
+
+problem = load_problem("exemplos/recrutamento-grande/data")
+rule = build_rule(problem, "minimo", tau=0.54)
+vagas = {"analista": 2, "engenheiro": 1, "gestor": 1}
+result = run_ga(rule, problem.groups, vagas, size=4, seed=2026)
+print(sorted(problem.alternatives[i] for i in result.team), result.score)
+# ['P007', 'P038', 'P192', 'P276'] 0.6785714285714286
+```
+
+| Módulo | O que faz |
+| --- | --- |
+| `memga.problema` | `Problem` (alternativas, critérios, direção, pesos, grupos), `load_problem` para ler os CSVs e `normalize` |
+| `memga.pesos` | Complementação calculada dos dados (1 − \|r\|, como no CRITIC, dentro de cada grupo) e pesos por grupo |
+| `memga.regras` | As duas regras, `mean_rule` e `minimum_rule`, e `build_rule` para montar uma delas a partir de um `Problem` |
+| `memga.busca` | `exhaustive` (todas as combinações), `run_ga` (algoritmo genético) e `traditional_choice` (os melhores de cada grupo, para comparar) |
+| `memga.radar` | Gráfico de radar com um painel por conjunto |
+
+## O método
+
+1. **Normaliza as avaliações.** Cada critério vai para a faixa de 0 a 1, com 1 para a melhor avaliação. Nos critérios em que menos é melhor, a escala se inverte.
+2. **Avalia o conjunto em grupos de critérios.** Para cada grupo de critérios, junta o desempenho do conjunto, os pesos e a complementação entre esses critérios num valor.
+3. **Aplica o tau de corte.** O grupo de critérios conta 1 se o valor alcançar o tau, e 0 se não alcançar. É esse corte que impede um resultado muito alto de pagar um resultado baixo em outro grupo: o método não é compensatório.
+4. **Dá a nota.** A nota é a fração dos grupos de critérios que alcançam o tau.
+
+Com grupos de alternativas (cargos, posições), a complementação é calculada dentro de cada grupo, e cada grupo pesa mais os critérios em que se destaca.
+
+## As duas regras
+
+As duas recebem um conjunto e devolvem `(nota, desempate)`, por isso qualquer busca funciona com qualquer regra.
+
+| | `media` (tese) | `minimo` (adaptação) |
+| --- | --- | --- |
+| Critérios | Combinados n a n, com n = tamanho do conjunto | Combinados 2 a 2 |
+| Dentro do grupo de critérios | Média do desempenho (Equação 3.4 da tese) | Mínimo do desempenho |
+| Nota | Fração dos grupos de critérios que alcançam o tau | Fração dos pares que alcançam o tau |
+| Desempate | Média de `mínimo(valor, tau)` nos grupos | Média de `mínimo(valor, tau)` nos pares |
+
+**Por que a adaptação.** Na tese, os critérios são combinados na mesma quantidade das alternativas escolhidas. Num conjunto grande, como 10 de 18 critérios, cada combinação fica perto da média geral do conjunto, e as diferenças entre conjuntos somem. Com os critérios 2 a 2, cada par ainda mostra o que o conjunto tem e o que falta. E, com o mínimo no lugar da média, um critério forte não cobre um fraco dentro do par, então o método fica não compensatório também ali.
+
+**O desempate da regra `media` é novo.** Na tese, ela só rodava testando todas as combinações, e o empate ficava na mesma posição. O algoritmo genético precisa de um desempate para ter direção entre conjuntos com a mesma nota, então a regra `media` usa o mesmo desempate da `minimo`: quanto falta, em média, para os grupos alcançarem o tau.
+
+**Limite da regra `media`.** O número de grupos de critérios é C(critérios, n). Com 18 critérios e um conjunto de 10, são 43.758 grupos por avaliação, lento demais para o algoritmo genético. Acima de 10.000 grupos (`MAX_MEAN_GROUPS`), a regra recusa o problema com uma mensagem que diz os números e sugere a regra `minimo`. Testar todas as combinações também tem limite: acima de 20 milhões de avaliações, a busca exaustiva recusa o problema.
+
+## Exemplo pequeno: 2 de 8 candidatos
+
+```bash
+python exemplos/recrutamento-pequeno/exemplo.py
+python exemplos/recrutamento-pequeno/exemplo.py --regra minimo
+```
+
+São 8 candidatos com notas em 6 critérios, e a busca testa todas as 28 duplas. Os candidatos A1 e A2 têm as melhores médias, mas são parecidos: fortes em planejamento, logística e qualidade, e medianos em custos e pessoas. O A3 é o contrário.
+
+| Ordem | Média ponderada | MEM, regra `media` | % dos grupos | MEM, regra `minimo` | % dos pares |
+| --- | --- | --- | --- | --- | --- |
+| 1.º | A1 | A1, A3 | 66,7% | A1, A3 | 46,7% |
+| 1.º | | A2, A3 | 66,7% | A2, A3 | 46,7% |
+| 3.º | A2 | A1, A2 | 60,0% | A1, A2 | 33,3% |
+
+A escolha tradicional fica com A1 e A2, os dois primeiros pela média ponderada. Nas duas regras, essa dupla fica em 3.º lugar, e as melhores juntam um deles com o A3, que cobre o que falta. Com tau 0,24, as duas regras concordam no ranking do topo. A regra `minimo` dá notas menores, porque cada par vale o critério mais fraco.
+
+No radar, cada linha colorida é um candidato e a área cinza é a média da dupla. À esquerda, A1 e A2 quase se sobrepõem. À direita, A1 e A3 se completam.
+
+![Radar das duplas A1, A2 e A1, A3](images/radar_pequeno.png)
+
+O resultado depende do tau. Com a regra `media` e tau de 0,27 ou mais, o corte fica alto a ponto de só as notas muito altas de A1 e A2 passarem, e essa dupla volta ao 1.º lugar. Por isso o programa mostra o que muda com o tau um pouco acima e um pouco abaixo. Mais detalhes em [exemplos/recrutamento-pequeno](exemplos/recrutamento-pequeno/).
+
+## Exemplo grande: equipe de 4 entre 300 candidatos
+
+```bash
+python exemplos/recrutamento-grande/exemplo.py
+```
+
+São 300 candidatos fictícios (150 analistas, 90 engenheiros e 60 gestores), com notas em 8 critérios, para uma equipe de 2 analistas, 1 engenheiro e 1 gestor. Seriam mais de 60 milhões de equipes possíveis, então a busca é feita pelo algoritmo genético. A execução leva cerca de 20 segundos.
+
+| Equipe | Pessoas | Nota `media` | Nota `minimo` |
+| --- | --- | --- | --- |
+| Regra `media` | P050, P110 (analistas), P218 (engenheiro), P276 (gestor) | **50,0%** | 32,1% |
+| Regra `minimo` | P007, P038 (analistas), P192 (engenheiro), P276 (gestor) | 24,3% | **67,9%** |
+| Escolha tradicional | P038, P110 (analistas), P218 (engenheiro), P276 (gestor) | 48,6% | 53,6% |
+
+A escolha tradicional pega os mais fortes de cada cargo. Cada regra acha uma equipe melhor que ela pela própria nota, e as duas regras escolhem equipes diferentes: a `media` troca um analista e fica perto da tradicional, e a `minimo` troca um analista e o engenheiro. A equipe da `minimo` perde um pouco em dados e programação e ganha em comunicação, negociação e organização: fica mais equilibrada, porque cada par de critérios vale o mais fraco dos dois. O gestor é o mesmo nas três.
+
+![Radar das três equipes](images/radar_grande.png)
+
+O tau de cada regra foi escolhido para a nota não saturar: com o tau baixo demais, toda equipe passa em tudo; alto demais, ninguém passa. Testando de 0,01 a 1,00, ficou o valor em que a escolha tradicional chega mais perto de 50% (0,63 na `media` e 0,54 na `minimo`). Mais detalhes, e como os dados foram gerados, em [exemplos/recrutamento-grande](exemplos/recrutamento-grande/).
+
+## Formato dos dados
+
+`load_problem` lê uma pasta com estes arquivos:
+
+- `criteria.csv`: `criterion`, `direction` (1 quando mais é melhor e 0 quando mais é pior) e `weight`.
+- `alternatives.csv`: a coluna `alternative`, uma coluna por critério e, se houver vagas por grupo, a coluna `group`.
+- `complementarity.csv` (opcional): a matriz de complementação entre critérios, com a diagonal vazia. Sem ela, a complementação é calculada dos dados.
+
+## Conferência com a tese
+
+A regra `media`, com a busca exaustiva, foi conferida com a aplicação numérica da tese, cujos dados não estão neste repositório. Na escolha de 2, com tau de 0,20, as 45 duplas do Quadro 3.9 bateram. Com tau de 0,19 e 0,21, 44 de 45 bateram nos Quadros 3.10 e 3.11, e a dupla diferente (A1, A8) tem um grupo de critérios a mais ou a menos. Na escolha de 3, os 40 conjuntos legíveis do Quadro 3.15 bateram. Os testes guardam o ranking do exemplo pequeno para que isso não mude sem aviso.
+
+## Fonte
+
+O MEM foi proposto na tese *Método de Escolha Múltipla: uma proposta multicritério para seleção em conjunto de mais de uma alternativa*, de Henrique Rego Monteiro da Hora (Universidade Federal Fluminense, 2013). A regra `minimo` e o algoritmo genético vêm da dissertação *MEM-GA: Método de Escolha Múltipla com Algoritmo Genético aplicado à formação de equipes de futebol*, de Sérgio Augusto Faria Salles (Instituto Federal Fluminense, 2018), escrita em MATLAB e trazida aqui para Python.

memga-1.1.0/README.md

@@ -0,0 +1,157 @@
+# mem-ga
+
+*Leia em: [English](README.en.md)*
+
+O Método de Escolha Múltipla (MEM) escolhe um conjunto de alternativas que se completam, em vez de pegar as melhores uma a uma. Serve para montar equipes, carteiras, comitês, qualquer escolha em que o grupo importa mais que cada parte.
+
+Este repositório traz o método como um pacote Python, `memga`, com:
+
+- as duas regras de nota: a da tese que propôs o MEM (`media`) e a adaptação da minha dissertação (`minimo`), com a mesma interface;
+- duas buscas: testar todas as combinações, para problemas pequenos, e um algoritmo genético (MEM-GA), para os grandes;
+- vagas por grupo (por exemplo, 2 analistas e 1 gestor), complementação e pesos calculados dos dados, e um gráfico de radar.
+
+Dois exemplos fictícios de recrutamento mostram o uso: um pequeno, para acompanhar a conta, e um grande, com 300 candidatos. A aplicação em futebol, com os dados do Brasileirão 2017, fica na pasta vizinha, [football-analytics](../football-analytics/README.md).
+
+## Instalação
+
+Do PyPI:
+
+```bash
+pip install memga
+```
+
+Para mexer no código, na pasta `mem-ga`:
+
+```bash
+pip install -e ".[test]"
+python -m pytest
+```
+
+## Uso
+
+A função `memga()` faz tudo: monta a regra, roda a busca e compara com a escolha tradicional. Os dois exemplos fictícios vêm dentro do pacote.
+
+```python
+from memga import memga, load_example
+
+# 2 de 8 candidatos, testando todas as duplas
+print(memga(load_example("small"), size=2))
+
+# Equipe de 4 entre 300, com vagas por grupo, pelo algoritmo genético
+resultado = memga(
+    load_example("large"), method="ga", tau=0.54,
+    quotas={"analyst": 2, "engineer": 1, "manager": 1}, seed=1,
+)
+print(resultado.team, resultado.score)
+# ('P007', 'P038', 'P192', 'P276') 0.6785714285714286
+```
+
+Os argumentos principais são `method` (`"exhaustive"` ou `"ga"`), `rule` (`"mean"`, a da tese, ou `"minimum"`), `tau`, `quotas` e `config` (um `GAConfig`). Sem `rule`, a busca exaustiva usa `"mean"` e o algoritmo genético usa `"minimum"`. O resultado traz `team`, `score`, `ranking` (na busca exaustiva), `history` (no algoritmo genético) e `traditional`.
+
+Para usar os módulos separadamente, a partir da pasta `mem-ga`:
+
+```python
+from memga.busca import run_ga
+from memga.problema import load_problem
+from memga.regras import build_rule
+
+problem = load_problem("exemplos/recrutamento-grande/data")
+rule = build_rule(problem, "minimo", tau=0.54)
+vagas = {"analista": 2, "engenheiro": 1, "gestor": 1}
+result = run_ga(rule, problem.groups, vagas, size=4, seed=2026)
+print(sorted(problem.alternatives[i] for i in result.team), result.score)
+# ['P007', 'P038', 'P192', 'P276'] 0.6785714285714286
+```
+
+| Módulo | O que faz |
+| --- | --- |
+| `memga.problema` | `Problem` (alternativas, critérios, direção, pesos, grupos), `load_problem` para ler os CSVs e `normalize` |
+| `memga.pesos` | Complementação calculada dos dados (1 − \|r\|, como no CRITIC, dentro de cada grupo) e pesos por grupo |
+| `memga.regras` | As duas regras, `mean_rule` e `minimum_rule`, e `build_rule` para montar uma delas a partir de um `Problem` |
+| `memga.busca` | `exhaustive` (todas as combinações), `run_ga` (algoritmo genético) e `traditional_choice` (os melhores de cada grupo, para comparar) |
+| `memga.radar` | Gráfico de radar com um painel por conjunto |
+
+## O método
+
+1. **Normaliza as avaliações.** Cada critério vai para a faixa de 0 a 1, com 1 para a melhor avaliação. Nos critérios em que menos é melhor, a escala se inverte.
+2. **Avalia o conjunto em grupos de critérios.** Para cada grupo de critérios, junta o desempenho do conjunto, os pesos e a complementação entre esses critérios num valor.
+3. **Aplica o tau de corte.** O grupo de critérios conta 1 se o valor alcançar o tau, e 0 se não alcançar. É esse corte que impede um resultado muito alto de pagar um resultado baixo em outro grupo: o método não é compensatório.
+4. **Dá a nota.** A nota é a fração dos grupos de critérios que alcançam o tau.
+
+Com grupos de alternativas (cargos, posições), a complementação é calculada dentro de cada grupo, e cada grupo pesa mais os critérios em que se destaca.
+
+## As duas regras
+
+As duas recebem um conjunto e devolvem `(nota, desempate)`, por isso qualquer busca funciona com qualquer regra.
+
+| | `media` (tese) | `minimo` (adaptação) |
+| --- | --- | --- |
+| Critérios | Combinados n a n, com n = tamanho do conjunto | Combinados 2 a 2 |
+| Dentro do grupo de critérios | Média do desempenho (Equação 3.4 da tese) | Mínimo do desempenho |
+| Nota | Fração dos grupos de critérios que alcançam o tau | Fração dos pares que alcançam o tau |
+| Desempate | Média de `mínimo(valor, tau)` nos grupos | Média de `mínimo(valor, tau)` nos pares |
+
+**Por que a adaptação.** Na tese, os critérios são combinados na mesma quantidade das alternativas escolhidas. Num conjunto grande, como 10 de 18 critérios, cada combinação fica perto da média geral do conjunto, e as diferenças entre conjuntos somem. Com os critérios 2 a 2, cada par ainda mostra o que o conjunto tem e o que falta. E, com o mínimo no lugar da média, um critério forte não cobre um fraco dentro do par, então o método fica não compensatório também ali.
+
+**O desempate da regra `media` é novo.** Na tese, ela só rodava testando todas as combinações, e o empate ficava na mesma posição. O algoritmo genético precisa de um desempate para ter direção entre conjuntos com a mesma nota, então a regra `media` usa o mesmo desempate da `minimo`: quanto falta, em média, para os grupos alcançarem o tau.
+
+**Limite da regra `media`.** O número de grupos de critérios é C(critérios, n). Com 18 critérios e um conjunto de 10, são 43.758 grupos por avaliação, lento demais para o algoritmo genético. Acima de 10.000 grupos (`MAX_MEAN_GROUPS`), a regra recusa o problema com uma mensagem que diz os números e sugere a regra `minimo`. Testar todas as combinações também tem limite: acima de 20 milhões de avaliações, a busca exaustiva recusa o problema.
+
+## Exemplo pequeno: 2 de 8 candidatos
+
+```bash
+python exemplos/recrutamento-pequeno/exemplo.py
+python exemplos/recrutamento-pequeno/exemplo.py --regra minimo
+```
+
+São 8 candidatos com notas em 6 critérios, e a busca testa todas as 28 duplas. Os candidatos A1 e A2 têm as melhores médias, mas são parecidos: fortes em planejamento, logística e qualidade, e medianos em custos e pessoas. O A3 é o contrário.
+
+| Ordem | Média ponderada | MEM, regra `media` | % dos grupos | MEM, regra `minimo` | % dos pares |
+| --- | --- | --- | --- | --- | --- |
+| 1.º | A1 | A1, A3 | 66,7% | A1, A3 | 46,7% |
+| 1.º | | A2, A3 | 66,7% | A2, A3 | 46,7% |
+| 3.º | A2 | A1, A2 | 60,0% | A1, A2 | 33,3% |
+
+A escolha tradicional fica com A1 e A2, os dois primeiros pela média ponderada. Nas duas regras, essa dupla fica em 3.º lugar, e as melhores juntam um deles com o A3, que cobre o que falta. Com tau 0,24, as duas regras concordam no ranking do topo. A regra `minimo` dá notas menores, porque cada par vale o critério mais fraco.
+
+No radar, cada linha colorida é um candidato e a área cinza é a média da dupla. À esquerda, A1 e A2 quase se sobrepõem. À direita, A1 e A3 se completam.
+
+![Radar das duplas A1, A2 e A1, A3](images/radar_pequeno.png)
+
+O resultado depende do tau. Com a regra `media` e tau de 0,27 ou mais, o corte fica alto a ponto de só as notas muito altas de A1 e A2 passarem, e essa dupla volta ao 1.º lugar. Por isso o programa mostra o que muda com o tau um pouco acima e um pouco abaixo. Mais detalhes em [exemplos/recrutamento-pequeno](exemplos/recrutamento-pequeno/).
+
+## Exemplo grande: equipe de 4 entre 300 candidatos
+
+```bash
+python exemplos/recrutamento-grande/exemplo.py
+```
+
+São 300 candidatos fictícios (150 analistas, 90 engenheiros e 60 gestores), com notas em 8 critérios, para uma equipe de 2 analistas, 1 engenheiro e 1 gestor. Seriam mais de 60 milhões de equipes possíveis, então a busca é feita pelo algoritmo genético. A execução leva cerca de 20 segundos.
+
+| Equipe | Pessoas | Nota `media` | Nota `minimo` |
+| --- | --- | --- | --- |
+| Regra `media` | P050, P110 (analistas), P218 (engenheiro), P276 (gestor) | **50,0%** | 32,1% |
+| Regra `minimo` | P007, P038 (analistas), P192 (engenheiro), P276 (gestor) | 24,3% | **67,9%** |
+| Escolha tradicional | P038, P110 (analistas), P218 (engenheiro), P276 (gestor) | 48,6% | 53,6% |
+
+A escolha tradicional pega os mais fortes de cada cargo. Cada regra acha uma equipe melhor que ela pela própria nota, e as duas regras escolhem equipes diferentes: a `media` troca um analista e fica perto da tradicional, e a `minimo` troca um analista e o engenheiro. A equipe da `minimo` perde um pouco em dados e programação e ganha em comunicação, negociação e organização: fica mais equilibrada, porque cada par de critérios vale o mais fraco dos dois. O gestor é o mesmo nas três.
+
+![Radar das três equipes](images/radar_grande.png)
+
+O tau de cada regra foi escolhido para a nota não saturar: com o tau baixo demais, toda equipe passa em tudo; alto demais, ninguém passa. Testando de 0,01 a 1,00, ficou o valor em que a escolha tradicional chega mais perto de 50% (0,63 na `media` e 0,54 na `minimo`). Mais detalhes, e como os dados foram gerados, em [exemplos/recrutamento-grande](exemplos/recrutamento-grande/).
+
+## Formato dos dados
+
+`load_problem` lê uma pasta com estes arquivos:
+
+- `criteria.csv`: `criterion`, `direction` (1 quando mais é melhor e 0 quando mais é pior) e `weight`.
+- `alternatives.csv`: a coluna `alternative`, uma coluna por critério e, se houver vagas por grupo, a coluna `group`.
+- `complementarity.csv` (opcional): a matriz de complementação entre critérios, com a diagonal vazia. Sem ela, a complementação é calculada dos dados.
+
+## Conferência com a tese
+
+A regra `media`, com a busca exaustiva, foi conferida com a aplicação numérica da tese, cujos dados não estão neste repositório. Na escolha de 2, com tau de 0,20, as 45 duplas do Quadro 3.9 bateram. Com tau de 0,19 e 0,21, 44 de 45 bateram nos Quadros 3.10 e 3.11, e a dupla diferente (A1, A8) tem um grupo de critérios a mais ou a menos. Na escolha de 3, os 40 conjuntos legíveis do Quadro 3.15 bateram. Os testes guardam o ranking do exemplo pequeno para que isso não mude sem aviso.
+
+## Fonte
+
+O MEM foi proposto na tese *Método de Escolha Múltipla: uma proposta multicritério para seleção em conjunto de mais de uma alternativa*, de Henrique Rego Monteiro da Hora (Universidade Federal Fluminense, 2013). A regra `minimo` e o algoritmo genético vêm da dissertação *MEM-GA: Método de Escolha Múltipla com Algoritmo Genético aplicado à formação de equipes de futebol*, de Sérgio Augusto Faria Salles (Instituto Federal Fluminense, 2018), escrita em MATLAB e trazida aqui para Python.

memga-1.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "memga"
+version = "1.1.0"
+description = "Multiple Choice Method (MEM): select a set of alternatives that complement each other, by exhaustive search or a genetic algorithm"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Sérgio Augusto Faria Salles", email = "safsalles@hotmail.com" },
+    { name = "Henrique Rego Monteiro da Hora" },
+]
+keywords = ["multicriteria", "decision-making", "genetic-algorithm", "selection", "mem"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Mathematics",
+]
+dependencies = ["numpy>=2.0", "matplotlib>=3.8"]
+
+[project.urls]
+Homepage = "https://github.com/safsalles/portfolio-ds/tree/main/mem-ga"
+Issues = "https://github.com/safsalles/portfolio-ds/issues"
+
+[project.optional-dependencies]
+test = ["pytest>=8.0"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+memga = ["data/*/*.csv"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

memga-1.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

memga-1.1.0/src/memga/__init__.py

@@ -0,0 +1,25 @@
+"""MEM: Método de Escolha Múltipla, com busca exaustiva ou por algoritmo genético.
+
+Uso mais simples:
+
+    from memga import memga, load_example
+    print(memga(load_example("small"), size=2))
+"""
+
+from memga.api import MemgaResult, Ranked, load_example, memga
+from memga.busca import GAConfig, traditional_choice
+from memga.problema import Problem, load_problem
+
+__version__ = "1.1.0"
+
+__all__ = [
+    "GAConfig",
+    "MemgaResult",
+    "Problem",
+    "Ranked",
+    "__version__",
+    "load_example",
+    "load_problem",
+    "memga",
+    "traditional_choice",
+]

memga-1.1.0/src/memga/api.py

@@ -0,0 +1,161 @@
+"""A função de entrada do pacote: `memga()` escolhe um conjunto de alternativas.
+
+Ela junta o que está nos outros módulos: monta a regra de nota, roda a busca exaustiva ou
+o algoritmo genético e compara o resultado com a escolha tradicional.
+"""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import numpy as np
+
+from memga.busca import GAConfig, exhaustive, run_ga, traditional_choice
+from memga.problema import Problem, load_problem, normalize
+from memga.regras import build_rule
+
+DEFAULT_TAU = 0.24
+METHODS = ("exhaustive", "ga")
+RULES = ("mean", "minimum")
+_RULE_NAMES = {"mean": "media", "minimum": "minimo"}
+DATA_DIR = Path(__file__).resolve().parent / "data"
+EXAMPLES = {"small": "recruiting-small", "large": "recruiting-large"}
+
+
+@dataclass(frozen=True)
+class Ranked:
+    position: int
+    alternatives: tuple[str, ...]
+    score: float
+
+
+@dataclass
+class MemgaResult:
+    """O resultado de `memga()`.
+
+    `team` e `score` valem para os dois métodos: com a busca exaustiva, é o primeiro
+    conjunto da ordem. `ranking` só existe na busca exaustiva e `history` só no algoritmo
+    genético. `traditional` é a escolha tradicional e a nota dela na mesma regra.
+    """
+
+    team: tuple[str, ...]
+    score: float
+    method: str
+    rule: str
+    tau: float
+    size: int
+    problem: Problem
+    traditional: tuple[tuple[str, ...], float]
+    quotas: dict | None = None
+    seed: int | None = None
+    ranking: list[Ranked] = field(default_factory=list)
+    history: list[float] = field(default_factory=list)
+    payment: np.ndarray | None = None
+
+    def __str__(self):
+        search = "exhaustive search" if self.method == "exhaustive" else "genetic algorithm"
+        lines = [
+            f"Multiple Choice Method: {search}, {self.rule} rule, tau {self.tau:g}",
+            f"{len(self.problem.alternatives)} alternatives, {len(self.problem.criteria)} criteria, "
+            f"selecting {self.size}",
+            "",
+        ]
+        if self.method == "exhaustive":
+            lines.append(f"Best sets ({len(self.ranking)} tested):")
+            for item in self.ranking[:10]:
+                lines.append(f"  {item.position:>3}. {', '.join(item.alternatives):<24} {item.score:6.1%}")
+            if len(self.ranking) > 10:
+                lines.append(f"  ... {len(self.ranking) - 10} more")
+        else:
+            lines.append(f"Selected: {', '.join(self.team)} ({self.score:.1%})")
+            if self.seed is not None:
+                lines.append(f"Seed: {self.seed}")
+        names, score = self.traditional
+        lines += ["", f"Traditional choice (best one by one): {', '.join(names)} ({score:.1%})"]
+        if self.ranking and len(names) == self.size:
+            place = next((r.position for r in self.ranking if set(r.alternatives) == set(names)), None)
+            if place:
+                lines.append(f"It ranks {place} in the Multiple Choice Method.")
+        return "\n".join(lines)
+
+
+def load_example(name="small"):
+    """Carrega um dos exemplos que vêm com o pacote: "small" (8 candidatos) ou "large" (300)."""
+    if name not in EXAMPLES:
+        raise ValueError(f"Exemplo desconhecido: {name!r}. Use 'small' ou 'large'.")
+    return load_problem(DATA_DIR / EXAMPLES[name])
+
+
+def _check_quotas(quotas, problem):
+    if quotas is None:
+        return None
+    if problem.groups is None:
+        raise ValueError("`quotas` precisa de `groups` no problema.")
+    unknown = sorted(set(quotas) - set(problem.groups.tolist()))
+    if unknown:
+        raise ValueError(f"`quotas` cita grupos que não estão no problema: {', '.join(unknown)}.")
+    if any(int(q) != q or q < 0 for q in quotas.values()):
+        raise ValueError("`quotas` precisa ter números inteiros, de zero para cima.")
+    quotas = {group: int(q) for group, q in quotas.items() if q > 0}
+    if not quotas:
+        raise ValueError("`quotas` precisa pedir pelo menos 1 alternativa.")
+    return quotas
+
+
+def memga(problem, size=None, method="exhaustive", rule=None, tau=DEFAULT_TAU, quotas=None,
+          config=None, seed=None, on_progress=None):
+    """Escolhe o conjunto de alternativas que mais se complementam.
+
+    Parâmetros:
+        problem: um `Problem`, de `load_problem` ou `load_example`.
+        size: quantas alternativas escolher. Pode faltar quando há `quotas`.
+        method: "exhaustive" (testa todas as combinações e devolve a ordem completa) ou
+            "ga" (algoritmo genético, para problemas grandes demais para testar tudo).
+        rule: "mean" (a regra da tese) ou "minimum" (critérios 2 a 2, com o menor dos dois).
+            Por padrão, "mean" na busca exaustiva e "minimum" no algoritmo genético.
+        tau: o corte; uma combinação de critérios conta quando o valor chega nele.
+        quotas: vagas por grupo, como {"analyst": 2, "manager": 1}. Precisa de `groups`.
+        config: um `GAConfig`, para ajustar o algoritmo genético.
+        seed: semente, para repetir um resultado do algoritmo genético.
+        on_progress: função (iteração, total, melhor nota) chamada durante o algoritmo genético.
+    """
+    if method not in METHODS:
+        raise ValueError(f"Método desconhecido: {method!r}. Use 'exhaustive' ou 'ga'.")
+    if rule is None:
+        rule = "mean" if method == "exhaustive" else "minimum"
+    if rule not in RULES:
+        raise ValueError(f"Regra desconhecida: {rule!r}. Use 'mean' ou 'minimum'.")
+
+    quotas = _check_quotas(quotas, problem)
+    if size is None:
+        if quotas is None:
+            raise ValueError("Informe `size`, quantas alternativas escolher.")
+        size = sum(quotas.values())
+    elif int(size) != size or size < 1:
+        raise ValueError(f"`size` precisa ser um número inteiro de pelo menos 1, e veio {size}.")
+    elif quotas is not None and size != sum(quotas.values()):
+        raise ValueError(f"`size` é {size}, mas `quotas` soma {sum(quotas.values())}.")
+    size = int(size)
+    if size > len(problem.alternatives):
+        raise ValueError(
+            f"O conjunto pede {size} alternativas, mas os dados têm só {len(problem.alternatives)}."
+        )
+
+    fitted = build_rule(problem, _RULE_NAMES[rule], tau, size=size)
+    names = problem.alternatives
+    normalized = normalize(problem.values, problem.direction)
+    weights = problem.weights if problem.weights.sum() > 0 else np.ones_like(problem.weights)
+    chosen = traditional_choice(normalized * weights, size, problem.groups, quotas)
+    traditional = (tuple(names[i] for i in chosen), fitted.rate(tuple(sorted(chosen)))[0])
+
+    result = dict(method=method, rule=rule, tau=tau, size=size, problem=problem,
+                  traditional=traditional, quotas=quotas, seed=seed, payment=fitted.payment)
+    if method == "exhaustive":
+        ranking = [
+            Ranked(c.position, tuple(names[i] for i in c.alternatives), c.score)
+            for c in exhaustive(fitted, len(names), size, problem.groups, quotas)
+        ]
+        return MemgaResult(team=ranking[0].alternatives, score=ranking[0].score, ranking=ranking, **result)
+
+    found = run_ga(fitted, problem.groups, quotas, size, config or GAConfig(), seed, on_progress)
+    return MemgaResult(team=tuple(names[i] for i in found.team), score=found.score,
+                       history=found.history, **result)