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 9, 2017 · 9 revisions

DESCRIPTION

Bindata is a utility designed to manipulate the .delay_dump files output by PYTHON in reverberation mode, convert them into sql databases, and process and output the results.

INPUTS

Bindata 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:

  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

TO CHANGE TO PYTHON

bindata -l 381 -lw 1550 -vel -v 1400 1600 -p 0 30 file_in -obs 3 -o file_out

Produces a transfer function in velocity-delay space for photons in spectrum 3 from file_in.delay_dump in the C-IV line, from 0-30 days, and writes it to file_out.eps. Will also produce an estimate of the virial mass from this line.

bindata -v 6000 7000 -rwp 1.5 -rwb 50 -r 1e14 1e16 -bl -s 1 1 -sc 0 0 -i file_in -r 1e14 1e16

Produce a transfer function in wavelength-delay space for all photons in spectrum 0 that have resonantly scattered once in the range 6000-7000 A, These photons are reweighted as if emitted from a disk with radius 1e14-1e16cm with emission proportional to r^(3/2), via 50 logarithmic bins. The transfer function delay range will cover 0 to (3.251e16C)/(seconds per day)

bindata -v 4200 4800 -xo -d 20 200 -obs 0 3 -p 0 5 -i file_in

Produce a centroid plot binned in 20 wavelength bins from 4200-4800 A, from 0-5 days, for observers 0,1,2 and 3. These will be output to files file_in.[0-3].eps.

TO DO

  • Convert -v to accept velocities in velocity mode?
  • Finish python rewrite
Clone this wiki locally