MatchedSources - EranOfek/AstroPack GitHub Wiki

Description

Class Hierarchy: Base -> Component -> MatchedSources

The MatchedSources class is a container for epoch-dependent measurements (e.g., RA, Dec, Mag as a function of time) for multiple sources. MatchedSources objects contain matrices for properties like X, Y, RA, Dec, Mag. Each matrix contains measurements for all the sources in all the epochs. By default, the first dimension of the matrix is for the epoch, and the second dimension is for the source. The MatchedSources object can be used to manipulate these data matrices, calibrate and create light curves.

The MatchedSources object is working with the AstroImage and AstroCatalog classes.

Properties

  • Data - A structure in which each field corresponds to a property (e.g., RA, Mag). Each field contains a matrix of Epoch X Src, containing the property measurments of all the sources over all the epochs. Non exitining measurments are filled with NaNs.
  • Units - A structure in which the field names are identical to those in the Data property, and contains the units of the specific property.
  • JD - A vector of JD per epoch. If not provided this will be a running index starting with 1.
  • SrcData - Like the Data property, but each field in the structure contains the average property (e.g., Mag) over all epochs. I.e, each field contains a vector with element per source.
  • FileName - The FileName from which the MatchedSources object was uploaded (if relevant).

Dependent Properties

  • Fields - Returning the field names in the Data property.
  • Nsrc - Return the number of sources in the matrices.
  • Nepoch - Return the number of epochs in the matrices. Constant Properties
  • DimEpoch - The dimension in the matrices in which the epochs are stored (1).
  • DimSrc - The dimension in the matrices in which the sources are stored (2).

More constant properties that contain synonyms for field names:

  • DefNamesX - Default is {'X','X_IMAGE','XWIN_IMAGE','X1','X_PEAK','XPEAK'};
  • DefNamesY Default is {'Y','Y_IMAGE','YWIN_IMAGE','Y1','Y_PEAK','YPEAK'};
  • DefNamesRA - Default is {'RA','ALPHA','ALPHAWIN_J2000','ALPHA_J2000','RA_J2000','RAJ2000','RightAsc'};
  • DefNamesDec - Default is {'Dec','DEC','DELTA','DELTAWIN_J2000','DELTA_J2000','DEC_J2000','DEJ2000','Declination'};
  • DefNamesErrRA - Default is {'RAERR','RA_ERR','ALPHAERR','ALPHA_ERR'};
  • DefNamesErrDec - Default is{'DecErr','DECERR','DEC_ERR','DELTAERR','DELTA_ERR'};
  • DefNamesMag - Default is {'Mag','PSF_MAG','MAG_PSF','Mag_BP','Mag_G','Mag_RP','MAG_CONV_2'};

Methods

Static methods

  • read - Read mat file or HDF5 file containing MatchedSources
  • read_rdir - Read all MatchedSources files in a dir tree into a MatchedSources object.
  • designMatrixCalib - Generate the design matrix for relative photometric calibration

Methods

Methods for writing the content of MatchedSources object to file

  • write1 - Write a MatchedSources object to HDF5 or mat file

Another useful function that can write MatchedSources object to a file name defined by the FileNames object is imProc.io.writeProduct

Methods for populating, and reading matrices from/to the object:

  • addMatrix - Add matrix/struct/matched AstroTable into the MatchedSources Data
  • getMatrix - Get matrix using the field name
  • getUnits - Return the units for a matrix name.
  • deleteMatrix - remove matrix and field name from a MatchedSources object
  • addSrcData - Populate/calculate the SrcData structure
  • addAirMassPA - Add Airmass, Parallactic angle, Az, Alt to MatchedSources.
  • addExtMagColor - Add magnitude/color from an external catalog into a MatchedSources object.

Convert a matched AstroCatalog to a MatchedSources object:

  • unifiedCatalogsIntoMatched - Unify and matched AstroCatalog objects into a MatchedSources object.

