Skip to content
This repository has been archived by the owner on Mar 5, 2020. It is now read-only.

Home

Jump to bottom
smangham edited this page Aug 11, 2017 · 9 revisions

DESCRIPTION

Bindata is the project name for a library tfpy designed to manipulate the .delay_dump files output by PYTHON in reverberation mode, convert them into sql databases, and process them to produce transfer functions then output the results.

INPUTS

tfpy takes .delay_dump files. These files record every photon that contributes to each spectrum in the run, along with some data on its properties:

  1. Frequency (Hz)
  2. Wavelength (A)
  3. Weight
  4. Last scatter position (X, cm)
  5. Last scatter position (Y, cm)
  6. Last scatter position (Z, cm)
  7. Number of resonant and continuum scatters
  8. Number of resonant scatters
  9. Lag behind the continuum (days)
  10. ??? [may be removed]
  11. Spectrum
  12. Photon origin
  13. Last scattering line (-1 is continuum)

Bindata processes these files into SQL databases, and from there they can be queried by it at a much faster speed. When I have time, I'll make it output straight to SQL. This is a bit nontrivial as the only SQL version that doesn't require a server set up and usernames (SQLite) doesn't handle parallel writes to the same DB. I think I'd solve this by just writing to separate DB per thread, which is simple, but that still needs doing.

USAGE

Bindata is based around the library tfpy.py.

  1. Load a SQL database or .delay_dump file using open_database( s_file ), providing the root (no suffix of .db or .delay_dump). The function returns the database connection.

  2. Declare a TransferFunction using the following arguments:

  • database: The DB this will be run on.

  • filename: The filename root for plots (e.g. qso_100).

  • Declare the bining via either:

    • template: Pass an existing TF you want to use the same settings as.
      • template_different_line=True: If you want to use the same delay and velocity bins but change the wavelength bins & line
      • template_different_spectrum=True: If you want to use the same bins but change the observer they're for
    • delay_bins & wave_bins: Pass the number of bins you'd like.

  • continuum: Specify the continuum luminosity. The TF will calculate the reprocessing efficiency for this continuum.

  1. Call filters on the TransferFunction. These filters stack, e.g. tf.spectrum(1).delay_range(0,300):
  • spectrum( number ): The observer/spectrum to run on.
  • line( number, wavelength ): Constrain the TF to photons that last scattered off of this line. Uses the internal PYTHON line number, and takes the wavelength in angstroms. Required for velocity-based work
  • lines( line_list ): Constrain the TF to photons that last scattered off of one of the listed lines. Takes a Python list.
  • velocities( velocity ): Constrain the TF to photons with Doppler shifts of ±velocity. Requires a single line
  • wavelengths( wave_min, wave_max ): Constrain the TF to photons within the wavelength range.
  • wavelength_bins( wave_range ): Constrain the TF to this specific set of wavelength bins. Overrides wave_bins.
  • delays( delay_min, delay_max, unit='d' ): Constrain the TF to photons within the specific delay range. Takes value in days by default, seconds if unit='s'.
  • delay_dynamic_range( delay_dynamic_range ): Constrain the TF to this many orders of magnitude of luminosity. DDR=1 will return the delay range accounting for 90% of the luminosity, DDR=2 gives 99%, DDR=3 gives 99.9%.
  • cont_scatters/res_scatters( scat_min, scat_max=None ): Constrain the TF to this range of continuum or resonant scatters. If no maximum is provided, then constrain to exactly that many scatters.
  • filter( *args ): Apply a standard SQLalchemy filter to the data.
  1. After filters have been applied, run the TransferFunction with tf.run(). Optional arguments and their default values are:
  • scaling_factor=1.0: The number of spectral cycles run for the input. This should be done by Python really.
  • limit=None: The number of photons to limit the database pull to. Use a low value when testing if the code works.
  • verbose=False: Set to True to get detailed output on what filters are being applied.

  1. You now have an emissivity function for your specified filters. If you would like to build a response function, you need to create and run one (or two) more TransferFunction objects, using the first as a template argument, e.g. tf_min = TransferFunction(db090, 'tf090', template=tf_mid).run()

  2. Now, add a response function to the middle TF using response_map_by_tf( low_state, high_state ).

  3. You can now query your emissivity/response functions using the following commands (e.g. tf.FWHM()):

  • FWHM( response=False, velocity=True ): Returns the FWHM of a line in either the emissivity or response function, in either km/s or Angstroms.
  • delay( response=False, threshold=0, bounds=None ): Returns the centroid delay.
    • threshold: Ignore all delays less than threshold * peak response (typically 0.8 for response)
    • bounds=Value: Return a tuple containing the delay, and the upper and lower bounds on the centroid of that value (i.e. if 0.25, returns (50% quartile, 25% quartile, 75% quartile)).
  • transfer_function_1d( response=False, days=True ): Returns the 1d emissivity or response function in seconds or days
  • count/emissivity/response( delay=None, wave=None, delay_index=None ): Returns the count of photons or value of the emissivity or response function for:
    • delay=Value/delay_bin=Value, wave=Value: One bin in the TF at the given delay & wavelength. Can specify by delay value in seconds, or by bin.
    • delay=Value/delay_bin=Value, wave=None: All wavelength bins in the TF for the given delay, as specified by delay in seconds or by bin. Useful for adding to a spectrum.
  1. Now you can produce the actual emissivity/response function plots using tf.plot(), to output to filename.eps (for filename specified in the creation of the TF). Optional arguments are:
  • log=False: Whether or not to plot on a logarithmic scale
    • dynamic_range=None: How many orders of magnitude to plot on this scale
  • normalised=False: Whether or not to normalise the TF to 1.0
  • rescaled=False: Whether or not to rescale the TF to 0-1
  • velocity=False: Whether to plot wavelength or velocity on the X-axis. Requires line
  • name=None: Suffix to add to the TF filename e.g. name="log" gives "tf100_log.eps"
  • days=True: Whether to plot delay as seconds or days
  • response_map=False: Whether to plot emissivity or response
    • RMS=False: Whether to add RMS spectrum to the response spectrum panel
  • keplerian=None: Dict with settings for adding a keplerian disk outline to the figure. Keys are:
    • angle:Value: Angle of the spectrum the TF was produced for, in degrees
    • mass:Value: Mass of the AGN in M_sol
    • radius:[Min, Max]: Radii for the disk

