setup_sim_to_match_data documentation improvement

[m-samland]

Hi all,

I've been using the webbpsf.setup_sim_to_match_data function to simulate some NIRCam non-coronagraphic data recently. Thanks for adding this functionality, it's really useful. However, I found the description in the documentation to be easily misunderstood.

In the documentation there is the following explanation:

If you have a particular detector region of interest, and want to include the subtle small dependence on position, simply adjust the detector_position attribute. To adjust subpixel positions, you can set options['source_offset_{x/y}'].

psf_center = (1996, 1413) # note this is in X, Y order
boxsize = 50

inst.detector_position = psf_center
inst.options['source_offset_x'] = 0.015

This makes it sound like you're supposed to define the detector position of the source in the used subarray up to an integer pixel and if you want to use subpixels further use the 'source_offset_{x/y}' attributes. However, this attribute shifts the source position in units of arcseconds, not pixels, as could be expected from the text.

This might simply be a simple mismatch between how a user may expect this to work vs. intended behaviour. It should be made clear that source_offset is in arcsec and that it is only the detector_position attribute that actually has an impact on the PSF shape and that source_offset only impacts the relative position to the center of the output simulated image. Maybe including an option to actually specify the offset in pixel may be useful, such that the user doesn't make any mistakes in the pixelscale of the data. The pixelscale should be included in the info retrieved from `setup_sim_to_match_data'.