Treine modelos em moléculas, espectros, sinais e episódios de robô

Novo na v2.14.0

Este tutorial treina quatro modelos em anotações científicas de um estudo do Potato. rdkit-property responde a uma pergunta sobre uma molécula, peak-cnn seleciona picos em espectros de RMN, IV, Raman, UV-Vis e de massas, signal-cnn classifica épocas de sono ou marca intervalos rotulados em gravações de EEG, ECG e sensores, e episode-model marca as fases, o resultado e a curva de recompensa de um episódio de robô. A página é para equipes que já anotam moléculas, espectros, sinais ou episódios de robô no Potato e querem um modelo que pré-rotule os itens restantes. Para cada treinador, a página dá um config que passa em potato validate config.yaml --strict, o que uma execução aprende, a pontuação em itens reservados a ler e como as predições chegam aos anotadores. Treine o seu primeiro modelo percorre a página Training com um classificador de texto, e este tutorial pressupõe essa explicação.

Os quatro treinadores

Cada treinador aprende com as respostas de um esquema de anotação e lê a entrada do modelo na exibição ou no arquivo para o qual o esquema aponta:

rdkit-property ajusta um modelo scikit-learn, e os outros três treinadores ajustam pequenas redes PyTorch no dispositivo que model_training.device seleciona. Toda execução treina em um esquema, pontua o modelo nos itens val e test reservados da execução e grava as predições de volta apenas para os esquemas listados em writeback.schemas. Itens da divisão train de uma execução nunca recebem pré-rótulo. peak-cnn, signal-cnn e episode-model mantêm o checkpoint da época que pontuou melhor em val, então o Potato toma a pontuação em itens reservados das três redes de test. Um estudo pequeno tem poucos itens de teste, e a métrica test_n da execução dá a contagem por trás da pontuação.

As três redes dão à predição de um item a confiança da parte menos certa da predição, isto é, o pico, o intervalo, a fase ou o resultado mais fraco. Um limite mínimo writeback.min_confidence portanto retém o item inteiro quando qualquer parte fica abaixo do limite. Uma predição de controle deslizante de rdkit-property não tem valor de confiança e sempre passa do limite.

Propriedades moleculares com rdkit-property

rdkit-property aprende as respostas a uma pergunta sobre a molécula que um item mostra, e a estrutura da molécula é a entrada do modelo, em vez do texto do item. Cada estrutura se torna uma impressão digital de Morgan de raio 2 e 2.048 bits, seguida dos descritores 2D do RDKit, por exemplo massa molecular e logP. Com raio 2, a impressão digital de Morgan equivale ao ECFP4, a impressão digital de conectividade estendida com diâmetro de 4 ligações. Por padrão, uma regressão logística ajusta uma resposta radio, select ou likert, e uma regressão ridge ajusta um slider. Uma floresta aleatória é a alternativa para ambos. Instale o RDKit no servidor que treina:

pip install "potato-annotation[chemistry]"

O config abaixo mostra cada composto como um desenho de estrutura e faz duas perguntas, um controle deslizante de 1 a 10 para a dificuldade de sintetizar o composto e uma escolha de sim ou não sobre sintetizar o composto em seguida:

annotation_task_name: "Compound triage"
task_dir: .
output_annotation_dir: annotation_output
data_files: [data/molecules.jsonl]
item_properties: {id_key: id, text_key: note}
user_config:
  allow_all_users: true
 
instance_display:
  fields:
    - key: smiles                 # SMILES, a molfile, or a .mol, .sdf or .smi file
      type: molecule
      label: "Compound"
 
annotation_schemes:
  - annotation_type: slider
    name: synthesis
    description: "How hard would this compound be to make? 1 is one step from a catalog reagent, 10 is a research project."
    min_value: 1
    max_value: 10
    starting_value: 5
    step: 1
  - annotation_type: radio
    name: advance
    description: "Would you make this compound next?"
    labels: ["yes", "no"]
 
