flystar.analysis
================

.. py:module:: flystar.analysis


Functions
---------

.. autoapisummary::

   flystar.analysis.query_gaia
   flystar.analysis.prepare_gaia_for_flystar
   flystar.analysis.run_flystar
   flystar.analysis.project_gaia
   flystar.analysis.rename_after_flystar
   flystar.analysis.pick_good_ref_stars
   flystar.analysis.startable_subset
   flystar.analysis.calc_chi2
   flystar.analysis.calc_nparam
   flystar.analysis.calc_F


Module Contents
---------------

.. py:function:: query_gaia(ra, dec, search_radius=30.0, table_name='gaiadr2')

   Query the Gaia database at the specified location
   and with the specified search radius

   Input
   ----------
   ra : string
       R.A. in hours in the format such as '17:45:40.3'

   dec : string
       Dec. in degrees in the format such as '-29:00:28.0'

   search_radius : float
       The search radius in arcseconds. 

   Optional Input
   --------------
   table_name : string
       Options are 'gaiadr2' or 'gaiaedr3'


.. py:function:: prepare_gaia_for_flystar(gaia, ra, dec, targets_dict=None, match_dr_max=0.2)

   Take a Gaia table (from astroquery) and produce a new table with a tangential projection
   and shift such that the origin is centered on the target of interest. 
   Convert everything into arcseconds and name columns such that they are 
   ready for FlyStar input.

   Inputs
   ------------
   gaia : astropy table
       Gaia Catalog from query_gaia()

   ra : float
       Units = hourangle

   dec : float
       Units = degree


.. py:function:: run_flystar()

.. py:function:: project_gaia(gaia, epoch, ra, dec)

   Take the Gaia measurements, forward them in time, and then convert them into a tangential projection.

   Inputs
   ----------
   epoch : float (year)
       The decimal year to project the measurement to. Note that we use 365.25 days per year.
       
   ra : float (deg)
       The right ascension (J2000) in decimal degrees of the center of the field.
       
   dec : float (deg)
       The declination (J2000) in decimal degrees of the center of the field.
       


.. py:function:: rename_after_flystar(star_tab, label_dat_file, new_copy=True, dr_tol=0.05, dm_tol=0.3, verbose=False)

   Take a StarTable output from FlyStar MosaicToRef that has been 
   aligned into R.A. and Dec. (usually by way of Gaia). Align
   the output to a label.dat file for this source and rename
   everything.


.. py:function:: pick_good_ref_stars(star_tab, r_cut=None, m_cut=None, p_err_cut=None, pm_err_cut=None, name_cut=None, reset=True)

   Set the 'use_in_trans' flag according to a set of cuts.


.. py:function:: startable_subset(tab, idx, mag_trans=True, mag_trans_orig=False)

   Input is MosaicToRef table from alignment of multiple filters, 
   such that the astrometry is combined but the photometry is not.
   This function is used to separate out a selected filter from the 
   combined astrometry + uncombined photometry table.


.. py:function:: calc_chi2(ref_mat, starlist_mat, transform, errs='both')

   calculate the chi2 and reduced chi2 of the position 
   between two matched starlists.
   Input:
   ref_mat: astropy table
       Reference starlist only containing matched stars that were used in the
       transformation. Standard column headers are assumed.
       
   starlist_mat: astropy table
       Transformed starlist only containing the matched stars used in
       the transformation. Standard column headers are assumed.

   transform: transformation object
       Transformation object of final transform. Used in chi-square
       determination

   errs: string; 'both', 'reference', or 'starlist'
       If both, add starlist errors in quadrature with reference errors.

       If reference, only consider reference errors. This should be used if the starlist
       does not have valid errors

       If starlist, only consider starlist errors. This should be used if the reference
       does not have valid errors

   Output:
   chi_sq: float
       chi2 = sum (diff_x**2 / xerr**2 + diff_y**2 /yerr**2)
   chi_sq_red: float
       reduced chi2 = chi2/ degree of freedom
   deg_freedom: int
       degree of freedom



.. py:function:: calc_nparam(transformation)

   calculate the degree of freedom for a transformation


.. py:function:: calc_F(red_chi2_1, red_chi2_2, v1, v2)

   compare two different models to get the proper polynomial fitting order

   Input:
   red_chi2_1: reduced chi2 for the first model
   red_chi2_2: reduced chi2 for the second model
   v1 = degree of freedom for the first model
      = 2*(N_star_matched) - model_parameters
   v2 = degree of freedom for the second mdoel

   Output:
   P: The probability that the first model is better

   Example:
   for 1st order polynomial fitting:
       x' = a0 + a1*x + a2*y
       y' = b0 + b1*x + b2*y
       v1 = 2*N1 - 2*3 (2*: because x and y direction) 
       red_chi2_1 = chi2/v1
   for 2nd order polynomial fitting:
       x' = a0 + a1*x + a2*y + a3*x**2 + a4*y**2 + a5*x*y
       y' = b0 + b1*x + b2*y + b3*x**2 + b4*y**2 + b5*x*y
       v1 = 2*N1 - 2*6 
       red_chi2_2 = chi2/v2
   calc_F(red_chi2_1, red_chi2_2, v1, v2)

   ***Note***
   * make sure the first model is the simple model 
     and the second model is the more complicated model
   * the return value represents the probability that 
     the first model is better than the second model, in other words,
     the small P means the more colicated model is needed.
     the large P means the simple model is good enough.
   * normally, the P value will increase from model1->model2, to 
     model2->model3, to model3->model4. The user can decide a 
     critical value (eg, 0.7) to find the proper model.