Basicamente, a taxonomia é uma ciência que se dedica a organizar os seres vivos de forma hierárquica, considerando caracteres comuns entre eles. A cada nível hierárquico que se avança, mais específico é o grupo (ou, nesse caso, táxon) onde o organismo de interesse estará alocado.

Embora esse conceito seja mais conhecido quando aplicado à classificação dos seres vivos, é possível adotar o mesmo conceito para vários outros grupos. Ao identificarmos padrões, por exemplo, em prefixos do transporte público, placas de carros, números de série de vários utensílios, vemos na prática as possibilidades de organização de tudo o que está ao nosso redor baseando-se em suas características, desde as mais comuns, chegando até o caractere mais específico possível, o mais único para aquele objeto de interesse.

Na pesquisa clínica, também não é diferente. Dentre muitos padrões relacionados às boas práticas preconizadas pelas maiores autoridades na área, alguns sistemas de codificação estão presentes. Um bom exemplo é a classificação ATC, que é o foco deste artigo.

A Classificação ATC (Anatomical Therapeutic Chemical Code) é uma referência internacional utilizada para catalogar substâncias com ação terapêutica. Isso inclui, por exemplo, medicamentos usados diariamente para aliviar ou tratar uma ampla variedade de doenças. Nos estudos clínicos, a classificação ATC é considerada o padrão-ouro para o monitoramento e pesquisa de diversos medicamentos administráveis.

A Taxonomia do ATC

Assim como em uma classificação biológica, o ATC também começa de um universo mais amplo (o grupo anatômico) rumo a grupos mais específicos (classes de medicamentos, grupos de moléculas, entre outros); o que diferencia é que, basicamente, em vez de um nome latino (como Canis lupus familiaris para os cães domésticos), o ATC retorna um código sequencial, refletindo cada grupo o qual aquela substância terapêutica pertence.

Esse código sequencial é dividido em cinco níveis, a saber:

1. Nível 1 – Domínio ou Grupo Anatômico (letra inicial, ex.: A, B, C)

2. Nível 2 – Subgrupo terapêutico principal (ex.: A10 – Drogas usadas no diabetes)

3. Nível 3 – Subgrupo terapêutico/farmacológico (ex.: A10B)

4. Nível 4 – Subgrupo químico/terapêutico/farmacológico (ex.: A10BA)

5. Nível 5 – Substância química (ex.: A10BA02 – Metformina, com DDD, dose, via, etc.)

O que será feito aqui

Organizando nossos pensamentos e ações, isto é o que será feito nesse artigo:

• Acesso à página da lista ATC;

• Reconhecimento dos dados de interesse, através da identificação e entendimento da estrutura em HTML da página;

• Web scraping dos dados;

• Armazenamento dos dados raspados em um arquivo estruturado (no caso, um arquivo Excel).

Como os dados de interesse estão dispostos na página oficial: entendendo o HTML

Se você chegou até aqui e sabe pouco, ou não tem a mínima ideia do que seja HTML, eis o que você precisa saber para continuar: HTML, sigla para HyperText Markup Language, é, como o nome diz, uma linguagem de marcação. Ela serve para definir a estrutura e o significado de uma página web. Imagine o esqueleto de um ser vivo; assim como os ossos são dispostos a definir o formato de um corpo, as tags HTML ajudam a definir a estrutura de uma página.

A imagem abaixo demonstra exemplos de tags que nós podemos encontrar em um texto HTML; à medida em que formos explorando o conteúdo das páginas web, reconheceremos a função de algumas tags mostradas aqui.

Como acessar a estrutura HTML de um site para ver as tags

Uma vez que sabemos da existência de uma estrutura HTML para um site, antes de partirmos à extração de dados propriamente dita, é interessante que tenhamos conhecimentos de meios de ver a estrutura de um site; assim, quando formos colocar a mão na massa, podemos sempre recorrer a uma fonte contínua que mostre as tags que compõem a página.

Os browsers que são mais utilizados atualmente costumam ter um recurso chamado 'Inspecionar', que pode ser acessado pela lista de opções que aparece quando se pressiona o botão direito do mouse. Como o próprio nome já diz, o recurso serve para fazer uma verificação mais profunda na estrutura da página que está sendo vista.

Uma vez selecionado o 'Inspecionar', aparecerá uma janela à parte em seu navegador. O que interessa para essa prática está em uma aba que tem variados nomes, como 'Inspetor' ou 'Elementos'. É possível identificar do que se trata ao ver as várias linhas de código que saltam aos olhos; compare com os exemplos que já foram dados, e você logo perceberá que se trata da estrutura HTML, ou não.