model_training:
  enabled: true
  writeback:
    schemas: [synthesis, advance]
    include_unlabeled: true
    min_confidence: 0.6

Cada linha do arquivo de dados tem um composto:

{"id": "cpd_023", "smiles": "CC(=O)Nc1ccc(O)cc1", "note": "Compound 23"}

O treinador toma a estrutura do primeiro campo molecule em instance_display. Um estudo sem um campo molecule pode fazer a pergunta ao lado de um esquema chemical_structure, e o treinador então aprende com a estrutura que os anotadores desenharam. Quando os anotadores desenharam estruturas diferentes, o treinador toma o desenho mais comum, e quando ninguém desenhou, o treinador toma a estrutura de que o editor partiu (prefill_field). A página Training oferece rdkit-property para um campo molecule quando pelo menos 80% dos itens preenchem o campo. Uma estrutura que o RDKit não consegue analisar fica de fora do treinamento, não recebe predição e é contada na métrica n_unparseable da execução. Para uma pergunta de escolha ou de Likert, a página Training também oferece os treinadores de texto, porque os itens ainda têm texto.

A predição de um controle deslizante é arredondada para o step do controle e mantida entre min_value e max_value, então o modelo sempre propõe uma posição que o controle tem. A pontuação principal para um controle deslizante é a acurácia de posição exata, que conta como errada uma predição de 6 contra uma resposta de 7. Leia val_mae ou test_mae, o erro absoluto médio, ao lado da acurácia antes de decidir se as predições estão próximas o bastante para serem mostradas. A execução precisa de pelo menos 10 moléculas rotuladas na divisão train. Parâmetros como model, class_weight, radius e bits vão no campo Parameters da página Training ou na requisição da API:

curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  http://localhost:8000/admin/training/api/runs \
  -d '{"trainer": "rdkit-property", "schemas": ["advance"],
       "params": {"model": "random_forest", "class_weight": "balanced"}}'

O log da execução nomeia a contagem de moléculas, a contagem de características e o modelo. Um peso de classe balanceado conta as respostas raras com mais peso. Use class_weight: balanced quando a maioria dos compostos recebe a mesma resposta. Quando a execução termina, um anotador que abre um composto não rotulado encontra o controle deslizante na posição do valor do modelo e a escolha do modelo selecionada, ambos editáveis.

Picos em espectros com peak-cnn

peak-cnn aprende a selecionar picos a partir das respostas peak_picking que os anotadores deram. O treinador lê o espectro que o viewer_field do esquema mostra, com os mesmos leitores que a exibição de espectros usa. O alvo de treinamento é todo pico que o anotador manteve, tanto sugestões aceitas quanto picos adicionados. Uma sugestão que o anotador rejeitou marca um lugar sem pico. O modelo prevê apenas posições de picos, e os anotadores ainda dão a cada pico uma atribuição, um rótulo ou uma multiplicidade. Instale o PyTorch na máquina que treina:

pip install "potato-annotation[train-vision]"

O config abaixo pede aos anotadores que revisem picos sugeridos em espectros de RMN de 1H:

annotation_task_name: "1H NMR peak picking"
task_dir: .
media_directory: media
output_annotation_dir: annotation_output
data_files: [data/spectra.jsonl]
item_properties: {id_key: id, text_key: note}
user_config:
  allow_all_users: true
 
instance_display:
  fields:
    - key: spectrum
      type: spectrum
      label: "1H NMR"
      display_options:
        prepick:
          method: auto            # item peaks, then model, then file peak table, then detector
          prominence: 0.05
          max_peaks: 30
 
annotation_schemes:
  - annotation_type: peak_picking
    name: peaks
    description: "Accept or reject each suggested peak, and add any the suggestions missed"
    viewer_field: spectrum
    peak_fields:
      - name: assignment
        placeholder: "e.g. OCH2"
    require_review: true
    label_requirement: {required: true}
 
