---
jupytext:
  formats: md:myst
  text_representation:
    extension: .md
    format_name: myst
kernelspec:
  display_name: Python 3
  language: python
  name: python3
---

# Choosing variations of stimulus (and parametrization)

You'll find that quite a few stimuli can be generated by various related functions.
Especially more complex stimuli (beyond basic components)
can be interpreted (and thus constructed) in multiple ways.
This can have implications for how one would parameterize the stimulus function.

A good example of this is the Todorovic Illusion:
```{code-cell}
from stimupy.stimuli import todorovics 
from stimupy.utils import plot_stim

resolution = {"visual_size": 5, "ppd": 10}

stim =  todorovics.rectangle(**resolution, target_size=2, covers_offset=1, covers_size=1)
plot_stim(stim)
```
This can be interpreted as
having a [rectangular target](todorovics.rectangle) that is partially occluded by some "covers"
OR as having a [cross-shaped target](todorovics.cross) with adjoining squares.
For a single stimulus parameterization,
these two conceptions may produce perfectly identical images.

However, when we start changing parameters 
-- e.g., "moving" the covering/adjoining squares --
you would expect different *behavior* from the stimulus functions
dependent on your conception/interpretation of the stimulus.
If you interpret the central target as a partially occluded rectangle,
then moving the covers should reveal more of that rectangle.
However, if you conceive it as a cross with adjoining squares,
then moving the squares should create a 'gap' around the cross.

The {py:mod}`stimupy.stimuli.todorovics` module provides functions for these variations,
which be have differently ([see fig, bottom](fig_todorovics2)).
```{code-cell}
---
mystnb:
  image:
    classes: shadow bg-primary
  figure:
    caption: |
      [`todorovics.cross()`](todorovics.cross) (left) and [`.rectangle()`](todorovics.cross) (right)
      can produce identical images (top) for some parameterizations,
      but have different behavior for others (bottom)
    name: fig_todorovics2
---
from stimupy.stimuli import todorovics
from stimupy.utils import plot_stimuli

resolution = {"visual_size": 5, "ppd": 10}

stims = {
    "cross, covers_size=1" : todorovics.cross(**resolution,     cross_size=2,  cross_thickness=1, covers_size=1),
    "rect, covers_size=1"  : todorovics.rectangle(**resolution, target_size=2, covers_offset=1,   covers_size=1),
    "cross, covers_size=.5": todorovics.cross(**resolution,     cross_size=2,  cross_thickness=1, covers_size=0.5),
    "rect, covers_size=.5" : todorovics.rectangle(**resolution, target_size=2, covers_offset=1,   covers_size=0.5),
}

plot_stimuli(stims)
```

Note that these functions not only _behave_  different;
they also take different arguments.
The `todorovics.rectangle()` function requires us to specify a `target_size`
for the partially occluded target rectangle, and `covers_offset` for the occluded squares.
The `todorovics.cross()` function, because it has a different interpretation of the elements,
requires us to specify a `cross_size` and `cross_thickness`.

For this stimulus, and many others, you can hopefully find a function
that aligns with your interpretation of the geometry, or you desired behavior of the parameters.
The goal of stimupy is to provide functions with _intuitive_ parameters relevant to vision science,
and thus we provide different functions for different intuitions of the stimuli.