flystar.transforms ================== .. py:module:: flystar.transforms Classes ------- .. autoapisummary:: flystar.transforms.Transform2D flystar.transforms.four_paramNW flystar.transforms.PolyTransform flystar.transforms.Shift flystar.transforms.LegTransform flystar.transforms.PolyClipTransform flystar.transforms.LegClipTransform flystar.transforms.PolyClipSplineTransform flystar.transforms.LegClipSplineTransform flystar.transforms.SplineTransform Functions --------- .. autoapisummary:: flystar.transforms.make_param_dict flystar.transforms.four_param Module Contents --------------- .. py:class:: Transform2D Bases: :py:obj:`object` Base class for transformations. It contains the properties common to all transformation objects. .. py:method:: from_file(filename) :classmethod: Initialize a Transform2D object (or a specified sub-class) from a file containing the transformation coefficients. .. py:method:: evaluate(x, y) .. py:method:: evaluate_error(x, y, xe, ye) .. py:method:: evaluate_mag(m) .. py:method:: evaluate_magerror(m, me) .. py:method:: evaluate_starlist(star_list) .. py:method:: evaluate_MC_errors(x, x_err, y, y_err, nsim=500) Run a MC simulation to figure out what the uncertainty from the transformation should be. Parameters: ----------- x, x_err, y, y_err - x,y position and their uncertainties Keywords: --------- nsim - number of simulations to run (default: 1000) Outputs: -------- x_trans, x_trans_err, y_trans, y_trans_err .. py:class:: four_paramNW(x, y, xref, yref, order=None, weights=None) Bases: :py:obj:`Transform2D` defines parameter tranformation between x,y and xref, yref does not weight the points .. py:attribute:: order :value: None .. py:method:: evaluate(x, y) .. py:method:: evaluate_error(x, y) Transform positional uncertainties. Parameters: ---------- x : numpy array The original x coordinates to be used in the transformation. y : numpy array The original y coordinates to be used in the transformation. xe : numpy array The raw x errors to be transformed. ye : numpy array The raw y errors to be transformed. Returns: ---------- xe' : array The transformed x errors. ye' : array The transformed y errors. .. py:class:: PolyTransform(order, px, py, pxerr=None, pyerr=None, mag_offset=0.0) Bases: :py:obj:`Transform2D` Defines a 2D affine polynomial transform between x, y -> xref, yref The tranformation is independent for x and y and has the form (for 2nd order fit): x' = a0 + a1*x + a2*y. + a3*x**2 + a4*x*y. + a5*y**2 y' = b0 + b1*x + b2*y. + b3*x**2 + b4*x*y. + b5*y**2 Note that a 0th order polynomial is x' = a0 y' = b0 .. py:attribute:: order .. py:attribute:: poly_order .. py:attribute:: pxerr :value: None .. py:attribute:: pyerr :value: None .. py:attribute:: mag_offset :value: 0.0 .. py:method:: make_param_dict(initial_param, order, isY=False) :staticmethod: Convert initial parameter arrays into a format that astropy model Polynomial2D can understand. We expect input arrays in the form: a0 + a1*x + a2*y + a3*x^2 + a4*x*y + a5*y^2 + a6*x^3 + a7*x^2*y + a8*x*y^2 + a9*y^3 and conver this into a dictionary where: c0_0 = a0 c1_0 = a1 c0_1 = a2 c2_0 = a3 c1_1 = a4 c0_2 = a5 c3_0 = a6 c2_1 = a7 c1_2 = a8 c0_3 = a9 The input/output ordering is set for easy coding using: for i in range(self.order + 1): for j in range(i + 1): coeff[i-j, j] for term x**(i-j) * y**(j) But astropy models Polynomial2D has its own special order... we try to hide this entirely inside our object. .. py:method:: evaluate(x, y) Apply the transformation to a starlist. Parameters: ---------- x : numpy array The raw x coordinates to be transformed. y : numpy array The raw y coordinates to be transformed. Returns: ---------- x' : array The transformed x coordinates. y' : array The transformed y coordinates. .. py:method:: evaluate_error(x, y, xe, ye) Transform positional uncertainties. Parameters: ---------- x : numpy array The original x coordinates to be used in the transformation. y : numpy array The original y coordinates to be used in the transformation. xe : numpy array The raw x errors to be transformed. ye : numpy array The raw y errors to be transformed. Returns: ---------- xe' : array The transformed x errors. ye' : array The transformed y errors. .. py:method:: evaluate_vel(x, y, vx, vy) Transform velocities. Parameters: ---------- x : numpy array The original x coordinates to be used in the transformation. y : numpy array The original y coordinates to be used in the transformation. vx : numpy array The raw vx to be transformed. vy : numpy array The raw vy to be transformed. Returns: ---------- vx' : array The transformed vx errors. vy' : array The transformed vy errors. .. py:method:: evaluate_vel_err(x, y, vx, vy, xe, ye, vxe, vye) Transform velocities. Parameters: ---------- x : numpy array The original x coordinates to be used in the transformation. y : numpy array The original y coordinates to be used in the transformation. vx : numpy array The raw vx to be transformed. vy : numpy array The raw vy to be transformed. xe : numpy array The original x coordinates to be used in the transformation. ye : numpy array The original y coordinates to be used in the transformation. vxe : numpy array The raw vx to be transformed. vye : numpy array The raw vy to be transformed. Returns: ---------- vxe' : array The transformed vx errors. vye' : array The transformed vy errors. .. py:method:: derive_transform(x, y, xref, yref, order, m=None, mref=None, init_gx=None, init_gy=None, weights=None, mag_trans=True) :classmethod: .. py:method:: from_file(trans_file) :classmethod: Given a transformation coefficients file, read in the coefficients and create a PolyTransform object. Coefficients in the input file should have the following order: x' = a0 + a1*x + a2*y + a3*x**2. + a4*x*y + a5*y**2. + ... y' = b0 + b1*x + b2*y + b3*x**2. + b4*x*y + b5*y**2. + ... Parameters: ---------- trans_file : str The name of the input file to read in. Returns: ---------- trans_obj: PolyTransform A transformation object instance. .. py:method:: to_file(trans_file) Given a transformation object, write out the coefficients in a text file (readable by java align). Outfile name is specified by user. Coefficients are output in file in the following way: x' = a0 + a1*x + a2*y + a3*x**2. + a4*x*y + a5*y**2. + ... y' = b0 + b1*x + b2*y + b3*x**2. + b4*x*y + b5*y**2. + ... Parameters: ---------- trans_file : str The name of the output file to save the coefficients and meta data to. This file can be read back in with trans_obj = PolyTransfrom.from_file(trans_file). .. py:class:: Shift(xshift, yshift, xshift_err=None, yshift_err=None) Bases: :py:obj:`PolyTransform` Defines shift tranformation between x,y and xref, yref Does not weight the points. .. py:attribute:: px .. py:attribute:: py .. py:attribute:: pxerr .. py:attribute:: pyerr .. py:attribute:: order :value: 0 .. py:method:: derive_transform(x, y, xref, yref, order=0, m=None, mref=None, weights=None, **kwargs) :classmethod: .. py:method:: evaluate_error(x, y, xe, ye) Transform positional uncertainties. Parameters: ---------- x : numpy array The original x coordinates to be used in the transformation. y : numpy array The original y coordinates to be used in the transformation. xe : numpy array The raw x errors to be transformed. ye : numpy array The raw y errors to be transformed. Returns: ---------- xe' : array The transformed x errors. ye' : array The transformed y errors. .. py:method:: evaluate_vel(x, y, vx, vy) Evaluate positions and velocities. Errors are only propogated IF all 4 errors (position and velocity) are input. .. py:method:: evaluate_vel_error(x, y, vx, vy, xe, ye, vxe, vye) Evaluate positions and velocities. Errors are only propogated IF all 4 errors (position and velocity) are input. .. py:class:: LegTransform(order, px, py, x_domain, y_domain, pxerr=None, pyerr=None, mag_offset=0.0, astropy_order=False) Bases: :py:obj:`Transform2D` Base class for transformations. It contains the properties common to all transformation objects. .. py:attribute:: px .. py:attribute:: py .. py:attribute:: order .. py:attribute:: pxerr :value: None .. py:attribute:: pyerr :value: None .. py:attribute:: mag_offset :value: 0.0 .. py:attribute:: x_domain .. py:attribute:: y_domain .. py:method:: derive_transform(x, y, xref, yref, order, m=None, mref=None, init_gx=None, init_gy=None, weights=None, mag_trans=True) :classmethod: Defines a bivariate legendre tranformation from x,y -> xref,yref using Legnedre polynomials as the basis. Transforms are independent for x and y and of the form: x' = c0_0 + c1_0 * L_1(x) + c0_1*L_1(y) + .... y' = d0_0 + d1_0 * L_1(x) + d0_1*L_1(y) + .... Note that all input coordinates will be renomalized to be on the interval of [-1:1] before fitting. The evaulate function must use the same renormalization procedure. .. py:method:: make_param_dict(initial_param, order, isY=False) :staticmethod: Convert initial parameter arrays into a format that astropy model Legendre2D can understand. We expect input arrays in the form: x' = c0_0 + c1_0 * L_1(x) + c0_1*L_1(y) + c1_1*L_1(x)*L_1(y) + .... y' = d0_0 + d1_0 * L_1(x) + d0_1*L_1(y) + d1_1*L_1(x)*L_1(y) +.... and convert this into a dictionary where: 0th order: c0_0 = a0 1st order: c0_1 = a1 c1_0 = a2 c1_1 = a3 2nd order: c0_2 = a4 c1_2 = a5 c2_0 = a6 c2_1 = a7 c2_2 = a8 3rd order: c0_3 = a9 c1_3 = a10 c2_3 = a11 c3_0 = a12 c3_1 = a13 c3_2 = a14 c3_3 = a15 Astropy models Polynomial2D has its own special order... we try to hide this entirely inside our object. .. py:method:: convert_domain_to_scale_offset() .. py:method:: poly_unmap_domain(x_cond, y_cond) Take conditioned data and put it back into the original domain. Recall that we always use a window of [-1, 1] so x_cond and y_cond should typically be within these bounds. The returned values will be within the domain specified in x_domain and y_domain at the time of object creation. .. py:method:: poly_map_domain(x, y) Map domain into window by shifting and scaling. The input values should be within the domain specified in x_domain and y_domain at the time of object creation. Recall that we always use a window of [-1, 1] so the returned x_cond and y_cond will typically be within these bounds. .. py:method:: poly_unmap_err_domain(xe_cond, ye_cond) Take conditioned error or velocity data and put it back into the original domain. Recall that we always use a window of [-1, 1] so x_cond and y_cond should typically be within these bounds. The returned values will be within the domain specified in x_domain and y_domain at the time of object creation. .. py:method:: poly_map_err_domain(xe, ye) Take conditioned error or velocity data in the original domain and map it onto a [-1, 1] fit window. Map domain into window by shifting and scaling. The input values should be within the domain specified in x_domain and y_domain at the time of object creation. Recall that we always use a window of [-1, 1] so the returned x_cond and y_cond will typically be within these bounds. .. py:method:: evaluate(x, y) Apply the transformation to a starlist. Parameters: ---------- x : numpy array The raw x coordinates to be transformed. y : numpy array The raw y coordinates to be transformed. Returns: ---------- x' : array The transformed x coordinates. y' : array The transformed y coordinates. .. py:method:: evaluate_error(x, y, xe, ye) Transform positional uncertainties. Parameters: ---------- x : numpy array The original x coordinates to be used in the transformation. y : numpy array The original y coordinates to be used in the transformation. xe : numpy array The raw x errors to be transformed. ye : numpy array The raw y errors to be transformed. Returns: ---------- xe' : array The transformed x errors. ye' : array The transformed y errors. .. py:method:: evaluate_vel(x, y, vx, vy) Transform velocities. Parameters: ---------- x : numpy array The original x coordinates to be used in the transformation. y : numpy array The original y coordinates to be used in the transformation. vx : numpy array The raw vx to be transformed. vy : numpy array The raw vy to be transformed. Returns: ---------- vx' : array The transformed vx errors. vy' : array The transformed vy errors. .. py:method:: evaluate_vel_err(x, y, vx, vy, xe, ye, vxe, vye) Transform velocities. Parameters: ---------- x : numpy array The original x coordinates to be used in the transformation. y : numpy array The original y coordinates to be used in the transformation. vx : numpy array The raw vx to be transformed. vy : numpy array The raw vy to be transformed. xe : numpy array The original x coordinates to be used in the transformation. ye : numpy array The original y coordinates to be used in the transformation. vxe : numpy array The raw vx to be transformed. vye : numpy array The raw vy to be transformed. Returns: ---------- vxe' : array The transformed vx errors. vye' : array The transformed vy errors. .. py:class:: PolyClipTransform(x, y, xref, yref, degree, niter=3, sig_clip=3, weights=None) Bases: :py:obj:`Transform2D` Base class for transformations. It contains the properties common to all transformation objects. .. py:attribute:: s_bool .. py:attribute:: t .. py:method:: evaluate(x, y) .. py:class:: LegClipTransform(x, y, xref, yref, degree, niter=3, sig_clip=3, weights=None) Bases: :py:obj:`Transform2D` Base class for transformations. It contains the properties common to all transformation objects. .. py:attribute:: s_bool .. py:attribute:: t .. py:method:: evaluate(x, y) .. py:class:: PolyClipSplineTransform(x, y, xref, yref, degree, weights=None, niter=0, sigma=3, kx=None, ky=None) Bases: :py:obj:`Transform2D` Performs polynomail fit, then a spline fit on the residual optionally performs signma clipping, if niter > 0 (default is zero) .. py:attribute:: poly .. py:attribute:: spline .. py:method:: evaluate(x, y) .. py:class:: LegClipSplineTransform(x, y, xref, yref, degree, weights=None, kx=None, ky=None, niter=0, sigma=3) Performas a Legendre fit, then fits the residual with a spline can optinall y perform sigma clipping in the legendre step, by setting niter as > 0 (default to zero) .. py:attribute:: leg .. py:attribute:: spline .. py:method:: evaluate(x, y) .. py:class:: SplineTransform(x, y, xref, yref, weights=None, kx=None, ky=None) Bases: :py:obj:`Transform2D` Base class for transformations. It contains the properties common to all transformation objects. .. py:attribute:: spline_x .. py:attribute:: spline_y .. py:method:: evaluate(x, y) .. py:function:: make_param_dict(initial_param) Convert an array of initial guesses .. py:function:: four_param(x, y, x_ref, y_ref) calulates the 4 parameter tranfrom between the inputs does not weight the fit returns two vecotors, with correct fromat to be the intitial guesses want to solve for four parameters equations x' = a0 + a1*x + a2 * y y' = b0 + -a2 * x + a1 * y Add in matrix notation of exactly what is going in here x'_0 x_0 y_0 1 0 a1 y'_0 y_0 -x_0 0 1 a2 x'_1 x_1 y_1 1 0 * a0 y'_1 = y_1 x_1 0 1 b0 Above is the first 4 line of the matrix equation, the LHS and matrix with the coordiantes set the pattern that contines through te entire list of coordinates To solve, I take the psuedo inverse of the coordinate matrix, and then take the dot product of coo_mat^-1 * LHS to give the tranformation coefficients As a final step, I recalucate the translation terms based on fixed value of a1 and a2, as the translatoin term is prone to numerical error