model_training:
  enabled: true
  trainer_params:
    peak-cnn:
      tolerance: 0.02             # ppm
  writeback:
    schemas: [peaks]
    include_unlabeled: true

Os picos do modelo chegam aos anotadores apenas pela configuração prepick da exibição, e sem prepick a exibição não mostra nenhuma sugestão. Com method: auto, a exibição oferece primeiro os peaks do próprio item, depois os picos do modelo, depois a tabela de picos do arquivo e depois os picos que o detector encontra. Antes da primeira execução, os anotadores revisam as sugestões do detector, e depois de uma execução os mesmos itens mostram os picos do modelo sem reiniciar. Com method: model, a exibição mostra apenas os picos do modelo. Use method: model para medir com que frequência os anotadores aceitam os picos do modelo sem as sugestões do detector misturadas. Cada pico do modelo é listado com "· model", a exibição mantém os max_peaks de maior confiança, e um pico do modelo aceito é armazenado com source: model.

O parâmetro tolerance define a que distância, em unidades de x, um pico previsto pode ficar de um pico anotado e ainda contar como encontrado. Sem tolerance, a execução usa 0,5% do intervalo de x do espectro, e 0,5% de uma janela de 1H de 12 ppm é 0,06 ppm. A 400 MHz, um acoplamento de 7 Hz separa as linhas de um multipleto em 0,0175 ppm. A tolerância padrão é maior que esse espaçamento, e o config define 0,02 ppm no lugar. A execução pontua precisão, revocação e F1 sobre picos casados um a um, do mais próximo ao mais distante, e informa o deslocamento médio dos picos casados. Um pico previsto em um espectro que o anotador disse não ter picos conta como alarme falso. A execução precisa de pelo menos 5 espectros anotados na divisão train.

Cada espectro é reamostrado para length pontos, 4.096 por padrão, antes de a rede ver o espectro. Aumente length quando os picos forem mais estreitos que 1/length do intervalo de x, por exemplo em um espectro de massas de alta resolução. Ler arquivos mzML também precisa do extra spectra, como a página da exibição de espectros descreve.

Estágios do sono e intervalos de sinais com signal-cnn

signal-cnn aprende com respostas interval_label em gravações fisiológicas e de sensores, como EEG, ECG, EMG e dados de acelerômetro. A rede é um pequeno modelo InceptionTime, uma pilha de convoluções paralelas de três larguras. O treinador lê cada gravação com os leitores da exibição de séries temporais, toma os canais que a exibição nomeia, reamostra cada canal para rate (100 Hz por padrão) e padroniza cada canal. Instale o PyTorch e o extra signals para gravações WFDB e Parquet:

pip install "potato-annotation[train-vision,signals]"

O config abaixo pontua o sono em épocas de 30 segundos em polissonografia noturna, do modo como um avaliador humano rotula cada época como vigília, N1, N2, N3 ou REM:

annotation_task_name: "Sleep staging"
task_dir: .
media_directory: media
output_annotation_dir: annotation_output
data_files: [data/psg.jsonl]
item_properties: {id_key: id, text_key: note}
user_config:
  allow_all_users: true
 
instance_display:
  fields:
    - key: signal
      type: time_series
      label: "PSG"
      display_options:
        window: 30
        channels: ["EEG Fpz-Cz", "EOG", "EMG chin"]   # also the channels signal-cnn reads
 
annotation_schemes:
  - annotation_type: interval_label
    name: stage
    description: "Sleep stage of each 30-second epoch"
    signal_field: signal
    mode: epoch
    epoch_length: 30
    require_all_epochs: true
    label_requirement: {required: true}
    labels:
      - {name: W, key_value: "1"}
      - {name: N1, key_value: "2"}
      - {name: N2, key_value: "3"}
      - {name: N3, key_value: "4"}
      - {name: REM, key_value: "5"}
 
