Utility Functions

piff.util.adjust_value(value, dtype)[source]

Possibly adjust a value to match the type expected for the given dtype.

e.g. change np.int16 -> int if dtype expects int. Or vice versa.

Parameters

value – The input value to possible adjust.

Returns

the adjusted value to use for writing in a FITS table.

piff.util.calculateSNR(image, weight)[source]

Calculate the signal-to-noise of a given image.

Parameters

  • image – The stamp image for a star

  • weight – The weight image for a star

  • logger – A logger object for logging debug info. [default: None]

Returns

the SNR value.

piff.util.calculate_moments(star, third_order=False, fourth_order=False, radial=False, errors=False, logger=None)[source]

Calculate a bunch of moments using HSM for the weight function.

The flux, 1st, and 2nd order moments are always calculated:

\[\begin{split}M_{00} &= \sum W(u,v) I(u,v) \\ M_{10} &= \sum W(u,v) I(u,v) du \\ M_{01} &= \sum W(u,v) I(u,v) dv \\ M_{11} &= \sum W(u,v) I(u,v) (du^2 + dv^2) \\ M_{20} &= \sum W(u,v) I(u,v) (du^2 - dv^2) \\ M_{02} &= \sum W(u,v) I(u,v) (2 du dv)\end{split}\]

where W(u,v) is the weight from the HSM fit and du,dv are the positions relative to the HSM measured centroid.

If third_order is set to True, then 3rd order moments are also calculated and returned:

\[\begin{split}M_{21} &= \sum W(u,v) I(u,v) du (du^2 + dv^2) \\ M_{12} &= \sum W(u,v) I(u,v) dv (du^2 + dv^2) \\ M_{30} &= \sum W(u,v) I(u,v) du (du^2 - 3 dv^2) \\ M_{03} &= \sum W(u,v) I(u,v) dv (3 du^2 - dv^2)\end{split}\]

If fourth_order is set to True, then 4th order moments are also calculated and returned:

\[\begin{split}M_{22} &= \sum W(u,v) I(u,v) (du^2 + dv^2)^2 \\ M_{31} &= \sum W(u,v) I(u,v) (du^2 + dv^2) (du^2 - dv^2) \\ M_{13} &= \sum W(u,v) I(u,v) (du^2 + dv^2) (2 du dv) \\ M_{40} &= \sum W(u,v) I(u,v) (du^4 - 6 du^2 dv^2 + dv^4) \\ M_{04} &= \sum W(u,v) I(u,v) (du^2 - dv^2) (4 du dv)\end{split}\]

Higher order normalized radial moments (4th through 8th, even) are calculated if radial is set to True:

\[\begin{split}r^2 &\equiv du^2 + dv^2 \\ M_{22} &= \sum W(u,v) I(u,v) r^4 \\ M_{33} &= \sum W(u,v) I(u,v) r^6 \\ M_{44} &= \sum W(u,v) I(u,v) r^8 \\ M_{22n} &= M_{22}/M_{11}^2 \\ M_{33n} &= M_{33}/M_{11}^3 \\ M_{44n} &= M_{44}/M_{11}^4\end{split}\]

For all of these, one can also have error estimates returned if errors is set to True.

Parameters

  • star – Input star, with stamp, weight

  • third_order – Return the 3rd order moments? [default: False]

  • fourth_order – Return the 4th order moments? [default: False]

  • radial – Return the higher order radial moments? [default: False]

  • errors – Return the variance estimates of other returned values? [default: False]

  • logger – A logger object for logging debug info. [default: None]

Returns

A dict of the calculated moments, with the following keys/values:

  • M00, M10, M01, M11, M20, M02

  • M21, M12, M30, M03 if third_order = True

  • M22, M31, M13, M40, M04 if fourth_order = True

  • M22n, M33n, M44n if radial = True

If errors = True, then also a second dict (with the same keys) giving the variances.

piff.util.ensure_dir(target)[source]

Ensure that the directory for a target output file exists.

Parameters

target – The file that you want to write to.

piff.util.estimate_cov_from_jac(jac)[source]

Estimate a covariance matrix from a jacobian as returned by scipy.optimize.least_squares .. math:

C = (J^T J)^{-1}

This is computed using Moore-Penrose inversion to discard singular values.

Parameters

jac – The Jacobian as a 2d numpy array

Returns

cov, a numpy array giving the estimated covariance.

piff.util.get_all_subclasses(cls)[source]

Get all subclasses of an existing class.

piff.util.make_dtype(key, value)[source]

A helper function that makes a dtype appropriate for a given value

Parameters

  • key – The key to use for the column name in the dtype.

  • value – The input value (just one item if using a column of multiple values)

Returns

a numpy.dtype instance

piff.util.read_kwargs(fits, extname)[source]

A helper function for reading a single row table from a fits file returning the values and column names as a kwargs dict.

Parameters

  • fits – An open fitsio.FITS instance

  • extname – The extension to read.

Returns

A dict of the kwargs that were read from the file.

piff.util.run_multi(func, nproc, raise_except, args, logger, kwargs=None)[source]

Run a function possibly in multiprocessing mode.

This is basically just doing a Pool.map, but it handles the logger properly (which cannot be pickled, so it cannot be passed to the function being run by the workers).

Parameters

  • func – The function to run. Signature should be: func(*args, logger=logger, **kwargs)

  • nproc – How many processes to run. If nproc=1, no multiprocessing is done. nproc <= 0 means use all the cores.

  • raise_except – Whether to raise any exceptions that happen in individual jobs.

  • args – a list of args for func for each job to run.

  • logger – The logger you would pass to func in single-processor mode.

  • kwargs – a list of kwargs for func for each job to run. May also be a single dict to use for all jobs. [default: None]

Returns

The output of func(*args[i], **kwargs[i]) for each item in the args, kwargs lists.

piff.util.write_kwargs(fits, extname, kwargs)[source]

A helper function for writing a single row table into a fits file with the values and column names given by a kwargs dict.

Parameters

  • fits – An open fitsio.FITS instance

  • extname – The extension to write to

  • kwargs – A kwargs dict to be written as a FITS binary table.