EXAMPLES OF USE

Basic Emissivity Mapping

import tfpy
db = open_database("qso_c4_100")
tf = tfpy.TransferFunction(db, 'qso_c4', wave_bins=50, delay_bins=50).wavelength(1250, 1850).run()
print(tf.delay())

Tries to open a database file qso_c4_100.db, if it doesn't exist produces it from qso_c4_100.delay_dump. Generates a transfer function from this database, binning all photons in the wavelength range 1250-1850 angstroms in 50 wavelength and 50 delay bins. Then prints the centroid delay for this emissivity function.

Basic Response Mapping

import tfpy
db100 = open_database("qso_c4_100")
db090 = open_database("qso_c4_090")
db110 = open_database("qso_c4_110")

tf_mid = tfpy.TransferFunction(db100, 'qso100', continuum=1e45, wave_bins=50, delay_bins=50).line(481, 1500).spectrum(2).run(scaling_factor=20)
tf_min = tfpy.TransferFunction(db090, 'qso090', continuum=0.9e45, template=tf_mid).run(scaling_factor=20)
tf_max = tfpy.TransferFunction(db110, 'qso110', continuum=1.1e45, template=tf_mid).run(scaling_factor=20)

tf_mid.response_function_by_tf(tf_min, tf_max)
tf_mid.plot(velocity=True)
tf_mid.plot(velocity=True, response_map=True, name='resp')

Opens three database files- one each for baseline, high and low continuum states. Declares one transfer function on using the C-IV photons arriving at observer 2, from a run with 20 spectral cycles. Templates two more off of it, that use different input files and have different continuua but have identical bins, spectra and lines.

Once all 3 have been created and run, a response function is added to the baseline continuum TF (tf_mid) by using the other two emissivity functions. The baseline emissivity function is plotted to "qso100.eps" and the responsivity function is plotted to "qso100_resp.eps", both with velocity as their x-axis.

Advanced Emissivity Mapping

import tfpy
db = open_database("qso_100")

tf_c4 = tfpy.TransferFunction(db, 'qso_c4', continuum=1e45, wave_bins=50, delay_bins=50).line(481, 1500).spectrum(2).delay_dynamic_range(4).run(scaling_factor=20)
tf_ha = tfpy.TransferFunction(db, 'qso_ha', template=tf_c4, template_different_line=True).line(28, 6562).run(scaling_factor=20)

print(tf_c4.FWHM(), tf_ha.FWHM())

Opens a file, and creates two transfer functions- one each for C-IV and Hα. The delay range for the C-IV TF is set to encompass 99.99% of all photon weight in the file. The Hα TF is templated off the C-IV one, and will have the same delay and velocity bins.

Prints the FWHM of both the C-IV and Hα lines.

Clone this wiki locally