model_training:
  enabled: true
  writeback:
    schemas: [stage]
    include_unlabeled: true

O mode do esquema define a tarefa. No modo epoch, cada época anotada é um exemplo de treinamento, e o modelo rotula cada época de uma gravação nova. Uma última época com menos da metade do comprimento da época gravada não recebe rótulo. A pontuação principal em itens reservados é o F1 macro sobre as épocas anotadas. O F1 macro dá a um estágio raro como N1 o mesmo peso que N2. Por padrão, a perda de treinamento pondera cada estágio pelo inverso da frequência do rótulo (balanced: true), e uma época N1 então conta mais que uma época N2. Toda gravação é lida com os canais da primeira gravação de treinamento, nessa ordem, e uma gravação que não tem um dos canais de treinamento recebe uma linha plana no lugar do canal ausente. Uma exibição que não nomeia canais dá ao treinador todos os canais, até max_channels (16).

O modo free treina com trechos marcados. Adicione um segundo esquema interval_label com mode: free ao mesmo signal_field para marcar artefatos ou despertares:

  - annotation_type: interval_label
    name: artifacts
    description: "Mark artifacts"
    signal_field: signal
    mode: free
    labels:
      - {name: artifact, key_value: "a"}
      - {name: spike, key_value: "s", kind: event}

No modo free, a rede treina em recortes aleatórios de 30 segundos (window_s), rotula cada quadro de 1 segundo (frame_s), une quadros consecutivos com um mesmo rótulo em um intervalo e descarta intervalos mais curtos que min_duration. A pontuação principal é o F1 de intervalos, que casa um intervalo previsto com um anotado do mesmo rótulo com IoU 0,5. Eventos pontuais como o rótulo spike acima não são treinados nem previstos. A execução precisa de pelo menos 3 gravações anotadas na divisão train, e o modo epoch também precisa de pelo menos dois rótulos diferentes nos dados.

Os intervalos do modelo aparecem na gravação como pré-anotações tracejadas, listadas com "· from the model", e são salvos quando o anotador faz uma primeira alteração ou clica em "Keep these". As anotações da própria gravação têm precedência. Um arquivo EDF+ que contém um hipnograma mostra o hipnograma e não os intervalos do modelo, e o mesmo vale para um item com intervalos de preannotation_field. Definir pre_annotations: false no esquema desativa os dois tipos.

Episódios de robô com episode-model

episode-model aprende as três camadas de uma resposta episode_annotation, isto é, as fases, o resultado e a curva de recompensa de progresso. A entrada do modelo é toda série numérica que o episódio registra, como posições de articulações e estado da garra, com uma linha por quadro. A entrada inclui séries que series_shown deixa fora da tela e exclui o vídeo. O modelo não consegue encontrar uma fase que só aparece na câmera e deixa as medições do robô inalteradas. Instale o PyTorch, mais pyarrow para conjuntos de dados LeRobot ou h5py para demonstrações HDF5:

pip install "potato-annotation[train-vision]"

O config abaixo coleta as três camadas em demonstrações de pegar e colocar, como a página de episódios de robô descreve:

annotation_task_name: "Robot episode review"
task_dir: .
media_directory: media
output_annotation_dir: annotation_output
data_files: [data/episodes.jsonl]
item_properties: {id_key: id, text_key: note}
user_config:
  allow_all_users: true
 
annotation_schemes:
  - annotation_type: episode_annotation
    name: episode_review
    description: "Mark the phases, judge the outcome, and draw the progress."
    source_field: episode
    layers: [phases, outcome, reward]
    phases:
      - {name: reach, key_value: "1"}
      - {name: grasp, key_value: "2"}
      - {name: transport, key_value: "3"}
      - {name: place, key_value: "4"}
      - {name: retract, key_value: "5"}
    outcomes: [success, partial, failure]
    failure_causes: [missed grasp, object slipped, collision]
    reward_range: [0.0, 1.0]
    series_shown: [gripper, wrist_force, shoulder_lift, elbow]
 