Summary and statistics of MatchedSources data:

  • Summary - Summary of a specific field matrix in MatchedSources.
  • notNanSources - Return a vector of logicals indicating sources which do have any NaNs in the data.
  • notNanEpochs - Return a vector of logicals indicating epochs that do have any NaNs in their data.
  • statSummary - Calculate statistical summary properties of a data property in a MatchedSources object.
  • combineFlags - Combine (bitwise or) the flags of each source over all epochs
  • searchFlags - Search specific flags in MatchedSources matrix. Return a matrix of logical indicating if the specific flags are present in each entry.
  • countFlags - Count specific flags per source or per epoch.

Find a field name using a dictionary:

  • getFieldNameDic -Get field name in MatchedSources Data properties that first appear in a dictionary (cell array).
  • getFieldNameSearch - Search for MatchedSources field names that contain a substring.
  • getLonLat - Get data matrices containing the RA/Dec fields.

Soring the data:

  • applySortInd - Reorder all sources according to a vector of indices (e.g., sort)
  • sortData - Sort (source-wise) all the Data and SrcData fields by some of the Data fields.

Merge multiple elements MatchedSoources object:

  • mergeByCoo - Merge MatchedSources objects by coordinates.

  • designMatrix - Generate a general-purpose design matrix from a MatchedSources object

Time Related functions:

  • juldayFun - Apply function to JD column pf each MatchedSources element.

Photometric zero points and light curves

  • applyZP - Apply zero point and optional color term to MatchedSources matrices.
  • binning - Bin MatchedSources Data, JD, SrcData entries.
  • psd - Estimate the mean power spectral density of all the sources.
  • rmsMag - Calculate rms of some parameter as a function of magnitude.
  • plotRMS - plot rms of a property (field) vs. its mean.
  • getLC_ind - get the LC [JD, Mag] of a source by its index (column number)

Search utilities:

  • coneSearch - search sources in MatchedSource object by RA/Dec
  • epochCooSearch - Search for epoch-dependent coordinates in MatchedSources object.

Examples

In the following example, load MatchedSources objects stored as hdf5 files. These files were generated by the LAST pipeline using imProc.io.writeProduct function.

% load LAST MatchedSources files stored in hdf5 files:
% The following command will read ALL the MergedMat files under the current
% directory and matching a certain FileTemplate. Note all these files should belong to a single field:

L = MatchedSources.rdirMatchedSourcesSearch('FileTemplate','*_sci_merged_MergedMat_*.hdf5');
MS = MatchedSources.readList(L);

This will generate an array of MatchedSOurces object in which different columns represents different CropID (i.e., sub images).

Alternatively you can specify the CropID:

L = MatchedSources.rdirMatchedSourcesSearch('FileTemplate','*_sci_merged_MergedMat_*.hdf5','CropID',[15]);
MS = MatchedSources.readList(L);

Next, you can merge all the sources in each sub image (CropID) by coordinates. In the following example the first entry MS(1,1) is used as a reference:

MS1=MS(:,1).mergeByCoo(MS(1,1));

You can use the plotRMS function to plot the rms vs. magnitude plot:

MS(1,1).plotRMS
% or:
MS(1,1).plotRMS('FieldX','MAG_APER_3')

If you will plot the rms vs. magnitude for the merged by coordinates results (in the above example this is stored in MS1):

MS1.plotRMS

you will likely get results with a higher scatter. The reason for this is that the data was not detrended.

There are several options to detrend the data. For example, a simple detrending based on adding a zero point to each epoch using the median differences method:

R = lcUtil.zp_meddiff(MS1,'MagField','MAG_APER_3','MagErrField','MAGERR_APER_3');

You can apply the zero points to each epoch using:

MS1.applyZP(R.FitZP);

The MatchedSources SrcData property may contain the average measurements per source, over all epochs. You can populate this property using:

MS1.addSrcData

You can apply sysrem detrending to the data:

MS1.sysrem;