![](https://i.ibb.co/0pb9hTc3/Captura-de-tela-2026-02-23-102913.png align="middle")

Com esse conhecimento em mãos, já podemos começar a usar o Python para acessar as páginas de interesse, e extrair os dados que estão nelas.

Utilizando Python para fazer o web scraping

Para esta parte, precisaremos importar uma série de bibliotecas que serão as responsáveis por acessarmos as páginas, extrairmos os dados e, por fim, adicionarmos tudo a uma planilha, que dará sentido a tudo o que fizermos.

import requests
from bs4 import BeautifulSoup as BS
import string, re
import pandas as pd
import numpy as np
import gc
from time import sleep

• Requests - HTTP para seres humanos

• re - Operações com REGEX (Expressões regulares)

• string - Operações com strings (sequência de caracteres)

• pandas - A biblioteca de análise de dados mais usada em Python

• numpy - A principal biblioteca Python para computação científica

• BeautifulSoup - Para extrair dados em HTML

• gc - O garbage collector do Python, para administrar a memória utilizada

• time - Para tudo que envolve tempo

Reconhecendo o que existe no site do ATC

A primeira coisa que faremos antes de começarmos a extrair os dados é entender como o site do ATC/DDD Index está estruturado. Para tanto, será preciso acessar o site https://atcddd.fhi.no/atc\_ddd\_index/ . A imagem abaixo indica o que vamos encontrar ao acessar o link.

![](https://i.ibb.co/Wh9VXQj/Screenshot-2026-02-17-at-07-11-02-ATCDDD-ATC-DDD-Index.png align="middle")

Ao usarmos o recurso 'Inspecionar' do browser, teremos acesso a cada detalhe da estrutura HTML, que é o que realmente importa aqui. Com isso já em mãos, podemos seguir para a escrita do código.

Construindo uma função de requisição (e evitando possíveis problemas)

Para fazer a raspagem dos dados, a construção do script será orientada por funções; isso será feito baseado no princípio de que a modularização facilita a legibilidade, manutenção, e reusabilidade do código.

A primeira função a ser criada é uma das mais importantes do script inteiro:

def get_page_content(url, retries=3, delay=0.5):
    """Função para fazer requisições com retry e delay"""
    for attempt in range(retries):
        try:
            response = requests.get(url, timeout=10)
            sleep(delay)  # Evita sobrecarregar o servidor
            return response.content
        except requests.RequestException as e:
            if attempt == retries - 1:
                print(f"Erro ao acessar {url}: {e}")
                return None
            sleep(delay * (attempt + 1))
    return None

O que temos aqui é uma função responsável por fazer as requisições ao site do ATC/DDD, construída de uma maneira que previna alguns problemas que podem ocorrer quando exploramos de forma automática páginas web.

• requests.get com timeout: evita que o código fique travado indefinidamente.

• Retry com backoff (delay * (attempt + 1)): trata instabilidades temporárias da rede ou do servidor, insistindo no código apenas depois de um tempo.

• Pequenos sleeps: respeita o servidor, reduz risco de um possível bloqueio por parte do servidor; isso poderia acontecer se fossem feitas muitas requisições em um período curto de tempo, o que poderia gerar uma sobrecarga no servidor, tornando o conteúdo do site indisponível para acesso.

Identificando os grupos anatômicos (nível 1)

O primeiro nível do ATC usa letras simples de A a Z, mas nem todas são válidas. A partir disso, uma função que itera por todo o alfabeto (usando o string.ascii_uppercase) é construída, e usa a presença de uma tag <h2> na resposta como sinal de que aquela letra não corresponde a um grupo existente.

![](https://i.ibb.co/fGD21fb5/Screenshot-2026-02-23-at-10-31-25-ATCDDD-ATC-DDD-Index.png align="middle")

def extract_domain_codes():
    """Extrai códigos de domínio (nível 1)"""
    print("Extraindo códigos de domínio...")
    results = []

    for letter in string.ascii_uppercase:
        content = get_page_content(f'https://atcddd.fhi.no/atc_ddd_index/?code={letter}&showdescription=no')
        if not content:
            continue

        soup = BS(content, 'html.parser')
        if soup.find('h2'):
            print(f'{letter} inválido')
        else:
            print(f'{letter} válido')
            try:
                link = soup.find('b').find('a')
                code = re.search('[A-Z]', link['href']).group(0)
                name = link.text.strip()
                results.append({'code': code, 'name': name, 'level': 1})
            except (AttributeError, TypeError):
                print(f"Erro ao processar {letter}")

    return pd.DataFrame(results)

O BeautifulSoup faz o parsing do HTML bruto retornado pelo requests, e o re (regex) extrai o código ATC do atributo href do link. Esse padrão de usar regex nos hrefs ao invés de depender do texto visível é mais robusto, porque o texto pode variar, mas a estrutura da URL tende a ser consistente. Ainda vale destacar a atribuição de um nível hieráquico para cada resultado, assim como é estabelecido no ATC/DDD; nesse caso, o nível atribuído é o número 1. A mesma coisa será feita para os níveis seguintes.

O resultado final é uma lista de dicionários que, usando o pandas, se tornará um DataFrame, que estará pronto para ser exportado no final de tudo.

Identificando os grupos terapêuticos (nível 2)

Aqui entra um ponto de autoridade importante: a preservação da hierarquia. Isso quer dizer que, para alcançar os códigos seguintes, será preciso considerar o código do nível anterior. Assim:

• Para cada domínio (nível 1), você acessa novamente o site. Uma vez que já temos os domínios válidos, serão acessados apenas estes.

• Usa regex para encontrar códigos [A-Z][0-9]+ dentro dos links. Isso porque, em cada link de domínio, aparece uma lista com os códigos do nível seguinte.

• Relaciona cada código de nível 2 com o parent_code (a letra do domínio). Exemplo: para o domínio A, estarão relacionados os códigos de nível 2 A01, A02, e assim por diante.

![](https://i.ibb.co/xtQwy5z3/Screenshot-2026-02-23-at-10-32-33-ATCDDD-ATC-DDD-Index.png align="middle")

Esse parent_code é crucial: ele permite, mais tarde, reconstruir a árvore completa sem precisar “chutar” ligações. Essa preocupação com hierarquia torna seu scraping analiticamente útil, não apenas uma extração bruta de texto.

def extract_therapeutic_subgroups(domain_codes):
    """Extrai subgrupos terapêuticos (nível 2)"""
    print("Extraindo subgrupos terapêuticos...")
    results = []

    for _, row in domain_codes.iterrows():
        letter = row['code']
        content = get_page_content(f'https://atcddd.fhi.no/atc_ddd_index/?code={letter}&showdescription=no')
        if not content:
            continue

        soup = BS(content, 'html.parser')
        for b_tag in soup.find_all('b'):
            try:
                link = b_tag.find('a')
                if not link:
                    continue

                code_match = re.search('[A-Z][0-9]+', link['href'])
                if code_match:
                    code = code_match.group(0)
                    name = link.text.strip()
                    # Relaciona com o domínio pai
                    parent_code = code[0]  # Primeiro caractere é o código do domínio
                    results.append({
                        'code': code,
                        'name': name,
                        'parent_code': parent_code,
                        'level': 2
                    })
            except (AttributeError, TypeError):
                continue

    return pd.DataFrame(results).drop_duplicates(subset=['code'])

Identificando subgrupos farmacológicos (nível 3) e químicos (nível 4)

Para os próximos dois níveis, 3 e 4, a lógica de preservação e relação com hierarquias segue sendo utilizada, mas com algumas diferenças para cada subgrupo, devido a suas peculiaridades. Vejamos:

def extract_pharmacological_subgroups(therap_subgroups):
    """Extrai subgrupos farmacológicos (nível 3)"""
    print("Extraindo subgrupos farmacológicos...")
    results = []

    for _, row in therap_subgroups.iterrows():
        code = row['code']
        content = get_page_content(f'https://atcddd.fhi.no/atc_ddd_index/?code={code}&showdescription=no')
        if not content:
            continue

        soup = BS(content, 'html.parser')
        for b_tag in soup.find_all('b'):
            try:
                link = b_tag.find('a')
                if not link:
                    continue

                code_match = re.search('[A-Z][0-9]{2}[A-Z]', link['href'])
                if code_match:
                    new_code = code_match.group(0)
                    name = link.text.strip()
                    parent_code = new_code[:3]  # ex.: A10
                    results.append({
                        'code': new_code,
                        'name': name,
                        'parent_code': parent_code,
                        'level': 3
                    })
            except (AttributeError, TypeError):
                continue

    gc.collect()
    return pd.DataFrame(results).drop_duplicates(subset=['code'])

def extract_chemical_subgroups(pharm_subgroups):
    """Extrai subgrupos químicos (nível 4)"""
    print("Extraindo subgrupos químicos...")
    results = []

    for _, row in pharm_subgroups.iterrows():
        code = row['code']
        content = get_page_content(f'https://atcddd.fhi.no/atc_ddd_index/?code={code}&showdescription=no')
        if not content:
            continue

        soup = BS(content, 'html.parser')
        for b_tag in soup.find_all('b'):
            try:
                link = b_tag.find('a')
                if not link:
                    continue

                code_match = re.search('[A-Z][0-9]{2}[A-Z]{2}', link['href'])
                if code_match:
                    new_code = code_match.group(0)
                    name = link.text.strip()
                    parent_code = new_code[:4]  # ex.: A10B
                    results.append({
                        'code': new_code,
                        'name': name,
                        'parent_code': parent_code,
                        'level': 4
                    })
            except (AttributeError, TypeError):
                continue

    gc.collect()
    return pd.DataFrame(results).drop_duplicates(subset=['code'])

Aqui, o que vale destacar é o seguinte:

• Há expressões regulares específicas para cada nível. Nesta altura, se sobressai o conhecimento da estrutura do ATC/DDD, indicando exatamente como cada código está disposto conforme seu nível.

• Construção sistemática do parent_code por fatiamento de string.

• Uso de gc.collect() para aliviar memória, uma preocupação que aparece em scrapers que percorrem muitas páginas. Isso se torna essencial quando vamos lidar com scripts como esse em máquinas cuja memória é bastante limitada. O que não está sendo mais utilizado é excluído com segurança, de modo que, a cada etapa passada, não seja comprometida tanta memória a ponto de travar a atividade.

Essa disciplina de padrões e relacionamentos é o que transforma o código em infraestrutura de dados, não apenas em um script pontual para extrair informação de um dado local.

![](https://i.ibb.co/nMxMNTyd/Screenshot-2026-02-23-at-10-33-48-ATCDDD-ATC-DDD-Index.png align="middle")

Identificando as substâncias químicas (nível 5) e dados complementares

![](https://i.ibb.co/PvHL5jKB/Screenshot-2026-02-23-at-10-35-20-ATCDDD-ATC-DDD-Index.png align="middle")

Essa é a parte final de extração de dados da página do ATC/DDD, e a que possui maior riqueza de detalhes. Aqui, além do código ATC por inteiro, faremos a extração do DDD, da unidade da dose, a via de administração, além de possíveis observações. Para tanto, precisamos considerar primeiramente um ponto em específico:

Alguns códigos não possuirão dados como a dose, a unidade de dose, e a via de administração. Para esses casos, precisaremos fazer um tratamento de dados faltantes, visando evitar possíveis quebras de linha que bagunçariam o resultado final.

Isso será feito da seguinte maneira:

• Trataremos explicitamente células vazias que vêm como '\xa0'(espaço não separável em HTML).

• Substituiremos essas células por np.nan (do NumPy), que é o padrão industrial para representar missing values em análises numéricas.

• Manteremos dose, unit, admin, note bem separados – isso facilita desde análise estatística até construção de dicionários de medicamentos. A célula que tiver dado ausente será representada por um nan, assim garantindo a representação de todas as colunas.

def extract_chemical_substances(chem_subgroups):
    """Extrai substâncias químicas (nível 5)"""
    print("Extraindo substâncias químicas...")
    results = []

    for _, row in chem_subgroups.iterrows():
        code = row['code']
        print(f'Processando dados de {code}')

        content = get_page_content(f'https://atcddd.fhi.no/atc_ddd_index/?code={code}&showdescription=no')
        if not content:
            continue

        soup = BS(content, 'html.parser')
        table = soup.find('table')

        if table:
            for tr in table.find_all('tr'):
                tds = tr.find_all('td')
                if len(tds) >= 6:  # Garante que temos todas as colunas
                    try:
                        atc_match = re.search('[A-Z][0-9]{2}[A-Z]{2}[0-9]{2}', tds[0].text)
                        if atc_match:
                            substance_code = atc_match.group(0)
                            name = tds[1].text.strip()
                            dose = tds[2].text.strip() if tds[2].text.strip() != '\xa0' else np.nan
                            unit = tds[3].text.strip() if tds[3].text.strip() != '\xa0' else np.nan
                            admin = tds[4].text.strip() if tds[4].text.strip() != '\xa0' else np.nan
                            note = tds[5].text.strip() if tds[5].text.strip() else np.nan

                            parent_code = substance_code[:5]  # ex.: A10BA

                            results.append({
                                'code': substance_code,
                                'name': name,
                                'dose': dose,
                                'unit': unit,
                                'admin': admin,
                                'note': note,
                                'parent_code': parent_code,
                                'level': 5
                            })
                    except (IndexError, AttributeError):
                        continue

    gc.collect()
    return pd.DataFrame(results).drop_duplicates(subset=['code'], keep='last')

Juntando tudo e construindo a árvore final: das páginas do ATC/DDD para uma estrutura de dados

Uma vez realizadas as coletas em todos os níveis de código ATC e dados complementares, chegamos à parte mais crítica do código: juntar todos os resultados em um DataFrame estruturado, observando sempre a preservação das hirearquias entre níveis.

Isso será feito usando os seguintes passos:

• Performando joins hierárquicos em pandas usando colunas derivadas (str[:4], str[:3], etc.).

• Uso de how='left' para não perder nenhuma substância mesmo que alguma descrição de nível superior falte.

• Renomear colunas para nomes sem ambiguidade (chemical_name, therapeutic_name, etc.).

O resultado será um DataFrame onde cada linha representa uma substância química, acompanhada de:

• Domínio (nível 1)

• Subgrupo terapêutico (nível 2)

• Subgrupo farmacológico (nível 3)

• Subgrupo químico (nível 4)

• Dados de DDD, unidade, via, nota (nível 5)

def build_hierarchical_structure(level1, level2, level3, level4, level5):
    """Constrói a estrutura hierárquica de forma eficiente"""
    print("Construindo estrutura hierárquica...")

    # Para o nível 5, fazemos joins hierárquicos diretos
    result = level5.copy()

    # Join com nível 4
    level4_slim = level4[['code', 'name']].rename(columns={'code': 'parent_code', 'name': 'chemical_name'})
    result = result.merge(level4_slim, on='parent_code', how='left')

    # Join com nível 3
    result['pharm_parent'] = result['parent_code'].str[:4]
    level3_slim = level3[['code', 'name']].rename(columns={'code': 'pharm_parent', 'name': 'pharmacological_name'})
    result = result.merge(level3_slim, on='pharm_parent', how='left')

    # Join com nível 2
    result['therap_parent'] = result['pharm_parent'].str[:3]
    level2_slim = level2[['code', 'name']].rename(columns={'code': 'therap_parent', 'name': 'therapeutic_name'})
    result = result.merge(level2_slim, on='therap_parent', how='left')

    # Join com nível 1
    result['domain_parent'] = result['therap_parent'].str[:1]
    level1_slim = level1[['code', 'name']].rename(columns={'code': 'domain_parent', 'name': 'domain_name'})
    result = result.merge(level1_slim, on='domain_parent', how='left')

    # Limpa colunas auxiliares
    result = result.drop(['parent_code', 'level', 'pharm_parent', 'therap_parent', 'domain_parent'], axis=1)

    return result

O DataFrame que surge de resultado é, basicamente, uma tabela bem estruturada, que considera todos os níveis de código do ATC e os junta de uma forma facilmente entendível. Esse resultado está pronto para ser utilizado de várias formas; vejamos alguns exemplos:

• Modelos de classificação de medicamentos

• Consolidação de bases de prescrição

• Integrações com sistemas regulatórios

• Dashboards de consumo/uso de medicamentos

La grande finale: o pipeline completo em Python

No final de tudo, todos as funções que já foram criadas serão incluídas em um único pipeline, na função main(), dividido em etapas lógicas que invocam cada nível do código em seu momento oportuno. Além disso, a função conta com logs que informam diretamente no console quantos registros foram extraídos em cada nível percorrido.

Todos os dados extraídos e organizados são finalmente consolidados em um arquivo Excel (.xlsx), valendo-se da função do pandas apropriada para a atividade; esse arquivo estará pronto para o consumo e verificação de qualquer usuário. Ainda, há o tratamento de possíveis exceções em uma escala global: basicamente, o script avisa qual exatamente foi o erro que ocorreu durante a sua execução, tornando a resolução mais rápida e assertiva.

def main():
    """Função principal otimizada"""
    try:
        # Extrai dados nível por nível
        level1 = extract_domain_codes()
        print(f"Nível 1: {len(level1)} registros")

        level2 = extract_therapeutic_subgroups(level1)
        print(f"Nível 2: {len(level2)} registros")

        level3 = extract_pharmacological_subgroups(level2)
        print(f"Nível 3: {len(level3)} registros")

        level4 = extract_chemical_subgroups(level3)
        print(f"Nível 4: {len(level4)} registros")

        level5 = extract_chemical_substances(level4)
        print(f"Nível 5: {len(level5)} registros")

        # Constrói estrutura final
        final_result = build_hierarchical_structure(level1, level2, level3, level4, level5)

        # Salva resultado
        output_file = "PATH/Lista_ATC_COMPLETA_Otimizada.xlsx" #Adapte para o caminho em sua máquina onde o arquivo será salvo.
        final_result.to_excel(output_file, index=False)
        print(f"Dados salvos em: {output_file}")
        print(f"Total de registros finais: {len(final_result)}")

        return final_result

    except Exception as e:
        print(f"Erro durante execução: {e}")
        return None

![](https://media.licdn.com/dms/image/v2/D4D22AQFavuRHlYMFWQ/feedshare-shrink_2048_1536/B4DZxw6uiiJIAk-/0/1771420969458?e=1773273600&v=beta&t=aEC4OnT7zl4JKdsu-7AElNqhl4KEpoc1qqu0iZRlwjY align="middle")

Insights valiosos sobre web scraping em contextos como o apresentado

1. Scraping não é só “raspar HTML” — é modelar o domínio de negócio
   Ao preservar a hierarquia (parent codes, níveis 1 a 5) e organizar os dados em um modelo coerente, estamos traduzindo a lógica regulatória do sistema ATC para um modelo de dados. Isso permite análises complexas (por domínio terapêutico, por via de administração, por dose definida diária) com rastreabilidade total até a fonte oficial.

2. Requests + BeautifulSoup + pandas + numpy formam um stack poderoso para dados regulatórios

   • requests: acesso controlado, com timeout e retries.

   • BeautifulSoup: extração precisa e legível de conteúdo HTML.

   • pandas: manipulação de tabelas, joins hierárquicos, limpeza.

   • numpy: representação rigorosa de valores ausentes e numéricos.

   Dominar esse conjunto significa ir além do Excel e ter controle total sobre a linha de produção dos dados farmacêuticos.

3. Eficiência e respeito ao servidor fazem parte da reputação técnica
   O uso de pausa entre requisições, retries controlados, limpeza de memória e filtragem por regex minimiza carga no servidor, reduz falhas e aumenta a confiabilidade do processo. Em contextos sensíveis como saúde, isso é mais do que uma boa prática de código — é um requisito ético e profissional, ainda mais em contextos em que ainda usamos recursos limitados para fazer análises mais complexas.

Agora, imagine: Se você tivesse hoje a hierarquia ATC/DDD completa e atualizada nesse formato tabular, qual seria a primeira análise ou automação de alto impacto que você implementaria com esses dados na sua realidade (por exemplo, na área clínica, regulatória, de mercado ou de pesquisa)? E, com os conhecimentos sobre web scraping passados aqui, quais possibilidades você já enxerga de extração de dados para auxiliar em outras análises, considerando o tempo e energia economizados para suas análises do dia-a-dia?

O nome já diz: a função join()

Quando você vê o nome da função, join(), é possível que pense outra vez na cláusula JOIN do SQL. E a verdade é… que é por aí mesmo. Veja a tabela abaixo; a função do pandas nada mais é que uma “tradução” das funções de JOIN para uma forma a ser utilizada através de uma biblioteca Python.

Agora, se você está conosco há algum tempo e se lembra das aulas anteriores, essas informações vão parecer um tanto familiares. E são familiares mesmo! Perceba que as características batem com uma outra função do pandas, merge().

Mas é tudo igual mesmo? Comparando join() com merge()

É possível que você pense que a função join()seja uma mera redundância do merge(), e que a escolha de qual recurso utilizar é indiferente quando se quer fazer uma combinação de DataFrames. No entanto, as coisas não precisam ser (e não são, na verdade) assim. Dê uma olhada na tabela abaixo; aqui você verá duas coisas: apontamentos sobre as diferenças entre as funções do pandas e a equivalência com a cláusula do SQL.

Desta tabela, uma coisa fica clara: enquanto merge() dá a possibilidade de combinar DataFrames baseados em colunas, a concentração de join() se dá nos índices do DataFrame. Para lembrar o que são índices para o pandas:

The index of a DataFrame is a series of labels that identify each row. The labels can be integers, strings, or any other hashable type. The index is used for label-based access and alignment, and can be accessed or modified using this attribute.

Traduzindo, é algo assim:

O índice de um DataFrame é uma série de etiquetas (labels) que identificam cada linha. Podem ser números inteiros, strings, ou qualquer tipo de dado que possa ser utilizada como chave. É utilizado para acesso e alinhamento de dados baseando-se em etiquetas, podendo acessar e modificar linhas usando esse mesmo atributo.

Então, em vez de nos orientarmos pelos nomes das colunas, como em merge(), podemos nos valer de, digamos, os “nomes” das linhas usando o join().

Um exemplo prático

Comecemos o exemplo criando dois DataFrames de características envolvendo aspectos corpóreos de um grupo limitado de aves. Nesse caso, como usaremos o join(), daremos uma atenção especial aos índices de cada DataFrame. Cada linha das tabelas possuirá um nome científico de uma ave em específico.

import pandas as pd
import numpy as np

# Criando DataFrame com dados das asas
df_asas = pd.DataFrame({
    'envergadura_cm': [240, 180, 85, 120, 300],
    'comp_dedo_medio_cm': [12, 8, 4, 6, 15],
    'comp_asa_cm': [110, 85, 40, 55, 145]
}, index=['Aquila chrysaetos',  # Águia-real
          'Buteo buteo',        # Águia-de-asa-redonda
          'Falco tinnunculus',  # Peneireiro-vulgar
          'Accipiter nisus',    # Gavião-da-europa
          'Gyps fulvus'])       # Grifo

# Criando DataFrame com dados das pernas
df_pernas = pd.DataFrame({
    'comp_tarso_cm': [9.5, 7.2, 4.5, 5.8, 10.2],
    'comp_total_perna_cm': [35, 28, 18, 22, 40],
    'circunf_tarso_cm': [8, 6, 3, 4, 9]
}, index=['Aquila chrysaetos',    # Águia-real
          'Buteo buteo',          # Águia-de-asa-redonda
          'Falco tinnunculus',    # Peneireiro-vulgar
          'Strix aluco',          # Coruja-do-mato
          'Gyps fulvus'])         # Grifo

Perceba já de início que existem alguns índices que possuem nomes iguais (que é o intuito dessa atividade); esta parte é muito importante para usar o join(). A partir daqui, então, já podemos “traduzir” as cláusulas do SQL para argumentos da função, assim como fizemos com o merge() anteriormente, como no bloco de código abaixo:

# Exemplo 1: Inner join (apenas espécies que aparecem em ambos os DataFrames)
df_inner = df_asas.join(df_pernas, how='inner')

# Exemplo 2: Left join (todas as espécies do DataFrame de asas)
df_left = df_asas.join(df_pernas, how='left')

# Exemplo 3: Right join (todas as espécies do DataFrame de pernas)
df_right = df_asas.join(df_pernas, how='right')

# Exemplo 4: Outer join (todas as espécies de ambos os DataFrames)
df_outer = df_asas.join(df_pernas, how='outer')

Como resultado, teremos para cada variável criada um DataFrame com os dados de asas e pernas de aves conforme o tipo de JOIN selecionado. Note que existem espécies que ocorrem em apenas uma das tabelas. Isso não vem a atrapalhar a mescla como um todo, mas é importante salientar que, no caso das colunas referentes ao outro DataFrame (onde a espécie não está descrita), os dados virão nulos.

O resumo da ópera

Chegando ao final das discussões sobre as diferentes formas de mesclar DataFrames usando pandas, podemos resumir tudo em uma tabela como esta abaixo, estabelecendo também comparações com a cláusula JOIN do SQL:

Comparação entre métodos de junção pandas e SQL

Comparação entre métodos de junção pandas e SQL

Esta é, portanto, a última aula que explora as três funções que podemos usar para juntar tabelas usando o pandas: concat(), join(), e merge(). Continuaremos a explorar outros atributos do pandas e do Python para analisar dados, especialmente os dados ecológicos, nas próximas aulas a serem publicadas em breve.

Aproveite o conteúdo para seguir estudando! Um abraço e até a próxima!

Para ler mais:

• Join no Pandas - Asimov Academy

• What is the difference between join and merge in Pandas? - Stack Overflow

O pandas, como vimos até então, é uma espécie de 'canivete suíço' para quem quer analisar seus dados; muito por isso, a biblioteca nos oferece mais funções para que possamos 'aliviar a dor' de juntar conjuntos de dados que temos em mãos. Nesta aula, a função da vez é a merge().

Junte-se a nós... mas de que jeito?: função merge()

Ainda mencionando a função concat(), vimos que ela funciona de maneira que se consiga empilhar dois ou mais DataFrames, seja um em cima do outro, seja um do lado do outro. Isso funciona bem para dados que possuam colunas exatamente iguais, ou até mesmo índices... mas e se não for o seu caso?

Se você conhece um pouco de SQL, é capaz de se lembrar de uma cláusula chamada JOIN. Como o próprio nome diz, é uma cláusula destinada a juntar dois conjutos de dados, num primeiro momento, em apenas um, podendo considerar diferentes aspectos para gerar o resultado esperado.

A função merge() do pandas, em bom português, possui poder semelhante ao JOIN; logo, você pode lançar mão dessa função para juntar DataFrames. Mas cuidado: assim como foi dito muitas vezes no universo de Homem-Aranha, "com grandes poderes vêm grandes responsabilidades". A pergunta que fica depois disso é: quais são as "responsabilidades" do merge()?

Como juntar? O parâmetro how

Caso voltemos nossos olhos à documentação do pandas, especialmente no que toca à função merge(), percebemos a presença de um grande número de parâmetros, onde você pode fazer várias modificações a fim de performar uma "sintonia fina", para chegar ao resultado que se espera. No entanto, demos foco primeiramente a um dos mais importantes: o parâmetro how.

Pensemos primeiro na cláusula JOIN do SQL: esta se desdobra em métodos específicos de mescla, como OUTER JOIN, INNER JOIN, e assim por diante. A mesma coisa pode ser vista na função merge(), através do argumento how; a diferença estará na sintaxe, basicamente.

Observe a tabela e a imagem abaixo, onde estão as diferenças de sintaxe entre o pandas e o SQL, e quais são as possibilidades de usar cada função e cláusula. Perceba que os nomes já indicam que tipo de operação será feita; mas, ainda assim, veremos com um pouco mais de detalhe cada uma delas mais à frente.

Quem está dentro, quem está fora: inner e outer

Examinemos com um pouco mais de detalhe as operações inner e outer. Para estabelecer comparações com as outras operações, estas duas primeiras consideram as duas fontes, ou tabelas, na sua totalidade. Isso quer dizer que, no momento da atuação do pandas, este dará o mesmo foco para quaisquer dados que apareçam para o mesmo juntar. Aqui, a diferença estará no que sairá de resultado.

A operação outer é, digamos, a mais simples dentre as que estamos analisando. Isso porque a única coisa que o pandas faz é juntar aquilo que aparece nas duas fontes igualmente, e incluir aquilo que aparece ou em uma, ou em outra fonte.

df = pd.merge(df1, df2, how='outer')

A operação inner, por sua vez, é marcada pelo fato de haver a separação de apenas aquilo que aparece nas duas tabelas/fontes que estamos analisando; ou seja, o que é comum entre os dois conjuntos de dados. O que é único dentro de cada conjunto fica fora do resultado.

df = pd.merge(df1, df2, how='inner')

Considerando um ou outro: left e right

Podemos dizer que as operações left e right, diferente das duas anteriores, estabelecem um foco especial em apenas uma das duas fontes, por vez. E isso se dá a partir da posição das tabelas no código que escrevemos. "Como assim?", você deve estar se perguntando. Explico:

• Assim como nas línguas portuguesa, inglesa, e tantas outras, o sentido de leitura de um código Python se dá da esquerda para a direita. Imagine uma operação matemática simples:

  5 + 2 + 3 + 12
  

  Intuitivamente, quando usamos a calculadora, ou fazemos o cálculo à mão, ou usamos a nossa imaginação para tanto, ordenamos os números da esquerda para a direita: Pegamos primeiro o 5, somamos com o 2, e assim por diante, até chegarmos ao resultado.

  22
  

• Com as fontes que usaremos para a mescla, é basicamente a mesma coisa. Observe a seguinte linha de código:

  pd.merge(df1, df2, how='left', on='ID')
  

  Por ser a primeira a aparecer na ordem de leitura, a fonte df1 assumirá a posição da esquerda, enquanto df2 assume a posição da direita.

A partir disso, a diferença entre left e right como operações do parâmetro how fica bem mais clara. Ao utilizarmos o primeiro, damos foco à fonte de dados da esquerda, adquirindo da outra fonte à direita apenas o que é semelhante a ambos. Já o right tem como foco a tabela da direita, operando da mesma forma.

Cadê a chave? O parâmetro on

Até aqui, foi possível entender de que forma a função merge() funciona no que se refere a de que jeito vamos mesclar os conjuntos de dados que temos, de acordo com o foco que o pandas dará em relação às tabelas e suas posições. Tendo esse conhecimento adquirido, já é possível lançar mão da função para fazer mesclas.

Entretanto, em muitos casos, a indicação das posições por si só não fará com que alcancemos o resultado que estamos esperando, uma vez que, caso tenhamos uma ou mais colunas em comum para os dois conjuntos de dados, uma mescla 'pura' pode gerar duplicidades, alteração em colunas que possuem nomes iguais... em suma, isso vem gerar uma confusão que nos dará mais trabalho depois. Mas, na própria função merge(), há uma solução simples: apontar as chaves de cada tabela, a partir do parâmetro on.

Voltando ao SQL e adicionando um pouco de conceitos básicos de banco de dados, sabemos que, em um conjunto de dados dentro de um banco é possível ter o que chamamos de chaves; estas nada mais são do que valores únicos pelos quais podemos identificar dados dentro de uma tabela.

Para entender melhor, imaginemos o seguinte: Temos em mãos dois DataFrames com dados envolvendo características corpóreas de certas espécies de mamíferos, conforme o bloco de código a seguir:

import pandas as pd
import numpy as np

# Criando o primeiro DataFrame com características físicas principais
df1 = pd.DataFrame({
    'Especie': ['Leão', 'Tigre', 'Urso Pardo', 'Lobo Cinzento', 'Jaguar'],
    'comprimento_cm': [250, 300, 200, 150, 180],
    'tamanho_pes_cm': [18, 20, 25, 15, 16],
    'tamanho_presas_cm': [8, 7.5, 5, 6, 7]
})

# Criando o segundo DataFrame com características faciais
df2 = pd.DataFrame({
    'Especie': ['Leão', 'Tigre', 'Urso Pardo', 'Lobo Cinzento', 'Onça Pintada'],
    'tamanho_garras_cm': [6, 8, 10, 4, 7],
    'tamanho_focinho_cm': [20, 22, 35, 25, 18]
})

Aqui, já de início, podemos perceber uma coisa: a existência de uma coluna com nome e valores em comum. Esta coluna, Especie, vem a servir de identificador dos DataFrames, uma vez que possui valores que, em princípio, não se repetem na tabela. Desse modo, podemos encarar essa coluna como a chave dos DataFrames que foram criados.

Seguindo a ideia dessa aula, imaginemos a situação de mesclar os dois DataFrames que criamos, com o intuito de juntar todas as características corpóreas de cada espécie registrada nesses dois conjuntos de dados. É perfeitamente possível se valer da função merge() indicando apenas os dois df, conforme exemplo abaixo:

df3 = pd.merge(df1, df2, how='outer')

Existe aí, no entanto, um porém: Ao executarmos esse código, e verificarmos seu resultado, é possível encontrar a coluna Especie repetida, com indicadores atrelados ao nome (algo como Especie_x e Especie_y). Isso, querendo nós ou não, atrapalha muito na hora de fazer quaisquer análises. E o que faremos com isso, então?

Nesse blog, procuramos sempre preconizar o princípio de que existirá uma solução efetiva para os problemas que encontramos na análise de dados usando Python; aqui não será diferente. Para resolvermos essa questão de uma vez por todas, basta complementarmos a linha de código anterior fazendo menção à coluna que as tabelas possuem em comum usando o parâmetro on, conforme exemplo:

df3 = pd.merge(df1, df2, how='outer', on='Especie')

Adicionando valor a esse parâmetro, indicaremos ao pandas que, uma vez encontrado um valor comum de Especie em ambos os conjuntos de dados, a única coisa que é preciso fazer é uma complementação dos dados que já existem, adicionando novas colunas e os valores atrelados a elas. Assim teremos um DataFrame único em df3, sem colunas repetidas, e com todos os dados disponíveis nas duas tabelas, prontas para que possamos tomar quaisquer outras ações posteriores.

Vimos até aqui duas formas muito interessantes de combinar dados oriundos de fontes distintas, concat() e merge(). Com elas, sem a menor sombra de dúvida, você já estará pronto para organizar os vários fragmentos de dados que acaso poderá encontrar ao lidar com arquivos do mundo real. Ainda nos falta discutir um pouco sobre uma outra função que também serve para combinações e mesclas, o join(). Isso faremos em uma próxima oportunidade, de forma mais detalhada e clara.

Um grande abraço, e até o próximo post!

Para ler mais:

• Pandas Merging 101 - StackOverflow

• What are the 'levels', 'keys', and names arguments for in Pandas' concat function? - Stack Overflow

• Python Pandas DataFrame Join, Merge, and Concatenate - Towards Data Science

• Practical uses of merge, join and concat - Towards Data Science

• Combining Data in pandas With merge(), .join(), and concat() - Real Python

In clinical studies, we often work with datasets that can come in various formats, depending on what the chosen EDC system can offer. However, in some situations, it will be necessary to extract a complete dataset according to what regulatory entities require for the approval submissions of drug and vaccine use, mainly. Among the formats that frequently appear as options are XML (which we have seen previously), and JSON. To ease the anxiety that sometimes arises when facing these "monsters," today we'll see in practice how to handle a JSON file.

What is JSON?

JSON stands for JavaScript Object Notation, a data representation that, like XML, can be used for data transmission. As the name suggests, it is based on a subset of the JavaScript language; however, it has a universal structure that can be read and manipulated by various programming languages ¹.

Dataset-JSON

Dataset-JSON is an ongoing initiative led by CDISC and PHUSE ², aiming to establish a lighter, faster, and more human-readable alternative to the current clinical data transfer models (namely, SAS and Dataset-XML, the latter already discussed on the blog).

Differences between JSON and XML for Data Storage and Transfer

Especially in the case of clinical study data, various sources indicate that the JSON format has certain advantages over the XML format. We can list a few here:

• XML, although an improvement over older clinical data models, is still a large file format, mainly due to its verbose nature. In a single tag, for example, there can be more than one attribute representing important information (this issue was discussed in the second post about XML on the blog). JSON has a simpler and more flexible structure, capable of storing the same amount of information as XML in a smaller, easier-to-read file, saving memory and energy.

• JSON is fully compatible with APIs and can be seen in newer versions of EDCs (such as OpenClinica from version v. 4.x, and the latest versions of REDCap Academic and Cloud), making data transmission easier without the need to manually download files ³. XML, although present in some APIs, does not have the same presence and ease as JSON.

• JSON contains basic information about the variables within its own file. For XML, although this is possible (as we have seen in previous posts), it is not necessarily the rule and often depends on external files ⁴.

• XML allows the addition of new namespaces, metadata, and other information, but its rigid structure is a critical limiting factor for this. JSON is much more flexible, with a simpler and more user-friendly structure for adding new data.

Let's look at examples of how the elements that make up XML and JSON files are distributed in memory when read. The first case is a tree similar to the ODM tree schema of XML files we have seen before. The XML tree has a high degree of complexity, as shown in the diagram below, with many elements needing to be stored in their own memory spaces. This requires more "jumps" between elements to reach the desired data.

When we talk about the tree of a JSON file, you can immediately notice a reduction in complexity: the data is with the sub-elements, which means it takes up less space in memory and requires fewer "jumps" here, saving time and energy. The diagram is below.

From here, we can provide a summary of this comparison:

Using Python to handle JSON

Data to be Used

The data we will use in this article is still from the CDISC repository on GitHub, but it is in a separate folder dedicated to Dataset-JSON files. Besides the example that will be our focus here, there are many other datasets available that can be viewed, extracted, and manipulated.

Libraries to be Imported

When using Python to handle data from JSON files, we will use a specific library dedicated to this type of document: json. This is a native Python library, so if you are using WinPython or Anaconda, you can likely access the tool with just an import. The other libraries to be imported are ones we are already familiar with: requests and pandas.

import requests, json
import pandas as pd

Acquiring and Exploring the Data

To get the data we will analyze, you can follow similar steps to those we've seen in previous posts using the requests library. With the requests.get() function, we send a request to GitHub to obtain the JSON file we want, and once this request is successful, we can store its content in a variable, example.

As mentioned before, unlike what we do with XML files, we will use the json package to read the file resulting from the request. For this case, we use the json.loads() function, as shown below.

example = requests.get('https://github.com/cdisc-org/DataExchange-DatasetJson/raw/refs/heads/master/examples/i18n/ae.json')
example = example.content
example = json.loads(example)

The result of this "loading" is an object similar to Python's dict, a dictionary ^{5 6}; this is one of the types proposed for JSON when it is read by some software or language package. In this dictionary, we will find all the information we need to identify the data and put it into a readable and explorable DataFrame.

If we explore this dictionary in an IDE like Spyder, which is available in both WinPython and Anaconda, we will see a classic key-value structure of a dictionary, but we will also see other things that interest us here, as shown in the image below.

From the metadata version to the number of records contained in the JSON file, there are several essential pieces of information in the file. However, let's focus on just two keys: columns and rows. These values will be used to build the pandas DataFrame that we can explore later.

Accessing Data Within the JSON

To access the data in rows and columns within the example object, we just need to follow the logic of a Python dictionary, as mentioned earlier. By using the method object[key], or objeto[chave], we can access the data we want within the example dictionary, using something like the block below:

columns = example['columns']
rows = example['rows']

With this, we can have full access to the content we will use to build the DataFrame. If we call the columns object in the console, we will be able to see all the content it contains.

columns

[{'itemOID': 'IT.AE.STUDYID',
  'name': 'STUDYID',
  'label': 'Study Identifier',
  'dataType': 'string',
  'length': 12},
 {'itemOID': 'IT.AE.DOMAIN',
  'name': 'DOMAIN',
  'label': 'Domain Abbreviation',
  'dataType': 'string',
  'length': 2},
 {'itemOID': 'IT.AE.USUBJID',
  'name': 'USUBJID',
  'label': 'Unique Subject Identifier',
  'dataType': 'string',
  'length': 11},
 {'itemOID': 'IT.AE.AESEQ',
  'name': 'AESEQ',
  'label': 'Sequence Number',
  'dataType': 'float'},
 {'itemOID': 'IT.AE.AESPID',
  'name': 'AESPID',
  'label': 'Sponsor-Defined Identifier',
  'dataType': 'string',
  'length': 3},
 {'itemOID': 'IT.AE.AETERM',
  'name': 'AETERM',
  'label': 'Reported Term for the Adverse Event',
  'dataType': 'string',
  'length': 200},
 {'itemOID': 'IT.AE.AELLT',
  'name': 'AELLT',
  'label': 'Lowest Level Term',
  'dataType': 'string',
  'length': 100},
 {'itemOID': 'IT.AE.AELLTCD',
  'name': 'AELLTCD',
  'label': 'Lowest Level Term Code',
  'dataType': 'float'},
 {'itemOID': 'IT.AE.AEDECOD',
  'name': 'AEDECOD',
  'label': 'Dictionary-Derived Term',
  'dataType': 'string',
  'length': 200},
 {'itemOID': 'IT.AE.AEPTCD',
  'name': 'AEPTCD',
  'label': 'Preferred Term Code',
  'dataType': 'float'},
 {'itemOID': 'IT.AE.AEHLT',
  'name': 'AEHLT',
  'label': 'High Level Term',
  'dataType': 'string',
  'length': 100},
 {'itemOID': 'IT.AE.AEHLTCD',
  'name': 'AEHLTCD',
  'label': 'High Level Term Code',
  'dataType': 'float'},
 {'itemOID': 'IT.AE.AEHLGT',
  'name': 'AEHLGT',
  'label': 'High Level Group Term',
  'dataType': 'string',
  'length': 100},
 {'itemOID': 'IT.AE.AEHLGTCD',
  'name': 'AEHLGTCD',
  'label': 'High Level Group Term Code',
  'dataType': 'float'},
 {'itemOID': 'IT.AE.AEBODSYS',
  'name': 'AEBODSYS',
  'label': 'Body System or Organ Class',
  'dataType': 'string',
  'length': 67},
 {'itemOID': 'IT.AE.AEBDSYCD',
  'name': 'AEBDSYCD',
  'label': 'Body System or Organ Class Code',
  'dataType': 'float'},
 {'itemOID': 'IT.AE.AESOC',
  'name': 'AESOC',
  'label': 'Primary System Organ Class',
  'dataType': 'string',
  'length': 100},
 {'itemOID': 'IT.AE.AESOCCD',
  'name': 'AESOCCD',
  'label': 'Primary System Organ Class Code',
  'dataType': 'float'},
 {'itemOID': 'IT.AE.AESEV',
  'name': 'AESEV',
  'label': 'Severity/Intensity',
  'dataType': 'string',
  'length': 8},
 {'itemOID': 'IT.AE.AESER',
  'name': 'AESER',
  'label': 'Serious Event',
  'dataType': 'string',
  'length': 1},
 {'itemOID': 'IT.AE.AEACN',
  'name': 'AEACN',
  'label': 'Action Taken with Study Treatment',
  'dataType': 'string',
  'length': 30},
 {'itemOID': 'IT.AE.AEREL',
  'name': 'AEREL',
  'label': 'Causality',
  'dataType': 'string',
  'length': 8},
 {'itemOID': 'IT.AE.AEOUT',
  'name': 'AEOUT',
  'label': 'Outcome of Adverse Event',
  'dataType': 'string',
  'length': 200},
 {'itemOID': 'IT.AE.AESCAN',
  'name': 'AESCAN',
  'label': 'Involves Cancer',
  'dataType': 'string',
  'length': 1},
 {'itemOID': 'IT.AE.AESCONG',
  'name': 'AESCONG',
  'label': 'Congenital Anomaly or Birth Defect',
  'dataType': 'string',
  'length': 1},
 {'itemOID': 'IT.AE.AESDISAB',
  'name': 'AESDISAB',
  'label': 'Persist or Signif Disability/Incapacity',
  'dataType': 'string',
  'length': 1},
 {'itemOID': 'IT.AE.AESDTH',
  'name': 'AESDTH',
  'label': 'Results in Death',
  'dataType': 'string',
  'length': 1},
 {'itemOID': 'IT.AE.AESHOSP',
  'name': 'AESHOSP',
  'label': 'Requires or Prolongs Hospitalization',
  'dataType': 'string',
  'length': 1},
 {'itemOID': 'IT.AE.AESLIFE',
  'name': 'AESLIFE',
  'label': 'Is Life Threatening',
  'dataType': 'string',
  'length': 1},
 {'itemOID': 'IT.AE.AESOD',
  'name': 'AESOD',
  'label': 'Occurred with Overdose',
  'dataType': 'string',
  'length': 1},
 {'itemOID': 'IT.AE.AEDTC',
  'name': 'AEDTC',
  'label': 'Date/Time of Collection',
  'dataType': 'string',
  'length': 10},
 {'itemOID': 'IT.AE.AESTDTC',
  'name': 'AESTDTC',
  'label': 'Start Date/Time of Adverse Event',
  'dataType': 'string',
  'length': 10},
 {'itemOID': 'IT.AE.AEENDTC',
  'name': 'AEENDTC',
  'label': 'End Date/Time of Adverse Event',
  'dataType': 'string',
  'length': 10},
 {'itemOID': 'IT.AE.AESTDY',
  'name': 'AESTDY',
  'label': 'Study Day of Start of Adverse Event',
  'dataType': 'float'},
 {'itemOID': 'IT.AE.AEENDY',
  'name': 'AEENDY',
  'label': 'Study Day of End of Adverse Event',
  'dataType': 'float'},
 {'itemOID': 'IT.AE.AETRTEM',
  'name': 'AETRTEM',
  'label': 'TREATMENT EMERGENT FLAG',
  'dataType': 'string',
  'length': 1}]

Notice that when we access columns, we not only have the column name but also what it means (through the label), the data type (through the dataType), and the OID, which is the object identifier ⁷. This highlights the ease with which JSON can handle and access file metadata, an advantage over XML, which, although it allows metadata access in the same file, does not do so as easily.

Moving forward, to see what the rows object contains, we use the same method as before. Since it is expected that the number of records is large (when we check the records key in the dictionary, we have 1191 records!), we will only look at the first occurrence in this case.

rows[0] #The first occurrence inside 'rows'

['CDISCPILOT01',
 'AE',
 '01-701-1015',
 1,
 'E07',
 'アプリケーションサイトの紅斑',
 'APPLICATION SITE REDNESS',
 None,
 'APPLICATION SITE ERYTHEMA',
 12345678,
 'HLT_0617',
 12345678,
 'HLGT_0152',
 12345678,
 'GENERAL DISORDERS AND ADMINISTRATION SITE CONDITIONS',
 87654321,
 'GENERAL DISORDERS AND ADMINISTRATION SITE CONDITIONS',
 None,
 'MILD',
 'N',
 '',
 'PROBABLE',
 'NOT RECOVERED/NOT RESOLVED',
 'N',
 'N',
 'N',
 'N',
 'N',
 'N',
 'N',
 '2014-01-16',
 '2014-01-03',
 '',
 2,
 None,
 'Y']

Notice the order of the data; it is expected that once we "link" the rows to the columns, each piece of data in this list will start to make sense. This same order will appear in all other rows found in this object, each in a separate list.

Building a DataFrame Simply

To build the DataFrame, you need to keep two things in mind: 1) We already have the rows of our table in the rows variable, which is expected to be ordered; and 2) We have the column name definitions in the columns object, as dictionaries in a list. So, before we use pandas to finally build the DataFrame, we first need to separate what will be the column names of the table. To do this, we just need to create a data list, which will be populated with the labels from an iteration using the columns key in our first dictionary, example. Since columns is a list with several dictionaries, we just need to access each dictionary within this list and extract the label using the object[key] principle. From this, we have the labels for each column, as they are the label values within each dictionary.

data = [] #List to be populated

for cl in example['columns']: #An iteraction in order to extract the labels
        data.append(cl['label'])

data #See which labels appear

['Study Identifier',
 'Domain Abbreviation',
 'Unique Subject Identifier',
 'Sequence Number',
 'Sponsor-Defined Identifier',
 'Reported Term for the Adverse Event',
 'Lowest Level Term',
 'Lowest Level Term Code',
 'Dictionary-Derived Term',
 'Preferred Term Code',
 'High Level Term',
 'High Level Term Code',
 'High Level Group Term',
 'High Level Group Term Code',
 'Body System or Organ Class',
 'Body System or Organ Class Code',
 'Primary System Organ Class',
 'Primary System Organ Class Code',
 'Severity/Intensity',
 'Serious Event',
 'Action Taken with Study Treatment',
 'Causality',
 'Outcome of Adverse Event',
 'Involves Cancer',
 'Congenital Anomaly or Birth Defect',
 'Persist or Signif Disability/Incapacity',
 'Results in Death',
 'Requires or Prolongs Hospitalization',
 'Is Life Threatening',
 'Occurred with Overdose',
 'Date/Time of Collection',
 'Start Date/Time of Adverse Event',
 'End Date/Time of Adverse Event',
 'Study Day of Start of Adverse Event',
 'Study Day of End of Adverse Event',
 'TREATMENT EMERGENT FLAG']

Once this is done, the return we see is a list of names that we will use to identify each column of our future DataFrame.

With this process completed and all this data in hand, it's time to put everything together in a single DataFrame. To do this, we'll use the pd.DataFrame() function, where we will specify where the data for the rows is located, using rows, and the column names, using the columns argument and the data object.

df = pd.DataFrame(rows, columns=data)

Once everything is integrated into a DataFrame, simply save it in your preferred format. From here, the semi-structured JSON data becomes structured spreadsheet data.

## Exporting

df.to_csv('df.csv') #.csv file
df.to_excel('df.xlsx') #.xlsx file
df.to_parquet('df.parquet') #.parquet file

Notes

1. More information about this can be found on the official JSON page: https://www.json.org/ ↩

2. PHUSE is a nonprofit organization that brings together people who share ideas and solutions involving clinical data, such as analyzing and subsequently reporting it. Many innovations in data involving clinical trials will certainly come from this organization; therefore, it's definitely worth following them at https://phuse.global/. ↩

3. PHUSE. https://phuse.s3.eu-central-1.amazonaws.com/Deliverables/Optimizing+the+Use+of+Data+Standards/WP-88+Dataset-JSON+Report.pdf ↩

4. "Another concern raised about Dataset-XML has been that the metadata - Define-XML - is completely separated from the data. To be able to process a Dataset-XML file one always needs the associated Define-XML document." Lex Jansen (https://www.lexjansen.com/pharmasug/2022/AD/PharmaSUG-2022-AD-150_ppt.pdf) ↩

5. "Python JSON is similar to a Python dictionary in that it stores data in key-value pairs enclosed in curly brackets ({}). However, double quotation marks around the JSON key are required in this case." Como visto em https://www.boardinfinity.com/blog/dict-to-json-in-python/ ↩

6. The differences between JSON objects and dict can be seen in detail in this GeeksforGeeks article: https://www.geeksforgeeks.org/difference-between-json-and-dictionary-in-python/ ↩

7. The object identifier varies from document to document, EDC to EDC. Using a specific EDC, OpenClinica, we see how this issue is addressed in the documentation here: https://docs.openclinica.com/3-1-technical-documents/openclinica-and-cdisc-odm-specifications/openclinica-and-cdisc-odm-specifications-cdisc-odm-representation-openclin-6/ ↩

Em estudos clínicos, é comum trabalharmos com conjuntos de dados que podem vir em variados formatos, dependendo do que o sistema EDC escolhido consegue oferecer. Entretanto, em algumas situações, será preciso extrair um conjunto de dados completo, de acordo com o que as entidades regulatórias exigem nas submissões de aprovação do uso de medicamentos e vacinas, principalmente. Dentre os formatos que aparecem como opções mais frequentes, estão o XML (que já vimos anteriormente) , e o JSON. Para aliviar um pouco mais do desespero que às vezes bate quando enfrentamos esses "monstros", hoje é a vez de ver na prática como lidar com um arquivo JSON.

O que é JSON?

JSON é a sigla para JavaScript Object Notation, uma representação de dados que, assim como o XML, pode ser utilizada para transmissões de dados. Como o próprio nome aponta, é baseado em um subconjunto da linguagem JavaScript; no entanto, possui uma estrutura universal, podendo ser lida e manipulada por várias linguagens de programação ¹.

Dataset-JSON

O Dataset-JSON é uma iniciativa em desenvolvimento contínuo liderada por CDISC e PHUSE ², com o objetivo de estabelecer uma alternativa mais leve, rápida, e legível para humanos, dos modelos de transferência de dados clínicos utilizados atualmente (a saber, SAS e Dataset-XML, este último já abordado no blog).

Diferenças entre JSON e XML para armazenamento e transferência de dados

Especialmente nos casos de dados de estudos clínicos, várias fontes apontam que o formato JSON leva certas vantagens sobre o formato XML. Podemos elencar alguns aqui:

• O XML, embora já seja um avanço frente a modelos de dados clínicos mais antigos, ainda é um formato de arquivo grande, muito em função da sua natureza verbosa; em uma mesma tag, por exemplo, é possível ter mais de um atributo que represente informações importantes (esse problema, inclusive, foi abordado no segundo post sobre o XML no blog). O JSON possui uma estrutura mais simples e flexível, podendo armazenar a mesma quantidade de informações que um XML num arquivo menor e de leitura mais fácil, economizando memória e energia;

• O JSON é inteiramente compatível com APIs, podendo ser visto em versões de EDCs mais novos (como o OpenClinica a partir da versão v. 4.x, e as versões mais novas dos REDCap Acadêmico e Cloud), facilitando a transmissão de dados, sem a necessidade de obrigatoriamente baixar arquivos manualmente ³. O XML, embora esteja presente em algumas APIs, não possui a mesma presença e facilidade do JSON;

• O JSON comporta informações básicas sobre as variáveis em seu próprio arquivo; para o XML, embora isso seja possível (como vimos em posts anteriores), não é necessariamente a regra, sendo dependente de arquivos externos ⁴;

• O XML permite a adição de novos namespaces, metadados e outras informações, mas sua estrutura rígida é um fator limitante crítico para tanto. O JSON é muito mais flexível, tendo uma estrutura mais simples e amigável para inserir novos dados.

Vejamos exemplos de como os elementos que formam arquivos XML e JSON são distribuídos na memória quando lidos. O primeiro caso é de uma árvore parecida com o esquema de árvore ODM de arquivos XML que já vimos antes. A árvore XML possui um grau alto de complexidade, evidenciada no diagrama abaixo, sendo que são muitos os elementos que precisam ser armazenados em espaços próprios na memória, fazendo com que seja preciso fazer mais "saltos" entre elementos para conseguir chegar ao dado que se quer.

Já quando falamos da árvore de um arquivo JSON, é possível perceber de cara uma redução na complexidade: os dados estão junto dos sub-elementos, fazendo com que o espaço ocupado na memória seja menor, assim como a quantidade de "saltos" feitos aqui, economizando tempo e energia. O esquema está no diagrama abaixo.

Podemos, a partir daqui, fornecer um resumo dessa comparação:

Usando Python para lidar com JSON

Dados que serão utilizados

Os dados que utilizaremos neste artigo ainda são do repositório do CDISC no GitHub, mas estão em uma pasta à parte dedicada aos arquivos Dataset-JSON. Além do exemplo que será nosso foco aqui, há muitos outros datasets que podem ser visualizados, extraídos, e manipulados à disposição.

Bibliotecas a serem importadas

Ao usarmos o Python para lidar com dados advindos de arquivos JSON, utilizaremos uma biblioteca em específico que é exatamente dedicada a esse tipo de documento: json. Esta é uma biblioteca nativa do Python; portanto, se você está utilizando WinPython ou Anaconda, é muito provável que consiga acessar a ferramenta apenas com uma importação. As outras bibliotecas que serão importadas já são de conhecimento nosso: requests e pandas.

import requests, json
import pandas as pd

Adquirindo e explorando os dados

Para obter os dados que iremos analisar, é possível utilizar passos semelhantes ao que já vimos em posts anteriores, usando a biblioteca requests. Com a função requests.get() enviamos uma requisição ao GitHub para obtermos o arquivo JSON que queremos, e, uma vez bem-sucedida essa requisição, podemos armazenar o conteúdo da mesma em uma variável, example.

Como retratado antes, diferentemente daquilo que fazemos com arquivos XML, usaremos o pacote json para lermos o arquivo resultante da requisição. Para este caso, usamos a função json.loads(), como abaixo.

example = requests.get('https://github.com/cdisc-org/DataExchange-DatasetJson/raw/refs/heads/master/examples/i18n/ae.json')
example = example.content
example = json.loads(example)

O resultado desse "carregamento" é um objeto parecido com o dict do Python, um dicionário ^{5 6}; esse é um dos tipos propostos para JSON quando da leitura do mesmo por algum software ou pacote de linguagem. Neste dicionário, encontraremos todas as informações de que precisamos para identificar os dados e colocá-los em um DataFrame legível e explorável.

Se explorarmos esse dicionário em uma IDE como o Spyder, que está disponível tanto no WinPython, quanto no Anaconda, veremos uma estrutura chave-valor clássica de um dicionário, mas estaremos também vendo outras coisas que nos interessam aqui, conforme a imagem abaixo.

Desde a versão dos metadados, até o número de registros contidos no arquivo JSON, várias informações essenciais do arquivo; foquemo-nos, no entanto, em apenas duas chaves: columns e rows. Nesses valores estarão aquilo que utilizaremos para montarmos o DataFrame em pandas que poderemos explorar mais à frente.

Acessando dados dentro do JSON

Para que seja possível acessar os dados de rows e columns dentro do objeto example, basta que sigamos a lógica de um dicionário em Python, como foi relatado antes. Usando o método object[key], ou objeto[chave], podemos acessar os dados que queremos dentro do dicionário example, usando algo como o bloco abaixo:

columns = example['columns']
rows = example['rows']

Com isso, podemos ter acesso pleno ao conteúdo que iremos utilizar para montar o DataFrame. Se invocarmos o objeto columns no console, será possível ver todo o conteúdo que ele possui.

columns

[{'itemOID': 'IT.AE.STUDYID',
  'name': 'STUDYID',
  'label': 'Study Identifier',
  'dataType': 'string',
  'length': 12},
 {'itemOID': 'IT.AE.DOMAIN',
  'name': 'DOMAIN',
  'label': 'Domain Abbreviation',
  'dataType': 'string',
  'length': 2},
 {'itemOID': 'IT.AE.USUBJID',
  'name': 'USUBJID',
  'label': 'Unique Subject Identifier',
  'dataType': 'string',
  'length': 11},
 {'itemOID': 'IT.AE.AESEQ',
  'name': 'AESEQ',
  'label': 'Sequence Number',
  'dataType': 'float'},
 {'itemOID': 'IT.AE.AESPID',
  'name': 'AESPID',
  'label': 'Sponsor-Defined Identifier',
  'dataType': 'string',
  'length': 3},
 {'itemOID': 'IT.AE.AETERM',
  'name': 'AETERM',
  'label': 'Reported Term for the Adverse Event',
  'dataType': 'string',
  'length': 200},
 {'itemOID': 'IT.AE.AELLT',
  'name': 'AELLT',
  'label': 'Lowest Level Term',
  'dataType': 'string',
  'length': 100},
 {'itemOID': 'IT.AE.AELLTCD',
  'name': 'AELLTCD',
  'label': 'Lowest Level Term Code',
  'dataType': 'float'},
 {'itemOID': 'IT.AE.AEDECOD',
  'name': 'AEDECOD',
  'label': 'Dictionary-Derived Term',
  'dataType': 'string',
  'length': 200},
 {'itemOID': 'IT.AE.AEPTCD',
  'name': 'AEPTCD',
  'label': 'Preferred Term Code',
  'dataType': 'float'},
 {'itemOID': 'IT.AE.AEHLT',
  'name': 'AEHLT',
  'label': 'High Level Term',
  'dataType': 'string',
  'length': 100},
 {'itemOID': 'IT.AE.AEHLTCD',
  'name': 'AEHLTCD',
  'label': 'High Level Term Code',
  'dataType': 'float'},
 {'itemOID': 'IT.AE.AEHLGT',
  'name': 'AEHLGT',
  'label': 'High Level Group Term',
  'dataType': 'string',
  'length': 100},
 {'itemOID': 'IT.AE.AEHLGTCD',
  'name': 'AEHLGTCD',
  'label': 'High Level Group Term Code',
  'dataType': 'float'},
 {'itemOID': 'IT.AE.AEBODSYS',
  'name': 'AEBODSYS',
  'label': 'Body System or Organ Class',
  'dataType': 'string',
  'length': 67},
 {'itemOID': 'IT.AE.AEBDSYCD',
  'name': 'AEBDSYCD',
  'label': 'Body System or Organ Class Code',
  'dataType': 'float'},
 {'itemOID': 'IT.AE.AESOC',
  'name': 'AESOC',
  'label': 'Primary System Organ Class',
  'dataType': 'string',
  'length': 100},
 {'itemOID': 'IT.AE.AESOCCD',
  'name': 'AESOCCD',
  'label': 'Primary System Organ Class Code',
  'dataType': 'float'},
 {'itemOID': 'IT.AE.AESEV',
  'name': 'AESEV',
  'label': 'Severity/Intensity',
  'dataType': 'string',
  'length': 8},
 {'itemOID': 'IT.AE.AESER',
  'name': 'AESER',
  'label': 'Serious Event',
  'dataType': 'string',
  'length': 1},
 {'itemOID': 'IT.AE.AEACN',
  'name': 'AEACN',
  'label': 'Action Taken with Study Treatment',
  'dataType': 'string',
  'length': 30},
 {'itemOID': 'IT.AE.AEREL',
  'name': 'AEREL',
  'label': 'Causality',
  'dataType': 'string',
  'length': 8},
 {'itemOID': 'IT.AE.AEOUT',
  'name': 'AEOUT',
  'label': 'Outcome of Adverse Event',
  'dataType': 'string',
  'length': 200},
 {'itemOID': 'IT.AE.AESCAN',
  'name': 'AESCAN',
  'label': 'Involves Cancer',
  'dataType': 'string',
  'length': 1},
 {'itemOID': 'IT.AE.AESCONG',
  'name': 'AESCONG',
  'label': 'Congenital Anomaly or Birth Defect',
  'dataType': 'string',
  'length': 1},
 {'itemOID': 'IT.AE.AESDISAB',
  'name': 'AESDISAB',
  'label': 'Persist or Signif Disability/Incapacity',
  'dataType': 'string',
  'length': 1},
 {'itemOID': 'IT.AE.AESDTH',
  'name': 'AESDTH',
  'label': 'Results in Death',
  'dataType': 'string',
  'length': 1},
 {'itemOID': 'IT.AE.AESHOSP',
  'name': 'AESHOSP',
  'label': 'Requires or Prolongs Hospitalization',
  'dataType': 'string',
  'length': 1},
 {'itemOID': 'IT.AE.AESLIFE',
  'name': 'AESLIFE',
  'label': 'Is Life Threatening',
  'dataType': 'string',
  'length': 1},
 {'itemOID': 'IT.AE.AESOD',
  'name': 'AESOD',
  'label': 'Occurred with Overdose',
  'dataType': 'string',
  'length': 1},
 {'itemOID': 'IT.AE.AEDTC',
  'name': 'AEDTC',
  'label': 'Date/Time of Collection',
  'dataType': 'string',
  'length': 10},
 {'itemOID': 'IT.AE.AESTDTC',
  'name': 'AESTDTC',
  'label': 'Start Date/Time of Adverse Event',
  'dataType': 'string',
  'length': 10},
 {'itemOID': 'IT.AE.AEENDTC',
  'name': 'AEENDTC',
  'label': 'End Date/Time of Adverse Event',
  'dataType': 'string',
  'length': 10},
 {'itemOID': 'IT.AE.AESTDY',
  'name': 'AESTDY',
  'label': 'Study Day of Start of Adverse Event',
  'dataType': 'float'},
 {'itemOID': 'IT.AE.AEENDY',
  'name': 'AEENDY',
  'label': 'Study Day of End of Adverse Event',
  'dataType': 'float'},
 {'itemOID': 'IT.AE.AETRTEM',
  'name': 'AETRTEM',
  'label': 'TREATMENT EMERGENT FLAG',
  'dataType': 'string',
  'length': 1}]

Perceba que, quando acessamos o columns, não tempos apenas o nome da coluna, mas também o que ela significa (através do label), tipo de dado (através do dataType), além do OID, que é o identificador do objeto ⁷. Isso evidencia a facilidade do JSON de comportar e acessar os metadados do arquivo, uma vantagem frente ao XML que, embora exista a possibilidade de acesso dos metadados em um mesmo arquivo, isso não é feito de forma tão facilitada.

Indo adiante, para vermos o que o objeto rows possui, usamos a mesmo método de antes. Como é esperado que o número de registros seja grande (ao verificarmos na chave recordsdo dicionário, temos 1191 registros!), veremos apenas a primeira ocorrência, neste caso.

rows[0] #A primeira ocorrência dentro da lista 'rows'

['CDISCPILOT01',
 'AE',
 '01-701-1015',
 1,
 'E07',
 'アプリケーションサイトの紅斑',
 'APPLICATION SITE REDNESS',
 None,
 'APPLICATION SITE ERYTHEMA',
 12345678,
 'HLT_0617',
 12345678,
 'HLGT_0152',
 12345678,
 'GENERAL DISORDERS AND ADMINISTRATION SITE CONDITIONS',
 87654321,
 'GENERAL DISORDERS AND ADMINISTRATION SITE CONDITIONS',
 None,
 'MILD',
 'N',
 '',
 'PROBABLE',
 'NOT RECOVERED/NOT RESOLVED',
 'N',
 'N',
 'N',
 'N',
 'N',
 'N',
 'N',
 '2014-01-16',
 '2014-01-03',
 '',
 2,
 None,
 'Y']

Perceba a ordem em que estão os dados; é de se esperar que, uma vez que "liguemos" as linhas às colunas, cada dado nessa lista comece a fazer sentido. Essa mesma ordem aparecerá em todas as outras linhas encontradas nesse objeto, que estão cada uma em uma lista separada.

Montando um DataFrame de um jeito simples

Para montarmos o DataFrame, primeiro é preciso ter duas coisas em mente: 1) Já temos as linhas da nossa tabela na variável rows, de forma (que se espera ser) ordenada; e 2) Temos as definições de nomes das colunas no objeto columns, em forma de dicionários em uma lista. Então, antes de usarmos o pandas para montarmos de vez o DataFrame, primeiro precisamos separar aquilo que serão os nomes das colunas da tabela. Para isso, basta criarmos uma lista data, que será populada com os rótulos, ou labels de uma iteração a partir da chave columns no nosso primeiro dicionário, example. Sendo columns uma lista com vários dicionários, basta com que a gente acesse cada dicionário dentro dessa lista, e extraia o label usando o princípio objeto[chave]. A partir disso, temos os rótulos de cada coluna, uma vez que são os valores de label dentro de cada dicionário.

data = [] #A lista a ser populada

for cl in example['columns']: #Iteração para extrairmos os rótulos
        data.append(cl['label'])

data #Acessar os dados da lista já populada

['Study Identifier',
 'Domain Abbreviation',
 'Unique Subject Identifier',
 'Sequence Number',
 'Sponsor-Defined Identifier',
 'Reported Term for the Adverse Event',
 'Lowest Level Term',
 'Lowest Level Term Code',
 'Dictionary-Derived Term',
 'Preferred Term Code',
 'High Level Term',
 'High Level Term Code',
 'High Level Group Term',
 'High Level Group Term Code',
 'Body System or Organ Class',
 'Body System or Organ Class Code',
 'Primary System Organ Class',
 'Primary System Organ Class Code',
 'Severity/Intensity',
 'Serious Event',
 'Action Taken with Study Treatment',
 'Causality',
 'Outcome of Adverse Event',
 'Involves Cancer',
 'Congenital Anomaly or Birth Defect',
 'Persist or Signif Disability/Incapacity',
 'Results in Death',
 'Requires or Prolongs Hospitalization',
 'Is Life Threatening',
 'Occurred with Overdose',
 'Date/Time of Collection',
 'Start Date/Time of Adverse Event',
 'End Date/Time of Adverse Event',
 'Study Day of Start of Adverse Event',
 'Study Day of End of Adverse Event',
 'TREATMENT EMERGENT FLAG']

Feito isso, o retorno que vemos é uma lista de nomes que utilizaremos para identificar cada coluna do nosso futuro DataFrame.

Com todo esse processo realizado, e com todos esses dados em mãos, já é hora de juntarmos tudo isso em um mesmo DataFrame; para tanto, lançaremos mão da função pd.DataFrame(), onde indicaremos onde está os dados que estarão nas linhas, rows, e os nomes das colunas, utilizando o argumento columns e o objeto data.

df = pd.DataFrame(rows, columns=data)

Uma vez integrado tudo em um DataFrame, basta salvar com o formato de preferência. A partir daqui, os dados semi-estruturados do JSON passam a ser dados estruturados de uma planilha.

## Exportando

df.to_csv('df.csv') #Arquivo .csv
df.to_excel('df.xlsx') #Arquivo .xlsx
df.to_parquet('df.parquet') #Arquivo .parquet

Notas do artigo

1. Mais informações sobre isso podem ser vistas na página oficial do JSON, que está traduzida em português, inclusive: https://www.json.org/json-pt.html ↩

2. O PHUSE é uma associação sem fins lucrativos que reúne pessoas que compartilham ideias e soluções envolvendo dados clínicos, como analisá-los e, posteriormente reportá-los. Muitas das inovações em dados envolvendo ensaios clínicos, certamente, virão dessa associação; portanto, vale muito a pena acompanhá-los via https://phuse.global/. ↩

3. PHUSE. https://phuse.s3.eu-central-1.amazonaws.com/Deliverables/Optimizing+the+Use+of+Data+Standards/WP-88+Dataset-JSON+Report.pdf ↩

4. "Another concern raised about Dataset-XML has been that the metadata - Define-XML - is completely separated from the data. To be able to process a Dataset-XML file one always needs the associated Define-XML document." Lex Jansen (https://www.lexjansen.com/pharmasug/2022/AD/PharmaSUG-2022-AD-150_ppt.pdf) ↩

5. "Python JSON is similar to a Python dictionary in that it stores data in key-value pairs enclosed in curly brackets ({}). However, double quotation marks around the JSON key are required in this case." Como visto em https://www.boardinfinity.com/blog/dict-to-json-in-python/ ↩

6. As diferenças entre objetos JSON e dict podem ser vistas neste artigo do GeeksforGeeks, de forma detalhada: https://www.geeksforgeeks.org/difference-between-json-and-dictionary-in-python/ ↩

7. O identificador do objeto varia de documento para documento, EDC para EDC. Usando um EDC específico, o OpenClinica, vemos como esse assunto é tratado na documentação, aqui: https://docs.openclinica.com/3-1-technical-documents/openclinica-and-cdisc-odm-specifications/openclinica-and-cdisc-odm-specifications-cdisc-odm-representation-openclin-6/ ↩

## Do you remember these libraries? ##
import requests
from lxml import etree
import pandas as pd

These libraries (especially pandas and lxml.etree) are designed to optimize the construction and manipulation of datasets contained in an XML document. However, we might encounter some obstacles along the way that were not addressed in the previous article. Here are a few:

• The XML document is huge: Previously, we used a file that was small in size; we know that in real life, things might not always be like that. We might end up with a file that is 1GB or larger;

• You don't need all the data contained in the file: To manipulate an XML document, libraries like lxml and ElementTree need, by the nature of this type of file, to read and interpret an XML from start to finish. For reasons like the problem mentioned above, this costs time and memory, affecting the performance of your Python script.

• You don't have a robust machine available: The two problems above are much harder to solve when we have a more limited machine. Using platforms like Google Colab can be a workaround for this, but we can't always rely on this resource.

From this, you might think something like, "I'm back to square one; how am I going to manipulate this darn XML and get the data I need? Will I have to look for an alternative other than Python?"

The goal of this article is to show that it's not time to give up on Python yet. By changing a few things in the code, you will certainly have another chance to tackle the "monsters" of XML and finally extract the much-anticipated data and information.

Understanding the obstacle itself

To start, let's focus on some of the first lines of code we're using:

from lxml import etree
import requests

url = 'https://github.com/cdisc-org/DataExchange-ODM/raw/main/examples/Demographics_RACE/Demographics_RACE_check_all_that_apply.xml' #Fonte do arquivo .xml que estamos utilizando
response = requests.get(url) #HTTP Request

tree = response.content #The request content

This block of code, as seen above, does three things: 1) Stores a string of a GitHub URL; 2) Makes a request to this URL via requests to get its content; and 3) Stores the content of the request in a variable (i.e., the XML file from which we will extract data).

The next step is to transform the content of the tree variable into something that can be read and explored by lxml, using the XML function. Like this:

tree = etree.XML(tree, etree.XMLParser(remove_comments=True))

print(tree)
<Element {http://www.cdisc.org/ns/odm/v2.0}ODM at 0x145a22f7a80>

The process of parsing, which is done here by lxml.etree, involves transforming the content extracted from the GitHub URL into an ODM tree with all its elements. This allows us to fully explore the content of the entire XML document since the element tree will be in the computer's memory, ready to be used...

... and that's where the problem might be.

Understanding the size of the obstacle

As mentioned earlier, the example we're using can be considered small in various ways. Besides the size, we can assume that the ODM tree resulting from the parsing isn't very large either. Transferring the example to your computer and running the entire script, it's possible that the processing will be fast and won't take up much memory.

For more real-life scenarios, it's not always like this. From personal experience, I've had to deal with XML files that, once transformed into pandas DataFrames, had more than 8 million rows. To give you an idea, an Excel spreadsheet has a row limit of just over 1 million. A real "monster."

For the ODM tree to be used through an lxml parse, it needs to be completely "unpacked," requiring memory allocation not only for the root node (which can be seen in this case using the tree.tag attribute in lxml) but also for the child nodes, or children, of the entire structure. This allocation not only adds complexity but can also consume a lot of the computer's memory (an example of how all this would be distributed in memory is illustrated in the diagram below).

The obstacle in the way starts to become the way

The idea here is to open the XML's structural tree without storing it all in memory. Instead, we open the data temporarily, allowing us to read the data sequentially without processing the entire file. This approach is especially recommended when we don't need all the data contained in the XML file. To do this, we'll add another Python library to our "toolbox": io.

Check out the snippet below:

import requests
from lxml import etree 
import pandas as pd
import io

url = 'https://github.com/cdisc-org/DataExchange-ODM/raw/main/examples/Demographics_RACE/Demographics_RACE_check_all_that_apply.xml'
response = requests.get(url)
tree = response.content

tree = io.BytesIO(tree)

Notice that after storing the HTTP request content in the tree variable using requests, the next step is transforming this content using the io.BytesIO() function. But what exactly are these things?

The io library, which is part of Python's Standard Library, handles raw data in the simplest way possible and temporarily. This means that when we read the content of the request stored in tree, we only read the content without turning it into a much more complex and heavy ODM tree. In other words, the io.BytesIO() function only opens the file and keeps it in a temporary memory space (a buffer) so it can be accessed while the code is running, through a sequence of bytes, as illustrated in the diagram below.

From this point, we can explore the data contained in the tree variable using another method available in lxml.etree, the etree.iterparse.

for _, element in etree.iterparse(io.BytesIO(den_xml2)): #DICA: Como o io.BytesIO(den_xml2) se trata de uma sequência temporária de caracteres, é mais interessante colocá-lo dentro da iteração em vez de tentar armazená-lo numa variável.
    ...

From here, it's possible to extract the data in a similar way to the method we used in the previous post.

But what's the difference?

You might be wondering what the actual difference is once the suggested changes are applied. It's possible to conduct various performance tests considering execution time and memory usage; but to summarize, look at the graph below, which shows relatively how much memory is used by each function, etree.XML() and io.BytesIO():

Notice that the graph divides between the raw data and the parsed ODM tree (remember the previous diagrams?); since io.BytesIO() only stores the raw data without needing to parse it to access the content, it only uses the space necessary for the bytes of that data to be available. On the other hand, the etree function, besides storing the raw data, has to keep the entire ODM tree available, thus needing more memory. This characteristic is crucial when dealing with XML files that exceed 1GB in size, for example; if we don't have enough memory to hold all the data from the file, we will certainly have numerous problems extracting what we want. Not to mention performance: the greater the memory requirement, the longer it takes to process everything as a result.

In the end, regardless of the size of the XML "monster" you have to deal with, it's still possible to do everything you need in an easier and less painful way using Python. It's up to us now to decide which method best suits each case and continue studying the tools and concepts discussed so far. So, the next time a huge obstacle appears in your path, you can take a moment to breathe, assess, and choose the best tool, so that obstacle becomes a simpler and—why not?—more enjoyable part of the journey.

## Lembra dessas bibliotecas? ##
import requests
from lxml import etree #Neste caso, usamos a API da biblioteca 'ElementTree' que está disponível na biblioteca 'lxml'
import pandas as pd

Essas bibliotecas (especialmente o pandas e o lxml.etree) foram pensados para otimizar a construção e manipulação de conjuntos de dados contidos em um documento XML. No entanto, é possível que encontremos alguns empecilhos no caminho, que não foram abordados no artigo anterior. Aqui estão alguns:

• O documento XML é enorme: Anteriormente, utilizamos um arquivo cujo tamanho é pequeno; sabemos que, na vida real, as coisas podem muito bem não vir assim. É possível que caia em nossas mãos um arquivo com 1GB de tamanho para mais;

• Você não precisa de todos os dados contidos no arquivo: Para poder manipular um documento XML, bibliotecas como lxml e ElementTree precisam, pela própria natureza desse tipo de arquivo, ler e interpretar um XML do início ao fim. Por razões como o problema já mencionado acima, isso custa tempo e memória, afetando a performance do seu script em Python.

• Você não tem à disposição uma máquina robusta: Os dois problemas acima são muito mais difíceis de resolver quando temos uma máquina mais limitada. Usar plataformas como o Google Colab podem ser uma alternativa de contorno a isso, mas nem sempre podemos lançar mão desse recurso.

A partir disso, você pode pensar algo como “voltei à estaca zero; como é que eu vou conseguir manipular esse bendito XML, e conseguir os dados de que preciso? Será que terei de ir atrás de outra alternativa senão o Python?”

O objetivo desse artigo é mostrar que ainda não é hora de desistir do Python. Mudando algumas coisas no código, você ganhará, com certeza, mais uma chance de enfrentar os “monstros” do XML, e finalmente conseguir extrair os dados e informações tão esperados.

Conhecendo o obstáculo

Para começar, debruçemo-nos em algumas das primeiras linhas de código que estamos utilizando:

from lxml import etree
import requests

url = 'https://github.com/cdisc-org/DataExchange-ODM/raw/main/examples/Demographics_RACE/Demographics_RACE_check_all_that_apply.xml' #Fonte do arquivo .xml que estamos utilizando
response = requests.get(url) #Requisição HTTP

tree = response.content #O conteúdo da requisição

Esse bloco de código, como é visto acima, faz três coisas: 1) Armazena uma string de um endereço URL do GitHub; 2) Faz uma requisição a esse URL via (requests)[https://requests.readthedocs.io/] para obter o conteúdo do mesmo; e 3) Armazena o conteúdo da requisição em uma variável (i.e., o arquivo XML do qual extrairemos os dados).

O próximo passo é transformar o conteúdo da variável tree em algo que pode ser lido e explorado pelo lxml, usando a função XML. Assim:

tree = etree.XML(tree, etree.XMLParser(remove_comments=True))

print(tree)
<Element {http://www.cdisc.org/ns/odm/v2.0}ODM at 0x145a22f7a80>

O processo de parsing, que é o processo aqui realizado pelo lxml.etree, consiste em transformar o conteúdo que foi extraído da URL do GitHub em uma árvore ODM com todos os seus elementos. Com isso, podemos explorar o conteúdo de todo o documento XML de forma completa, uma vez que a árvore de elementos estará na memória do computador, pronta para ser utilizada...

... e é aí que pode estar o problema.

Entendendo o tamanho do problema

Como dito anteriormente, o exemplo que estamos utilizando pode ser considerado pequeno, nos mais variados sentidos. Além do tamanho, podemos assumir que a árvore ODM que é resultado do parsing também não é muito grande. Transferindo o exemplo para o seu computador e executando o script inteiro, é possível que o processamento seja rápido e não ocupe tanta memória.

Para casos mais próximos da vida real, nem sempre é assim. Exemplificando através de uma experiência pessoal, já me encontrei na situação de ter de lidar com arquivos XML que, uma vez transformados em DataFrames do pandas, possuíam mais de 8 milhões de linhas. Para se ter uma ideia, uma planilha do Excel possui um limite de linhas de um pouco mais de 1 milhão. Um verdadeiro "monstro".

Acontece que, para que a árvore ODM possa ser utilizada através de um parse do lxml, ela precisa ser totalmente "destrinchada", precisando alocar na memória, além do nó raiz (que pode ser visto, neste caso, usando o atributo tree.tag no lxml), os nós filhos, ou children, de toda a estrutura. Essa alocação toda não só gera toda uma complexidade da coisa, mas também pode custar muita memória do computador (um exemplo de como isso tudo estaria distribuído na memória é ilustrado no diagrama abaixo).

Transformando o obstáculo no caminho

A ideia aqui é, em vez de abrir toda a árvore estrutural do XML e armazenar na memória, abrir os dados sem precisar processar o arquivo, de uma forma temporária, onde nós poderemos ler os dados em sequência. Essa abordagem é especialmente recomendada quando não precisamos de todos os dados contidos no arquivo XML. Para tanto, adicionaremos mais uma biblioteca Python em nossa "caixa de ferramentas": io.

Observe o snippet abaixo:

import requests
from lxml import etree 
import pandas as pd
import io

url = 'https://github.com/cdisc-org/DataExchange-ODM/raw/main/examples/Demographics_RACE/Demographics_RACE_check_all_that_apply.xml'
response = requests.get(url)
tree = response.content

tree = io.BytesIO(tree)

Perceba que, após armazenar o conteúdo da requisição HTTP na variável tree usando o requests, o passo seguinte é a transformação desse conteúdo usando a função io.BytesIO(). Mas, afinal, o que são essas coisas?

A biblioteca io, que compõe a Biblioteca Padrão do Python, vem lidar com os dados brutos da maneira mais simples possível, e de forma temporária. Isso quer dizer que, ao lermos o conteúdo da requisição que foi armazenada em tree, faremos apenas uma leitura do conteúdo, sem torná-lo uma árvore ODM bem mais complexa e pesada. Ou seja, a função io.BytesIO() somente abre o arquivo, e o deixa em um espaço temporário da memória (um buffer) para que seja possível acessá-lo enquanto o código é executado, através de uma sequência de bytes, conforme ilustrado no diagrama abaixo.

A partir disso, podemos realizar uma exploração dos dados contidos na variável tree através de um outro método presente no lxml.etree, o etree.iterparse.

for _, element in etree.iterparse(io.BytesIO(den_xml2)): #DICA: Como o io.BytesIO(den_xml2) se trata de uma sequência temporária de caracteres, é mais interessante colocá-lo dentro da iteração em vez de tentar armazená-lo numa variável.
    ...

A partir daqui, é possível extrair os dados de maneira semelhante ao método que utilizamos no post anterior.

Mas qual é a diferença?

Você pode estar se perguntando sobre qual é a diferença factual vista uma vez aplicada as mudanças sugeridas. É possível fazer vários testes de performance considerando o tempo de execução e a quantidade de memória utilizada; mas, para resumir, observe o gráfico a seguir, que mostra de maneira relativa o quanto de memória é ocupada por cada função, etree.XML() e io.BytesIO():

Perceba que o gráfico faz a divisão entre os dados brutos e a árvore ODM parseada (lembra dos diagramas anteriores?); uma vez que o io.BytesIO() apenas armazena os dados brutos, sem precisar fazer nenhum parsing para acessar o conteúdo, ele ocupa apenas o espaço necessário para que os bytes desses dados estejam disponíveis; já a função do etree, além de armazenar os dados brutos, tem de manter disponível a árvore ODM inteira, assim tendo que ocupar mais memória. Essa característica é decisiva na hora de lidarmos com arquivos XML que rompem a barreira dos 1GB de tamanho, por exemplo; se não temos uma quantidade de memória o suficiente para que caiba todos os dados do arquivo, certamente teremos inúmeros problemas para extrair o que queremos. Isso sem falar na performance: quanto maior a necessidade de memória, mais tempo para processarmos tudo, por consequência.

Ao fim e ao cabo, independentemente do tamanho do "monstro" XML com o qual você terá de lidar, ainda é possível fazer tudo que se precisa de uma maneira mais fácil e menos dolorosa usando o Python. Cabe a nós agora decidirmos qual método se adapta melhor a cada caso, e seguir estudando sobre as ferramentas e conceitos que foram abordados até agora. E assim, da próxima vez que um obstáculo enorme aparecer em seu caminho, você pode parar pra respirar, avaliar e escolher a melhor ferramenta, para que esse obstáculo se torne uma parte mais simples e - por que não? - mais divertida do caminho.

In clinical studies, it's common to work with datasets that can come in various formats, depending on what the chosen EDC system can offer. However, in some situations, it will be necessary to extract a complete dataset, according to what regulatory entities require for the approval submissions of drug and vaccine use, mainly. From that point, there isn't much choice; an XML document will always appear as the most facilitated option. For those used to dealing with all types of data, some effort might be needed to transform it into something that can be used in various analyses. And for those used to dealing only with structured data (like spreadsheets), panic sets in. What now? What to do from there?

In this article, we will explore some of the secrets hidden in an ODM-XML document, as well as how we can uncover these secrets and produce a spreadsheet that makes sense for clinical study data analysis.

Why XML?

In general, there are some good reasons to use XML when working with data. For example:

• You can create a file that works with many data manipulation tools. Since an XML document is a text file, it can be easily transferred between different technologies. Many technologies can read and process XML for this reason (some examples can be found here).

• It maintains data integrity, which is crucial when working with databases. This is achieved by combining metadata and data in a single file, ensuring all resources are available without needing to import other files (we will explore this in more detail throughout the article)¹.

• The organization and categorization of data are more efficient, making it easier and faster to find specific information within an XML document.

What is ODM?

ODM stands for Operational Data Model. According to CDISC, "it is a format that can be used to store and exchange data between data management systems, as well as to store data, metadata, and administrative data related to a clinical study." For some health regulatory entities, like the FDA in the United States ^{2 3 4 5}, CDISC has suggested this format as the standard for data archiving because of its ability to carry all relevant information for clinical studies in a single interchangeable file when needed.

The ODM model offers an XML model that facilitates the capture of clinical data; from a schema like the one in the figure below, we can divide the XML document into two main parts: the metadata, which provides the definition of the variables to be used, and the actual data, where the clinical study information is stored.

The schema of an XML document for clinical data, according to the ODM model established by CDISC. ⁶

Another schema of an XML document for clinical data. ⁷

Importing libraries

When using Python to extract data from .xml documents, you need to import some libraries. If you use platforms like Anaconda or WinPython, simply using import might be enough. If you're using a "pure" version of Python, I recommend installing the libraries using pip before proceeding with the following steps.

In this article, we will use libraries such as:

• requests, the simplest library for making web page requests (because life is complex enough);

• lxml, another easy-to-use library for processing XML files;

• pandas, the most well-known library for data manipulation and analysis; with it, you can create a spreadsheet with the XML data.

import requests
from lxml import etree #In this case, we are going to use the ElementTree API available in the lxml library.
import pandas as pd

Getting the data

The .xml document we will use comes from a CDISC GitHub repository. To obtain it directly, i.e., without downloading any files, we will use the requests library. The get function of this library makes a request to a GitHub page containing the file and waits for a response from that page, which we are storing in the response variable. If the response is code 200, it means the request was successful.

url = 'https://github.com/cdisc-org/DataExchange-ODM/raw/main/examples/Demographics_RACE/Demographics_RACE_check_all_that_apply.xml'
response = requests.get(url)
print(response)

<Response [200]>

From this response, we will use the content object to actually get the XML that will be explored. The content will be available in the tree variable, as shown in the code below:

tree = response.content

The variable tree will be with us throughout the entire process of building the spreadsheet from the information we have.

Transforming and Checking the XML Structure

After extracting the content from the GitHub page, you can observe the structure of the XML that will be explored when the content is transformed into a readable variable. This is important for locating the tags, attributes, and values where the relevant data is found.

From here, we begin using another library we imported: lxml, which is dedicated to obtaining the XML elements mentioned earlier. We will store the entire XML in the variable tree, where the content from the GitHub page will be passed along with the type of parser (the transformer) that will be used. The variable tree2, in this case, serves to allow us to actually observe the "skeleton" of the XML.

tree = etree.XML(tree, etree.XMLParser(remove_comments=True))
tree2 = etree.tostring(tree, pretty_print = True, encoding = str)
print(tree2)

    <ODM xmlns="http://www.cdisc.org/ns/odm/v2.0" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xlink="http://www.w3.org/1999/xlink" CreationDateTime="2020-07-06T10:20:15+01:00" FileOID="DEMOGRAPHICS_EXAMPLE" FileType="Snapshot" Granularity="Metadata" ODMVersion="2.0" SourceSystem="XML4Pharma CDISC ODM Study Designer" SourceSystemVersion="2015-R1">
       <Study OID="ST.DEMOGRAPHICS_EXAMPLE" StudyName="Study with Demographics example" ProtocolName="MyStudy">
          <Description><TranslatedText xml:lang="en" Type="text/plain">Demographics example with Race, with "check all that apply"</TranslatedText></Description>
          <MetaDataVersion Name="Version 1" OID="MV.1.0">
             <Description><TranslatedText xml:lang="en" Type="text/plain">Version 1</TranslatedText></Description>
             <StudyEventDef Name="Screening visit with demographics" OID="SE.SCREENING" Repeating="No" Type="Scheduled">
                <ItemGroupRef ItemGroupOID="FO.DEMOGRAPHICS" Mandatory="Yes"/>
             </StudyEventDef>
             <ItemGroupDef Name="Demographics form" OID="FO.DEMOGRAPHICS" Type="Form" Repeating="No">
                <ItemGroupRef ItemGroupOID="IG.DEMOGRAPHICS" Mandatory="Yes"/>
             </ItemGroupDef>
             <ItemGroupDef Name="Demographics" OID="IG.DEMOGRAPHICS" Type="Section" Repeating="No">
                <ItemRef ItemOID="IT.DOB" Mandatory="Yes"/>
                <ItemRef ItemOID="IT.SEX" Mandatory="Yes"/>
                <ItemRef ItemOID="IT.ETHNIC" Mandatory="Yes"/>


                <ItemGroupRef ItemGroupOID="IG.RACE" Mandatory="Yes"/>
             </ItemGroupDef>

             ...

             <CodeList DataType="integer" Name="Sex" OID="CL.SEX">
                <CodeListItem CodedValue="1">
                   <Decode>
                      <TranslatedText xml:lang="en" Type="text/plain">Male</TranslatedText>
                   </Decode>
                </CodeListItem>
                <CodeListItem CodedValue="2">
                   <Decode>
                      <TranslatedText xml:lang="en" Type="text/plain">Female</TranslatedText>
                   </Decode>
                </CodeListItem>
             </CodeList>
             <CodeList DataType="integer" Name="Ethnicity" OID="CL.ETHNIC">
                <CodeListItem CodedValue="1">
                   <Decode>
                      <TranslatedText xml:lang="en" Type="text/plain">Hispanic</TranslatedText>
                   </Decode>
                </CodeListItem>
                <CodeListItem CodedValue="2">
                   <Decode>
                      <TranslatedText xml:lang="en" Type="text/plain">Non-hispanic</TranslatedText>
                   </Decode>
                </CodeListItem>
             </CodeList>

             ...

          </MetaDataVersion>
       </Study>

       <ClinicalData StudyOID="ST.DEMOGRAPHICS_EXAMPLE" MetaDataVersionOID="MV.1.0">

          <SubjectData SubjectKey="001">
             <StudyEventData StudyEventOID="SE.SCREENING">
                <ItemGroupData ItemGroupOID="FO.DEMOGRAPHICS">
                   <ItemGroupData ItemGroupOID="IG.DEMOGRAPHICS">
                      <ItemData ItemOID="IT.DOB"><Value>1957-05-07</Value></ItemData>
                      <ItemData ItemOID="IT.SEX"><Value>1</Value></ItemData>
                      <ItemData ItemOID="IT.ETHNIC"><Value>2</Value></ItemData>

                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="1">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>1</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>false</Value></ItemData>
                      </ItemGroupData>

                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="2">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>2</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>true</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="3">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>3</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>false</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="4">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>4</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>4</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="5">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>5</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>false</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="6">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>99</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>false</Value></ItemData>
                      </ItemGroupData>
                   </ItemGroupData>
                </ItemGroupData>
             </StudyEventData>
          </SubjectData>

          ...

          <SubjectData SubjectKey="003">
             <StudyEventData StudyEventOID="SE.SCREENING">
                <ItemGroupData ItemGroupOID="FO.DEMOGRAPHICS">
                   <ItemGroupData ItemGroupOID="IG.DEMOGRAPHICS">
                      <ItemData ItemOID="IT.DOB"><Value>1961-06-09</Value></ItemData>
                      <ItemData ItemOID="IT.SEX"><Value>2</Value></ItemData>
                      <ItemData ItemOID="IT.ETHNIC"><Value>1</Value></ItemData>

                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="1">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>1</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>false</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="2">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>2</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>false</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="3">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>3</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>false</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="4">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>4</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>false</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="5">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>5</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>false</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="6">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>99</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>true</Value></ItemData>
                         <ItemData ItemOID="IT.RACEOTH"><Value>Native Amazonian</Value></ItemData>
                      </ItemGroupData>
                   </ItemGroupData>
                </ItemGroupData>
             </StudyEventData>
          </SubjectData>
       </ClinicalData>
    </ODM>

Checking the namespaces

When exploring an XML, it's essential to be aware of the namespaces it contains. Namespaces can provide a unique identification for each component tag. The use of namespaces is recommended by the W3C and is very necessary when we have tags or attributes with similar names but associated with different elements or tags. To see which namespaces appear in the XML document, use the nsmap object, as shown below:

ns = tree.nsmap
print(ns)

{None: 'http://www.cdisc.org/ns/odm/v2.0', 'xs': 'http://www.w3.org/2001/XMLSchema', 'xlink': 'http://www.w3.org/1999/xlink'}

Checking tags

Now that we know about the namespaces, we can analyze what the names of the tags are. These names will allow us to extract the data of interest later on.

elements = []
for elem in tree.iter():
    elements.append(elem.tag)

elements = list(set(elements))
print(elements)

['{http://www.cdisc.org/ns/odm/v2.0}TranslatedText', '{http://www.cdisc.org/ns/odm/v2.0}Description', '{http://www.cdisc.org/ns/odm/v2.0}ItemGroupDef', '{http://www.cdisc.org/ns/odm/v2.0}Decode', '{http://www.cdisc.org/ns/odm/v2.0}ClinicalData', '{http://www.cdisc.org/ns/odm/v2.0}ODM', '{http://www.cdisc.org/ns/odm/v2.0}ItemGroupData', '{http://www.cdisc.org/ns/odm/v2.0}ItemRef', '{http://www.cdisc.org/ns/odm/v2.0}Question', '{http://www.cdisc.org/ns/odm/v2.0}CodeListItem', '{http://www.cdisc.org/ns/odm/v2.0}SubjectData', '{http://www.cdisc.org/ns/odm/v2.0}ItemGroupRef', '{http://www.cdisc.org/ns/odm/v2.0}MetaDataVersion', '{http://www.cdisc.org/ns/odm/v2.0}StudyEventData', '{http://www.cdisc.org/ns/odm/v2.0}Study', '{http://www.cdisc.org/ns/odm/v2.0}Value', '{http://www.cdisc.org/ns/odm/v2.0}CodeListRef', '{http://www.cdisc.org/ns/odm/v2.0}StudyEventDef', '{http://www.cdisc.org/ns/odm/v2.0}ItemDef', '{http://www.cdisc.org/ns/odm/v2.0}ItemData', '{http://www.cdisc.org/ns/odm/v2.0}CodeList']

Extracting the first attributes

Knowing how the XML file is structured and which tags are present, it's possible to select where the data of interest is located. The next step is to analyze what's inside the tags. This content is called attributes. Attributes are internal parts of the tags that follow a pattern 'Name="Value"'. Notice the attribute 'ItemOID' at the end of the first line; it is accompanied by a value "IT.DOB". This is the pattern used and recommended by the W3C when it comes to attributes. ⁸

print(etree.tostring(tree.find('.//ItemData', ns), pretty_print = True, encoding = str))

    <ItemData xmlns="http://www.cdisc.org/ns/odm/v2.0" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xlink="http://www.w3.org/1999/xlink" ItemOID="IT.DOB">
      <Value>1957-05-07</Value>
    </ItemData>

To access the attributes of a specific tag, you can use two functions from lxml, depending on the situation: find and findall. The first one is used to retrieve only the first occurrence of a tag in the XML file, while the other returns all occurrences of tags with the mentioned name.

tree.find('.//ClinicalData', ns) #Only the first occurence of the tag 'ClinicalData'.

<Element {http://www.cdisc.org/ns/odm/v2.0}ClinicalData at 0x21052103e80>

tree.findall('.//SubjectData', ns) #Todas as ocorrências da tag SubjectData

[<Element {http://www.cdisc.org/ns/odm/v2.0}SubjectData at 0x21052102e00>,
<Element {http://www.cdisc.org/ns/odm/v2.0}SubjectData at 0x21052108540>,
<Element {http://www.cdisc.org/ns/odm/v2.0}SubjectData at 0x21052108840>]

Notice that when we use these functions, the return is an object of the class Element; however, this is not exactly what we are looking for. To find out what the tags and their attributes really are, we can use two objects with suggestive names: attrib and tag. For attributes, the results return as a dictionary, where the key is the attribute's name, and the value is the attribute's value. The tag function, on the other hand, returns the names of the mentioned tags.

tree.find('.//ClinicalData', ns).attrib #The attributes of the tag 'ClinicalData' (the only tag, in this case).

{'StudyOID': 'ST.DEMOGRAPHICS_EXAMPLE', 'MetaDataVersionOID': 'MV.1.0'}

for subject in tree.findall('.//SubjectData', ns):
    subj = subject.attrib #Attributes of each 'SubjectData' tag.
    print(subj)

{'SubjectKey': '001'}
{'SubjectKey': '002'}
{'SubjectKey': '003'}

tree.find('.//SubjectData', ns).tag #Name of the tag.

'{http://www.cdisc.org/ns/odm/v2.0}SubjectData'

for subject in tree.findall('.//SubjectData', ns):
    for eve in subject:
        print(eve.attrib) #All attributes of the 'SubjectData' tag.

{'StudyEventOID': 'SE.SCREENING'}
{'StudyEventOID': 'SE.SCREENING'}
{'StudyEventOID': 'SE.SCREENING'}

for subject in tree.findall('.//SubjectData', ns):
    for event in subject:
        for item in event:
            ite = item.attrib
            print(ite) #All the attributes of 'ItemGroupOID'

{'ItemGroupOID': 'FO.DEMOGRAPHICS'}
{'ItemGroupOID': 'FO.DEMOGRAPHICS'}
{'ItemGroupOID': 'FO.DEMOGRAPHICS'}

If you want to extract only the value of a specific attribute, just select the attribute using its name in brackets, similar to how you find the value of a specific key stored in a dictionary:

print(subj['SubjectKey']) #Value of the last 'SubjectKey' attribute in the 'SubjectData' tag.

003

Checking the XML structure for just one subject

We have already seen how to filter one or more tags by their names and discover their attributes and values. If it is interesting or necessary to analyze the XML structure of just one tag occurrence (in this case, an individual) more deeply, you can use the find function, which we already know. With the code below, we can check the XML structure for the first subject.

print(etree.tostring(tree.find('.//SubjectData', ns), pretty_print = True, encoding = str))

    <SubjectData xmlns="http://www.cdisc.org/ns/odm/v2.0" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xlink="http://www.w3.org/1999/xlink" SubjectKey="001">
             <StudyEventData StudyEventOID="SE.SCREENING">
                <ItemGroupData ItemGroupOID="FO.DEMOGRAPHICS">
                   <ItemGroupData ItemGroupOID="IG.DEMOGRAPHICS">
                      <ItemData ItemOID="IT.DOB"><Value>1957-05-07</Value></ItemData>
                      <ItemData ItemOID="IT.SEX"><Value>1</Value></ItemData>
                      <ItemData ItemOID="IT.ETHNIC"><Value>2</Value></ItemData>

                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="1">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>1</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>false</Value></ItemData>
                      </ItemGroupData>

                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="2">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>2</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>true</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="3">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>3</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>false</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="4">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>4</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>4</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="5">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>5</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>false</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="6">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>99</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>false</Value></ItemData>
                      </ItemGroupData>
                   </ItemGroupData>
                </ItemGroupData>
             </StudyEventData>
          </SubjectData>

Now, if we want to filter the tags and attributes related to a specific subject, we need to mention the SubjectKey attribute and specify the subject's value (in this case, '002'), as shown in the code below:

print(etree.tostring(tree.find('.//SubjectData[@SubjectKey="002"]', ns), pretty_print = True, encoding = str))

    <SubjectData xmlns="http://www.cdisc.org/ns/odm/v2.0" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xlink="http://www.w3.org/1999/xlink" SubjectKey="002">
             <StudyEventData StudyEventOID="SE.SCREENING">
                <ItemGroupData ItemGroupOID="FO.DEMOGRAPHICS">
                   <ItemGroupData ItemGroupOID="IG.DEMOGRAPHICS">
                      <ItemData ItemOID="IT.DOB"><Value>1975-01-31&gt;</Value></ItemData>
                      <ItemData ItemOID="IT.SEX"><Value>2</Value></ItemData>
                      <ItemData ItemOID="IT.ETHNIC"><Value>2</Value></ItemData>

                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="1">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>1</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>1</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="2">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>2</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>false</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="3">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>3</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>true</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="4">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>4</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>false</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="5">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>5</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>false</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="6">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>99</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>false</Value></ItemData>
                      </ItemGroupData>
                   </ItemGroupData>
                </ItemGroupData>
             </StudyEventData>
          </SubjectData>

Looking for data from just one tag

Just as we can analyze how an entire XML document is structured, it is possible to specify a tag and separate its structure, allowing us to examine how the tag itself is arranged, as well as the tags connected to it.

print(etree.tostring(tree.find('.//ItemData', ns), pretty_print = True, encoding = str))

    <ItemData xmlns="http://www.cdisc.org/ns/odm/v2.0" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xlink="http://www.w3.org/1999/xlink" ItemOID="IT.DOB">
      <Value>1957-05-07</Value>
    </ItemData>

Now, check the Value tag: it has a value we want to extract, but it's not in an attribute; it's text between the tags. To access the content between the opening and closing tags, we can use the text class from lxml.

tree.find('.//Value', ns).text

'1957-05-07'

We can do the same with the tag name, this time using the tag class.

tree.find('.//Value', ns).tag

'{http://www.cdisc.org/ns/odm/v2.0}Value'

Making spreadsheets

Now that we know some basic points about XML and how to manipulate them using Python libraries, we can move on to the next phase: creating spreadsheets (or producing DataFrames). But before we do that, with what we've already learned, we'll organize a data extraction scheme using lxml.

Our goal here is to create a DataFrame containing the date of birth, gender, and ethnicity data for each individual recorded in the XML document. To achieve this, we'll adopt a strategy of establishing a for loop, so that with each iteration, we can extract the data associated with the SubjectData tag and its descendants. After completing the iterations, we'll store the data in a results list, whose outcome is shown below. This is an interesting method because the extracted values are organized into three distinct groups, which will become the columns of our future DataFrame.

results = []
for ide in tree.findall('.//SubjectData', ns):
    for subj in ide.findall('.//StudyEventData/ItemGroupData/ItemGroupData/ItemData', ns):
            for value in subj:
                results.append([ide.attrib['SubjectKey'], subj.attrib['ItemOID'], value.text])

results

[['001', 'IT.DOB', '1957-05-07'],
['001', 'IT.SEX', '1'],
['001', 'IT.ETHNIC', '2'],
['002', 'IT.DOB', '1975-01-31>'],
['002', 'IT.SEX', '2'],
['002', 'IT.ETHNIC', '2'],
['003', 'IT.DOB', '1961-06-09'],
['003', 'IT.SEX', '2'],
['003', 'IT.ETHNIC', '1']]

Once the list is created and stored in the results variable, we can easily use pandas to make a DataFrame with the pd.DataFrame function. It's easy because we can use the list we produced directly, without needing more transformations. In this function, we'll pass the list as an argument and specify the names of the columns we want to appear: ID, Variable, Value. It's possible, without any issues, to assign any name to each column.

results = pd.DataFrame(results, columns=['ID', 'Variable', 'Value']) 
results

We have a DataFrame, but we need to go a bit further before considering it complete. The main idea here is to have results with only one ID per row, ensuring all data related to that ID is in the same row. Here, we see that we could use the values from the Variable column as column names, and what's in the Value column would be the values for each column by ID.

The good news is that pandas allows us to do this without any problem. What we will perform now is a pivot of the data we have. For this, we can use two functions: pivot and pivot_table, with a slight difference between them. The function chosen here is pivot_table, where we will use results as the data source, the ID column as the temporary index of the DataFrame, the Variable column to name the new columns, and the Value column to provide the values for the columns. Additionally, we need to invoke a function in the aggfunc argument, which serves as a function to perform calculations or organize data in a specific order (the first data to appear, the last, etc.). In this case, we will use the first function because we simply want the first (and only) value to appear in the DataFrame. Finally, we will use reset_index, making ID a manipulable column again.

results = pd.pivot_table(results, index='ID', columns='Variable', values='Value', aggfunc='first').reset_index()
results

This way, we are giving a more definitive appearance to our DataFrame. However, notice that the column names, as well as the values in the last two sheets, still do not clearly tell us what information is being shown. By looking more closely at the XML document, we can see that there is a part that provides valuable information to give more meaning to the data we have: the metadata section. This is what we will explore from now on.

Searching for the metadata of the XML document (and improving the spreadsheet)

Metadata are the definitions of each variable and value within the XML document. It is interesting, even necessary, to obtain them so we can truly understand what each column and value represents in a DataFrame. In this specific document, the metadata we are interested in are located in the tags named ItemDef, and we can extract them with the block of code illustrated below:

for meta in tree.findall('.//ItemDef', ns):
    print(meta.attrib)

{'DataType': 'date', 'Name': 'Date of birth', 'OID': 'IT.DOB'}
{'DataType': 'integer', 'Length': '1', 'Name': 'Sex', 'OID': 'IT.SEX'}
{'DataType': 'integer', 'Length': '1', 'Name': 'Ethnicity', 'OID': 'IT.ETHNIC'}
{'OID': 'IT.RACE_CODE', 'Name': 'Race code', 'DataType': 'integer', 'Length': '1'}
{'DataType': 'boolean', 'Length': '1', 'Name': 'Race', 'OID': 'IT.RACE_BOOLEAN'}
{'DataType': 'text', 'Length': '20', 'Name': 'Other Race', 'OID': 'IT.RACEOTH'}

Notice that the output is a series of dictionaries with keys indicating aspects like 'Name' and 'OID' (a unique ID for each object in the XML). We can extract these to convert the coded column names into names that show what each column actually represents. To do this, we'll create a dictionary with each column's OID as the key and the column name as the value, as shown below:

names = {}
for meta in tree.findall('.//ItemDef', ns):
    names[meta.attrib['OID']] = meta.attrib['Name']
names

{'IT.DOB': 'Date of birth',
'IT.SEX': 'Sex',
'IT.ETHNIC': 'Ethnicity',
'IT.RACE_CODE': 'Race code',
'IT.RACE_BOOLEAN': 'Race',
'IT.RACEOTH': 'Other Race'}

Now, with the rename function from pandas, we can change the column names in results, and things start to make more sense.

results = results.rename(columns=names)
results

We also have two columns here that are in numeric codes: Ethnicity and Sex. The definitions of these codes are usually at the beginning of the XML document, along with the metadata. To get the names of the sex and ethnicity codes, in this case, there is a tag that will be our target: CodeList. The code below shows how the tag is structured:

print(etree.tostring(tree.find('.//CodeList', ns), pretty_print = True, encoding = str))

    <CodeList xmlns="http://www.cdisc.org/ns/odm/v2.0" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xlink="http://www.w3.org/1999/xlink" DataType="integer" Name="Sex" OID="CL.SEX">
                <CodeListItem CodedValue="1">
                   <Decode>
                      <TranslatedText xml:lang="en" Type="text/plain">Male</TranslatedText>
                   </Decode>
                </CodeListItem>
                <CodeListItem CodedValue="2">
                   <Decode>
                      <TranslatedText xml:lang="en" Type="text/plain">Female</TranslatedText>
                   </Decode>
                </CodeListItem>
             </CodeList>

Now, recall the previous method we used to get column names. Basically, the principle for obtaining the values of numeric codes is the same; however, it is a bit more complex, requiring a few more lines of code. When accessing the CodeList tag, if we want to extract values for Ethnicity, we need to filter by mentioning the name of this attribute using XPATH. This comes right after the tag name; thus, we can create a new dictionary, ethnicity, to hold codes and values for the ethnicities represented in the DataFrame.

ethnicity = {}
for eth in tree.findall('.//CodeList[@Name="Ethnicity"]', ns):
    for code in tree.findall('.//CodeList[@Name="Ethnicity"]/CodeListItem', ns):
        for decode in code:
            for name in decode:
                ethnicity[code.attrib['CodedValue']] = name.text
ethnicity

{'1': 'Hispanic', '2': 'Non-hispanic'}

To get the values of the codes in the Sex column, just use the same method as before, only replacing the name of the attribute to be filtered.

sex = {}
for eth in tree.findall('.//CodeList[@Name="Sex"]', ns):
    for code in tree.findall('.//CodeList[@Name="Sex"]/CodeListItem', ns):
        for decode in code:
            for name in decode:
                sex[code.attrib['CodedValue']] = name.text
sex

{'1': 'Male', '2': 'Female'}

With the dictionaries ready, we can proceed with the remaining substitutions. Here, we'll use the pandas map function, which associates the keys (i.e., the numeric codes) of the dictionaries we created with the values that name the numbers. We'll do this for both columns, Ethnicity and Sex; notice that the spreadsheet now makes much more sense and is ready for the desired analyses.

results['Ethnicity'] = results['Ethnicity'].map(ethnicity)
results['Sex'] = results['Sex'].map(sex)
results

To save the DataFrame that was created, simply use the built-in pandas functions for this purpose. This way, the extracted information will be stored in a file that is lighter and faster to handle.

## Exportando

results.to_csv('results.csv') #.csv file
results.to_excel('results.xlsx') #.xlsx file
results.to_parquet('results.parquet') #.parquet file

Notes

1. This is succinctly and very well supported in Shabo et al. (2006): “The Clinical Data Interchange Standards Consortium (CDISC) is leading the development of standards to improve data quality and accelerate product development in the pharmaceutical industry.19 The CDISC model focuses on the use of metadata, and the approach is to combine XML representation with the tabular presentation traditionally used for clinical-trial data.” - Shabo, A., S. Rabinovici-Cohen, e P. Vortman. “Revolutionary impact of XML on biomedical information interoperability”. IBM Systems Journal 45, nº 2 (2006): 361–72. https://doi.org/10.1147/sj.452.0361. ↩

2. “Interest in ODM as a research topic has grown significantly over the last several years with increasing interest in the CDISC data standards from regulatory authorities such as the FDA and the Japanese Pharmaceutical and Medical Devices Agency (PMDA)” - Hume, Sam, Jozef Aerts, Surendra Sarnikar, e Vojtech Huser. “Current Applications and Future Directions for the CDISC Operational Data Model Standard: A Methodological Review”. Journal of Biomedical Informatics 60 (abril de 2016): 352–62. https://doi.org/10.1016/j.jbi.2016.02.016. ↩

3. “While it is a requirement to submit pre-clinical and clinical data in CDISC format to regulatory bodies such as the US FDA and Japan’s Pharmaceuticals and Medical Devices Agency (PDMA), the actual usage of CDISC standards spans a much wider array of entities.” Hufstedler, Heather, Yannik Roell, Andressa Peña, Ankur Krishnan, Ian Green, Adriano Barbosa-Silva, Andreas Kremer, et al. “Navigating data standards in public health: A brief report from a data-standards meeting”. Journal of Global Health 14 ([s.d.]): 03024. https://doi.org/10.7189/jogh.14.03024. ↩

4. "The CDISC Operational Data Model (ODM) is an XML format that facilitates the exchange of clinical data captured during a clinical study. ODMbased files contain the study data and the associated descriptions of the data items, their groupings into Case Report Forms (CRFs), which are electronic documents to record the study data, and the associated questions and code lists. Furthermore, the FDA has mandated the use of other CDISC standards in clinical studies." Leroux, Hugo, e Laurent Lefort. “Semantic Enrichment of Longitudinal Clinical Study Data Using the CDISC Standards and the Semantic Statistics Vocabularies”. Journal of Biomedical Semantics 6, nº 1 (dezembro de 2015): 16. https://doi.org/10.1186/s13326-015-0012-6. ↩

5. “The Federal Drug Administration has mandated the use of the CDISC standards for the electronic capture and reporting of clinical study data” Leroux, Hugo, Alejandro Metke-Jimenez, e Michael J. Lawley. “Towards Achieving Semantic Interoperability of Clinical Study Data with FHIR”. Journal of Biomedical Semantics 8, nº 1 (19 de setembro de 2017): 41. https://doi.org/10.1186/s13326-017-0148-7. ↩

6. Lefort, Laurent, e Hugo Leroux. “Design and generation of Linked Clinical Data Cubes”, 2013. https://doi.org/10.13140/RG.2.1.3677.2967. ↩

7. Brix, Tobias Johannes, Philipp Bruland, Saad Sarfraz, Jan Ernsting, Philipp Neuhaus, Michael Storck, Justin Doods, Sonja Ständer, e Martin Dugas. “ODM Data Analysis—A Tool for the Automatic Validation, Monitoring and Generation of Generic Descriptive Statistics of Patient Data”. PLOS ONE 13, nº 6 (22 de junho de 2018): e0199242. https://doi.org/10.1371/journal.pone.0199242. ↩

8. An important note: From now on, in addition to Python libraries and XML, we will use another language, this one for querying: XPath. With it, we can properly access XML elements and attributes. I won't go into details about it in this article, but if you want to understand more about it, you can see more details here and here, as well as a good cheat sheet here. We won't use many different things from this language here, but it's interesting to explore it further later.. ↩

Em estudos clínicos, é comum trabalharmos com conjuntos de dados que podem vir em variados formatos, dependendo do que o sistema EDC escolhido consegue oferecer. Entretanto, em algumas situações, será preciso extrair um conjunto de dados completo, de acordo com o que as entidades regulatórias exigem nas submissões de aprovação do uso de medicamentos e vacinas, principalmente. A partir disso, não há muita escolha; sempre aparecerá como a opção mais facilitada um documento XML. Para quem está acostumado a lidar com todo tipo de dado, talvez um pouco de esforço terá de ser feito pra transformar isso em algo que possa ser usados em várias análises. E para quem está acostmado a lidar apenas com dados estruturados (planilhas), o desespero bate. E agora? O que fazer?

Neste artigo, veremos um pouco dos segredos que escondem um documento ODM-XML, além de como podemos extrair esses segredos, e produzir uma planilha com algo que faça sentido na hora das análises de dados de estudos clínicos.

Por que XML?

Num apanhado geral, há alguns (bons) motivos para se usar XML ao lidar com dados. Exemplificando:

• É possível criar um arquivo que pode ser utilizado com as mais variadas ferramentas de manipulação de dados. Sendo o documento XML um arquivo de texto, pode ser transferido de uma tecnologia para outra sem maior esforço; muitas tecnologias, por isso mesmo, conseguem ler e processar XML (alguns exemplos podem ser vistos aqui.

• Mantém a integridade dos dados, o que é um aspecto vital na hora de lidar com base de dados. Isso é feito a partir da concentração de aspectos como metadados e dados dentro de um só arquivo, fazendo com que todos os recursos estejam à disposição sem precisar importar outros arquivos (e isto iremos explorar de forma um pouco mais detalhada ao longo do artigo)¹.

• A organização e categorização dos dados é mais eficiente, fazendo com que a busca por uma determinada informação dentro de um documento XML seja mais rápida e menos, digamos, "dolorosa".

O que é ODM?

ODM é a sigla para Operational Data Model. Segundo o CDISC, "é um formato que pode ser utilizado para armazenar, intercambiar entre sistemas de gestão de dados, bem como para armazenar os dados, metadados, e dados administrativos referentes a um estudo clínico". Para algumas entidades regulatórias de saúde, como a FDA dos Estados Unidos ²³⁴⁵, o CDISC sugeriu este formato como o padrão para arquivamento de dados, por sua capacidade de carregar todas as informações pertinentes a estudos clínicos em um só arquivo intercambiável, quando preciso.

O modelo ODM oferece um modelo XML que facilita a captura de dados clínicos; a partir de um esquema como o da figura abaixo, podemos dividir o documento XML em duas partes principais: a de metadados, que dá a definição das variáveis que serão utilizadas, e a dos dados propriamente ditos, onde estarão depositados as informações do estudo clínico.

O esquema de um documento XML para dados clínicos, segundo o modelo ODM estabelecido pelo CDISC. ⁶

Outro esquema de um documento XML para dados clínicos. ⁷

Importando bibliotecas

Ao usar o Python para extrair dados de documentos .xml, é preciso importar algumas bibliotecas; se você usa plataformas como o Anaconda ou o WinPython, é provável que apenas o uso do import já seja o suficiente. Se você estiver usando uma versão "pura" do Python, recomendo que, antes de executar os passos a seguir, seja feita a instalação das bibliotecas usando o pip.

Neste artigo, usaremos bibliotecas como:

• requests, a biblioteca mais simples para requisições envolvendo páginas web (porque de complexa já basta a vida);

• lxml, outra biblioteca 'easy-to-use', esta para processar os arquivos XML;

• pandas, que é a biblioteca mais conhecida para manipulação e análise de dados; com ela, será possível construir uma planilha com os dados do XML.

import requests
from lxml import etree #Neste caso, usaremos a API da biblioteca 'ElementTree' que está disponível na biblioteca 'lxml'
import pandas as pd

Obtendo os dados

O documento .xml que será utilizado origina-se de um repositório no GitHub da CDISC; para obtê-lo diretamente, i.e., sem precisar fazer o download de qualquer arquivo, usaremos a biblioteca requests. A função get dessa biblioteca faz uma requisição a uma página do GitHub que contém o arquivo, e espera uma resposta dessa página em forma de código, que estamos armazenando na variável response. Se a resposta for o código 200, significa que a requisição foi bem-sucedida.

url = 'https://github.com/cdisc-org/DataExchange-ODM/raw/main/examples/Demographics_RACE/Demographics_RACE_check_all_that_apply.xml'
response = requests.get(url)
print(response)

<Response [200]>

A partir dessa resposta, utilizaremos o objeto content para de fato obter o XML que será explorado. O conteúdo estará disponível na variável tree, conforme o código que está abaixo:

tree = response.content

A variável tree nos acompanhará durante todo o processo de construção da planilha a partir das informações que temos.

Fazendo a transformação e verificando a estrutura do XML

Feita a extração do conteúdo que está na página do GitHub, é possível observar a estrutura do XML que será explorado, quando o conteúdo será transformado em uma variável legível; isso é importante para serem localizadas as tags, atributos, e valores onde estão os dados que interessam de fato.

A partir daqui, começamos o uso de outra biblioteca que importamos: lxml, que se dedicará à obtenção dos elementos XML que já foram mencionados. Armazenaremos o XML inteiro na variável tree, onde serão passados o conteúdo da página do GitHub, além do tipo de parser (o transformador) que será utilizado. A variável tree2, neste caso, serve para podermos observar de fato o "esqueleto" do XML.

tree = etree.XML(tree, etree.XMLParser(remove_comments=True))
tree2 = etree.tostring(tree, pretty_print = True, encoding = str)
print(tree2)

    <ODM xmlns="http://www.cdisc.org/ns/odm/v2.0" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xlink="http://www.w3.org/1999/xlink" CreationDateTime="2020-07-06T10:20:15+01:00" FileOID="DEMOGRAPHICS_EXAMPLE" FileType="Snapshot" Granularity="Metadata" ODMVersion="2.0" SourceSystem="XML4Pharma CDISC ODM Study Designer" SourceSystemVersion="2015-R1">
       <Study OID="ST.DEMOGRAPHICS_EXAMPLE" StudyName="Study with Demographics example" ProtocolName="MyStudy">
          <Description><TranslatedText xml:lang="en" Type="text/plain">Demographics example with Race, with "check all that apply"</TranslatedText></Description>
          <MetaDataVersion Name="Version 1" OID="MV.1.0">
             <Description><TranslatedText xml:lang="en" Type="text/plain">Version 1</TranslatedText></Description>
             <StudyEventDef Name="Screening visit with demographics" OID="SE.SCREENING" Repeating="No" Type="Scheduled">
                <ItemGroupRef ItemGroupOID="FO.DEMOGRAPHICS" Mandatory="Yes"/>
             </StudyEventDef>
             <ItemGroupDef Name="Demographics form" OID="FO.DEMOGRAPHICS" Type="Form" Repeating="No">
                <ItemGroupRef ItemGroupOID="IG.DEMOGRAPHICS" Mandatory="Yes"/>
             </ItemGroupDef>
             <ItemGroupDef Name="Demographics" OID="IG.DEMOGRAPHICS" Type="Section" Repeating="No">
                <ItemRef ItemOID="IT.DOB" Mandatory="Yes"/>
                <ItemRef ItemOID="IT.SEX" Mandatory="Yes"/>
                <ItemRef ItemOID="IT.ETHNIC" Mandatory="Yes"/>


                <ItemGroupRef ItemGroupOID="IG.RACE" Mandatory="Yes"/>
             </ItemGroupDef>

             ...

             <CodeList DataType="integer" Name="Sex" OID="CL.SEX">
                <CodeListItem CodedValue="1">
                   <Decode>
                      <TranslatedText xml:lang="en" Type="text/plain">Male</TranslatedText>
                   </Decode>
                </CodeListItem>
                <CodeListItem CodedValue="2">
                   <Decode>
                      <TranslatedText xml:lang="en" Type="text/plain">Female</TranslatedText>
                   </Decode>
                </CodeListItem>
             </CodeList>
             <CodeList DataType="integer" Name="Ethnicity" OID="CL.ETHNIC">
                <CodeListItem CodedValue="1">
                   <Decode>
                      <TranslatedText xml:lang="en" Type="text/plain">Hispanic</TranslatedText>
                   </Decode>
                </CodeListItem>
                <CodeListItem CodedValue="2">
                   <Decode>
                      <TranslatedText xml:lang="en" Type="text/plain">Non-hispanic</TranslatedText>
                   </Decode>
                </CodeListItem>
             </CodeList>

             ...

          </MetaDataVersion>
       </Study>

       <ClinicalData StudyOID="ST.DEMOGRAPHICS_EXAMPLE" MetaDataVersionOID="MV.1.0">

          <SubjectData SubjectKey="001">
             <StudyEventData StudyEventOID="SE.SCREENING">
                <ItemGroupData ItemGroupOID="FO.DEMOGRAPHICS">
                   <ItemGroupData ItemGroupOID="IG.DEMOGRAPHICS">
                      <ItemData ItemOID="IT.DOB"><Value>1957-05-07</Value></ItemData>
                      <ItemData ItemOID="IT.SEX"><Value>1</Value></ItemData>
                      <ItemData ItemOID="IT.ETHNIC"><Value>2</Value></ItemData>

                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="1">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>1</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>false</Value></ItemData>
                      </ItemGroupData>

                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="2">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>2</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>true</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="3">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>3</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>false</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="4">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>4</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>4</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="5">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>5</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>false</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="6">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>99</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>false</Value></ItemData>
                      </ItemGroupData>
                   </ItemGroupData>
                </ItemGroupData>
             </StudyEventData>
          </SubjectData>

          ...

          <SubjectData SubjectKey="003">
             <StudyEventData StudyEventOID="SE.SCREENING">
                <ItemGroupData ItemGroupOID="FO.DEMOGRAPHICS">
                   <ItemGroupData ItemGroupOID="IG.DEMOGRAPHICS">
                      <ItemData ItemOID="IT.DOB"><Value>1961-06-09</Value></ItemData>
                      <ItemData ItemOID="IT.SEX"><Value>2</Value></ItemData>
                      <ItemData ItemOID="IT.ETHNIC"><Value>1</Value></ItemData>

                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="1">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>1</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>false</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="2">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>2</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>false</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="3">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>3</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>false</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="4">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>4</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>false</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="5">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>5</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>false</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="6">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>99</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>true</Value></ItemData>
                         <ItemData ItemOID="IT.RACEOTH"><Value>Native Amazonian</Value></ItemData>
                      </ItemGroupData>
                   </ItemGroupData>
                </ItemGroupData>
             </StudyEventData>
          </SubjectData>
       </ClinicalData>
    </ODM>

Verificando os namespaces

Ao explorarmos um XML, é essencial que tomemos conhecimento dos namespaces que este possui. Os namespaces podem servir de identificação única para cada tag componente. O uso de namespaces é recomendado pela W3C, e se vê muito necessário quando temos tags ou atributos de nome semelhante, mas associado a elementos ou tags diferentes. Para vermos quais namespaces aparecem no documento XML, utliza-se o objeto nsmap, como abaixo:

ns = tree.nsmap
print(ns)

{None: 'http://www.cdisc.org/ns/odm/v2.0', 'xs': 'http://www.w3.org/2001/XMLSchema', 'xlink': 'http://www.w3.org/1999/xlink'}

Verificando as tags

Tendo já conhecimento dos namespaces, podemos agora analisar quais são os nomes daquilo que chamamos de tags. É através desses nomes que será possível extrair os dados de interesse mais para frente.

elements = []
for elem in tree.iter():
    elements.append(elem.tag)

elements = list(set(elements))
print(elements)

['{http://www.cdisc.org/ns/odm/v2.0}TranslatedText', '{http://www.cdisc.org/ns/odm/v2.0}Description', '{http://www.cdisc.org/ns/odm/v2.0}ItemGroupDef', '{http://www.cdisc.org/ns/odm/v2.0}Decode', '{http://www.cdisc.org/ns/odm/v2.0}ClinicalData', '{http://www.cdisc.org/ns/odm/v2.0}ODM', '{http://www.cdisc.org/ns/odm/v2.0}ItemGroupData', '{http://www.cdisc.org/ns/odm/v2.0}ItemRef', '{http://www.cdisc.org/ns/odm/v2.0}Question', '{http://www.cdisc.org/ns/odm/v2.0}CodeListItem', '{http://www.cdisc.org/ns/odm/v2.0}SubjectData', '{http://www.cdisc.org/ns/odm/v2.0}ItemGroupRef', '{http://www.cdisc.org/ns/odm/v2.0}MetaDataVersion', '{http://www.cdisc.org/ns/odm/v2.0}StudyEventData', '{http://www.cdisc.org/ns/odm/v2.0}Study', '{http://www.cdisc.org/ns/odm/v2.0}Value', '{http://www.cdisc.org/ns/odm/v2.0}CodeListRef', '{http://www.cdisc.org/ns/odm/v2.0}StudyEventDef', '{http://www.cdisc.org/ns/odm/v2.0}ItemDef', '{http://www.cdisc.org/ns/odm/v2.0}ItemData', '{http://www.cdisc.org/ns/odm/v2.0}CodeList']

Extraindo os primeiros atributos

Sabendo já como o arquivo XML está estruturado, bem como quais são as tags que estão presentes, é possível selecionar os locais onde estão os dados de interesse. A próxima coisa a se fazer é analisar o que está dentro das tags. A esse conteúdo damos o nome de atributos. Atributos são partes internas das tags que obedecem um padrão 'Nome="Valor"'. Perceba o atributo 'ItemOID' no final da primeira linha; ele vem acompanhado de um valor "IT.DOB". Este é o padrão utilizado e recomendado pela W3C quando se tratam de atributos. ⁸

print(etree.tostring(tree.find('.//ItemData', ns), pretty_print = True, encoding = str))

    <ItemData xmlns="http://www.cdisc.org/ns/odm/v2.0" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xlink="http://www.w3.org/1999/xlink" ItemOID="IT.DOB">
      <Value>1957-05-07</Value>
    </ItemData>

Para acessar os atributos de uma tag em específico, é possível utilizar duas funções do lxml, dependendo da situação: find e findall. A primeira serve para resgatar somente a primeira ocorrência de uma tag no arquivo XML, enquanto que a outra retorna todas as ocorrências de tags com o nome mencionado.

tree.find('.//ClinicalData', ns) #Apenas a primeira ocorrência da tag ClinicalData

<Element {http://www.cdisc.org/ns/odm/v2.0}ClinicalData at 0x21052103e80>

tree.findall('.//SubjectData', ns) #Todas as ocorrências da tag SubjectData

[<Element {http://www.cdisc.org/ns/odm/v2.0}SubjectData at 0x21052102e00>,
<Element {http://www.cdisc.org/ns/odm/v2.0}SubjectData at 0x21052108540>,
<Element {http://www.cdisc.org/ns/odm/v2.0}SubjectData at 0x21052108840>]

Perceba que, ao usarmos estas funções, o retorno é um objeto de classe Element; contudo, não é exatamente isso que está sendo procurado. Para buscar o que realmente são as tags e os atributos dentro delas, podemos nos valer de dois objetos, cujos nomes são sugestivos: attrib e tag. No caso do atributo, os resultados retornam em forma de dicionário, onde a chave é o nome do atributo, e o valor é o valor desse mesmo atributo. A função tag, por sua vez, retorna os nomes das tags que foram mencionadas.

tree.find('.//ClinicalData', ns).attrib #Atributos apenas da primeira (e única) tag ClinicalData

{'StudyOID': 'ST.DEMOGRAPHICS_EXAMPLE', 'MetaDataVersionOID': 'MV.1.0'}

for subject in tree.findall('.//SubjectData', ns):
    subj = subject.attrib #Atributos de cada tag SubjectData
    print(subj)

{'SubjectKey': '001'}
{'SubjectKey': '002'}
{'SubjectKey': '003'}

tree.find('.//SubjectData', ns).tag #Nome da tag SubjectData

'{http://www.cdisc.org/ns/odm/v2.0}SubjectData'

for subject in tree.findall('.//SubjectData', ns):
    for eve in subject:
        print(eve.attrib) #Atributos das tags StudyEventData

{'StudyEventOID': 'SE.SCREENING'}
{'StudyEventOID': 'SE.SCREENING'}
{'StudyEventOID': 'SE.SCREENING'}

for subject in tree.findall('.//SubjectData', ns):
    for event in subject:
        for item in event:
            ite = item.attrib
            print(ite) #Atributos da tag ItemGroupDef

{'ItemGroupOID': 'FO.DEMOGRAPHICS'}
{'ItemGroupOID': 'FO.DEMOGRAPHICS'}
{'ItemGroupOID': 'FO.DEMOGRAPHICS'}

Caso se queira extrair somente o valor de um determinado atributo, basta fazer uma seleção do atributo com seu nome em colchetes, o mesmo que se faz quando se quer descobrir o valor de uma determinada chave armazenada em um dicionário:

print(subj['SubjectKey']) #Valor do atributo SubjectKey na última tag SubjectData

003

Verificando a estrutura do XML para apenas um indivíduo

Nós já vimos como fazer uma filtragem de uma ou mais tags através de seus nomes, e descobrir os atributos e seus valores. Caso seja interessante ou necessário analisar mais a fundo a estrutura XML de apenas uma ocorrência de tag (nesse caso, um indivíduo), basta utilizar a função find, que já conhecemos. Com o código abaixo, podemos verificar a estrutura do XML para o primeiro indivíduo.

print(etree.tostring(tree.find('.//SubjectData', ns), pretty_print = True, encoding = str))

    <SubjectData xmlns="http://www.cdisc.org/ns/odm/v2.0" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xlink="http://www.w3.org/1999/xlink" SubjectKey="001">
             <StudyEventData StudyEventOID="SE.SCREENING">
                <ItemGroupData ItemGroupOID="FO.DEMOGRAPHICS">
                   <ItemGroupData ItemGroupOID="IG.DEMOGRAPHICS">
                      <ItemData ItemOID="IT.DOB"><Value>1957-05-07</Value></ItemData>
                      <ItemData ItemOID="IT.SEX"><Value>1</Value></ItemData>
                      <ItemData ItemOID="IT.ETHNIC"><Value>2</Value></ItemData>

                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="1">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>1</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>false</Value></ItemData>
                      </ItemGroupData>

                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="2">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>2</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>true</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="3">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>3</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>false</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="4">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>4</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>4</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="5">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>5</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>false</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="6">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>99</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>false</Value></ItemData>
                      </ItemGroupData>
                   </ItemGroupData>
                </ItemGroupData>
             </StudyEventData>
          </SubjectData>

Agora, se queremos filtrar as tags e atributos referentes a um outro indivíduo em específico, é preciso mencionar o atributo SubjectKey e mencionar o valor do indivíduo (no caso, '002'), como o código abaixo:

print(etree.tostring(tree.find('.//SubjectData[@SubjectKey="002"]', ns), pretty_print = True, encoding = str))

    <SubjectData xmlns="http://www.cdisc.org/ns/odm/v2.0" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xlink="http://www.w3.org/1999/xlink" SubjectKey="002">
             <StudyEventData StudyEventOID="SE.SCREENING">
                <ItemGroupData ItemGroupOID="FO.DEMOGRAPHICS">
                   <ItemGroupData ItemGroupOID="IG.DEMOGRAPHICS">
                      <ItemData ItemOID="IT.DOB"><Value>1975-01-31&gt;</Value></ItemData>
                      <ItemData ItemOID="IT.SEX"><Value>2</Value></ItemData>
                      <ItemData ItemOID="IT.ETHNIC"><Value>2</Value></ItemData>

                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="1">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>1</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>1</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="2">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>2</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>false</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="3">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>3</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>true</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="4">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>4</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>false</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="5">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>5</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>false</Value></ItemData>
                      </ItemGroupData>
                      <ItemGroupData ItemGroupOID="IG.RACE" ItemGroupRepeatKey="6">
                         <ItemData ItemOID="IT.RACE_CODE"><Value>99</Value></ItemData>
                         <ItemData ItemOID="IT.RACE_BOOLEAN"><Value>false</Value></ItemData>
                      </ItemGroupData>
                   </ItemGroupData>
                </ItemGroupData>
             </StudyEventData>
          </SubjectData>

Buscando dados de uma tag apenas

Assim como podemos analisar como um documento XML inteiro está estruturado, é possível especificar uma tag e separar sua estrutura, podendo assim analisar como está disposta a prórpia tag, bem como as tags que estão ligadas a ela.

print(etree.tostring(tree.find('.//ItemData', ns), pretty_print = True, encoding = str))

    <ItemData xmlns="http://www.cdisc.org/ns/odm/v2.0" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xlink="http://www.w3.org/1999/xlink" ItemOID="IT.DOB">
      <Value>1957-05-07</Value>
    </ItemData>

Agora, verifique a tag Value: ela possui um valor que nos interessa extrair, mas não está em um atributo; é um texto que está entre as tags. Para acessar o conteúdo que está entre as tags de abertura e fechamento, podemos nos valer da classe text do lxml.

tree.find('.//Value', ns).text

'1957-05-07'

O mesmo podemos fazer com o nome da tag, usando dessa vez a classe tag.

tree.find('.//Value', ns).tag

'{http://www.cdisc.org/ns/odm/v2.0}Value'

Produzindo planilhas

Sabendo já alguns pontos básicos de XML, e como manipulá-los usando bibliotecas do Python, podemos agora ir para a fase seguinte: produzir planilhas (ou produzir DataFrames). Mas antes de fazermos isso, com o que já vimos, organizaremos um esquema de extração de dados usando o lxml.

O nosso objetivo aqui é elaborar um DataFrame que contenha os dados de data de nascimento, sexo, e etnia de cada indivíduo registrado no documento XML. Para tanto, adotaremos a estratégia de estabelecer um loop em for, para que, a cada iteração, consigamos extrair os dados associados à tag SubjectData e suas herdeiras. Feitas as iterações, armazenaremos os dados em uma lista results, cujo resultado aparece abaixo. É um método de resultado interessante, dado que os valores extraídos estão organizados em três grupos próprios, que serão as colunas do nosso futuro DataFrame.

results = []
for ide in tree.findall('.//SubjectData', ns):
    for subj in ide.findall('.//StudyEventData/ItemGroupData/ItemGroupData/ItemData', ns):
            for value in subj:
                results.append([ide.attrib['SubjectKey'], subj.attrib['ItemOID'], value.text])

results

[['001', 'IT.DOB', '1957-05-07'],
['001', 'IT.SEX', '1'],
['001', 'IT.ETHNIC', '2'],
['002', 'IT.DOB', '1975-01-31>'],
['002', 'IT.SEX', '2'],
['002', 'IT.ETHNIC', '2'],
['003', 'IT.DOB', '1961-06-09'],
['003', 'IT.SEX', '2'],
['003', 'IT.ETHNIC', '1']]

Elaborada a lista e armazenada na variável results, podemos agora facilmente usar o pandas para fazer um DataFrame, com a função pd.DataFrame. É fácil pois podemos utilizar a lista que produzimos diretamente, sem precisar de mais transformações. Nessa função, passaremos a lista como um argumento, e faremos menção aos nomes das colunas que queremos que apareça. São elas ID, Variable, Value. É possível, sem quaisquer problemas, colocar qualquer nome a cada coluna.

results = pd.DataFrame(results, columns=['ID', 'Variable', 'Value']) 
results

Conseguimos um DataFrame, mas precisamos ir um pouco mais além antes de dar tudo como terminado. A ideia principal aqui é fazer com que results esteja com apenas um ID por linha, fazendo com que todos os dados referentes ao ID estejam nessa mesma linha. Aqui vemos que poderíamos utilizar os valores da coluna Variable como nomes das colunas, e o que está na coluna Value seriam os valores de cada coluna por ID.

A boa notícia é que o pandas permite fazer isso sem o menor problema. O que iremos performar agora é uma pivotagem dos dados que temos. Para tanto, podemos utilizar duas funções: pivot e pivot_table, com uma leve diferença entre as duas. A função escolhida aqui é a pivot_table, onde vamos lançar o results como fonte de dados, a coluns ID como índice temporário do DataFrame, a coluna Value como quem dará o nome às novas colunas, e a coluna Value como quem dará os valores às colunas. Ainda, teremos de invocar uma função no argumento aggfunc, que serve como uma função para fazer cálculos ou lançar um dado de forma ordenada (o primeiro dado a aparecer, o último, etc.). Nesse caso, usaremos a função first, porque simplesmente queremos que o primeiro (e único) valor a aparecer seja aquele aparente no DataFrame. Para fechar, utilizaremos o reset_index, fazendo com que ID volte a ser uma coluna manipulável.

results = pd.pivot_table(results, index='ID', columns='Variable', values='Value', aggfunc='first').reset_index()
results

Assim estamos dando uma aparência mais definitiva ao nosso DataFrame. Mas veja que os nomes das colunas, bem como os valores das últimas duas planilhas ainda não nos informam com clareza qual a informação a ser mostrada. Analisando mais atentamente ao documento XML, se percebe que há uma parte nele que nos fornece informações valiosas para darmos mais sentido aos dados que temos: a parte dos metadados. É isso que exploraremos a partir de agora.

Buscando os metadados do documento XML (e melhorando a planilha)

Os metadados são as definições de cada variável e valor dentro do documento XML. É interessante, até preciso, obtê-los para que possamos compreender de fato o que cada coluna e valor representa em um DataFrame. Neste documento em específico, os metadados que nos interessam estão depositados nas tags de nome ItemDef, e podemos extraí-los com o bloco de código ilustrado abaixo:

for meta in tree.findall('.//ItemDef', ns):
    print(meta.attrib)

{'DataType': 'date', 'Name': 'Date of birth', 'OID': 'IT.DOB'}
{'DataType': 'integer', 'Length': '1', 'Name': 'Sex', 'OID': 'IT.SEX'}
{'DataType': 'integer', 'Length': '1', 'Name': 'Ethnicity', 'OID': 'IT.ETHNIC'}
{'OID': 'IT.RACE_CODE', 'Name': 'Race code', 'DataType': 'integer', 'Length': '1'}
{'DataType': 'boolean', 'Length': '1', 'Name': 'Race', 'OID': 'IT.RACE_BOOLEAN'}
{'DataType': 'text', 'Length': '20', 'Name': 'Other Race', 'OID': 'IT.RACEOTH'}

Perceba que o retorno é uma série de dicionários cujas chaves indicam aspectos como 'Nome' e 'OID' (um ID único para cada objeto que compõe o XML); para extrair esses dois e torná-los úteis para convertermos os nomes em código das colunas em um nome que nos indica o que determinada coluna realmente representa. Para tanto, criaremos um dicionário com o OID de cada coluna como chave, e o valor como o nome da coluna, como está abaixo:

names = {}
for meta in tree.findall('.//ItemDef', ns):
    names[meta.attrib['OID']] = meta.attrib['Name']
names

{'IT.DOB': 'Date of birth',
'IT.SEX': 'Sex',
'IT.ETHNIC': 'Ethnicity',
'IT.RACE_CODE': 'Race code',
'IT.RACE_BOOLEAN': 'Race',
'IT.RACEOTH': 'Other Race'}

Agora, com a função rename do pandas, podemos mudar os nomes das colunas em results, e as coisas começam a ter mais sentido.

results = results.rename(columns=names)
results

Nós temos aqui também duas colunas que estão em códigos numéricos: Ethnicity e Sex. As definições desses códigos, costumeiramente, estão no início do documento XML, junto dos metadados. Para obtermos os nomes dos códigos de sexo e etnia, nesse caso, há uma tag que será nosso alvo: CodeList. O código abaixo mostra como a tag está estruturada:

print(etree.tostring(tree.find('.//CodeList', ns), pretty_print = True, encoding = str))

    <CodeList xmlns="http://www.cdisc.org/ns/odm/v2.0" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xlink="http://www.w3.org/1999/xlink" DataType="integer" Name="Sex" OID="CL.SEX">
                <CodeListItem CodedValue="1">
                   <Decode>
                      <TranslatedText xml:lang="en" Type="text/plain">Male</TranslatedText>
                   </Decode>
                </CodeListItem>
                <CodeListItem CodedValue="2">
                   <Decode>
                      <TranslatedText xml:lang="en" Type="text/plain">Female</TranslatedText>
                   </Decode>
                </CodeListItem>
             </CodeList>

Agora, dê uma recordada do método anterior que utilizamos para obter os nomes de colunas. Basicamente, o princípio para obter os valores dos códigos numéricos é o mesmo; contudo, ele é um pouco mais complexo, demandando um pouco mais de linhas de código. Ao acessar a tag CodeList, para o caso de querermos extrair os valores para Ethnicity, precisamos fazer uma filtragem mencionando o nome desse atributo, através do XPATH. Isso vem logo depois do nome da tag; assim sendo, podemos criar um novo dicionário, ethnicity, para abrigar códigos e valores para as etnias que estão representadas no DataFrame.

ethnicity = {}
for eth in tree.findall('.//CodeList[@Name="Ethnicity"]', ns):
    for code in tree.findall('.//CodeList[@Name="Ethnicity"]/CodeListItem', ns):
        for decode in code:
            for name in decode:
                ethnicity[code.attrib['CodedValue']] = name.text
ethnicity

{'1': 'Hispanic', '2': 'Non-hispanic'}

Para obtermos os valores dos códigos da coluna Sex, basta usar o mesmo método anterior, apenas substituindo o nome do atributo a ser filtrado.

sex = {}
for eth in tree.findall('.//CodeList[@Name="Sex"]', ns):
    for code in tree.findall('.//CodeList[@Name="Sex"]/CodeListItem', ns):
        for decode in code:
            for name in decode:
                sex[code.attrib['CodedValue']] = name.text
sex

{'1': 'Male', '2': 'Female'}

Dicionários preparados, podemos proceder às substituições que faltam. Aqui, usaremos a função do pandas map, que associa as chaves (i.e., os códigos numéricos) dos dicionários que criamos aos valores que dão nome aos números. Faremos isso para as duas colunas, Ethnicity e Sex; perceba que a planilha agora faz muito mais sentido, e está já pronta para fazer as análises que se deseja.

results['Ethnicity'] = results['Ethnicity'].map(ethnicity)
results['Sex'] = results['Sex'].map(sex)
results

Para salvar o DataFrame que foi criado, por fim, basta usar as funções próprias do pandas para tanto. Assim as informações que foram extraídas estarão armazenadas em um arquivo mais leve e mais rápido de manipular.

## Exportando

results.to_csv('results.csv') #Arquivo .csv
results.to_excel('results.xlsx') #Arquivo .xlsx
results.to_parquet('results.parquet') #Arquivo .parquet

Notas do artigo

1. Isso é sucintamente e muito bem corroborado em Shabo et. al (2006): “The Clinical Data Interchange Standards Consortium (CDISC) is leading the development of standards to improve data quality and accelerate product development in the pharmaceutical industry.19 The CDISC model focuses on the use of metadata, and the approach is to combine XML representation with the tabular presentation traditionally used for clinical-trial data.” - Shabo, A., S. Rabinovici-Cohen, e P. Vortman. “Revolutionary impact of XML on biomedical information interoperability”. IBM Systems Journal 45, nº 2 (2006): 361–72. https://doi.org/10.1147/sj.452.0361. ↩

2. “Interest in ODM as a research topic has grown significantly over the last several years with increasing interest in the CDISC data standards from regulatory authorities such as the FDA and the Japanese Pharmaceutical and Medical Devices Agency (PMDA)” - Hume, Sam, Jozef Aerts, Surendra Sarnikar, e Vojtech Huser. “Current Applications and Future Directions for the CDISC Operational Data Model Standard: A Methodological Review”. Journal of Biomedical Informatics 60 (abril de 2016): 352–62. https://doi.org/10.1016/j.jbi.2016.02.016. ↩

3. “While it is a requirement to submit pre-clinical and clinical data in CDISC format to regulatory bodies such as the US FDA and Japan’s Pharmaceuticals and Medical Devices Agency (PDMA), the actual usage of CDISC standards spans a much wider array of entities.” Hufstedler, Heather, Yannik Roell, Andressa Peña, Ankur Krishnan, Ian Green, Adriano Barbosa-Silva, Andreas Kremer, et al. “Navigating data standards in public health: A brief report from a data-standards meeting”. Journal of Global Health 14 ([s.d.]): 03024. https://doi.org/10.7189/jogh.14.03024. ↩

4. "The CDISC Operational Data Model (ODM) is an XML format that facilitates the exchange of clinical data captured during a clinical study. ODMbased files contain the study data and the associated descriptions of the data items, their groupings into Case Report Forms (CRFs), which are electronic documents to record the study data, and the associated questions and code lists. Furthermore, the FDA has mandated the use of other CDISC standards in clinical studies." Leroux, Hugo, e Laurent Lefort. “Semantic Enrichment of Longitudinal Clinical Study Data Using the CDISC Standards and the Semantic Statistics Vocabularies”. Journal of Biomedical Semantics 6, nº 1 (dezembro de 2015): 16. https://doi.org/10.1186/s13326-015-0012-6. ↩

5. “The Federal Drug Administration has mandated the use of the CDISC standards for the electronic capture and reporting of clinical study data” Leroux, Hugo, Alejandro Metke-Jimenez, e Michael J. Lawley. “Towards Achieving Semantic Interoperability of Clinical Study Data with FHIR”. Journal of Biomedical Semantics 8, nº 1 (19 de setembro de 2017): 41. https://doi.org/10.1186/s13326-017-0148-7. ↩

6. Lefort, Laurent, e Hugo Leroux. “Design and generation of Linked Clinical Data Cubes”, 2013. https://doi.org/10.13140/RG.2.1.3677.2967. ↩

7. Brix, Tobias Johannes, Philipp Bruland, Saad Sarfraz, Jan Ernsting, Philipp Neuhaus, Michael Storck, Justin Doods, Sonja Ständer, e Martin Dugas. “ODM Data Analysis—A Tool for the Automatic Validation, Monitoring and Generation of Generic Descriptive Statistics of Patient Data”. PLOS ONE 13, nº 6 (22 de junho de 2018): e0199242. https://doi.org/10.1371/journal.pone.0199242. ↩

8. Uma nota importante: A partir de agora, além das bibliotecas Python, e do XML, nos valeremos de uma outra linguagem, esta de consulta: o XPath. Com ela, podemos acessar de forma apropriada os elementos e atributos do XML. Não entrarei em detalhes sobre ela neste artigo; mas, caso você queira entender melhor do que se trata, você pode ver mais detalhes aqui e aqui, além de um bom cheatsheet aqui. Não usaremos muitas coisas diferentes dessa linguagem por aqui, mas é interessante ir mais a fundo depois. ↩

• Os dados que chegam a você para análises estão divididos em duas ou mais tabelas;

• Você precisa dividir o conteúdo de uma tabela em dois para poder processar melhor os dados... e depois precisa os juntar outra vez, ou precisa fazer uma análise com uma parte da primeira tabela, e outra parte da segunda;

• E nessas duas situações, você não tem ideia do que fazer, além de juntar tudo manualmente, no Ctrl+C, Ctrl+V, sempre se sujeitando a errar em algo.

Essas situações podem gerar um desperdício de tempo, energia, e dinheiro considerável, sem falar no desespero que pode bater. Então, sendo uma biblioteca completa para análise de dados, o pandas também providencia funções para agregação de diferentes dataframes, sendo soluções fáceis e bastante práticas. A documentação da biblioteca mostra com detalhes as possibilidades para fazer essas combinações, e é esse aspecto do pandas que exploraremos nessa aula.

Então, o que será visto aqui:

• Como combinar dataframes com a biblioteca pandas;

• Principais funções do pandas para concatenar, unir, e juntar.

Combinar dataframes com o pandas

A documentação do pandas, especialmente no Guia do Usuário, indica que temos, pelo menos, três modos de combinar conjuntos de dados: com concatenação (concat()), união (merge()), e a junção (join()). Para usar essas funções, é preciso levar em consideração duas coisas: o que você quer juntar de duas ou mais tabelas, e onde você quer chegar com isso. Caso isso tenha ficado confuso por agora, não se preocupe, pois à medida em que as funções e suas capacidades forem apresentadas, você poderá já identificar qual a função que vem de encontro ao seu objetivo, e como usá-la para conseguir aquilo que se quer.

Antes de mais nada: carregando os datasets para uso no pandas

Como essa série é baseada na mistura entre partes teóricas e práticas, antes de irmos à parte de apresentação das funções, precisamos carregar os conjuntos de dados com os quais iremos trabalhar aqui. Esses conjuntos estão no repositório da série no GitHub, para que você possa os usar livremente. E como carregaremos mais de um conjunto, faremos aqui uma coisa diferente: em vez de apenas nomear o objeto atribuído ao conjunto de dados apenas como df, usaremos os nomes de cada arquivo .csv disponibilizados. No caso, portanto, os objetos serão nomeados surveys e species, sendo que o processo de nomeação é o mesmo que utilizamos para df.

import pandas as pd #Importação da biblioteca pandas (sempre a primeira coisa a ser feita)
surveys = pd.read_csv("https://github.com/mhalmenschlager/python-biologia/raw/main/archives/surveys.csv") #Carrega o arquivo 'surveys.csv'
species = pd.read_csv("https://github.com/mhalmenschlager/python-biologia/raw/main/archives/species.csv") #Carrega o arquivo 'species.csv'

Isso posto, agora podemos começar a entender como as funções concat(), merge(), e join() funcionam. Para tanto, a aula será dividida em três posts ou partes diferentes:

• A primeira parte, que vem a seguir, apresenta a função concat();

• A segunda parte discute sobre a função join();

• A terceira e última parte será dedicada à função merge().

Concatenação: função concat()

A função de concatenação é considerada o 'canivete suíço' das funções de combinação de dataframes, podendo operar tanto com linhas, quanto com colunas. A questão aqui é que os dataframes a serem selecionados para a operação serão apenas "colados", seja pelo eixo de suas linhas, ou pelo eixo de suas colunas.

Para entender melhor, façamos o seguinte: a partir do dataframesurveys criado anteriormente, criemos dois outros, com as cinco primeiras entradas e as cinco últimas entradas desse conjunto. Assim:

surveys_primeiras = surveys.head() #Cinco primeiras entradas de 'surveys'

surveys_ultimas = surveys.tail() #Cinco últimas entradas de 'surveys'

**Um detalhe: **Se você executar os blocos de código que foram até agora aqui expostos, poderá perceber uma coisa: ao criarmos os novos objetos, a tabela surveys_ultimas mantém a indexação da tabela da qual se originou. Caso queiramos que haja uma indexação nova, há uma função para isso: reset.index(). Usamos ela da seguinte forma:

surveys_ultimas = surveys_ultimas.reset_index(drop=True) #Reorganiza o índice de 'surveys_ultimas', trocando o índice antigo de 'surveys' para um novo.

Esta função será mencionada outras vezes nessa aula, uma vez que ela será importante para que possamos fazer o processo de concatenação de forma correta em um dado momento.

Tendo esses novos objetos em mãos, podemos fazer a operação de concatenação, seja ela vertical (colados pelo eixo das colunas), ou horizontal (colados pelo eixo das linhas), usando a função concat().

vertical = pd.concat([surveys_primeiras, surveys_ultimas], axis=0) #Concatenação vertical

horizontal = pd.concat([surveys_primeiras, surveys_ultimas], axis=1) #Concatenação horizontal

Repare que, quando a função concat()é chamada, há um parâmetro que indica por qual eixo queremos fazer a concatenação, o axis. Então, para que a operação corra bem, lembre-se sempre de que, para fazer a operação vertical, o axis possui valor 0; para a horizontal, valor 1. Ainda, precisamos sempre reparar se as coisas estão fazendo sentido: ao fazermos a concatenação horizontal, os dados contidos nas linhas a serem coladas precisam estar relacionados de alguma forma. Na concatenação vertical, é imperativo verificar se as colunas possuem as mesmas características, i.e., o mesmo nome e o mesmo tipo de dado.

Um detalhe: Quando fazemos a concatenação vertical, podemos passar por um pequeno problema: os índices das linhas não tem continuidade, pulando do índice 4 para o 35544 de uma vez só. Isso acontece porque colamos linhas e colunas de dataframes com seus próprios índices. Um modo de contornar o problema é utilizar a função reset_index() (olha ela aqui de novo!) para que o índice seja reorganizado. Assim:

vertical = vertical.reset_index() #Reseta o índice

Perceba que a indexação agora aparece organizada.

Outro detalhe: Não parece que a concatenação horizontal ficou parecendo uma bagunça, cheia de NaN? Isso aconteceu por um motivo simples: quando as tabelas são colocadas lado a lado, as identificações das colunas podem se repetir, e as linhas acabam por ganhar 'extensões'; como não há dados nessas novas células, elas aparecem como dados nulos. Para resolver essa 'zona', podemos utilizar o reset_index()mais uma vez. Nesse caso, podemos criar um novo objeto com o índice resetado, e fazermos a concatenação outra vez. Assim:

surveys_ultimas2 = surveys_ultimas.reset_index(drop=True) #Cria um novo objeto, 'surveys_ultimas2', com o índice resetado
horizontal_2 = pd.concat([surveys_primeiras, surveys_ultimas2], axis=1) #Faz concatenação horizontal, com as duas tabelas tendo mesmo índice

Agora sim, temos uma concatenação horizontal mais bem organizada do que a anterior.

A função concat() é uma excelente função para a união de dois ou mais dataframes baseando-se em suas indexações, uma vez que pode trabalhar tanto com o eixo das linhas, quanto o das colunas, se transformando no 'canivete suíço' das funções que usam o índice como base. O que foi apresentado aqui é uma parte mais básica da função, com a qual você já pode sair praticando com outras bases de dados; concat() possui mais detalhes em seus argumentos, fazendo com que valha a pena analisar a documentação e outras referências para ter noção do poder dessa função no que se refere a juntar conjuntos de dados.

Aproveite para praticar a função concat()e nos vemos nas próximas partes, onde discutiremos mais sobre merge(), outra formas de juntar conjuntos de dados.

Um grande abraço e até o próximo post!

Para ler mais:

• Pandas Merging 101 - StackOverflow

• pandas.concat - Documentação do pandas

• What are the 'levels', 'keys', and names arguments for in Pandas' concat function? - Stack Overflow

• Python Pandas DataFrame Join, Merge, and Concatenate - Towards Data Science

• Practical uses of merge, join and concat - Towards Data Science

No entanto, quando nos deparamos com datasets do mundo real, inclusive aqueles que nós mesmos coletamos, percebemos que eles correm o grande risco de não serem completos e padronizados, fazendo com que todo aquele tempo com limpeza dos dados acabe por ocorrer conosco também. Mesmo com o processo de coleta e ingestão de dados mais rigoroso, mais cuidadoso possível, todo conjunto de dados está suscetível a alguma "sujeira". Por isso mesmo, é essencial aprender a detectar as inconsistências nos dados que podemos encontrar, e, sobretudo, saber o que fazer com elas.

Essa aula é dedicada a uma parte do processo de limpeza de dados, com exemplo e recomendação do que fazer quando você se deparar com aquilo que se costuma chamar dados nulos.

Então, eis o que veremos aqui:

• O que são dados nulos (e por que eles aparecem);
• Como detectar dados nulos;
• Como lidar com dados nulos.

Afinal, o que são dados nulos (e por que eles aparecem?)

Dados nulos ou não-respostas (missing values, em inglês) são os dados que, por alguma circunstância, não estão disponíveis para análise. A origem deles pode ser variada, e aqui cita-se alguns exemplos:

• Erros de digitação/transcrição para o banco de dados (ou seja, na ingestão desses dados);
• Esquecimento da coleta de uma determinada variável em um momento específico;
• Adição ou subtração de variáveis no decorrer do processo de coleta de dados (especialmente aquelas coletas que levam anos a serem feitas);
• Falta de uma padronização na organização dos dados.

NOTA: Para entender mais sobre os tipos de dados nulos e como eles aparecem, recomendo algumas referências: os artigos de Kang (2013) e Dong e Peng (2013), além do verbete sobre missing data na Wikipédia em inglês e em português.

A presença de dados nulos, apesar de ser comum, pode afetar a análise dos dados, reduzindo seu poder estatístico e explicativo. Por isso mesmo, é bastante importante não ignorá-los; A seguir veremos como podemos detectar esses dados nulos no dataset com o qual estamos trabalhando.

Como detectar dados nulos

A detecção de dados nulos no pandas é bem simples, e normalmente é um das primeiras coisas ao se trabalhar com essa biblioteca. Na documentação do pandas, há um guia chamado "Working with missing data", onde funções relacionadas com dados nulos são apresentadas. Com o mesmo dataframe que estamos utilizando desde o início da parte prática da série, exploraremos aqui algumas funções (algumas citadas nesse guia) para detectar dados nulos.

Funções head()e tail()

Com as funções que usualmente iniciamos os nossos passos para análise de dados dentro da linguagem Python com o pandas, já é possível observar uma possível existência de dados nulos. Usando head() e tail(), podemos verificar se as primeiras e as últimas linhas da tabela possuem células preenchidas com NaN, NaT, ou None.

import pandas as pd #Sempre importe o pandas antes de começar
import numpy as np #Sempre bom importar o Numpy também

df = pd.read_csv("https://github.com/mhalmenschlager/python-biologia/raw/main/archives/surveys.csv") #Nosso dataset de exemplo. Importe-o no seu notebook ou IDE de preferência
df.head() #Cinco primeiras entradas
df.tail() #Cinco últimas entradas

Função info()

A função info(), que já foi vista por aqui, é uma das funções que podem ser utilizadas para observar a existência de dados nulos, através da análise de cada coluna/variável no dataframe. Essa função retorna uma lista com a quantidade de células em cada variável que possua dados válidos (non-null); é possível, a partir daí, comparar os números de células com dados válidos com o número total de linhas e colunas de df.

df.info() #Observação de dados não-nulos

Função isnull()

A resposta da função é um indicador booleano: para dados nulos, aparece o True, enquanto que para os dados não-nulos, é o Falsequem surge. Você pode utilizá-la junto da função sum()para quantificar os dados nulos de uma determinada coluna, por exemplo.

df.isnull() #Dados nulos (com retorno booleano) de todo o dataframe
df.column.isnull() #Dados nulos de uma variável
df.column.isnull().sum() #Soma de células com dados nulos em uma variável
nulo = df.isnull().sum().sort_values(ascending=False) #Verificação de dados nulos, em ordem decrescente
(nulo / df.shape[0])*100 #Verificação de porcentagem de dados nulos por variável

Função notnull()

A função notnull(), assim como a função isnull(), retorna um valor booleano, apenas aqui sendo o contrário: o Trueaparece para dados não-nulos. Usando a função sum(), o retorno também será quantitativo, com resultado semelhante à função info(), com a diferença da possibilidade de quantificação de uma só coluna.

df.notnull() #Dados válidos (com retorno booleano) de todo o dataframe
df.column.notnull() #Dados válidos (com retorno booleano) de uma variável
df.column.notnull().sum() #Soma de células de uma variável com dados válidos
### Usando as funções para criar novos objetos ###
valido = df.notnull().sum().sort_values(ascending=False) #Verificação de dados válidos, em ordem decrescente
(valido / df.shape[0])*100 #Verificação de porcentagem de dados nulos por variável

Funções isna() e notna()

Outro conjunto de funções que pode ser utilizado para verficiar a presença de dados nulos e que aparece na documentação do pandas é o composto por isna() e notna(). Essas funções são semelhantes a isnull() e notnull(), respectivamente, dando um retorno booleano ao processo de verificação.

df.isna() #Dados nulos (com retorno booleano) de todo o dataframe
df.notna() #Dados válidos (com retorno booleano) de todo o dataframe

Como lidar com dados nulos?

Existem diversas formas de fazer um processo de manipulação de dados para contornar o problema dos dados nulos; isso depende, portanto, da capacidade de discernimento do pesquisador ao definir qual é a melhor maneira a ser adotada. Tal capacidade vem com a compreensão do conjunto de dados (saber o que são as variáveis a serem analisadas, qual o peso delas para as análises a serem feitas...) e, principalmente, qual o problema a ser resolvido ou a pergunta que se quer responder com aquilo que foi coletado. Nessa parte da aula, veremos algumas funções do pandas que nos ajudam a fazer a "contenção de danos" ao lidarmos com a "sujeira" dos nossos dados.

Função dropna()

A função dropna()tem como objetivo retirar linhas ou colunas que contenham, pelo menos, um valor nulo. Por padrão, a função sozinha elimina todas as linhas, mas isso pode ser alterado de acordo com os argumentos que são passados na linha de código.

df.dropna() #Elimina todas as linhas que possuam qualquer dado nulo
df.dropna(axis=1) #Elimina todas as colunas que possuam qualquer dado nulo
df.dropna(axis=0, have='any') #Elimina todas as linhas que possuam qualquer dado nulo
df.dropna(axis=0, have='all') #Elimina todas as linhas que possuam todos os valores como dados nulos
df.dropna(axis=0, thresh=2) #Mantém linhas que possuam, no máximo, 2 valores como dados nulos, eliminando as demais

Função fillna()

Se a função dropna()serve para, simplesmente, eliminar dados nulos, a função fillna() serve para mantê-los, fazendo um processo de preenchimento das células que apresentam valores como NA, NaN, ou NaT. Para preenchimento efetivo, é necessário especificar o método a ser adotado, passando argumentos ao código que será executado.

df.fillna(0) #Preenche todos os elementos NaN com o valor 0
df.fillna(method='pad') #Preenche os elementos NaN com a última observação válida
df.fillna(method='ffill') #Preenche os elementos NaN com a última observação válida
df.fillna(method='bfill') #Preenche os elementos NaN com a observação válida posterior a eles
df.fillna(method='backfill') #Preenche os elementos NaN com a observação válida posterior a eles
df.fillna(value=0, limit=1) #Preenche apenas o primeiro elemento NaN do dataframe com o valor 0

#### Usando índices de tendência central ####

df['column'].fillna(int(mean), inplace=True) #Preenche elementos NaN com a média
df['column'].fillna(int(median), inplace =True) #Preenche elementos NaN com a mediana
df['column'].fillna(int(mode), inplace=True) #Preenche elementos NaN com a moda

Função interpolate()

Quando as medidas de tendência central não parecem ser suficientes para preencher o espaço dos valores nulos num dataframe, é possível lançar mão do método chamado de interpolação. Basicamente, interpolar é gerar um dado novo a partir de um conjunto de dados que já são conhecidos. Nesse caso, o pandas pode usar os valores vizinhos de uma célula cujo valor ainda não é conhecido aqui (NaN) para estimar um valor novo que pareça fazer mais sentido àquele conjunto de dados que estamos analisando. A função de interpolação é semelhante ao fillna(), mas com a diferença é que é muito mais flexível; ao usar interpolate(), o analista possui uma variedade interessante de interpolações à mão, sendo que a interpolação padrão por parte do pandas é a do tipo linear. Algumas dessas interpolações podem ser vistas no exemplo abaixo:

df.interpolate() #Interpolação do tipo linear para os valores nulos do dataframe
df.interpolate(method='polynomial', order=2) #Interpolação do tipo polinomial para os valores nulos do dataframe
df.interpolate(method='pad', limit=2) #Interpolação com preenchimento com o valor acima do valor nulo, com limite de 2 valores NaN
df.interpolate(method='linear', limit_direction='forward') #Interpolação do tipo linear para os valores nulos do dataframe utilizando o valor anterior como limite
df.interpolate(method ='linear', limit_direction ='backward', limit = 1) #Interpolação do tipo linear para os valores nulos do dataframe utilizando o valor posterior ao NaN como limite, sendo 1 o número máximo de valores NaN que podem ser preenchidos com esse método

E agora, Que tal fazer você mesmo?

Com todos os códigos em mãos, aproveite apara abrir um novo arquivo .ipynb ou .pyno Google Colab, no Anaconda ou em outra IDE que você conheça, e vá explorando os blocos de código aqui citados, tanto com o dataset de exemplo, quanto o seu próprio conjunto de dados, ou algum outro que você viu na Internet ou que passaram para você treinar.

Ao terminar essa aula, recomendo a você que dê uma olhada na documentação do pandas e nas referências que estão nos hyperlinks e na seção 'Para ler mais' abaixo para entender bem essa parte de verificar dados nulos e lidar com eles. Por ser um processo que se inclui na limpeza de dados, é uma das mais importantes ações que é preciso fazer ao lidar com análise e visualização de dados, e as aplicações posteriores a isso. Não se esqueça também de praticar exaustivamente com os códigos aqui passados, para absorver todo o potencial de cada função do pandas explanada aqui.

Então, cuide bem dos seus dados! Economiza tempo, energia e, dependendo do caso, até dinheiro...

Um grande abraço, divirta-se com os códigos e até a próxima aula!

Para ler mais:

• Manipulando Missing Values com Pandas - Minerando Dados
• Handling Missing Data - Python Data Science Handbook
• Data Cleaning with Python and Pandas: Detecting Missing Values, por John Sullivan - Towards Data Science
• Handling Missing Data in Pandas: NaN Values Explained – BMC Software
• Como Tratar Dados Ausentes com Pandas - Sigmoidal
• How to Handle Missing Data, por Alvira Swalin - Towards Data Science
• How to Deal with Missing Data - Masters in Data Science
• Methods for handling missing data. - PsycNET
• A Guide to Handling Missing values in Python - Kaggle
• Junção de Dados com Pandas em Python – FLAI
• Pythonic Data Cleaning With Pandas and NumPy - Real Python

O que veremos aqui:

• Como a visualização de dados é encarada no pandas;
• Principais linhas de código para você começar a criar seus próprios gráficos em Python usando o pandas.

Então, como podemos visualizar os dados com o pandas?

A biblioteca pandas baseia sua parte de visualização usando uma API de outra biblioteca, o Matplotlib. Por isso mesmo, quando planejamos plotar algum gráfico em um relatório ou notebook usando o pandas, podemos utilizar recursos do Matplotlib para fazer isso.

import pandas as pd #Importa o pandas
import matplotlib.pyplot as plt #Importa a API do Matplotlib
%matplotlib inline #Define que os resultados/plots obtidos com o Matplotlib sejam apresentados e armazenados junto do notebook com o qual estamos trabalhando

A API do Matplotlib, nesse caso, é a pyplot: esta é uma coleção de funções que permitem fazer gráficos simples, mas apresentáveis, e que já ajudam muito na visualização dos dados que importamos e manipulamos com o pandas. Você pode explorar mais as possibilidades de plotagem de gráficos com o pandas que serão apresentadas aqui dando uma olhada no Guia do Usuário do pandas, além do Cookbook e o 10 minutes to pandas, projetos do próprio site do pandas para compreender melhor a bibiloteca.

Sem mais delongas, vamos à apresentação dos tipos de gráficos que podem ser produzidos usando as bibliotecas pandas e Matpotlib.

O básico do básico: função plot()

Essa é a função que servirá de base para fazer as plotagens de gráficos ao usarmos o pandas (e o Matplotlib) em nossos projetos. Por padrão, a função plot() tem como output um gráfico de linhas; é interessante usar esse gráfico ao lidarmos, por exemplo, com conjuntos de dados que possuam amostragens ocorrentes em um período de tempo contínuo.

Para lidarmos com a parte prática da aula, utilizaremos o mesmo conjunto de dados com o qual estamos trabalhando nas últimas semanas (surveys.csv). A partir dele, faremos algumas alterações conforme necessário.

df = pd.read_csv("https://github.com/mhalmenschlager/python-biologia/raw/main/archives/surveys.csv")
df.head()

Gráfico de linha

Como foi já referenciado no título dessa seção, começemos com o básico do básico, usando a função plot() puramente. O retorno será de um gráfico de linha, considerando linhas e colunas da tabela que importamos, conforme visto em df.head():

df.plot()

Mesmo que o gráfico não faça o menor sentido nesse momento, já podemos perceber aqui que tipo de resultado teremos quando usarmos a função plot(). Essa função também nos dá possibilidades de plotar gráficos com variáveis específicas, de outros tipos, até mesmo com diferentes títulos e legendas; nesses casos, é necessário apenas adicionar alguns outros argumentos a essa linha, indicando quais variáveis serão consideradas para fazer o gráfico, que tipo de gráfico queremos, e assim por diante. Esses argumentos são colocados dentro dos parênteses da função plot(), conforme o exemplo abaixo:

df.plot(x='year', y='record_id') #Especifica os valores dos eixos 'x' e 'y'

Neste caso, queremos especificar que tipos de variáveis queremos que apareçam nos eixos x e y; usemos as variáveis de ano e ID de registro como exemplo. O resultado dessa linha de código possui um pouco mais de sentido pois, a partir do gráfico, podemos avaliar a evolução das quantidades de amostragem conforme os anos considerados no dataframe.

Outro exemplo que podemos utilizar para explorar o gráfico de linhas, e que também envolve os anos de amostragem, tem a ver com agrupamentos. Nessa situação, veremos a contagem total de amostras feitas por cada ano, e a partir disso plotar um gráfico para acompanhar visualmente a evolução dessa amostragem. Para tanto, utilizaremos as funções groupbye count na mesma linha de código antes de plotarmos o gráfico, para organização do frame que será a base do gráfico.

year = df.groupby('year')['record_id'].count() #Contagem de amostragens, com base em seus IDs, por ano
year.head() #Cinco primeiras entradas do frame

A partir disso, usaremos o objeto criado year para plotar um gráfico de linha:

year.plot() #Gráfico de linha do objeto 'year'

Uma dica: Por n+1 razões, haverá momentos em que a figura parecerá pequena para a quantidade de informação que está dentro dela. Quando ocorrer isso, podemos sempre lançar mão do argumento figsize para ajustar o tamanho da figura até que ela fique em um tamanho que se possa considerar razoável.

year.plot(figsize=(17,3)) #Gráfico de linha do objeto 'year', com tamanho de figura (17,3)

Avançando na função plot(): outros tipos de gráficos disponíveis

Como dito anteriormente, a função plot(), além dos gráficos de linha, possibilita ao usuário plotar uma série de gráficos. A documentação do pandas expõe, em detalhes, as capacidades de visualização de dados do pandas; aqui, serão expostos alguns baseados no dataframe que estamos utilizando como exemplo.

Gráfico de barras

Enquanto um gráfico de linhas é mais utilizado para acompanhar a evolução de uma amostragem usando uma série contínua, geralmente temporal, o gráfico de barras é largamente recomendado para avaliar as amostragens de um conjunto de dados categóricos. Usando o df ainda como exemplo, em vez de avaliarmos as amostragens de acordo com os anos de coleta, podemos observar a quantidade de coletas feitas de acordo com as espécies consideradas. Em vez de utilizarmos a variável year, dessa vez nos valeremos da variável species_id, e a partir da quantidade de IDs feitos, poderemos observar as diferenças entre espécies.

count = df.groupby('species_id')['record_id'].count() #Contagem dos IDs das amostragens de acordo com os IDs de espécies
count.head() #As cinco primeiras entradas do objeto 'count'

count.plot(kind='bar', figsize=(18,3)) #Plotagem de um gráfico de barras do objeto 'count', com tamanho (18, 3)

O resultado do plot é a amostragem de espécies em ordem alfabética. Aqui, já vemos a representatividade de algumas espécies, como 'DM', 'DO', 'OT', e 'PP' no número total de coletas. Se quisermos organizar os dados de forma ordenada, do maior para o menor, por exemplo, antes de usarmos a função plot() é preciso apenas usar a função sorting.values(). Assim, criaremos um novo objeto, count2, adicionando esse argumento.

count2 = df.groupby('species_id')['record_id'].count().sort_values(ascending = False) #Contagem dos IDs das amostragens de acordo com os IDs de espécies, de forma ordenada. O (ascending = False) indica que a organização será feita de forma decrescente, do maior para o menor.
count2.head() #As cinco primeiras entradas do objeto 'count2'

count2.plot(kind='bar', figsize=(18,3)); #Plotagem de um gráfico de barras do objeto 'count2', com tamanho (18, 3)

Aqui já vemos um gráfico mais bem organizado, com uma ordenação decrescente da amostragem das espécies. Lembre-se que cada ID de espécies é associado com o nome desta; você pode ver isso com mais detalhes nas aulas anteriores, com o dicionário de variáveis, bem como no repositório da série no GitHub.

Gráfico de pizza

O gráfico de pizza é, sem dúvidas, um dos mais utilizados por qualquer profissional, independente da área. E, infelizmente, é um dos gráficos mais mal utilizados; embora a proposta seja a exibição de dados de uma forma fácil de ler, muitas vezes os resultados são horrendos (em uma outra postagem envolvendo visualização de dados, escreverei mais sobre).

Esse gráfico é muito usado para apresentar proporções entre os dados amostrados, mais frequentemente na forma de porcentagens. Plotá-lo com o pandas também é muito simples, ainda usando a função plot(). Comecemos separando os dados que utilizaremos aqui: observaremos a contagem total de três espécies, 'DM', 'DO', e PP, utilizando a função count(), e separando-as por um groupby().

dmXdoXpp = df.groupby('species_id')['record_id'].count()[['DO', 'DM', 'PP']] #Contagem da amostragem das espécies 'DM', 'DO', e 'PP', considerando seus IDs de registro
dmXdoXpp #Chamamento do objeto 'dmXdoXpp'

dmXdoXpp.plot(kind='pie') #Plotagem de um gráfico de pizza do objeto 'dmXdoXpp'

Gráfico de caixa (boxplot)

Gráficos de caixa, ou boxplots, são largamente utilizados para avaliar a variação de um conjunto de dados através de um sistema de máximos, mínimos, e quartis ou percentis. São ótimos para ver como se comportam as amostragens de um determinado grupo ou variável, propiciando inclusive a verificação de dados que são muito discrepantes, os chamados outliers. Esse tipo de plotagem é muito conhecido por estar presente em Análises Exploratórias de Dados (AEDs), que são as primeiras análises a serem feitas após a coleta de dados. No caso do boxplot, destacamos aqui uma função levemente distinta do simples plot()para fazê-lo, embora seja possível ir por esse caminho também.

Para mostrar como se faz um boxplot com o pandas, criaremos um novo objeto, MxF, uma vez que avaliaremos a variação do comprimento do retropé conforme o sexo de cada animal amostrado. Para isso, faremos uma nova tabela, com a função pivot_table():

MxF = df.pivot_table('hindfoot_length', 'record_id', 'sex') #Tabela com a variação do comprimento do retropé de acordo com o sexo das amostras consideradas no conjunto de dados
MxF

Para fazer a plotagem do gráfico de caixas, usaremos aqui a função boxplot() a partir do novo objeto:

MxF.boxplot(); #Gráfico de caixa do objeto 'MxF'

Neste gráfico, já podemos ter uma ideia da variação do comprimento em centímetros do retropé de cada amostragem considerada, com a separação por sexo. Repare que, quando chamada a função boxplot(), o gráfico aparece com um gradeamento. Há uma linha de código alternativa para criar um gráfico de caixas que usa a função plot(), só que essa sem gradeamento:

MxF.plot(kind = 'box') #Gráfico de caixa do objeto 'MxF'

Outros tipos de gráfico suportados pelo pandas

Além desses, há outros tipos de gráfico (área, scatter plot, etc.) que são suportados pela biblioteca pandas, que não são mencionados aqui; isso permite que o usuário possa fazer gráficos apresentáveis para seus relatórios, apresentações ou outras exposições usando uma só biblioteca. Para conhecer e praticar mais exaustivamente, é recomendada uma leitura atenta à documentação do pandas, onde se expõe, com exemplos práticos, todas as possibilidades que a biblioteca oferece para visualização de dados.

Outras bibliotecas, como o Matplotlib e o Seaborn, fazem parte do ecossistema do pandas e são especializados em visualização de dados. Em outro momento da série, esses recursos serão apresentados com mais detalhes, e haverá uma discussão mais extensa sobre a visualização de dados em Python, e como você pode utilizar essas ferramentas da melhor forma possível com seus dados.

Por aqui, encerramos uma outra aula de apresentação da biblioteca pandas. Com o que já foi exposto aqui, você já tem conhecimento e referências para começar a fazer suas próprias análises de dados. Não esqueça de fazer duas coisas importantes: ler de forma exaustiva as documentações e referências expostas nas aulas, e praticar muito, com o dataset de exemplo e tantos outros. Com isso, você aprenderá a usar a linguagem Python para alçar posições de destaque na sua área profissional e/ou acadêmica, seja na Ecologia, em outras áreas da Biologia, ou com outros projetos de seu interesse. Aproveite para deixar um feedback das aulas e, caso surjam dúvidas ou curiosidades acerca dos temas expostos por aqui, estarei sempre à disposição para auxílio ou, até mesmo, uma motivação a mais. Siga buscando conhecimento!

Um grande abraço, até a próxima aula e, sobretudo, divirta-se com os gráficos!

Para ler mais

• Data Visualization in Python | Data Visualization for Beginners
• 10 Python Data Visualization Libraries for Any Field - Mode.com
• How to create plots in pandas? — Documentação do pandas
• Plot With Pandas: Python Data Visualization for Beginners – Real Python
• How to Plot a DataFrame using Pandas - Data to Fish
• Pandas - Plotting - w3schools
• Pandas - Visualização inicial dos dados - Digital Innovation One
• Introdução à Análise de Dados - Python e pandas - Kaggle
• Uma folha de dicas definitiva para visualização de dados em pandas - Ichi.pro

Nessa aula, veremos:

• Outros métodos de fatiamento: loc e iloc;
• Seleções por critérios

Outros métodos de fatiamento: loc e iloc

Anteriormente, vimos já alguns métodos do processo chamado de fatiamento ou slicing, no qual é possível criar novos frames separando linhas e colunas com as quais se quer trabalhar. No pandas, existem uma série de recursos que exploram esse processo, tornando a experiência com a biblioteca mais proveitosa à medida em que vai se dominando as diferentes maneiras de seleção de linhas e colunas. Nessa aula, serão apresentados os métodos loce iloc.

Método loc - Localização por rótulos

Grosso modo, o método de seleção loc seleciona linhas e colunas de acordo com o seu rótulo (label), isto é, seu "nome" na tabela, aquilo que aparece visualmente quando temos um output de comando. Você pode usar essa seleção de acordo com algumas fórmulas:

• df.loc[linha] : Seleciona uma ou mais linhas pelo seu rótulo;
• df.loc[: , coluna]: Seleciona uma ou mais colunas pelo seu rótulo;
• df.loc[linha, coluna]: Seleciona linhas e colunas pelo seu rótulo.

Vejamos isso em termos práticos, usando o dataframe df, já nosso conhecido:

df.loc['NL'] #Seleciona as linhas contendo a ID de espécie 'NL'

df.loc['NL', ['sex', 'hindfoot_length']] #Seleciona as linhas nas colunas 'sex' e 'hindfoot_length' contendo a ID de espécie 'NL'

df.loc[:['year','species_id']] #Seleciona as colunas 'year' e 'species_id'

df.loc[['NL', 'DM', 'DO'], ['sex', 'hindfoot_length']] #Seleciona as linhas nas colunas 'sex' e 'hindfoot_length' contendo a IDs de espécie 'NL', 'DM' e 'DO'

Acima, portanto, fomos selecionando diversas linhas e colunas observando sempre seus rótulos na tabela. Quando da seleção apenas de colunas, repare o uso do : isolado; este indica que serão filtradas todas as linhas do dataframe. A separação de linhas e colunas no comando, repare também, é feita pelo separador ,. Um outro detalhe importante de se destacar: ao usar os métodos de seleção, atente a utilizar sempre linhas e colunas não-nulas (apontados comumente como NaN; veremos o que são dados nulos - e o que fazer com eles - com mais detalhes em outra aula).

Que tal fazer você mesmo?

Com o primeiro notebook da serie e os dados e a biblioteca pandas importadas nele, experimente fazer uma seleção com espécies e colunas diferentes, sempre usando o df.loc. Pratique bastante, e encorajo-lhe a buscar outras referências e exemplos na literatura ou na Internet para entender melhor. Algumas sugestões de lugares para buscar mais ajuda estarão em "Para ler mais"

Método iloc - Localização por números inteiros

O método iloc segue o mesmo princípio do loc, mas com uma diferença essencial: enquanto o loc faz uma seleção por rótulos, o iloc busca linhas e colunas em relação às suas localizações inteiras (em números). Cada linha e coluna em um dataframe possui uma localização inteira que a define, sendo isso uma espécie de acréscimo ao rótulo que é exibido no output de cada comando. Essa localização é o número da linha/coluna no qual o nosso alvo estará localizado, sempre começando da parte superior esquerda.

Para usar esse método, podemos nos basear nas seguintes fórmulas:

• df.iloc[0]: Seleciona a primeira linha por sua localização inteira;
• df.iloc[linha]: Seleciona uma linha por sua localização inteira;
• df.iloc[:, coluna]: Seleciona uma coluna por sua localização inteira;

Vejamos isso em termos práticos, usando outra vez o dataframe df:

df.iloc[0] #Seleciona a primeira linha de 'df'

df.iloc[4] #Seleciona a quinta linha de 'df' (lembre-se: a contagem de linhas no Python começa por 0)

df.iloc[:, 2] #Seleciona a terceira coluna de 'df'

df.iloc[[1, 2], [0, 2, 1]] #Seleciona a segunda e terceira linha, e a primeira, terceira, e segunda coluna de 'df', nesta ordem

Que tal fazer você mesmo?

Com os dados de dfem mãos, aproveite para testar o método iloc, localizando diferentes linhas e colunas na tabela. Se você não se lembra a quantidade de linhas e colunas que há no dataframe, é simples descobrir: use o comando df.shape(). É esperado que o output venha na fórmula (linhas, colunas). Pratique bastante, e encorajo-lhe a buscar outras referências e exemplos na literatura ou na Internet para entender melhor. Algumas sugestões de lugares para buscar mais ajuda estarão em "Para ler mais"

Seleções por critérios

No pandas, além de fazermos seleções por posição ou rótulo, também podemos selecionar informações de nossos dataframes por uma série de critérios ou condições expressos nas linhas de comando.

Entendi foi nada: o que seriam esses 'critérios' ou 'condições'?

Como temos conhecimento de como estão dispostos os dados no dataframe que estamos utilizando aqui, podemos fazer subsets (um dataframe do dataframe) baseados em normas ou critérios que podemos estabelecer. Se você quiser, por exemplo, separar todas as linhas de amostras que foram coletadas no ano de 2001, apenas é preciso usar um operador lógico do Python para chegar a esse fim, o ==. Veja um exemplo:

df_2001 = df[df.year == 2001] #Separa as linhas cujo ano, 'year', é igual a 2001

Nesse caso, estamos criando um novo dataframe, df_2001, usando o nosso frame principal, df, com a condição/critério de que sejam selecionados apenas as linhas que, na coluna year, possuam o valor de ano 2001. Assim, se chamarmos df_2001, aparecerá o dataframe criado com a condição que fora estabelecida.

Não apenas para selecionar valores que coincidam com o critério, podemos usar outros operadores lógicos do Python para criar novos dataframes. Tais operadores são, segundo a sintaxe:

• ==: igual a;
• !=: não igual a;
• > ou <: maior ou menor que;
• >=: maior ou igual que;
• <=: menor ou igual que.

Se, por algum acaso, queiramos definir mais de um conjunto de critérios, podemos utilizar o operador & para conectá-los:

df_conj = df[(df.year >= 1990) & (df.year <= 1995)] #Separa as linhas cujas amostragens possuam valor 'year' maior ou igual a 1990, e menor ou igual a 1995

Que tal fazer você mesmo?

Da mesma forma que usamos o df para explorar as possibilidades de usar os métodos loc e iloc, podemos aqui utilizar esse dataframe para fitrá-lo de acordo com condições que nós mesmos podemos estabelecer. Assim sendo, você pode explorar os operadores lógicos do Python para escrever algumas linhas de código.

Nessa aula vimos mais alguns recursos do pandas para fazer seleções de linhas e colunas, além da criação de subsets. Esses são aspectos essenciais a se levar em conta ao trabalhar com dados, uma vez que eles proporcionam uma variedade de possibilidades de se manipular tabelas sem a necessidade de carregar o mesmo dataset toda vez; isso facilita, e muito, o trabalho a ser feito. Nas próximas aulas continuaremos a discutir sobre como manipular dados com o pandas; mas antes, será interessante apresentar para vocês algumas características dessa biblioteca no que se refere à visualização de dados. Haverá, portanto, uma apresentação de códigos e conceitos para plotar dados usando pandas. Com isso, você já pode avançar nos primeiros relatórios usando seu próprio material, tendo já visto o resumo estatístico e um pouco de manipulação de tabelas.

Recomendo fortemente, mais uma vez, que você dê uma olhada nas referências apresentadas no 'Para ler mais'. Ali estarão links de várias fontes com as quais você poderá explorar os processos de seleção do pandas de forma exaustiva, com um conteúdo bastante didático.

Dito isso, vejo vocês na próxima aula. Um grande abraço!

Para ler mais:

• 23 Efficient Ways of Subsetting a pandas DataFrame - Towards Data Science
• Selecting rows in pandas DataFrame based on conditions - GeeksforGeeks
• Decisões e Seleção — Como pensar como um Cientista da Computação: Edição Interativa em Python
• A comprehensive guide to mastering data analysis with pandas - Dunder Data
• Indexing and selecting data — pandas 1.3.2 documentation
• Noções básicas sobre notação de fatia - QAStack
• Selecionando várias colunas em um dataframe do pandas - QAStack
• 5 Essential Pandas Tips For Easier Data Manipulation - Towards Data Science
• pandas.DataFrame.loc — pandas 1.3.2 documentation
• Qual a diferença entre iloc, ix e loc? - QAStack
• Pandas loc vs iloc | Delft Stack
• loc vs iloc in Pandas and Python - Towards Data Science

O que veremos nessa aula:

• Um pouco mais sobre agrupamento: value_counts(), unique()e count();
• Referenciando e copiando objetos no pandas.

Um pouco mais sobre agrupamento

Aqui, vamos explorar mais um pouco as possibilidades que se tem ao usar o pandas para fazer agrupamentos e fatiamentos. Esses conceitos já foram explicados na aula passada; caso não lembre, é só voltar um post e verificar o texto e as referências sobre essa parte.

Anteriormente, nós vimos uma função chamada value_counts(), para ver quantos registros de cada sexo temos no dataset que estamos utilizando. Há um outro recurso usando essa função que é interessante, envolvendo a proporção de cada variável numa determinada coluna. Para ver o resultado disso, apenas é necessário adicionar um outro argumento dentro de value_counts(), envolvendo um processo de normalização dos dados. A linha de código fica assim:

df[['sex']].value_counts(normalize = True)

Que tal fazer você mesmo?

Nessa parte envolvendo a função value_counts(), vimos o recurso de proporção, que usa o recurso da normalização, que é bastante interessante. Com esse mesmo recurso, podemos também extrair a representatividade de cada variável em porcentagem. Como você poderia fazer isso?

Funções unique() e count()

Uma função parecida com o value_counts(), que já vimos antes, é a função count(). A diferença entre elas é que a segunda, em termos básicos, permite avaliar uma contagem de uma variável por outra, usando o groupby em vez de usar apenas uma variável para contar.

Para entender melhor: fizemos na aula anterior um agrupamento por sexo (variável sex), avaliando quantas ocorrências de cada sexo há no dataframe que estamos utilizando. Agora, trabalharemos um pouco com as identificações de espécies do conjunto de dados. Para descobrir quais são as espécies registradas, podemos lançar mão da função unique():

df['species_id'].unique() #Quais são as espécies que aparecem no dataframe

A partir disso, se queremos observar quantos registros existe para cada espécie, lançamos mão da função count()

df.groupby('species_id')['record_id'].count() #Número de amostras por cada espécie

Ainda, se queremos saber a amostragem de uma espécie apenas, podemos adicionar mais um argumento à linha de código. Neste caso, ao final da linha, escrevemos o nome da espécie em colchetes (['SP']):

df.groupby('species_id')['record_id'].count()['DO']

Que tal fazer você mesmo?

Aproveite a linha de código acima para obter resultados de espécies diferentes!

A diferença entre associar/referenciar e copiar objetos

Copiando objetos

Em aulas passadas, vimos como é possível criar objetos em um ambiente Jupyter com o Python, e a importância dessa criação para analisar dados. Às vezes, por certa precaução, nos é recomendado não trabalhar em cima de apenas um objeto de dado dataframe no Python; isso porque corremos o risco de perder informações ao chamar alguma função sem querer. Então, para garantirmos que ficará tudo bem, podemos criar novos objetos a partir de um mesmo dataframe com o mesmo conteúdo; isso seria uma cópia do objeto. Obtemos essas cópias de objetos usando o método copy().

df_copia = df.copy()

Com essa linha de código, portanto, criamos um novo objeto, chamado df_copia; tal objeto possui um novo dataframe, que tem conteúdo igual ao objeto df, sendo possível assim usá-lo para diferentes propósitos.

Que tal fazer você mesmo?: Repita essa operação em um notebook Jupyter/do Google Colab, com a mesma fonte de dados que estamos utilizando, criando o objeto df_copia, e compare os objetos. Você pode fazer isso usando a função head().

Referenciando objetos

Suponhamos que alguém alegue que achou uma solução "mais simples e mais rápida" para essa situação. Observe a linha abaixo:

df_copia = df

Com ela, argumenta esse alguém, criamos o mesmo objeto, df_copia, usando o df que utilizamos como dataframe anteriormente; isso teria o mesmo efeito que usar a função copy(), ao fazermos o mesmo exercício de comparação anterior. Logo, em vez de usarmos o copy() para fazer uma nova cópia de df, apenas criamos um novo objeto usando esse mesmo dataframe, porque dá na mesma... certo?

Nada mais errado. E eu explico o porquê:

O que se está a fazer aqui é, basicamente, dar um outro nome de objeto a um mesmo dataframe. Esse é o processo, em Python, chamado de associação ou referência. Então, nesse caso, df pode ser chamado tanto por esse nome, quanto pelo nome df_copia.

Para entender melhor, usando a mesma fonte: Imagine que estamos criando agora três objetos distintos, a saber:

df2 = df.copy()
df3 = df

Observe que, enquanto o df2 é criado usando a função copy(), o df3 é criado fazendo uma referência à df. Em princípio, os dois objetos estariam associados com o mesmo dataframe, se seguirmos a ideia anterior. Ao verificarmos os dois nomes usando a função head()ou info(), percebemos que eles são iguais, certo?

Até aqui, o pensamento está OK, mas façamos uma coisa diferente nessa situação. Usemos o df2 para fazer uma inclusão de colunas nele (isso será visto em uma próxima aula com mais detalhes, não se preocupe; a ideia agora é apenas fazer uma mudança):

df2['alternative_id'] = 0.0 #Incluir uma coluna no 'df2'

Feita essa mudança, verifiquemos de novo , usando a função head() ou info(). Se você fizer isso no Google Colab ou em um Jupyter Notebook, perceberá que df2 e df3, em seu conteúdo, são agora diferentes um do outro. Isso porque o que fizemos com o df2 foi, conforme visto anteriormente, criar um novo dataframe de fato utilizando o conteúdo de df, enquanto df3 acaba por ser um outro nome para o df. Pode parecer repetitivo, mas é importante que fique clara essa diferença entre as duas funções, para que, quando for analisar seus próprios dados, não ocorram erros que podem consumir um tempo que será importante.

Nessa aula de pandas, vimos algumas coisas que são essenciais ter em mente ao usar a biblioteca para analisar seus dados, além de alguns recursos interessantes. Nas referências abaixo, há uma riqueza de conteúdo para entender melhor sobre os counts, além de mais links para você entender melhor os conceitos de referência e cópia de objetos. Além disso, no último link há um eBook gratuito feito pelos usuários do Stack Overflow para você aprender mais sobre a biblioteca pandas.

Nas próximas aulas, continuaremos a falar sobre aspectos da biblioteca pandas para análise de dados, além de começar a fazer uns plots simples. O início da visualização de dados na série está perto de chegar, não perca!

Um grande abraço e até a próxima aula!

Leia mais:

• Documentação do Pandas sobre value_counts
• 8 Python Pandas Value_counts() tricks that make your work more efficient - Re/thought
• Getting more value from the Pandas’ value_counts() - Towards Data Science
• Python Variable Scope (passing by reference or copy?) - Stack Overflow
• References and Copies - Python Essential Reference - InformIT
• Understanding Reference and Copy in Python - Gitconnected
• Python - RIP Tutorial
• Learning pandas eBook - RIP Tutorial

Nessa aula, então, veremos:

• Como importar os dados para um notebook Jupyter através do pandas;
• Primeiras análises com o pandas: resumo estatístico, medidas de tendência central e dispersão.
• Agrupamentos e fatiamentos no pandas

Mas antes, algumas considerações sobre os dados

Os dados que utilizaremos durante as aulas estarão sempre disponíveis no repositório da série no GitHub, para que vocês possam baixar e explorá-los offline, assim como trabalhar com eles na nuvem, através do Google Colaboratory. Além disso, todos os códigos e as respostas dos desafios estarão em uma pasta de notebooks do mesmo repositório; você pode acessá-las quando quiser para ver os outputs e respostas dos desafios. Aproveite também para explorar os notebooks no Google Colab; sempre haverá um botão 'Open in Colab' ou um link para a plataforma nos notebooks do GitHub. Usaremos sempre o Google Colab para as práticas.

Os dados que utilizaremos nessa primeira parte são originados do curso "Data Analysis and Visualization in Python for Ecologists", aula Starting with Data. Os arquivos são do Portal Project Teaching Database e podem ser encontrados originalmente aqui. Ressalto aqui que os arquivos estão disponibilizados no repositório do GitHub na íntegra, e estão em domínio público; logo, é possível usar os dados livremente. O dicionário de variáveis pode ser consultado tanto na aula original, quanto no notebook dessa aula.

Vamos logo à parte prática?

Instalação e importação do Pandas para um notebook Jupyter (ou do Google Colaboratory)

Acesse os notebooks práticos por aqui: GitHub e Google Colab

A instalação do pandas pode ser necessária se você estiver usando alguma plataforma à parte o Google Colaboratory, que já possui a biblioteca instalada. Para fazer isso, é possível usar o !pip install. Considerada essa parte, podemos fazer a importação usando o comando import.

!pip install pandas #Para instalar
import pandas as pd #Para importar ao notebook

Importação de dados

O pandas, como já foi relatado em aulas anteriores, possui suporte para importação de vários arquivos de dados (.xlsx, .csv, e .json são alguns exemplos); para cada um deles, existe uma função específica, mas que segue um mesmo padrão: pd.read_type(). O pd é o alias do pandas, e a função que estaremos chamando é read_type(), sendo que é preciso mencionar o tipo de arquivo onde estão os dados. No caso do nosso exemplo, como usaremos o arquivo surveys.csv, é preciso chamar a função pd.read_csv("local do arquivo").

df = pd.read_csv("https://github.com/mhalmenschlager/python-biologia/raw/main/archives/surveys.csv")

Assim foi feita a importação dos dados para o notebook; repare que estamos criando um novo objeto através do comando df =. Isso quer dizer que estamos criando um objeto do conjunto de dados que importamos. É importante fazer isso para prosseguirmos aos próximos passos.

Primeiras visualizações com pandas

A primeira coisa que podemos fazer com o dataframe e o pandas importados ao nosso notebook é verificar como os dados foram importados e como estão dispostos no objeto que criamos anteriormente. Para tanto, podemos usar duas funções: a função head() nos permite ver as cinco primeiras entradas do df; além disso, a função info() nos dá a informação de que tipos de dados há no dataframe e quantos dados são considerados como não-nulos.

df.head() #Cinco primeiras entradas
df.info() #Tipos de dados existentes

Após isso, podemos obter também um resumo estatístico dos dados. Isso pode valer tanto para todo o dataframe, quanto para apenas uma coluna ou variável dele. Para isso, usamos a função describe().

Que tal fazer você mesmo?

(1) Vimos aqui que a função head() aponta as cinco primeiras entradas do nosso dataframe. Há também uma outra função relacionada a essa chamada tail() O que ela faz?

(2) Ainda sobre a função head(): se quisermos exibir mais de 5 linhas, o que devemos fazer? Será que podemos fazer o mesmo para exibir menos que isso?

Você pode usar o mesmo objeto df para descobrir. As respostas estarão no repositório da série no GitHub e no notebook do Google Colab.

df.describe() #Resumo estatístico de todo o dataframe
df['weight'].describe() #Resumo estatístico da variável 'weight'

Medidas de tendência central e dispersão (média, mediana, moda, desvio-padrão)

O resumo estatístico, tanto do dataframe inteiro, quanto de uma variável específica, aponta algumas medidas interessantes, tanto de tendência central, quanto de dispersão. Essas medidas são essenciais para começarmos a analisar a variância do conjunto de dados que temos. Mas, e se quisermos fazer uma análise de apenas uma dessas medidas? No pandas, é simples de apontar esses índices em separado: basta usar a fórmula dataframe['variável'].medida(). A seguir há alguns exemplos para que você possa entender melhor:

df['weight'].mean() #Para descobrir a média
df['weight'].median() #Para descobrir a mediana
df['weight'].std() #Para descobrir o desvio-padrão

Agrupamentos no pandas

Algumas variáveis dentro do nosso dataset de exemplo são consideradas como categóricas; a partir disso, podemos fazer alguns exercícios envolvendo essas variáveis utilizando o método de agrupamento no pandas.

Por exemplo: sabendo da existência da variável sex dentro do dataset e, importada essa mesma variável pro nosso dataframe, quantos registros de cada sexo biológico constam no nosso conjunto de dados? Para descobrir isso, podemos utilizar a função value_counts(), assim:

df['sex'].value_counts()

No entanto, também temos outro recurso do pandas com o qual podemos trabalhar com agrupamentos de variáveis categóricas: o groupby(). Com ele, podemos ir mais além da contagem e usar medidas de tendência central e dispersão para observar variâncias de uma variável por outra. A fórmula fica assim: dataframe.groupby('variável1')['variável2'].medida().

Para entender melhor: imagine que queremos descobrir a média dos pesos das nossas amostragens, agrupando-as por sexo. Para descobrir isso, podemos utilizar a fórmula citada antes, assim:

df.groupby('sex')['weight'].mean()

Perceba como as variáveis estão posicionadas na linha de código; a variável sex, que é a que agruparemos, está na primeira posição, em parênteses, associada com a função groupby(), enquanto que a variável weight, de onde tiraremos as médias, vem logo depois, em colchetes. A mesma fórmula pode ser usada para tirar outras medidas com outros agrupamentos.

Que tal fazer você mesmo?

Com o mesmo dataframe podemos então comparar mais medidas agrupando as amostras por sexo. Será que você consegue comparar essa categoria:

• por medianas de peso?
• por médias de comprimento do retropé (hindfoot)? E qual o máximo do comprimento para cada sexo?

Você pode ainda usar o objeto df para descobrir. As respostas estarão no repositório da série no GitHub e no notebook do Google Colab.

Filtragem do conjunto de dados por fatiamento

Na ciência de dados, há uma prática conhecida por slicing ou fatiamento, onde há a possibilidade de fazermos uma filtragem do conjunto de dados, podendo criar inclusive subsets do conjunto para que possamos explorar e visualizar melhor os dados mais adiante. Esse fatiamento pode ser feito tanto com linhas, quanto por colunas de uma certa tabela.

Usemos o nosso objeto df para entender melhor essa prática. Se quisermos fazer um fatiamento por linhas do dataframe, podemos utilizar uma fórmula simples: df[linha início: linha fim +1] Um detalhe importante a ser mencionado aqui é que a indexação do Python, ao contrário de algumas outras linguagens, começa pelo 0. Então, se quisermos fatiar o dataframe da primeira até a sétima linha, podemos fazer assim:

df_linha = df[0:7] #Linha de início (0): linha final (6)+1

O fatiamento de colunas também é fácil; apenas em vez de usarmos números, mencionaremos os nomes das colunas. A fórmula é df['nome da coluna'] para fatiar apenas uma coluna, e df[['col1', 'col2', 'col3'...'colN']] para uma lista de colunas. Repare na duplicação de colchetes quando usamos a segunda fórmula; isso porque estamos usando o caractere de lista do Python para fazer isso, o que não é necessário quando queremos separar apenas uma coluna.

df_coluna = df['weight'] #Uma coluna
df_coluna = df[['weight', 'sex']] #Mais de uma coluna

Até agora, vimos um pouco de análise de dados com o pandas, assunto no qual nos estenderemos por mais aulas. Nas referências abaixo, assim como no hyperlinks ao longo do texto, terá mais conteúdo para você poder praticar os conceitos apresentados, além de poder avançar um pouco mais na biblioteca pandas. Não se esqueça de dar uma olhada no notebook das aulas, onde você pode ver os outputs de cada bloco de código citado, as resoluções dos desafios e explorar a linguagem Python por si.

Um grande abraço e até a próxima aula!

Leia mais:

• As principais funções do pandas que todo mundo deveria saber - Enzo Delcompare
• Guias sobre Python - Odemir Delpieri Jr. no Linkedin
• Dicas de Manipulação de Dados com pandas - Vitor Diego Ramos
• Python for Data Science - A Guide to pandas - Towards Data Science
• Pandas for Data Science (Learning Path) - Real Python

Nesta aula, portanto, veremos:

• O que são bibliotecas;
• Como instalar e importar bibliotecas no ambiente Jupyter Notebook;
• Quais bibliotecas são importantes para trabalhar com dados.

O que são bibliotecas afinal?

Se você já deu uma pesquisada sobre assuntos e características envolvendo a linguagem Python (ou outras linguagens, como o R), deve ter visto algumas fontes escrevendo algo sobre as ditas 'bibliotecas'.

Bibliotecas), em Python, são um conjunto de linhas de códigos construídas para um propósito específico (acessos a bases de dados, cálculos, modelos... o que você puder imaginar) e que podem ser utilizadas para reduzir o tamanho dos códigos escritos num processo de programação, além do tempo que se leva na escrita e organização desses códigos, uma vez que são reutilizáveis.

O Python, por si só, possui o que é conhecido como Biblioteca Padrão, que é um conjunto de módulos essenciais e úteis para o seu funcionamento. Essa biblioteca já vem junto com o pacote que é instalado do site oficial, ou seja, não é preciso nenhuma ação posterior para tê-la em sua máquina. Para outras bibliotecas, dependendo do caso, é preciso fazer a instalação antes de usá-las. E como se faz isso?

Como instalar e importar bibliotecas em um ambiente Jupyter Notebook

No nosso caso, independente de ser no ambiente Jupyter Notebook instalado com o pacote Anaconda, ou o ambiente do Google Colaboratory (que é inspirado na iniciativa Jupyter), podemos utilizar comando semelhante para o caso de querer instalar alguma biblioteca, o pip:

!pip install PackageName
!pip install geopandas #Um exemplo de biblioteca para instalar

Para descobrir quais bibliotecas estão instaladas no ambiente no qual você trabalhará com seus dados, existem comandos como o pip freezee o help(); este último também serve para acionar a ajuda de qualquer biblioteca já disponível no ambiente (inclusive a chamada Biblioteca Padrão do Python).

pip freeze
help("modules")

No caso de a biblioteca já ter sido instalada, o que precisamos fazer somente é importá-la para o ambiente antes de começarmos a trabalhar; por uma questão de conveniência, sobretudo, nem o Python, nem o ambiente Jupyter carregam todas as bibliotecas que já possuem instaladas. Para tanto, usamos a função import:

import pandas as pd
import geopandas as gpd
import matplotlib.pyplot as plt
import seaborn as sns
import folium

Repare que, nesse comando, utilizamos um argumento aspara importar, seguido de uma sigla. Tal atributo serve como um alias da biblioteca a ser importada, facilitando o processo; em vez de escrevermos matplotlib.pyplot toda vez que queremos usar uma função da biblioteca, apenas escrevemos plte a função que queremos para fazer funcionar (isso será melhor compreendido quando partirmos para a pare prática/analítica da série, não se preocupe). Nem todas as bibliotecas terão esse alias; nos notebooks da série, essas abreviações aparecerão quando for conveniente.

O uso dessas bibliotecas também é bem simples: na linha de comando, se utiliza a ordem biblioteca.função(). O mesmo para a criação de objetos, quando necessário, apenas atribuindo uma variável ao mesmo.

import pandas as pd
dataframe = pd.read_csv("exemplo.csv")

As bibliotecas mais importantes para trabalhar com dados

Agora que sabemos o que são bibliotecas, além como proceder à instalação e importação das mesmas, podemos fazer a apresentação das bibliotecas que você poderá utilizar para trabalhar com seus dados. Vale ressaltar que, assim como o Python propriamente dito, as bibliotecas citadas são gratuitas e de código-aberto; então, você pode usá-las livremente a qualquer momento.

pandas

!pip install pandas
import pandas as pd

De início, podemos mencionar a biblioteca pandas (assim mesmo, em lower case). Ela é uma das mais conhecidas bibliotecas de análise de dados em Python, e geralmente é a primeira a ser apresentada aos futuros cientistas de dados. A razão para isso é simples: o pandas, além de ser uma biblioteca completa para análise de dados, é fácil de manusear. Você pode trabalhar com variados tipos de arquivos de dados, como JSON e Excel (.csv, .xlsx). É nessa biblioteca que a série baseará suas primeiras aulas práticas.

Você pode consultar a documentação do pandas aqui, além de verificar a seção dedicada ao projeto pandas no PyPI.

NumPy

!pip install numpy
import numpy as np

O NumPy também é uma das bibliotecas basais para quem quer lidar com dados no Python. Essa biblioteca trabalha, principalmente, com arranjos de matrizes e vetores, cobrindo todas as funções de álgebra linear, além de poder trabalhar com manipulação de imagens, estatística, e operações matemáticas. Isso faz com que o NumPy esteja presente nas linhas de código de várias bibliotecas utilizadas no mundo da ciência de dados, como o pandas. Não é à toa que, segundo o site oficial do NumPy, "quase todo cientista que usa Python se vale do poder do NumPy".

Você pode saber mais sobre o ecossistema do NumPy acessando a página inicial, e verificar o poder da biblioteca na sua documentação.

GeoPandas

!pip install geopandas
import geopandas as gpd

Outra biblioteca a qual a série dará atenção é a GeoPandas. Como o nome e o logo já entregam, a biblioteca se baseia em pandas, sendo especializada na importação de dados geográficos para o ambiente; então, é com essa biblioteca que você pode trabalhar com as coordenadas que estão juntas dos seus dados de coleta, por exemplo. Também é possível trabalhar com shapefiles (arquivos .shp, .shx, .dbf...), além de dados em formato GeoJSON.

Verifique a documentação do GeoPandas aqui para saber mais sobre as possibilidades de se trabalhar com essa biblioteca.

Matplotlib

!pip install matplotlib
import matplotlib.pyplot as plt

O Matplotlib é a principal biblioteca para visualização de dados no Python. Com ela, é possível plotar os mais diversos gráficos, tendo a capacidade de administrar desde o título do gráfico, até escalas, cores e fontes. A parte de visualização de dados do pandas é baseada no Matplotlib, sendo que muitas vezes trabalham juntas.

A documentação do Matplotlib pode ser vista aqui.

Seaborn

!pip install seaborn
import seaborn as sns

Em matéria de visualização de dados, o Seaborn é uma ótima opção. A biblioteca permite ir mais além dos plots do Matplotlib, gerando gráficos com um estilo mais elegante e com poucas linhas de código.

Na página oficial da biblioteca, você pode explorar todas as possibilidades de visualização de dados que o Seaborn oferece.

Onde encontrar outras bibliotecas úteis para dados

Python Package Index

Para encontrar e se atualizar sobre outras bibliotecas úteis para trabalhar com seus dados, além dos projetos a elas associados, o Python Package Index (PyPI) é uma ótima referência. Lá você pode buscar por mais de 320 mil projetos baseados em Python nas mais variadas áreas do conhecimento, além de encontrar várias instruções de como instalar e atualizar bibliotecas.

Nesta aula da série, vimos o que são bibliotecas, como lidar com elas, além de uma apresentação rápida sobre as bibliotecas mais importantes para trabalhar com dados em Python. Uma vez conhecida essa questão, estamos prontos para começar a parte 'mão na massa' da série. A partir da próxima aula, conceitos que foram apresentados nos posts introdutórios começaram a ser assentados na sua mente de uma das melhores formas possíveis: praticando, sem muitos rodeios. Em cada início de aula serão apresentados, caso necessário, os conjuntos de dados, ou datasets, que serão utilizados; é a partir deles que faremos nossas primeiras análises.

A primeira, e principal, biblioteca que usaremos nessa série, será o pandas. Recomendo que, antes de prosseguir, você dê uma olhada na página oficial e na documentação da biblioteca; lá estarão aspectos que, por variadas questões, não conseguirão ser cobertas aqui por completo. Faça o mesmo com as outras bibliotecas, além de verificar o site do PyPI.

Bora começar a praticar análise e visualização de dados em Python juntos?

Caso queira, deixe um feedback ou sua dúvida em um comentário ou mensagem, para que nosso aprendizado seja cada vez mais amplo.

Um forte abraço e até a próxima aula!

Para ler mais:

• Conheça 11 bibliotecas Python aplicadas na Ciência de Dados - Voitto
• As 30 melhores bibliotecas e pacotes Python para Iniciantes - Terminal Root
• How to List all installed Packages in Python in 4 Ways - Python Daddy
• What is the difference between Python’s Module, Package and Library? - GeeksforGeeks
• For Anyone Using Jupyter Notebook — Installing Packages - Shivangi Sareen
• Installing Python Packages from a Jupyter Notebook - Pythonic Perambulations

Então, o que será visto aqui:

• O que são funções, e para que servem;
• Como escrevê-las em Python.

O que são funções?

Em várias linguagens de programação, funções são recursos que muito auxiliam na hora de meter a mão na massa; elas são blocos de código que performam tarefas que, normalmente, precisam ser executadas mais de uma vez dentro de uma aplicação. Assim, um algoritmo ou notebook fica menor, mais rápido de executar e, sobretudo, mais legível a outros usuários.

As funções também servem para a criação de bibliotecas em Python. No contexto de análise de dados, há bibliotecas que possuem funções prontas para calcular medidas de variância, de dispersão, tendência central, similaridade, entre outros (citam-se aqui exemplos que podem ser encontrados no cookbook da biblioteca SciPy, além da documentação do NumPy); além disso, para ecólogos, haverá funções que executam os principais cálculos necessários para mensurar diversidade, abundância, dominância, e tantas outras operações mais as quais os profissionais precisam lançar mão. Nesse caso em específico, a documentação da biblioteca EcoPy proporciona um leque de cálculos ecológicos, sendo cada um deles descrito em detalhes, para entendimento dos parâmetros e comandos usados.

Como criar funções no Python

Uma função em Python é definida por três partes: nome, parâmetros, e corpo (ou comandos). Nós podemos definir uma função usando essa sintaxe:

def nome( parâmetros ):
    comandos

Aqui vemos que a definição de uma função é feita usando a palavra-chave def. Você pode colocar qualquer nome para as funções que está criando, ao colocá-lo na posição nome; no entanto, você não pode usar um nome que é considerado palavra reservada. Os parâmetros vão especificar qual informação, caso haja alguma, é preciso providenciar para que a função seja usada. Em outra palavras, os parâmetros dizem o que a função precisa para executar tarefas. Observe também a presença dos dois pontos (:); isso indica que o código que está nas linhas seguidas a ele faz parte da função que será criada. As linhas seguintes aparecerão avançadas em relação à primeira linha; isso é o que chamamos de indentação, e é uma forma de respeito à sintaxe da linguagem que estamos usando.

Para podemos executar a função, devemos simplesmente chamar o seu nome e passar os parâmetros. A lista de parâmetros pode ser vazia, ter apenas um parâmetro, ou ter mais de um parâmetro, sempre separados por vírgulas. Independente disso, os parênteses são obrigatórios no momento de definir uma função.

Vamos a um breve exemplo prático, para entender melhor:

Python:

def add_func(a, b):
    resultado = a + b
    return resultado
z = add_func(10, 12)
print(z)

Neste bloco de código, estamos fazendo duas coisas: definir uma função e criar uma variável chamando essa função. O nome dessa função é add_func, que possui dois parâmetros, ae b. Dentro da função há dois comandos: resultadoe o return resultado; isso quer dizer que, no caso dessa função, se solicitará a soma dos dois parâmetros já citados (a + b) e, para expressar essa soma, a função dará um retorno (return) com o resultado.

A variável z possuirá como valor o resultado do uso da função add_func, tendo como parâmetros os números 10 e 12. Uma vez criada, podemos verificar qual será o valor da variável z, usando a função print(z). O resultado sairá conforme está no output abaixo:

Output:

22

O assunto referente às funções pode se estender bem mais, uma vez que funções podem comportar mais de um parâmetro ou comando, mas não nos ateremos muito a isso. O objetivo aqui é entender como se faz uma função, para que, mais à frente, consigamos entender melhor como trabalhar com as bibliotecas Python que serão apresentadas na série.

Com isso, já temos um arcabouço de como o Python funciona, com seus elementos principais e funções. Nas próximas aulas, começará a parte de mexer com dados; é justamente aí que o Python fica bem mais interessante.

Aproveite para dar seu feedback, e nos vemos nas próximos posts da série!

Para ler mais:

• Como criar funções em Python - DevMedia
• Funções - Como pensar como um cientista da computação - IME-USP
• Documentação Python - Análise léxica
• Documentação Python - Definindo funções
• Functions - Geo-Python
• Python Functions - W3Schools
• Python Functions: How to Call & Write Functions - Datacamp
• Defining Your Own Python Function - Real Python
• Creating Functions - Programming with Python
• Funções e mais funções em Python - Let's Code

Literatura recomendada:

• Capítulo 8 do Curso Intensivo de Python, de Eric Matthes (Library Genesis)
• Capítulo 2 do Data Science do Zero, de Joel Grus (Library Genesis)
• Capítulos 3 e 4 do Learn to Program with Python 3, de Irv Kalb (Library Genesis)
• Capítulo 3 do Basic Core Python Programming, de Meenu Kohli (Library Genesis)

• Operações básicas no Python: adição, subtração, multiplicação, divisão, potenciação, e módulo aritmético;
• Operações de lógica e comparação;
• Tipos de dados em Python: strings, integers, e floats;
• Sequências em Python: listas e tuplas;
• Dicionários.

Operações básicas em Python

Como foi dito na aula anterior, uma das coisas mais básicas para fazer com a linguagem Python é usá-la como uma "calculadora científica", fazendo operações matemáticas básicas com uma linha de código somente. Aqui estão alguns exemplos:

Python:

2 + 2 #Adição (veja 'NOTA 1' para entender o papel do '#')

Output:

4

Python:

5 - 8 #Subtração

Output:

3

Python:

6 * 2 #Multiplicação

Output:

12

Python:

50 / 5 #Divisão

Output:

10

Python:

2 ** 2 #Potenciação

Output:

4

Python:

13 % 5 #Módulo aritmético (para entender do que se trata, veja 'NOTA 2')

Output:

3

Operações de lógica, comparação, e identidade

Nós podemos também utilizar operadores de lógica e comparação (<, >, ==, !=, <=, >=) em uma só linha de código em Python:

Python:

3 > 4

Output:

False

Python:

6 == 6

Output:

True

Além disso, podemos escrever operações de identidade (and, or, not) e obter resultados:

Python:

True and True

Output:

True

Python:

True and False

Output:

False

Estes resultados obtidos (True e False) são dados que chamamos de booleanos (boolean). Inclusive, é sobre os tipos de dados que falaremos em seguida.

Tipos de dados em Python

Uma das coisas que também está entre as mais básicas no Python é a associação de valores à variáveis. Isso quer dizer que, quando introduzimos dados em um ambiente ou notebook, devemos nomeá-los, para que possamos identificá-los ao trabalhar com funções e bibliotecas. Essa associação é feita usando o operador de atribuição =. Um detalhe: não confunda esse operador com o de comparação ==.

Por exemplo:

Python:

texto = "Exemplo de texto"  # Um exemplo de linha (string)
numero = 42  # Um exemplo de número inteiro (integer)
pi_valor = 3.1415  # Um exemplo de número decimal (float)

Junto do exemplo está uma exposição de alguns tipos de dados que podemos utilizar em Python:

• Linhas (string): são sequências de caracteres, que podem ser letras, números (quando dentro de aspas), pontuações e até emojis (🤔);
• Números inteiros (integer): números inteiros que podem ser utilizados em funções e operações;
• Números decimais (float): números separados por pontos, que também podem ser utilizados em funções ou operações.
• Dados booleanos (boolean): são dados que retornam após operações lógicas ou de comparação. Basicamente, apontam se uma operação como as citadas é procedente ou não, verdadeira ou falsa. Também podem se referir a um dado ausente ou presente num dado dataframe ou dataset. No Python, os dados booleanos aparecem como True ou False.

Tudo que está em Python possui um tipo, e é importante sempre ter em mente quais são os tipos de dados que estão sendo utilizados, para evitar erros de interpretação ou incompatibilidades. Para descobrir qual o tipo de um objeto, lançamos mão da função type().

Python:

type(texto)

Output:

<class 'str'>

Nós podemos ver o valor de alguma coisa usando a função print().

Python:

texto_novo = 'Um outro exemplo de texto'
print(texto_novo)

Output:

Um outro exemplo de texto

Sequências em Python: Listas e tuplas

Nesta parte da aula, veremos como lidar com uma sequência ordenada de elementos. Temos dois casos a cobrir: listas e tuplas.

• Listas: são sequências simples de elementos, separados por vírgulas. Criamos uma lista usando colchetes ([]).

  Python:

  lista = [1, 2, 3, 4]
  

  Em uma sequência ordenada como essa, cada elemento é acessível por meio de um índice. Importante notar que, em Python, os índices sempre iniciam em 0, em vez de 1. Ou seja, para acessar o primeiro elemento, é necessário chamar o número 0.

  Python:

  lista[0]
  

  Output:

  1
  

• Tuplas: também são sequência simples de elementos, tais como as listas; a diferença é que, nesse caso, os elementos dentro de uma tupla são imutáveis (não podem ser mudados após sua criação). Criamos uma tupla usando parênteses.

  Python:

  tupla = (1, 2, 3, 4)
  outra_tupla = ('um', 'dois', 'três', 'quatro')
  

Dicionários

Em Python, consideramos como dicionários os objetos que possuem um par de outros objetos em seu interior. Também funcionam como as listas e tuplas, mas, em vez de terem índices, são organizados por chaves - é como se fosse uma etiqueta única ou um nome do objeto.

Para entender como funciona:

ordem = {'um': 'primeiro', 'dois': 'segundo'}

Perceba que os objetos 'um' e 'primeiro'estão separados por dois pontos (:). É assim que se formam os dicionários: para o objeto 'um'é atribuído outro objeto, o 'primeiro', e assim sucessivamente. Para localizarmos um objeto dentro de uma lista, o procedimento é parecido com a lista:

Python:

ordem['um']

Output:

'primeiro'

Nesta aula, foram apresentados alguns elementos essenciais na linguagem Python que você precisará ter em mente ao programar. Continuaremos a introdução em um próximo post da série, onde será mostrado um conteúdo referente a funções.

Até a próxima aula e, caso queira, já vá deixando um feedback! 😁

NOTAS:

(NOTA 1: Na linguagem Python, é permitido fazer comentários dentro de linhas de código. Para tanto, basta adicionar o sinal # antes de escrever. Tais comentários não serão consideradas pelo programa interpretador ao ler o código.)

(NOTA 2: Como foi mencionado antes, em vez de ser um símbolo de porcentagem, em Python o símbolo % representa uma operação aritmética distinta, o módulo. Basicamente, o módulo representa o resto de uma divisão. Exemplo: no caso acima, quando chamada a linha 13 % 5, estamos efetuando a divisão de 13 por 5; o quociente dessa divisão é 5, enquanto que o resto (que é o que aparece no output) é 3. Você pode ver mais sobre isso clicando aqui e aqui)

Para ler mais:

• Documentação do Python - Usando o Python como uma calculadora
• Criando coleções - DevMedia
• Documentação do Python - Estruturas de dados
• Basic elements of Python - GeoPython
• Python Basics - Astro Users

Literatura recomendada

• Basic Core Python Programming, de Meenu Kohli (Library Genesis)
• Coding Python, de Michael e Eric Scratch
• Curso Intensivo de Python, de Eric Matthes (Library Genesis)
• Data Science do Zero: Primeiras Regras com Python, de Joel Grus (Library Genesis)

Nesta aula, veremos:

• O que é a linguagem Python e por que utilizá-la ao analisar e visualizar dados;
• Esclarecer os conceitos de codificação e programação;
• Entender como escrever os primeiros códigos de Python, seja em linhas de código ou blocos.

O que é o Python, afinal?

O Python é uma linguagem de programação que possui um propósito geral; isso significa que sua concepção se apoia no intuito de atender um grande número de áreas. No caso da análise de dados, o Python é utilizado em boa parte das aplicações, por sua rápida e fácil capacidade de desenvolvimento e processamento.

Há grandes vantagens de usar o Python, nos quais se incluem:

• O Python é gratuito: ao contrário de muitos softwares de análise de dados que existem por aí, não é necessário a aquisição de licenças ou pagamento de mensalidades para usar o Python. Ele é gratuito, e sempre será.
• Ele é de código aberto: isso significa que você pode fazer cópias, modificações e reutilizações do Python sem nenhuma preocupação. Esse é um fato importante, pois o uso do Python se torna ilimitado. Você pode criar bibliotecas, algoritmos, e outras aplicações no Python livremente.
• O Python está disponível nos principais sistemas operacionais: não importa se você usa Windows, Linux ou Mac para fazer suas atividades, o Python estará lá, de diversas formas. Inclusive, projetos como o Google Colaboratory permitem que você use Python tendo apenas acesso à Internet e um navegador.
• Uma imensa comunidade de desenvolvedores, cientistas de dados e, esperamos a partir de agora, ecólogos usam o Python. Às vezes, você pode se sentir perdido quando for usar o Python, o que é normal. O importante aqui é que, se for buscar respostas para suas dúvidas, quase certamente as achará, pois alguém da comunidade Python também passou pelas mesmas dificuldades. Plataformas como Kaggle e Stack Overflow são ótimos lugares para encontrar respostas para aquilo que você ainda tem dúvida.
• O Python possui um riquíssimo ecossistema de pacotes/bibliotecas criadas por terceiros: Pesquisadores e desenvolvedores de todos os cantos do mundo desenvolvem diariamente pacotes de códigos em Python para atender as necessidades de várias áreas do conhecimento (a Ecologia, como será visto nas próximas aulas, está entre essas áreas.)

O que é programação? O que é codificação?

Antes de começarmos a ver as primeiras linhas de código em Python para analisar seus dados, é importante esclarecer dois conceitos: o de programação e codificação. Estes termos, apesar de comumente virem juntos, não significam a mesma coisa; 'programar' e 'codificar', portanto, não deveriam ser utilizadas de forma intercalada, como se fossem sinônimos.

Então, o que significam esses dois termos?

Programação é o ato de escrever "programas" que um computador possa executar e produzir alguns (úteis, na maioria das vezes) resultados. Esse é um processo que envolve vários passos, como:

1. Identificar aspectos do mundo real que podem ser resolvidos computacionalmente;
2. Identificar uma solução computacional para esses aspectos, focando sempre no que for melhor (mais rápido, mais fácil, mais abrangente possível);
3. Implementar essa solução em uma linguagem de computação específica;
4. Testar, validar, e ajustar essa solução implementada de forma frequente.

A codificação é uma parte do processo geral de programação, mais especificamente o terceiro passo: "Implementar a solução em uma linguagem de computação específica". Isso significa, portanto, fazer um processo de transcrição da solução para uma linguagem que possa ser interpretada por um computador. Seria o mesmo que o processo de escrever um texto em um determinado idioma, ou até mesmo escrever uma função matemática; nessas situações, você transfere algo que você pensou/imaginou para o papel ou para uma tela de uma maneira que outros entes (pessoas ou computadores) possam interpretar a mensagem e, quando necessário, fazer mais abstrações sobre ela.

É muito importante notar que, quando falamos na "melhor" solução computacional, temos sempre de considerar fatores muito além do computador. Aspectos como quem usará o programa, quais recursos (sejam financeiros ou mão-de-obra) o projeto possui e, sobretudo, a quantidade de tempo necessária há para formatar tal solução e assim poder extrair o melhor dela.

Agora, que você já tem ideia do que é o Python, e alguns pontos foram esclarecidos, podemos começar a ver como funciona a linguagem.

Primeiras linhas em Python para começar a entender

O Python é uma linguagem interpretada, que pode ser usada de duas principais maneiras:

• De forma interativa: quando você usa o Python como se fosse uma "calculadora científica", executando um comando de cada vez. Aqui entra os arquivos .ipynb, os chamados notebooks, com os quais trabalharemos na série.

  Um exemplo simples disso é fazer uma operação matemática:

  Python:

  2+2
  

  Output:

  4
  

  Também podemos utilizar como exemplo o caso da função print()

  Python:

  print('Hello world!')
  

  Output:

  Hello world!
  

  Para entender melhor: abra um novo notebook no Google Colab e repita as linhas indicadas como Python acima. Observe os resultados.

• Em forma de script: quando você vai executar uma série de comandos salvos num arquivo de texto. Usualmente, tais arquivos vêm em extensão .py.

  • Exemplo: imagine que você tenha escrito em um ambiente do Anaconda um comando print('Hello, world!')e o tenha salvo num arquivo meu_script.py. Uma vez que você execute esse arquivo em um console Python, o resultado será a execução do comando que está dentro do arquivo .py. Para fazer a edição do arquivo, você precisará de uma IDE, pois o console apenas faz a execução.

Para as aulas dessa série, como já vimos, usaremos o Jupyter Notebook, seja no Anaconda ou no Google Colab. Nessas plataformas, usaremos a maneira interativa, através de arquivos .ipynb, para aprendermos a mexer com códigos Python, uma vez que trabalharemos com uma ou mais linhas de código, através de blocos.

Exemplificando: toda vez que iniciamos um notebook, precisamos importar algumas bibliotecas para podermos analisar e visualizar dados. Nesse caso, podemos, em vez de executar uma linha de cada vez para importação, puxar todas as bibliotecas de uma só vez usando um bloco de código:

import pandas as pd
import geopandas as gpd
import seaborn as sns
import matplotlib.pyplot as plt

Estes blocos de código podem comportar qualquer quantidade de linhas de código necessárias para performar uma ação em específico. Comumente o notebook é separado em vários blocos de código, obedecendo o princípio de execução de um (bloco de) código por vez.

Nesta primeira aula, apresentamos a linguagem Python de forma mais teórica e prosaica, com uma introdução prática muito breve. Nas próximas aulas, iniciaremos a parte prática da série, misturando a teoria com códigos para fazer suas primeiras análises em Python, e assim entrar de vez no mundo dos dados e da programação.

Para ir conhecendo mais do Python, aproveite para explorar as referências dos hyperlinks, da seção Para ler mais, e da literatura recomendada. É um material complementar que, a cada aula, proverá variadas visões e modos de explicar os assuntos abordados em cada post.

Espero que a série possa te beneficiar o máximo possível. Um grande abraço e até a próxima aula!

Para ler mais:

• As linguagens de codificação mais populares do mundo - Back4App
• Programação e Codificação. A diferença entre ambas definições - 3xbit Academy
• Programação Vs. Codificação - Bytes da Informação
• Programação x Codificação - Engenharia de Algoritmo, Desenvolvimento Tecnológico e Inovação
• [Off-Topic] Carreira em Programação - Codificar não é Programar - AkitaOnRails.com
• What is the Difference Between Coding and Programming? - FreeCodeCamp
• Coding vs. Programming: A Never Ending Debate - upGrad
• Coding Vs Programming For Beginners: What Is The Difference? - GoodCore
• Coding vs Programming - Thinkful
• What is Python? Executive Summary - Python.org
• What Is Python Used For? A Beginner’s Guide - Coursera
• What Is Python? the Programming Language, Explained - BusinessInsider
• What is Python? - Opensource.com
• What is Python used for? | 10 practical Python uses - FutureLearn
• Introduction to Python - w3Schools

Literatura recomendada:

• Pense em Python, de Allen B. Downey (Library Genesis)
• Learn to Program with Python 3: A Step-by-Step Guide to Programming, de Irv Kalb (Library Genesis)
• Beginning Programming with Python (Série For Dummies), de John Paul Mueller (Library Genesis)
• Starting out with Python, de Tony Gaddis (Library Genesis)
• Learn Python Visually, de Tristan Bunn (Library Genesis)
• Python Basics: A Practical Introduction to Python 3, de Fetcher Heisler, David Amos, Dan Bader, e Joanna Jablonski, do site Real Python (Library Genesis)
• Beyond the Basic Stuff with Python, de Al Sweigart (Library Genesis)
• Python in a Nutshell: A Desktop Quick Reference, de Alex Martelli, Anna Ravenscroft, e Steve Holden (Library Genesis)

Nessa série de posts, como já foi escrito, utilizaremos a linguagem Python para analisar dados. Uma vantagem de se utilizar o Python para analisar dados é a sua faciliade de acesso: para usá-lo, em um primeiro momento, é necessário apenas um computador com acesso à Internet. A razão para tanto é simples: na rede mundial estão disponíveis os chamados 'notebook interfaces' (uma explicação do que se trata isso está aqui, em inglês.

Google Colaboratory para trabalhar na web

Nessa série, em específico, concentrarei as aulas e desafios na ferramenta Google Colaboratory. Ela é baseada no Jupyter Notebook e permite fazer uma mescla de anotações e códigos em um só local, usando a computação em nuvem da Google para isso. Portanto, quem não possui uma máquina capaz de fazer um processamento de dados mais robusto, poderá usar o Google Colab livremente para a série, sem precisar fazer download de nenhum software ou dataset. A única coisa que você precisará fazer, se ainda não tiver, é criar uma conta Google para poder acompanhar o conteúdo. O vídeo a seguir relata um pouco do que se trata o Google Colab, e como você pode utilizá-lo para fazer suas análises em Python:

(Só um detalhe: Se for usar a ferramenta Google Colab, você provavelmente não precisará instalar nenhuma biblioteca, pois a Google fornece um ambiente com as principais ferramentas de análises instaladas. Em vários tutoriais, inclusive na série original que está sendo base para essa, há orientações de como instalar bibliotecas no Python, mas em algum post próximo escreverei sobre o procedimento.)

Instalando o pacote Anaconda para trabalhar localmente/off-line

No caso de você querer trabalhar localmente ou off-line com os notebooks, você pode instalar o pacote Anaconda. No caso, você precisará instalar o Anaconda versão Python 3, onde você poderá acessar o Jupyter Notebook. Aqui vai uma sugestão de vídeo com um tutorial para instalação do Jupyter através do Anaconda:

(Outro detalhe: Aqui, diferente de quando se vai trabalhar com o Google Colab, é necessário que você instale as bibliotecas que irá utilizar antes de começar a fazer qualquer coisa. Como já foi escrito, num próximo post estarei explicando como fazer isso em pacotes como o Anaconda e no Jupyter Notebook.)

Acessando o repositório no GitHub

O GitHub, para quem não conhece, é como uma rede social, mas voltada ao compartilhamento de códigos, softwares e outros notebooks. É nele que se encontrará o repositório de notebooks que serão criados e utilizados para a série, além dos dados que utilizaremos nas aulas. Você não precisa necessariamente criar uma conta no GitHub, mas é interessante dar uma olhada na plataforma, que pode lhe ajudar em projetos futuros. Ela é baseada no sistema Git de versionamento de arquivos, que é relativamente fácil de aprender. Uma breve explicação sobre o Git e o GitHub pode ser encontrada aqui.

Datasets

Falando em dados, é importante saber que os datasets (ou seja, os conjuntos de dados) que utilizaremos nas aulas, estarão disponíveis na Internet, seja no repositório do GitHub, seja em outras fontes. No início de cada parte prática, os links para acessar os dados serão disponibilizados. A não ser que você queira trabalhar com os dados off-line, os datasets não precisarão ser salvos da máquina, uma vez que serão 'puxados' desses links. Instruções sobre como fazer isso, além de orientações sobre como é possível trabalhar off-line com o Python e os dados, aparecerão nas próximas aulas.

Uma vez conhecidos esses pontos, acredito que você estará pronto para começar a aprender como usar o Python para analisar seus dados. Quaisquer outras dúvidas, fique à vontade para questionar pelos canais de comunicação.

Um grande abraço e até a primeira aula!