Quickstart#

Note

We recommend first following the Examples if you’re unfamiliar with the package. It is more comprehensive than this page.

To get started, install the package with pip install solpolpy.

Resolve between systems#

This package allows you to convert between different polarization systems relevant to solar physics. You can find a detailed description of these systems with their equations in Deforest et al. 2022.

The easiest way to interact with solpolpy is through the resolve method:

from solpolpy import resolve, load_data
paths = ['path_to_image0.fits', 'path_to_image1.fits', 'path_to_image2.fits']
out_system = "BpB"
input_collection = load_data(paths)
output_collection = resolve(input_collection, out_system)

# to access the data, just access the appropriate cube
print(output_collection['B'].data)

resolve takes two (or more depending on the polarization systems) parameters: 1. the input data and 2. the desired output polarization system. Valid polarization systems are described in the documentation.

solpolpy.resolve(input_data: list[str] | NDCollection, out_system: str, imax_effect: bool = False, out_angles: Unit('deg') = None, offset_angle: Unit('deg') = None) → NDCollection#

Apply a polarization transformation to a set of input dataframes.

Parameters:

  • input_data (NDCollection or List[str]) – Either: 1) a collection where each member NDCube has an expected name or 2) a list of paths to FITS files. We recommend option 2.

  • out_system (string) –

    The polarization state you want to convert your input dataframes to. Must be one of the following strings:

    • ”mzp”: Triplet of images taken at -60°, 0°, and +60° polarizing angles.

    • ”btbr”: Pair of images with polarization along the tangential and radial direction with respect to the Sun respectively.

    • ”stokes”: Total brightness (“I”), polarized brightness along vertical and horizontal axes (Q) and polarized brightness along ±45° (U) .

    • ”bpb”: Total brightness and ‘excess polarized’ brightness images pair respectively.

    • ”bp3”: Analogous to Stokes I, Q and U, but rotates around the Sun instead of a fixed frame of reference of the instrument.

    • ”bthp”: Total brightness, angle and degree of polarization.

    • ”fourpol”: For observations taken at sequence of four polarizer angles, i.e. 0°, 45°, 90° and 135°.

    • ”npol”: Set of images taken at than arbitrary polarizing angles other than MZP

  • imax_effect (Boolean) – The ‘IMAX effect’ describes the change in apparent measured polarization angle as an result of foreshortening effects. This effect becomes more pronounced for wide field polarized imagers - see Patel et al (2024, in preparation) If True, applies the IMAX effect for wide field imagers as part of the resolution process.

  • out_angles (u.degree) – Angles to use when converting to npol or some arbitrary system

  • offset_angle (u.degree) – Reference angle used for the polarizer offset. If None, it will try to determine it from the metadata.

Returns:

The transformed data are returned as a NDCollection.

Return type:

NDCollection

The equations required for the transformations from one system to another can be found in Deforest et al. 2022.

IMAX Effect#

Wide field polarizing imagers such as the Wide Field Imager (WFI) of PUNCH suffer from foreshortening of the polarizer angle across their field of view (FOV). The observed polarization angles deviate from the ideal based on their spatial location. The foreshortening effect draws parallels with IMAX 3D presentation which use linear polarizer systems and a wide screen. In solpolpy, the IMAX effect is corrected in input data using equation 44 from Deforest et al. 2022. Details about IMAX effect on WFI data will be soon published as a research article.

solpolpy supports this correction with the imax_effect keyword on the ~solpolpy.resolve function. If set to true, it corrects for the IMAX effect and converts the apparent non-ideal angle to ideal MZP configuration.

Plotting results#

You can plot any input or output collection using the plot_collection function provided.

from solpolpy import plot_collection
plot_collection(input_collection)
plot_collection(output_collection)

It has many options:

solpolpy.plot_collection(collection: NDCollection, figsize=(8, 8), show_colorbar=False, lat_ticks=None, lon_ticks=None, major_formatter='dd', xlabel='HP Longitude', ylabel='HP Latitude', vmin=None, vmax=None, cmap='Greys_r', ignore_alpha=True, fontsize=18)#

Plot a solpolpy NDCollection input or output.

Parameters:

  • collection (NDCollection) – collection to visualize

  • figsize (Tuple[float, float]) – figure size according to Matplotlib

  • show_colorbar (bool) – whether to show a colorbar

  • lat_ticks (Optional[np.ndarray]) – if provided, shows as the tick marks for latitude. default values used otherwise.

  • lon_ticks (Optional[np.ndarray]) – if provided, shows as the tick marks for longitude. default values used otherwise.

  • major_formatter (str) – the formatter for major tickmarks as specified by Matplotlib

  • xlabel (str) – label for plot x axes

  • ylabel (str) – label for plot y axes

  • vmin (float, list of floats, or None) – minimum values of the plots. if a list is provided, they are applied left to right to each plot

  • vmax (float, list of floats, or None) – maximum values of the plots. if a list is provided, they are applied left to right to each plot

  • cmap (str or Matplotlib colormap) – a Matplotlib accepted colormap or colormap string

  • ignore_alpha (bool) – whether to plot the alpha array. defaults to True as it is not normally helpful to visualize.

  • fontsize (int) – font size for some aspects of the plot

Returns:

the plotted figure and axes are returned for any additional edits

Return type:

Matplotlib figure and axes