Apresentação do PsychoPy e seus elementos básicos
7 de agosto de 2026
O PsychoPy (Peirce, 2007, 2008; Peirce et al., 2019) é um software livre desenvolvido para desenhar, implementar e correr experiências de Psicologia e Neurociência Cognitiva em Python (uma linguagem de programação popular, entre outras, em aplicações científicas). Compatível com todos os principais sistemas operativos (Windows, Linux e macOS), o PsychoPy oferece uma precisão temporal que iguala ou suplanta a de várias alternativas comerciais (Bridges et al., 2020).
Uma das principais características que faz o PsychoPy destacar-se entre alguns equivalentes refere-se à sua flexibilidade, sendo possível preparar uma simples tarefa experimental usando a janela Builder – uma interface gráfica intuitiva e fácil de usar – ou programar de raiz, em Python, na janela Coder, uma tarefa tão complexa quanto seja necessário. É ainda possível combinar as vantagens de ambas, sendo possível inserir linhas de código Python a partir da janela Builder. Finalmente, o PsychoPy é constituído por uma terceira janela, denominada Runner, a partir da qual se pode iniciar uma tarefa experimental já programada bem como consultar alertas e mensagens de erro que ocorram quando, por alguma razão, a experiência não é executada com sucesso.
No restante do presente documento é apresentada brevemente a estrutura da janela Builder do PsychoPy, seguida de uma breve clarificação acerca das unidades espaciais usadas neste software, e uma breve listagem de alguns dos principais componentes disponíveis para implementar uma experiência em Psicologia Cognitiva. Antes de mais, porém, importará clarificar de antemão que será consistentemente referenciada a versão nativa, em inglês, do software – a razão para tal prende-se com o facto de a tradução para português ser, francamente, medíocre e susceptível de imprecisões, além de incompleta (e.g., "Routine", "Loop", e "Trial" nem sequer são traduzidos, mantendo-se em inglês).
Janela Builder
A janela Builder do PsychoPy divide-se em quatro grandes áreas (ver Figura 1). No topo (a azul na Figura 1) encontra-se o menu principal, onde se pode aceder, com o ponteiro do rato, a opções de ficheiros (abrir, criar novo, guardar, etc.), a definições gerais da tarefa experimental aberta (definições do ecrã, periféricos de entrada, dados recolhidos) e opções para testar/correr a mesma, bem como opções e definições para correr a experiência online (através da plataforma Pavlovia).
No fundo da janela (a amarelo, na Figura 1), encontra-se o fluxograma (flow), onde é apresentada uma linha temporal que lista, da esquerda para a direita, a ordem das diferentes rotinas (diferentes caixas) bem como a existência de ciclos (loops). É também nesta área onde se podem introduzir novas rotinas e ciclos à experiência.
No centro, e ocupando a maior área da janela Builder (a laranja, na Figura 1), encontra-se a área de rotinas – nesta são listados os diferentes componentes incluídos na rotina seleccionada (pode-se seleccionar uma qualquer rotina listada no fluxograma pressionando com o botão esquerdo do rato a caixa correspondente), incluindo uma representação visual dos seus inícios e términos.
Finalmente, do lado direito (a verde na Figura 1), encontra-se o menu de componentes, onde são listados os diferentes componentes que podem ser introduzidos na rotina seleccionada. O menu de componentes encontra-se organizado em várias subsecções, sendo as mais relevantes dedicadas a estímulos (eventos perceptíveis pelo participante, como elementos visuais ou auditivos) e respostas (periféricos através dos quais os participantes possam fornecer uma resposta).
A introdução e definição de parâmetros de um qualquer evento que se queira incluir numa tarefa experimental (e.g., mostrar uma imagem ao participante ou registar o pressionar de uma tecla por esse) faz-se a partir do menu de componentes. Quando um desses é seleccionado, e uma vez definidos alguns parâmetros e definições, surge listado na área de rotinas. Os diferentes componentes incluídos numa rotina encontram-se aqui listados verticalmente, sendo que os seus inícios e términos (em relação ao início da rotina e na escala temporal no topo desta área) são visualmente representados na horizontal, sob a forma de barras mais ou menos extensas. As rotinas constituem, assim, sequências estruturadas de eventos e, na sua forma mais elementar, são usadas para apresentar um qualquer estímulo ao participante e recolher a sua resposta a esse. Novas rotinas, bem como ciclos que determinam a repetição de uma ou mais rotinas, podem ser inseridos no fluxograma, o qual fornece uma representação visual da estrutura sequencial (em termos de rotinas e ciclos) da totalidade da tarefa experimental, da esquerda para a direita (o extremo esquerdo representa o início da tarefa experimental, quando colocada a correr, e o extremo direito, com uma seta, o término da tarefa experimental; rotinas são representadas por caixas e ciclos por linhas/setas que englobam uma ou mais rotinas).
Dado constituírem os ingredientes básicos para o desenho e implementação de uma tarefa experimental no PsychoPy, segue-se, no restante do presente texto, uma breve apresentação de alguns dos principais componentes disponíveis neste software, antecedida de algumas notas acerca de unidades espaciais.
Unidades espaciais no PsychoPy
Um aspecto particularmente relevante para as configurações de vários componentes disponíveis no PsychoPy, especialmente estímulos visuais, refere-se à definição das coordenadas no ecrã onde esses são mostrados, bem como a extensão espacial que ocupam.
O PsychoPy incorpora uma série de unidades espaciais para tal, incluindo pixéis e, caso seja explicitado o tamanho físico do ecrã e a sua distância do observador, centímetros e ângulos de grau visual. Para qualquer unidade espacial escolhida para uma tarefa experimental ou para um componente em particular, a origem (isto é, as coordenadas [0, 0]) é dada pelo centro do ecrã. Em todo o caso, a opção de unidades espaciais por defeito e, indubitavelmente, a mais adequada para a implementação da maioria das tarefas experimentais é dada em unidades height (altura). Estas são unidades normalizadas para a altura do ecrã acoplado ao computador onde é corrida a tarefa experimental, o que possibilita que a mesma disposição relativa de elementos visuais seja respeitada, independentemente das dimensões físicas do ecrã ou da sua resolução em pixéis, mesmo que a tarefa tenha sido preparada num outro computador.
Em unidades height, a altura do ecrã corresponde a um valor de 1. Ou seja, se se definir que um qualquer estímulo (e.g., uma imagem) é apresentado com uma extensão horizontal de 1, a sua largura será igual à da altura do ecrã. Se o tamanho de um estímulo (em que w se refere à sua extensão horizontal – width – e h à sua extensão vertical – height) for definido como
As coordenadas espaciais no ecrã funcionam de forma similar (ver Figura 2). Em relação ao centro do ecrã (origem), com coordenadas (0, 0), qualquer estímulo posicionado à direita/esquerda ou acima/baixo desse ponto, terá coordenadas horizontais/verticais positivas/negativas, respectivamente. Os valores introduzidos nas coordenadas são, igualmente, normalizados face à altura do ecrã. Assim, por exemplo, o ponto (0.5, 0) encontra-se centrado verticalmente e distanciado para a direita em metade da altura do ecrã. Um estímulo colocado nas coordenadas (0.25, -0.4) encontra-se à direita do centro do ecrã em 25% da altura do ecrã e abaixo do centro em 40% da altura do ecrã. Finalmente, um estímulo colocado nas coordenadas (-0.5, 0.1) encontra-se situado à esquerda do centro do ecrã em metade da altura do ecrã e acima desse ponto em 10% da altura do ecrã. A Figura 2 representa, com cruzes, diversas localizações, acompanhadas pelas suas coordenadas em unidades height, numa representação esquemática de um ecrã. O rectângulo cinzento representa um possível estímulo, sendo indicada a sua extensão vertical e horizontal com valores a cinzento. Sabendo-se a resolução do ecrã usado, é fácil determinar a extensão e/ou coordenadas de um qualquer estímulo em pixéis. Por exemplo, num ecrã com resolução de 1920 × 1080 pixéis, um estímulo com uma largura, em unidades height, de 0.75 ocupará uma extensão de 0.75 × 1080 = 810 pixéis. Caso o mesmo estímulo seja mostrado num ecrã com uma resolução de 1024 × 768 pixéis, a sua largura será de 0.75 × 768 = 576 pixéis. Obviamente, caso esses dois ecrãs, pese embora as diferentes resoluções, tenham o mesmo tamanho físico, o estímulo manter-se-á também com o mesmo tamanho físico (nomeadamente, 0.75 da altura do ecrã). Isto não seria obviamente o caso se o tamanho do estímulo fosse definido em pixéis, tendo esse valor de ser ajustado para cada ecrã.
Componentes para estímulos
Texto. Este componente, como deverá ser óbvio pelo nome, permite a apresentação de sequências de texto. É possível definir a cor e tipo de letra, a sua opacidade e tamanho no ecrã, bem como apresentar o texto invertido (horizontalmente ou verticalmente) e/ou mais ou menos rodado. Quando o texto a apresentar é relativamente longo, é possível ainda definir uma extensão máxima para as linhas.
Polígono. Este componente apresenta no ecrã uma forma geométrica, incluindo linhas, triângulos, rectângulos/quadrados, círculos, cruzes, estrelas, e setas. É ainda possível definir polígonos regulares com n lados. Para qualquer forma geométrica, pode-se definir o seu tamanho, a cor de preenchimento, a cor e largura do bordo, a opacidade e a orientação.
Imagem. O componente de imagem apresenta no ecrã uma imagem, aceitando quase todos os tipos de ficheiro possíveis (e.g., .tif, .jpg, .bmp, .png, etc.). Para além do tamanho no ecrã, é possível definir o espaço de cor da imagem (e.g., RGB, HSV, etc.), a sua coloração e contraste. É também possível inverter a imagem, na vertical ou na horizontal, ou alterar a sua orientação. Finalmente, pode-se definir uma máscara através da qual a imagem é apresentada, especificando uma imagem de máscara, usando uma das máscaras já definidas (circle, gauss, raisedCos), ou ainda especificando numa matriz (com valores entre -1 e 1) um filtro espacial personalizado.
Filme/Animação. Este componente possibilita a apresentação de ficheiros em formato de vídeo (e.g., .mpeg, .avi, .mov). Pode ser definido o tamanho no ecrã e a duração do vídeo, sendo possível indicar se a rotina deve ou não terminar com o término do vídeo. Pode-se ainda repetir o vídeo (até que alguma outra instrução espoletada por um outro componente determine o seu término) e ajustar ou eliminar o som. Por fim, pode-se variar a opacidade do vídeo, o seu contraste e orientação no ecrã.
Som. Este componente, o único estímulo não visual no PsychoPy, apresenta um som nas colunas do computador durante um tempo especificado. Pode-se usar um ficheiro de som (os tipos de ficheiros compatíveis incluem .mid, .wav, .ogg; importa enfatizar que o formato .mp3 não é compatível) ou definir uma nota específica, usando a nomenclatura anglo-saxónica: C (dó), D (ré), E (mi), F (fá), G (sol), A (lá), B (si). Essas podem ainda ser combinadas com os termos 'sh' e 'f' para, respectivamente, sustenidos e bemóis (por exemplo, Gsh toca um Sol#). Finalmente, pode-se ajustar o volume numa escala normalizada entre 0 (mínimo) e 1 (máximo).
Componentes para respostas
Teclado. Este componente monitoriza o teclado e regista o pressionar de qualquer tecla que seja definida como uma possível resposta. Para além do momento a partir do qual, e até ao qual, pode ser pressionada uma tecla, neste componente pode-se definir se se registam dados para o momento em que é(são) pressionada(s) ou solta(s) a(s) tecla(s) especificada(s) e se a ocorrência de uma resposta deve ou não interromper a rotina. Sendo um componente de resposta, é também possível especificar que dados são guardados – se a primeira tecla pressionada, se a última tecla pressionada, se todas as teclas pressionadas (caso uma resposta interrompa a rotina, estas últimas serão provavelmente opções desnecessárias) ou se nenhum dado deva ser registado (útil para quando se pretenda que o participante interaja com uma parte da experiência que não vise a recolha de dados, como por exemplo para terminar uma rotina de instruções). Finalmente, é possível definir que respostas devem ser classificadas como respostas correctas. Como em todos os restantes componentes, também este deve ter uma designação única, isto é, um nome que não seja utilizado para nomear qualquer outro componente ou variável. Assumindo que o nome escolhido é Resposta, o componente regista no ficheiro de dados, para cada repetição do ensaio, os seguintes valores (em colunas distintas): Resposta.keys – que tecla(s) foi(foram) pressionada(s); Resposta.rt – o momento, em segundos, em que foi pressionada a tecla, sendo o tempo medido a partir do início do componente (e.g., caso o componente seja iniciado 2 segundos após o início da rotina e a tecla seja pressionada 0.25 segundos após o início do componente, o valor registado é 0.25, e não 2.25); Resposta.corr – caso tenha sido definida uma resposta como sendo a correcta, este assume um valor de 1 para essa resposta e um valor de 0 para qualquer outra (note-se que esta opção pode ser útil mesmo em casos em que, tecnicamente, não há uma única resposta correcta – por exemplo, numa tarefa de bissecção temporal, em que interessa registar a frequência de respostas 'longo' para um dado estímulo com uma duração variável, se se definir a resposta 'longo' como sendo a resposta "correcta", as médias de valores registados em Resposta.corr para cada duração traduzirão directamente a frequência de respostas 'longo').
Rato. Este componente permite que os participantes forneçam respostas através de um rato, trackball, touchpad, ou dispositivos equivalentes. Uma vez mais, deve-se definir um nome único para este, bem como início (relativamente à rotina) e duração do momento em que é monitorizado o rato. À semelhança do componente de teclado, também o componente de rato permite optar se uma resposta (isto é, pressionar um dos botões do rato) termina ou não a rotina, pese embora com mais opções: pode-se definir (i) que a rotina não termina com uma resposta do rato, (ii) que termina com qualquer resposta do rato, (iii) que a rotina termina com uma resposta válida (caso sejam definidos estímulos clicáveis; ver adiante), ou (iv) que a rotina termina com uma resposta correcta (se se definirem estímulos clicáveis sendo um desses classificado como uma resposta correcta; ver adiante). Pode-se especificar que estímulos visuais (conquanto estejam presentes no ecrã no mesmo período em que é monitorizado o rato) são clicáveis, isto é, se o pressionar de um botão do rato só deve ser considerado caso o cursor esteja posicionado por cima desse(s) estímulo(s). Para tal, são listados os nomes desses componentes no campo Clickable stimuli. No que se refere aos dados que são registados, pode-se optar por nenhum, somente o estado do rato aquando do término da rotina, apenas aquando do pressionar de um dos botões, apenas aquando do pressionar de um dos botões por cima de um estímulo válido (definido como clicável) ou a cada refrescamento do ecrã (i.e., em todos os frames; útil quando se pretende registar a trajectória, ao longo do tempo, do movimento do rato). Caso se opte pelo registo de dados deste componente, serão guardados, em cada repetição do ensaio, os seguintes valores, assumindo que o componente foi designado de Resposta: Resposta.x – coordenadas horizontais no ecrã do cursor do rato, nas unidades especificadas (por defeito unidades height; ver acima); Resposta.y – coordenadas verticais no ecrã do cursor do rato, nas unidades especificadas; Resposta.leftButton, Resposta.midButton e Resposta.rightButton – se foi pressionado o botão esquerdo, central ou direito do rato, respectivamente (1 para pressionado e 0 para não pressionado); Resposta.time – momento, em segundos e relativamente ao início do componente rato, em que foi pressionado um botão; Resposta.clicked_name – caso tenha(m) sido definido(s) estímulo(s) como clicável(eis), este especifica o nome do estímulo em cima do qual foi pressionado o botão.
Componente de código Python
Código. Este componente possibilita que sejam introduzidas linhas de código em Python (o PsychoPy traduz também automaticamente estas linhas de código para Javascript, permitindo que a experiência possa ser corrida online), sendo possível especificar se estas devem ser lidas antes da experiência, no início da experiência, no início da rotina na qual o componente de código foi inserido, em cada refrescamento do ecrã (frame) dessa mesma rotina, no final da rotina ou ainda no final da experiência. Ainda que os componentes de base, disponíveis no menu de componentes, possibilitem já a implementação de inúmeras tarefas experimentais, é graças a este componente que o PsychoPy é tão flexível e permite a programação de virtualmente qualquer tarefa (ou, se se desejar, programa ou aplicação) que se pretenda. Mesmo uma utilização relativamente modesta deste componente permite fazer pequenos, mas importantes, ajustes à forma como uma dada experiência é executada, para além do que é oferecido pelos componentes de base do PsychoPy.
Bibliografia
-
Bridges, D., Pitiot, A., MacAskill, M. R., & Peirce, J. W. (2020). The timing mega-study: Comparing a range of experiment generators, both lab-based and online. PeerJ, 8, e9414.
-
Peirce, J. W. (2007). PsychoPy—Psychophysics software in Python. Journal of Neuroscience Methods, 162(1–2), 8–13.
-
Peirce, J. W. (2008). Generating stimuli for neuroscience using PsychoPy. Frontiers in Neuroinformatics, 2.
-
Peirce, J. W., Gray, J. R., Simpson, S., MacAskill, M., Höchenberger, R., Sogo, H., Kastman, E., & Lindeløv, J. K. (2019). PsychoPy2: Experiments in behavior made easy. Behavior Research Methods, 51(1), 195–203.