model_training:
  enabled: true
  writeback:
    schemas: [episode_review]
    include_unlabeled: true

A rede aplica uma convolução sobre as séries seguida de uma GRU bidirecional com três cabeças, uma para a fase de cada quadro, uma para o resultado do episódio e uma para a recompensa em cada quadro. Uma camada que uma resposta deixa vazia fica de fora da perda desse episódio, então um episódio marcado apenas com um resultado ainda treina a cabeça de resultado. A cabeça de resultado treina quando os episódios de treinamento incluem pelo menos dois resultados diferentes. A cabeça de recompensa treina apenas no trecho em que o anotador desenhou a curva, porque fora desse trecho o anotador não deu resposta. Episódios mais longos que max_frames (2.000) são treinados em recortes aleatórios.

A predição tem o formato de uma resposta armazenada, com fases da lista do esquema, um dos resultados do esquema e uma curva de recompensa de 50 pontos dentro de reward_range, para as camadas que o esquema mostra. A predição pré-preenche a linha do tempo e é armazenada quando o anotador edita a linha do tempo. A causa da falha e a instrução ficam por conta do anotador. A pontuação principal em itens reservados é o F1 macro de fases em uma grade de 0,1 segundo. A execução também informa o F1 de segmentos de fase com IoU 0,5, a acurácia do resultado e o r de Pearson da curva de recompensa onde uma curva foi desenhada. Um esquema sem fases toma a acurácia do resultado como pontuação principal, e depois a correlação da recompensa. A execução precisa de pelo menos 5 episódios anotados na divisão train. O Potato não tem treinador para rollout_evaluation, porque uma preferência de rollout compara vídeos e episode-model não lê vídeo.

Inicie uma execução e verifique o resultado

Reinicie o servidor depois de adicionar model_training:

potato start config.yaml -p 8000

Abra /admin/training, escolha o esquema e o treinador e clique em Train now. A página oferece apenas os treinadores que se ajustam a cada esquema, e um treinador que não está instalado é listado como "not installed", com o comando de instalação. Quando a execução termina, o Potato lista a pontuação em itens reservados na tabela Runs, com a divisão e a métrica em uma dica. A página da execução lista todas as métricas e a divisão de cada item. O relatório de gravação de volta em GET /admin/training/api/status conta as predições publicadas e as que cada verificação reteve, por exemplo n_skipped_low_confidence.

Os pré-rótulos ancoram os anotadores na resposta do modelo, então ative include_unlabeled em um estudo novo apenas quando a pontuação em itens reservados justificar mostrar as respostas do modelo. Revise pré-rótulos de modelos no ciclo trata de servir primeiro os pré-rótulos de menor confiança e de retreinar com as correções, e Configuração lista todas as chaves, os backends e as verificações de gravação de volta.

Leitura complementar

• Visão geral do treinamento de modelos
• Todos os treinadores
• Estruturas químicas, espectros e séries temporais
• Anotação de episódios de robô e o guia de episódios de robô
• Potato para química, fisiologia e robótica
• Rotulagem assistida por modelo
• Referência upstream para rdkit-property, peak-cnn, signal-cnn e episode-model

Referências

• Ismail Fawaz, H., Lucas, B., Forestier, G., Pelletier, C., Schmidt, D. F., Weber, J., Webb, G. I., Idoumghar, L., Muller, P.-A., and Petitjean, F. (2020). InceptionTime: Finding AlexNet for Time Series Classification. Data Mining and Knowledge Discovery, 34(6), 1936-1962. https://doi.org/10.1007/s10618-020-00710-y
• Rogers, D., and Hahn, M. (2010). Extended-Connectivity Fingerprints. Journal of Chemical Information and Modeling, 50(5), 742-754. https://doi.org/10.1021/ci100050t