B d@sdZddlmZyddlmZWnek r<edZYnXddlZddlZddl Z ddl Z ddl Z ddl m Z ddlZddlmZmZddlZddlmZdd lmZdd lmZdd lmZddlZd d lmZdZd dlm Z!d dlm"Z#ddZ$Gddde%Z&Gddde%Z'Gddde%Z(Gddde%Z)Gddde%Z*Gddde%Z+Gdd d e%Z,Gd!d"d"e%Z-Gd#d$d$e%Z.dS)%z+ Generic time interval coincidence engine. ) bisect_left)NegInfz-infN)spatial)ChainMapCounter)ligolw) lsctables)coincs)segments) offsetvectorz"Kipp Cannon )date)versioncCs0tj|jtj|j}t||tjS)a Compute and return the time required for light to travel through free space the distance separating the two instruments. The inputs are two instrument prefixes (e.g., "H1"), and the result is returned in seconds. Note how this differs from LAL's XLALLightTravelTime() function, which takes two detector objects as input, and returns the time truncated to integer nanoseconds. )lalZcached_detector_by_prefixlocationmathsqrtsumC_SI)Z instrument1Z instrument2Zdxr_/work/yifan.wang/ringdown/master-ringdown-env/lib/python3.7/site-packages/lalburst/snglcoinc.pylight_travel_timeHs rc@sTeZdZdZeddZddZddZedd Z ed d Z d d Z ddZ dS) singlesqueuea Queue a stream of partially time ordered events: as new events are added, sort them into the queue in time order; maintain a record of the time up-to which the list of events is complete; and provide events sorted in time order to coincidence tests. Searches must define a class subclassed from this that defines an override of the .event_time() method. See coincgen_doubles for information on what to do with the subclass. Implementation notes: What is actually inserted into the queue is the time of the event as defined by the .event_time() method provided by the subclass. This allows sorts and bisection searches to be performed quickly, without the need for much additional code. When we need to retrieve an event, we need some way of turning the time of the event (i.e., the thing that is actually in the queue) back into that event, and this is done by adding an attribute to the time object that points back to the original event. This means that builtin Python numeric types cannot be used for the times of the events because new attributes cannot be attached to them. Subclasses of the builtin numeric types can be used as time objects, as can be LAL's LIGOTimeGPS. cCstdS)a7 Override with a method to return the "time" of the given event. The "time" object that is returned is typically a lal.LIGOTimeGPS object. If some other type is used, it must support arithmetic and comparison with python float objects and lal.LIGOTimeGPS objects, and support comparison with ligo.segments.PosInfinity and ligo.segments.NegInfinity, and it must have a .__dict__ or other mechanism allowing an additional attribute named .event to be set on the object. The builtin float type is not suitable, but a subclass of float would be. N)NotImplementedError)eventrrr event_timemszsinglesqueue.event_timecCs||}||_|S)zd For internal use. Construct the object that is to be inserted into the queue from an event. )rr)selfrentryrrrqueueentry_from_event}s z"singlesqueue.queueentry_from_eventcCs8||_|dkrtd|||_tj|_g|_i|_dS)a Initialize a new, empty, singles queue. offset is the time that will be added to events in this queue when forming coincidences with events from other queues, and max_coinc_window is an upper bound on the maximum time that can separate events in this queue from events in other queues and they still be able to form coincidences --- it is not that maximum time, necessarily, but the true maximum time cannot be larger than max_coinc_window. Note that max_coinc_window is not defining the coincidence test, that is defined by the get_coincs machinery within the coincgen_doubles class. max_coinc_window is used by the streaming logic to determine where in the event sequences complete n-tuple candidates can be constructed. Although max_coinc_window need only bound the time interval described above, the latency of the coincidence engine is reduced and the number of events stored in the queue (and the computational overhead they cause) is reduced if the number is as small as possible. gzmax_coinc_window < 0 (%g)N)offset ValueErrormax_coinc_windowr NegInfinity t_completequeueindex)rrr!rrr__init__s zsinglesqueue.__init__cCs|jr|jdS|jS)a Using .event_time() to define the times of events, the time of the oldest event in the queue or self.t_complete if the queue is empty. The time scale for .age is that of the events themselves, not their shifted times (the offset parameter is not applied). This is not used by the coincidence engine. This information is provided as a convenience for calling code. For example, some performance improvements might be realized if segment lists or other information are clipped to the range of times spanned by the contents of the coincidence engine queues, and this allows calling codes to see what interval that is, in physical event times not time-shifted event times. r)r$r#)rrrrageszsinglesqueue.agecCs|j|j|jS)a The time up to which the time-shifted events in other detectors' queues can be considered complete for the purpose of forming n-tuple coincidences with the time-shifted events in this queue. This precedes the (time-shifted) time up to which this event list is complete by the maximum coincidence window that can separate an event in this queue from events in others and they still be considered coincident in time. The earliest such time across all detectors is the time up to which the n-tuple candidate list can be completely constructed, assuming the "time" of an n-tuple candidate is defined to be the earliest time-shifted time of the events in the n-tuple. )r#rr!)rrrrt_coinc_completeszsinglesqueue.t_coinc_completecCs^||jkrtd|j|f|rT|jdd|D|jt|j||j||_dS)a Add new events to the queue. Mark the queue complete up to t_complete, meaning you promise no further events will be added to the queue earlier than t_complete. The time scale for t_complete is that of the events themselves, not their shifted times (the offset parameter is not applied). NOTE: the events sequence will be iterated over multiple times. It may not be a generator. z6t_complete has gone backwards: last was %s, new is %scss|]}t||fVqdS)N)id).0rrrr sz$singlesqueue.push..N) r#r r%updater$extendmaprsort)reventsr#rrrpushs  zsinglesqueue.pushc Cs|dkr>tdd|jD}|jdd=|jtj|_|S||j8}||j|jkrxt d||j|j|j|jft |j||j}tdd|jd|D}|jd|=x|D]}|j t |qW|tdd|jdt |j||jDS)a t is the time up to which the calling code is in the process of constructing all available n-tuple coincident candidates. The return value is a tuple of all events from the queue whose time-shifted end times are up to (not including) t + max_coinc_window, which are all the events from this queue that could form a coincidence with an event up to (not including) t. t is defined with respect to the time-shifted event times. The contents of the returned tuple is time-ordered as defined by .event_time(). Assuming that t cannot go backwards, any of the reported events that cannot be used again are removed from the internal queue. If t is None, then the queue is completely flushed. All remaining events are pulled from the queue and reported in the tuple, .t_complete is reset to -inf and all other internal state is reset. After calling .pull() with t = None, the object's state is equivalent to its initial state and it is ready to process a new stream of events. Ncss|] }|jVqdS)N)r)r*rrrrr+sz$singlesqueue.pull..zfpull to %g fails to precede time to which queue is complete, (%g + %g), by the required margin of %g scss|] }|jVqdS)N)r)r*rrrrr+)scss|] }|jVqdS)N)r)r*rrrrr+1s) tupler$r%clearr r"r#rr!r rpopr))rtr0iZflushed_eventsrrrrpulls      zsinglesqueue.pullN) __name__ __module__ __qualname____doc__ staticmethodrrr&propertyr'r(r1r7rrrrrSs  -  rc@sheZdZdZeZGdddeZddZeddZ edd Z ed d Z d d Z ddZ ddZdS)coincgen_doublesa Using a pair of singlesqueue objects, constructs pairs of coincident events from streams of partially time-ordered events. Searches must subclass this. The .singlesqueue class attribute must be set to the search-specific singlesqueue implementation to be used, i.e., a subclass of singlesqueue with an appropriate .event_time() override. The internally-defined .get_coincs class must be overridden with an implementation that provides the required .__init__() and .__call__() methods. c@s eZdZdZddZddZdS)zcoincgen_doubles.get_coincsa This class defines the coincidence test. An instance is initialized with a sequence of events, and is a callable object. When the instance is called with a single event from some other instrument, a time offset to apply to that event (relative to the events in this list) and a time coincidence window, the return value must be a (possibly empty) sequence of the initial events that are coincident with that given event. The sequence of events with which the instance is initialized is passed in time order. It is not required that the implementation be subclassed from this. This placeholder implementation is merely provided to document the required interface. A minimal example: class get_coincs(object): def __init__(self, events): self.events = events def __call__(self, event_a, offset_a, coinc_window): return [event_b for event_b in self.events if abs(event_a.time + offset_a - event_b.time) < coinc_window] This is performance-critical code and a naive implementation such as the one above will likely be found to be inadequate. Expect to implement this code in C for best results. cCstdS)a  Prepare to search a collection of events for coincidences with other single events. events is a time-ordered iterable of events. It is recommended that any additional indexing required to improve search performance be performed in this method. N)r)rr0rrrr&fsz$coincgen_doubles.get_coincs.__init__cCstdS)aV Return a sequence of the events from those passed to .__init__() that are coincident with event_a. The sequence need not be in time order. The object returned by this method must be iterable and support being passed to bool() to test if it is empty. offset_a is the time shift to be added to the time of event_a before comparing to the times of events passed to .__init__(). This behaviour is to support the construction of time shifted coincidences. coinc_window is the maximum time, in seconds, separating coincident events from the shifted time of event_a. Here, this is the interval that defines the coincidence test between the two detectors, not the bound on all such intervals used by the singlesqueue object to determine the interval for which n-tuple candidates can be constructed. N)r)rZevent_aoffset_a coinc_windowrrr__call__psz$coincgen_doubles.get_coincs.__call__N)r8r9r:r;r&rArrrr get_coincsEs rBcst|dkrtdt||t|_jdkr@tdtt|dkr`tdtfdd|D_t ddjD_ d S) a offset_vector must be a two-instrument offset vector. This sets which two instruments' events are to be processed by this object, and the offsets that should be applied to their events when searching for coincidences. coinc_windows is a dictionary mapping pairs of instruments (as sets) to the largest time that can separate events from those pairs of instruments (after applying the required time offsets) and they still be considered coincident. z6offset_vector must name exactly 2 instruments (got %d)gzcoinc_window < 0 (%g)zmax(coinc_window) < 0 (%g)c3s"|]\}}||fVqdS)N)r)r* instrumentr)r!rrrr+sz,coincgen_doubles.__init__..css|] }|jVqdS)N)r%)r*r$rrrr+sN) lenr frozensetr@maxvaluesdictitemsqueuesrr%)r offset_vector coinc_windowsr)r!rrr&s     zcoincgen_doubles.__init__cCstdd|jDS)Ncss|]\}}||jfVqdS)N)r)r*rDr$rrrr+sz1coincgen_doubles.offset_vector..)rIrKrJ)rrrrrLszcoincgen_doubles.offset_vectorcCstdd|jDS)z0 The earliest of the internal queues' .age. css|] }|jVqdS)N)r')r*r$rrrr+sz'coincgen_doubles.age..)minrKrH)rrrrr'szcoincgen_doubles.agecCstdd|jDS)z= The earliest of the internal queues' .t_coinc_complete. css|] }|jVqdS)N)r()r*r$rrrr+sz4coincgen_doubles.t_coinc_complete..)rNrKrH)rrrrr(sz!coincgen_doubles.t_coinc_completecCs|j|||dS)ax Push new events from some instrument into the internal queues. The iterable of events need not be time-ordered. With self.singlesqueue.event_time() defining the time of events, t_complete sets the time up-to which the collection of events is known to be complete. That is, in the future no new events will be pushed whose times are earlier than t_complete. N)rKr1)rrDr0r#rrrr1s zcoincgen_doubles.pushc cst|t|kr*||}}| }dd}ndd}||dd|D|j}|j}|j}||} xX|D]P} | | ||} t| } | rx2| D] } t| } || || | VqWqp|| qpWdS)z For internal use only. cSs||fS)Nr)abrrrz-coincgen_doubles.doublesgen..cSs||fS)Nr)rOrPrrrrQrRcss|]}t|VqdS)N)r))r*rrrrr+sz.coincgen_doubles.doublesgen..N)rEr3r,adddiscardr@rBr)) rZeventsar?Zeventsb singles_idsZunswapZsingles_ids_addZsingles_ids_discardr@Zqueueb_get_coincsZeventamatchesZeventbrrr doublesgens(      zcoincgen_doubles.doublesgencCsRt|j\}}|j|j|j|j}t||j||||j|||S)a Generate a sequence of 2-element tuples of Python IDs of coincident event pairs. Calling code is assumed to be in the process of constructing all possible n-tuple coincidences such that at least one time-shifted event in the n-tuple is before t, and so we construct and return all pairs required to decide that set, meaning we will construct and return pairs that might contain only events after t so that the calling code can test them for coincidence with events from other instruments that precede t. The internal queues are flushed of events that cannot be used again assuming that t never goes backwards. If t is the special value None then all coincident pairs that can be constructed from the internal queues are constructed and returned, the queues are emptied and returned to their initial state. The order of the IDs in each tuple is alphabetical by instrument. The Python IDs of events that are not reported in a coincident pair are placed in the singles_ids set. NOTE: the singles_ids parameter passed to this function must a set or set-like object. It must support Python set manipulation methods, like .clear(), .update(), and so on. )sortedrKrrWr7)rr5rUZ instrumentaZ instrumentbr?rrrr7s! zcoincgen_doubles.pullN)r8r9r:r;robjectrBr&r=rLr'r(r1rWr7rrrrr>4s D#    -r>c@sJeZdZdddZeddZeddZedd Zd d Z d d Z dS)TimeSlideGraphNodeNcs||_||_t| |_t|k|_t|dkrztfdd||t|dD|_ t dd|j D|_ ndt|dkr|f|_ |j dj |_ n:t|dkrֈrt  df|_ |j dj |_ ntdtj|_j j|_dS) NrCc3s|]}t|VqdS)N)rZ)r*Zcomponent_offset_vector)rMcoincgen_doubles_typemin_instrumentsrrr+Fsz.TimeSlideGraphNode.__init__..r css |]}|jjD] }|VqqdS)N)r%maps)r*noder%rrrr+Osrgzoffset_vector cannot be empty) time_slide_idrLanyrHZ is_zero_lagrE keep_partialr2component_offsetvectors componentsrr%AssertionErrorrr r r" previous_tr)rr[rLrMr\r_r)rMr[r\rr&6s" ,   zTimeSlideGraphNode.__init__c#sRd|krtksntx.t|D]}tfdd|DVq,WdS)a Equivalent to offsetvector.component_offsetvectors() except only one input offsetvector is considered, not a sequence of them, and the output offsetvector objects preserve the absolute offsets of each instrument, not only the relative offsets between instruments. r c3s|]}||fVqdS)Nr)r*rD)rLrrr+ssz=TimeSlideGraphNode.component_offsetvectors..N)rErd itertools combinationsr )rLnZselected_instrumentsr)rLrrbhs z*TimeSlideGraphNode.component_offsetvectorscCstdd|jDS)z0 The earliest of the component nodes' .age. css|] }|jVqdS)N)r')r*r^rrrr+zsz)TimeSlideGraphNode.age..)rNrc)rrrrr'uszTimeSlideGraphNode.agecCstdd|jDS)z= The earliest of the component nodes' .t_coinc_complete. css|] }|jVqdS)N)r()r*r^rrrr+sz6TimeSlideGraphNode.t_coinc_complete..)rNrc)rrrrr(|sz#TimeSlideGraphNode.t_coinc_completecCsn|j}t|jdkr<|f|jks(t|jd||n(x&|jD]}||jkrD||||qDW|j|kS)a Push new events from some instrument into the internal queues. The iterable of events need not be time-ordered. With self.singlesqueue.event_time() defining the time of events, t_complete sets the time up-to which the collection of events is known to be complete. That is, in the future no new events will be pushed whose times are earlier than t_complete. Returns True if this node's .t_coinc_complete property has been changed by this operation, False otherwise. If .t_coinc_complete does not change, then no new candidates can yet be formed and it is not necessary to perform a coincidence analysis at this time. r r)r(rErLkeysrdrcr1)rrDr0r#Zt_beforer^rrrr1s  zTimeSlideGraphNode.pushc sh|jkrttfSdk r"ntj|_t|jdkr`tdd|jddDtfSt|jdkrt}t|jd|}||j rtdd|DntfSt|jdkst tfdd|jD}td d|D}|j r,tt j |}| d dtt j d d|DDnt}~g}|d}|d}|d } ~x|D]} |t|| dd t|| dd | d df} | t| | ddt| | dd | d df} x| D]x} | dd| d d}t| |}|t| kr| ||kr| dd|}|t |t|d||qWqXW|t|}||fS)a Using the events contained in the internal queues construct and return all coincidences they participate in. It is assumed calling code is in the process of constructing n-tuple candidates such that each candidate contains at least one event preceding t, and so we construct and return all candidates required to decide that set, which might include candidates all of whose events come after t. Two objects are returned: a tuple of the (n=N)-way coincidences, where N is the number of instruments in this node's offset vector, and a set of the (min_instruments<=nN)-tuple coincidences, any that fail to contain at least one event preceding t could, at this stage, be discarded, however testing for that would require paying the price of the ID-->event look-up on all events in all candidates, which we will have to perform at each level of the graph, including the final stage before reporting candidates, so it is more efficient to leave the invalid candidates in the stream at this stage and cull them in a single pass at the end. The coincidences are reported as tuples of the Python IDs of the events that form coincidences. The .index look-up table can be used to map these IDs back to the original events. To do that, however, a copy of the contents of the .index mapping must be made before calling this method because this method will result in some of the events in question being removed from the queues, and thus also from the .index mapping. Nr css|]}t|fVqdS)N)r))r*rrrrr+sz*TimeSlideGraphNode.pull..rrCcss|] }|fVqdS)Nr)r*Zeventidrrrr+sc3s|]}|VqdS)N)r7)r* component)r5rrr+scss|]}|dVqdS)rNr)r*elemrrrr+ scss|]\}}|dkr|VqdS)rCNr)r*coinccountrrrr+3scss|]}|dVqdS)r Nr)r*rkrrrr+3s)rer2setr r"rErLrcr7rardrfchainr,rrJrdifference_updatergappendr/)rr5rUr Z#component_coincs_and_partial_coincsZcomponent_coincsZpartial_coincsZcomponent_coincs0Zcomponent_coincs1Zcomponent_coincs2Zcoinc0Zcoincs1Zcoincs2Zcoinc1Z confirmationr6Z new_coincr)r5rr7sF)  ( " !. 66  zTimeSlideGraphNode.pull)N) r8r9r:r&r<rbr=r'r(r1r7rrrrrZ5s  2  rZc@s4eZdZd ddZeddZddZd d d Zd S)TimeSlideGraphrCFcsHdkrtdtdd|DkrPtdtt|dddftfd dttd d|Dd D|rtd d dd D|rtdt |t j dtfddt| D|_tdd|jD|_t|_t|_|rDfddtdttfdd|jDt j ddS)Nr z!require min_instruments >= 1 (%d)css|]}t|VqdS)N)rE)r*rLrrrr+sz*TimeSlideGraph.__init__..z@encountered offset vector (%s) smaller than min_instruments (%d)cSst|S)N)rE)rLrrrrQrRz)TimeSlideGraph.__init__..)keyc3s"|]}t|t|fVqdS)N)rFr)r*pair)r@rrr+scss|]}|D] }|Vq qdS)Nr)r*rLrDrrrr+srCzcoincidence windows: %sz, css(|] \}}ddt||fVqdS)z %s = %g s+N)joinrX)r*rvdtrrrr+szAconstructing coincidence assembly graph for %d offset vectors ...)filec3s$|]\}}t||dVqdS))r_N)rZ)r*r_rL)rMr[r\rrr+scss|] }|jVqdS)N)r%)r*r^rrrr+scs:t|jdkrtdStdtfdd|jDS)Nr )r r)rr c3s|]}|VqdS)Nr)r*r^)walkrrr+sz8TimeSlideGraph.__init__..walk..)rErcnumpyarrayr)r^)r{rrr{sz%TimeSlideGraph.__init__..walkz:graph contains %d fundamental nodes, %d higher-order nodesc3s|]}|VqdS)Nr)r*r^)r{rrr+s)r rNrHstrrIrfrgrpprintrxrJrEsysstderrr2rXheadrr%used_ids reported_idsr)rr[Zoffset_vector_dictr@r\verboser)r@rMr[r\r{rr&s$ "0    zTimeSlideGraph.__init__cCstdd|jDS)z3 The earliest of the graph's head nodes' .age. css|] }|jVqdS)N)r')r*r^rrrr+sz%TimeSlideGraph.age..)rNr)rrrrr'szTimeSlideGraph.agecstfdd|jDS)aL Push new events from some instrument into the internal queues. The iterable of events need not be time-ordered. With self.singlesqueue.event_time() defining the time of events, t_complete sets the time up-to which the event stream from this instrument is known to be complete. That is, in the future no new events will be pushed from this instrument whose times are earlier than t_complete. t_complete is measured with respect to the unshifted times of the events. Returns True if the graph's .t_coinc_complete has changed, indicating that it might be possible to form new candidates; False if the addition of these events does not yet allow new candidates to be formed. If the return value is False, .pull() is guaranteed to return an empty candidate list unless the graph is flushed of all candidates. cs$g|]}|jkr|qSr)rLr1)r*r^)r0rDr#rr sz'TimeSlideGraph.push..)r`r)rrDr0r#r)r0rDr#rr1szTimeSlideGraph.pushNc#st|j|dkrdd}|dkr0dd}n|j}t}t} |j} |jj} xt|jddD]\} } | j | j |rd}t | j t j}n| j}t | j |}xztj| |D]f}tfdd|D}tfdd|D|krq| |||||s| || |fVqWqbW|rB||j8}|j|O_| t|j8} | r~| |j}|j| 8_|j| 8_nt}|r|js|jrt|dk r‡fd d|D|dd<|dk rfd d| D|dd<|dk r fd d|D|dd<dS) NcSsdS)NFr)r0rLrrrrQrRz%TimeSlideGraph.pull..cSsdS)Nr) event_idsrLrrrrQrRr )startc3s|]}|VqdS)Nr)r*event_id)r%rrr+sz&TimeSlideGraph.pull..c3s |]}||jVqdS)N)Zifo)r*r)rrLrrr+ sc3s|]}|VqdS)Nr)r*r)r%rrr+Esc3s|]}|VqdS)Nr)r*r)r%rrr+Gsc3s|]}|VqdS)Nr)r*r)r%rrr+Is)rIr%rJr1rpr,r enumeraterrrLr segmentreZ PosInfinityr(rfrqr7r2rNrrd)rZnewly_reportedflushedZflushed_unusedflushZ coinc_sieveZevent_collectorZevent_collector_pushZnewly_reported_idsZ flushed_idsZnewly_reported_updateZ used_updaterhr^r5Z candidate_segrr0Zflushed_unused_idsr)rr%rLrr7sV       zTimeSlideGraph.pull)rCF)NNNFNN)r8r9r:r&r=r'r1r7rrrrrts O rtc@s(eZdZdZddZddZddZdS) CoincTableszx A convenience interface to the XML document's coincidence tables, allowing for easy addition of coincidence events. cCsytj||_Wn4tk rFttj|_|jd|jYnX|jytj ||_ Wn4tk rttj |_ |jd|j YnXt j ||j |jd|jd|_tj||_|j|_dS)NrT)Z create_new description)rZ CoincTableZ get_table coinctabler ZNewZ childNodesZ appendChildZ sync_next_idZ CoincMapTable coincmaptable ligolw_coincsZget_coinc_def_idsearchZsearch_coinc_typer coinc_def_idZTimeSlideTableZtime_slide_tableas_dictZtime_slide_index)rZxmldocZcoinc_definer_rowrrrr&Zs zCoincTables.__init__c sHfdd|D}|s tdjj|jd|dt|dd}||fS)a From a process ID, a time slide ID, and a sequence of events (generator expressions are OK), constructs and initializes a coinc_event table row object and a sequence of coinc_event_map table row objects describing the coincident event. The return value is the coinc_event row and a sequence of the coinc_event_map rows. The coinc_event is *not* assigned a coinc_event_id by this method. It is expected that will be done in .append_coinc(). This allows sub-classes to defer the question of whether or not to include the coincidence in the search results without consuming additional IDs. The coinc_event row's .instruments and .likelihood attributes are initialized to null values. The calling code should populate as needed. When subclassing this method, if the time shifts that were applied to the events in constructing the coincidence are required to compute additional metadata, they can be retrieved from self.time_slide_index using the time_slide_id. cs g|]}jjd|jdqS)N)coinc_event_id table_namer)rRowTyper)r*r)rrrrrsz*CoincTables.coinc_rows..zcoincs must contain >= 1 eventN) process_idrrr_ZinstsZneventsZ likelihood)rdrrrrE)rrr_r0rZ coincmapsrlr)rrr coinc_rowsqs  zCoincTables.coinc_rowscCs>|j|_|j|x |D]}|j|_|j|qW|S)z Appends the coinc_event row object and coinc_event_map row objects to the coinc_event and coinc_event_map tables respectively after assigning a coinc_event_id to the coincidence. Returns the coinc_event row object. )rZ get_next_idrrsr)rZcoinc_event_rowZcoinc_event_map_rowsrowrrr append_coincs    zCoincTables.append_coincN)r8r9r:r;r&rrrrrrrUs,rc@sReZdZdddZeddZddZd d Zd d Zd dZ ddZ ddZ dS) CoincRatesrC-C6?c szt_|_|_jtjkr.tdjdkr@td|dkrPtdtfddtt jdD_ i_ xj D]}t fdd d t tgsd j |<qtd krd j tdfj |<qt}tj||d |d fdd}xjtD]^\}} |} |d9}d ||| f<d||d | f<j t| f ||df<||d df<q&Wxtttd|D]\}\\} } \} }|d9}d ||| f<d||| f<d||d | f<d ||d | f<j t| |f ||df<||d df<qWtjtfdd}y tt||jjj |<Wqtk rpYnXqt fddD}t fddtttdD}tj}tjd |}d\}}xV||||kr&t fdd|Dtfdd|Dr|d 7}|d 7}qWt|t|j |<x2D]*} j |d j t| f9<qDWqWdS)a Model for coincidences among noise events collected from several antennas. Independent Poisson processes are assumed. The coincidence window for each pair of instruments is (delta_t + light travel time between that pair). A coincidence is assumed to require full N-way coincidence and require at least min_instruments to participate. Initial configuration requires some relatively expensive pre-calculation of internal quantities, but once initialized coincidence rates can be computed quickly from observed event rates. Several other related quantities can be computed. Example: >>> coincrates = CoincRates(("H1", "L1", "V1"), 0.005, 2) z+require len(instruments) >= min_instrumentsgzrequire delta_t >= 0.z#require abundance_rel_accuracy > 0.c3s$|]}t|jt|fVqdS)N)rFdelta_tr)r*ab)rrrr+sz&CoincRates.__init__..rCcs"tfddtgDS)Nc3s&|]}tjt|fVqdS)N)rlogtaurF)r*rP)rOrrrr+sz8CoincRates.__init__....)rrp)rO) instrumentsr)rOrrQrRz%CoincRates.__init__..)rug?r g@rdouble)Zdtypegrnc3s6|].}jt|f jt|f fVqdS)N)rrF)r*rD)anchorrrrr+Usc3s2|]*\}}||jt||ffVqdS)N)rrF)r*r6j)rrrrr+[s)rrc3s|]}|VqdS)Nr)r*Zwindow)random_uniformrrr+{sc3s,|]$\}}}t|||kVqdS)N)abs)r*r6rmaxdt)ryrrr+|sN)rFrrr\rEr rIrfrgr2r rate_factorsall_instrument_combosrNrpr|zerosrrZ ConvexHullZHalfspaceIntersectionZ intersectionsvolumeAttributeErrorrangerrrandomuniformallfloat)rrrr\Zabundance_rel_accuracyru dimensionsZ halfspacesr6rDrZj1rOZj2rPZinteriorwindowsijseqZ math_sqrtZ two_epsilonrhdr)rryrrrrr&sl  & ;  " 2,  2 ( zCoincRates.__init__cs0t|jtfddt|jtdDS)a. A tuple of all possible instrument combinations (as frozensets). Example: >>> coincrates = CoincRates(("H1", "L1", "V1"), 0.005, 1) >>> coincrates.all_instrument_combos (frozenset(['V1']), frozenset(['H1']), frozenset(['L1']), frozenset(['V1', 'H1']), frozenset(['V1', 'L1']), frozenset(['H1', 'L1']), frozenset(['V1', 'H1', 'L1'])) >>> coincrates = CoincRates(("H1", "L1", "V1"), 0.005, 2) >>> coincrates.all_instrument_combos (frozenset(['V1', 'H1']), frozenset(['V1', 'L1']), frozenset(['H1', 'L1']), frozenset(['V1', 'H1', 'L1'])) c3s(|] }t|D]}t|VqqdS)N)rfrgrF)r*rhr)all_instrumentsrrr+sz3CoincRates.all_instrument_combos..r )r2rrr\rE)rr)rrrs z CoincRates.all_instrument_comboscKst||jkr4tddt|jdt|ftdd|DrRtd|jrt|t|jdkrtd|t|jft |j }x.|D]&}x |D]}||||9<qWqW|S)a` Given the event rates for a collection of instruments, compute the rates at which N-way coincidences occur among them where N >= min_instruments. The return value is a dictionary whose keys are frozensets of instruments and whose values are the rate of coincidences for that set. NOTE: the computed rates are the rates at which coincidences among at least those instruments occur, not the rate at which coincidences among exactly those instruments occur. e.g., considering the H1, L1, V1 network, for the pair H1, L1 the return value is the sum of the rate at which those two instruments form double coincidences and also the rate at which they participate in H1, L1, V1 triple coincidences. See also .strict_coinc_rates(). Example: >>> coincrates = CoincRates(("H1", "L1", "V1"), 0.005, 2) >>> coincrates.coinc_rates(H1 = 0.001, L1 = 0.002, V1 = 0.003) {frozenset(['V1', 'H1']): 1.9372787960306537e-07, frozenset(['V1', 'H1', 'L1']): 1.0125819710267318e-11, frozenset(['H1', 'L1']): 6.00513846088957e-08, frozenset(['V1', 'L1']): 3.77380092200718e-07} >>> coincrates.coinc_rates(H1 = 0.001, L1 = 0.002, V1 = 0.002) {frozenset(['V1', 'H1']): 1.291519197353769e-07, frozenset(['V1', 'H1', 'L1']): 6.750546473511545e-12, frozenset(['H1', 'L1']): 6.00513846088957e-08, frozenset(['V1', 'L1']): 2.5158672813381197e-07} >>> coincrates.coinc_rates(H1 = 0.001, L1 = 0.002, V1 = 0.001) {frozenset(['V1', 'H1']): 6.457595986768845e-08, frozenset(['V1', 'H1', 'L1']): 3.3752732367557724e-12, frozenset(['H1', 'L1']): 6.00513846088957e-08, frozenset(['V1', 'L1']): 1.2579336406690598e-07} z,require event rates for %s, got rates for %sz, css|]}|dkVqdS)gNr)r*raterrrr+sz)CoincRates.coinc_rates..zrates must be >= 0g?zGevents per coincidence window must be << 1: rates = %s, max window = %g) rprr rxrXr`rHrrGrIr)rrates coinc_ratesrrDrrrrs&$   zCoincRates.coinc_ratescKs||jf|}xHt|ddddD]2}x,|D] \}}||kr.|||8<q.Wq Wtdd|Dsxtd||S)an Given the event rates for a collection of instruments, compute the rates at which strict N-way coincidences occur among them where N >= min_instruments. The return value is a dictionary whose keys are frozensets of instruments and whose values are the rate of coincidences for that set. NOTE: the computed rates are the rates at which coincidences occur among exactly those instrument combinations, excluding the rate at which each combination participates in higher-order coincs. e.g., considering the H1, L1, V1 network, for the pair H1, L1 the return value is the rate at which H1, L1 doubles occur, not including the rate at which the H1, L1 pair participates in H1, L1, V1 triples. See also .coinc_rates(). Example: >>> coincrates = CoincRates(("H1", "L1", "V1"), 0.005, 2) >>> coincrates.strict_coinc_rates(H1 = 0.001, L1 = 0.002, V1 = 0.003) {frozenset(['V1', 'H1']): 1.937177537833551e-07, frozenset(['V1', 'H1', 'L1']): 1.0125819710267318e-11, frozenset(['H1', 'L1']): 6.004125878918543e-08, frozenset(['V1', 'L1']): 3.7736996638100773e-07} >>> coincrates.strict_coinc_rates(H1 = 0.001, L1 = 0.002, V1 = 0.002) {frozenset(['V1', 'H1']): 1.2914516918890337e-07, frozenset(['V1', 'H1', 'L1']): 6.750546473511545e-12, frozenset(['H1', 'L1']): 6.004463406242219e-08, frozenset(['V1', 'L1']): 2.5157997758733847e-07} >>> coincrates.strict_coinc_rates(H1 = 0.001, L1 = 0.002, V1 = 0.001) {frozenset(['V1', 'H1']): 6.457258459445168e-08, frozenset(['V1', 'H1', 'L1']): 3.3752732367557724e-12, frozenset(['H1', 'L1']): 6.004800933565894e-08, frozenset(['V1', 'L1']): 1.2578998879366924e-07} TcSst|S)N)rE)rrrrrQrRz/CoincRates.strict_coinc_rates..)reverserucss|]}|dkVqdS)gNr)r*rrrrr+sz0CoincRates.strict_coinc_rates..zencountered negative rate: %s)rrXrJrrHrd)rrstrict_coinc_ratesrrurrrrrs "zCoincRates.strict_coinc_ratesc stjkr4tddtjdtftfddjD}t|d}x\|D]P\}xFj ftfdd|DD]\}}||||7<qWqdW|S)z A dictionary mapping instrument combination (as a frozenset) to the total number of coincidences involving precisely that combination of instruments expected from the background. z#require segmentlists for %s, got %sz, c 3s4|],}|tt|j|fVqdS)N)rr intersectionunionr)r*on_instruments)seglistsrrrr+ sz>CoincRates.marginalized_strict_coinc_counts..gc3s&|]\}}||kr|ndfVqdS)gNr)r*rDr)rrrr+s) rprr rxrXrIrfromkeysrJr)rrrZlivetimeZ coinc_countTZcoinc_instrumentsrr)rrrr marginalized_strict_coinc_countss& 0z+CoincRates.marginalized_strict_coinc_countsc s|jf|}t|dkr(tdtfdd|D}tt|tddksfttfdd|DS)a Given the event rates for a collection of instruments, compute the natural logarithm of the probability that a coincidence is found to involve exactly a given set of instruments. This is equivalent to the ratios of the values in the dictionary returned by .strict_coinc_rates() to their sum. Raises ZeroDivisionError if all coincidence rates are 0. See also .strict_coinc_rates(). Example: >>> coincrates = CoincRates(("H1", "L1", "V1"), 0.005, 2) >>> coincrates.lnP_instruments(H1 = 0.001, L1 = 0.002, V1 = 0.003) {frozenset(['V1', 'H1']): -1.181124067253893, frozenset(['V1', 'H1', 'L1']): -11.040192999777876, frozenset(['H1', 'L1']): -2.352494317162074, frozenset(['V1', 'L1']): -0.5143002401188091} gzall rates are 0c3s|]\}}||fVqdS)Nr)r*rr) total_raterrr++sz-CoincRates.lnP_instruments..g?g+=c3s,|]$\}}||rt|ntfVqdS)N)rrr)r*rP)normrrr+/s) rrrHZeroDivisionErrorrIrJrXrrd)rrrZ P_instrumentsr)rrrlnP_instrumentss  zCoincRates.lnP_instrumentsc+sN|jf|}tt|tfdd|D}tj}x||Vq>> coincrates = CoincRates(("H1", "L1", "V1"), 0.005, 2) >>> x = iter(coincrates.random_instruments(H1 = 0.001, L1 = 0.002, V1 = 0.003)) >>> x.next() # doctest: +SKIP (frozenset(['H1', 'L1']), -3.738788683913535) c3s|]\}}||fVqdS)Nr)r*rZlnP)lnNrrr+Gsz0CoincRates.random_instruments..N)rrrrEr2rJrchoice)rrrresultsrr)rrrandom_instruments2s  zCoincRates.random_instrumentsc#sttjkr6tddttjtjkrZtdjtfddddff}tj tfdd D}tfd d t t td D}x>tfd d |Dt fd d |Drt|VqWdS)a  Generator that yields dictionaries of random event time-of-arrival offsets for the given instruments such that the time-of-arrivals are mutually coincident given the maximum allowed inter-instrument \Delta t's. The values returned are offsets, and would need to be added to some common time to yield absolute arrival times. Example: >>> coincrates = CoincRates(("H1", "L1", "V1"), 0.005, 2) >>> x = iter(coincrates.plausible_toas(("H1", "L1"))) >>> x.next() # doctest: +SKIP {'H1': 0.0, 'L1': -0.010229226372297711} znot configured for %sz, z'require at least %d instruments, got %drr Ngc3s8|]0}|jt|f jt|f fVqdS)N)rrF)r*rD)rrrrr+esz,CoincRates.plausible_toas..c3s2|]*\}}||jt||ffVqdS)N)rrF)r*r6r)rrrrr+fsrCc3s"|]\}}}|||fVqdS)Nr)r*rDlohi)rrrr+hsc3s4|],\}}}t|d|d|kVqdS)r N)r)r*r6rr)ryrrr+is)r2rprr rxrXrEr\rrrfrgrrrI)rrZ anchor_offsetrrr)rryrrrrplausible_toasMs  (zCoincRates.plausible_toasN)rCr) r8r9r:r&r=rrrrrrrrrrrrs Q 60rc@s2eZdZdZejfddZddZeddZ dS) TOATriangulatorax Time-of-arrival triangulator. See section 6.6.4 of "Gravitational-Wave Physics and Astronomy" by Creighton and Anderson. An instance of this class is a function-like object that accepts a tuple of event arival times and returns a tuple providing information derived by solving for the maximum-likelihood source location assuming Gaussian-distributed timing errors. cCs"t|t|kstt|dks$tt||_t||_||_t|j|jddtj fdtd|jd}|j||_ |j |j|jddtj f}tj |\|_ |_|_t|dkrt|j|jdk|_n8t|jd|jd|jd|jdd|j|_dS)a Create and initialize a triangulator object. rs is a sequence of location 3-vectors, sigmas is a sequence of the timing uncertainties for those locations. Both sequences must be in the same order --- the first sigma in the sequence is interpreted as belonging to the first location 3-vector --- and, of course, they must be the same length. v is the speed at which the wave carrying the signals travels. The rs 3-vectors carry units of distance, the sigmas carry units of time, v carries units of distance/time. What units are used for the three is arbitrary, but they must be mutually consistent. The default value for v in c, the speed of light, in metres/second, therefore the location 3-vectors should be given in metres and the sigmas should be given in seconds unless a value for v is provided with different units. Example: >>> from numpy import array >>> triangulator = TOATriangulator([ ... array([-2161414.92636, -3834695.17889, 4600350.22664]), ... array([ -74276.0447238, -5496283.71971 , 3224257.01744 ]), ... array([ 4546374.099 , 842989.697626, 4378576.96241 ]) ... ], [ ... 0.005, ... 0.005, ... 0.005 ... ]) ... >>> This creates a TOATriangulator instance configured for the LIGO Hanford, LIGO Livingston and Virgo antennas with 5 ms time-of-arrival uncertainties at each location. Note: rs and sigmas may be iterated over multiple times. rCNr g:0yE>rg?)rErdr|Zvstackrsr}sigmasvrZnewaxisRZlinalgZsvdUSVTrrNrGsingulardotZmax_dt)rrrrZrbarMrrrr&s*  4    zTOATriangulator.__init__c st|t|jkstt|tfdd|D}t||jdtd|jd}|||j}t|jj |dd}t|j dkr|j rrt||j ||j g}yjt d|ddd|ddd|dd<t d|ddd|ddd |dd<Wn>tk rZd |j d<|t t|d|d}YnXttdtdg}t|jj |j j }tt|d|ddd ksttt|d|ddd kstt|t|j |d|j|jdtd|jd}tt|j|d|j|j|d}||t|j |d|j} t t| | } q|j ||j |j fd d fd d} |j |j } | d} d} x*| | | | dkr| | d} } qWtj| | | }|}t|jj |}tt||dd ks&tt|t|j ||j|jdtd|jd}tt|j||j|j|d}||t|j ||j} t t| | } n|d|j d}y"t|dt d|dg}Wn&tk rt|ddg}YnXt|jj |}tt||dd ks@tt|t|j ||j|jdtd|jd}tt|j||j|j|d}||t|j ||j} t t| | } d}|||t|j| fS)a Triangulate the direction to the source of a signal based on a tuple of times when the signal was observed. ts is a sequence of signal arrival times. One arrival time must be provided for each of the observation locations provided when the instance was created, and the units of the arrival times must be the same as the units used for the sequence of sigmas. The return value is a tuple of information derived by solving for the maximum-likelihood source location assuming Gaussian-distributed timing errors. The return value is (n, toa, chi2 / DOF, dt) where n is a unit 3-vector pointing from the co-ordinate origin towards the source of the signal, toa is the time-of-arrival of the signal at the co-ordinate origin, chi2 / DOF is the \chi^{2} per degree-of-freedom from to the arrival time residuals, and dt is the root-sum-square of the arrival time residuals. Example: >>> from numpy import array >>> from numpy import testing >>> triangulator = TOATriangulator([ ... array([-2161414.92636, -3834695.17889, 4600350.22664]), ... array([ -74276.0447238, -5496283.71971 , 3224257.01744 ]), ... array([ 4546374.099 , 842989.697626, 4378576.96241 ]) ... ], [ ... 0.005, ... 0.005, ... 0.005 ... ]) ... >>> n, toa, chi2_per_dof, dt = triangulator([ ... 794546669.429688, ... 794546669.41333, ... 794546669.431885 ... ]) ... >>> n array([[-0.45605637, 0.75800934, 0.46629865], [-0.45605637, 0.75800934, 0.46629865]]) >>> testing.assert_approx_equal(toa, 794546669.4269662) >>> testing.assert_approx_equal(chi2_per_dof, 0.47941941158371465) >>> testing.assert_approx_equal(dt, 0.005996370224459011) NOTE: if len(rs) >= 4, n is a 1x3 array. if len(rs) == 3, n is a 2x3 array. if len(rs) == 2, n is None. NOTE: n is not the source direction but the propagation direction of GW. Therefore, if you want source direction, you have to multiply -1. NOTE: n is represented by earth fixed coordinate, not celestial coordinate. Up to your purpose, you should transform \phi -> RA. To do it, you can use dir2coord. csg|]}t|qSr)r)r*r5)t0rrrsz,TOATriangulator.__call__..rCr Nrg?rgg:0yE>cSs |||S)Nr)lZ StauprimeZS2rrrn_prime/sz)TOATriangulator.__call__..n_primecs|}t||dS)Nr )r|r)rnp)rrrsecular_equation1sz2TOATriangulator.__call__..secular_equationrn)rErrdrNr|r}rrrrrrrrrr rrrrrscipyoptimizeZbrentq)rtsZtbarrZ tau_primerrhZtoaZchi2ryrZlsingZl_loZl_hirZxpr)rrrrAsf>$28 $&&<*   8&"8&zTOATriangulator.__call__cCsdt|dkrtd|tt||}| }t|d|dt|}t |d}||fS)a This transforms from propagation direction vector to right ascension and declination source co-ordinates. The input is the propagation vector, n, in Earth fixed co-ordinates (x axis through Greenwich merdian and equator, z axis through North Pole), and the time. n does not need to be a unit vector. The return value is the (ra, dec) pair, in radians. NOTE: right ascension is not necessarily in [0, 2\pi). rzn must be a 3-vectorr rrC) rEr rrr|rZarctan2rZGreenwichMeanSiderealTimeZarcsin)rhZgpsZRAZDECrrr dir2coords zTOATriangulator.dir2coordN) r8r9r:r;rrr&rAr<rrrrrrvs  D>rc@s`eZdZdZddZddZddZdd Zd d Zd d Z ddZ e ddZ e ddZ dS) LnLRDensitya Base class for parameter distribution densities for use in log likelihood ratio ranking statistics. Generally several instances of (subclasses of) this will be grouped together to construct a log likelihood ratio class for use as a ranking statistic in a trigger-based search. For example, as a minimum one would expect one instance for the numerator and another for the denominator, but additional ones might be included in a practical ranking statistic implementation, for example a third might be used for storing a histogram of the candidates observed in a search. Typically, the ranking statistic implementation will provide a function to transform a candidate to the arguments to use with the .__call__() implementation, and so in this way a LnLRDensity object is generally only meaningful in the context of the ranking statistic class for which it has been constructed. cOstdS)za Evaluate. Return the natural logarithm of the density evaluated at the given parameters. N)r)rargskwargsrrrrAszLnLRDensity.__call__cCstdS)z$ Marginalize the two densities. N)r)rotherrrr__iadd__szLnLRDensity.__iadd__cOstdS)zK Increment the counts defining this density at the given parameters. N)r)rrrrrr incrementszLnLRDensity.incrementcCstdS)z- Return a duplicate copy of this object. N)r)rrrrcopyszLnLRDensity.copycCstdS)aB Ensure all internal densities are normalized, and initialize interpolator objects as needed for smooth evaluation. Must be invoked before .__call__() will yield sensible results. NOTE: for some implementations this operation will irreversibly alter the contents of the counts array, for example often this operation will involve the convolution of the counts with a density estimation kernel. If it is necessary to preserve a pristine copy of the counts data, use the .copy() method to obtain a copy of the data, first, and then .finish() the copy. N)r)rrrrfinishszLnLRDensity.finishcCstdS)a+ Generator returning a sequence of parameter values drawn from the distribution density. Some subclasses might choose not to implement this, and those that do might choose to use an MCMC-style sample generator and so the samples should not be assumed to be statistically independent. N)r)rrrrsampless zLnLRDensity.samplescCstdd|iS)z Serialize to an XML fragment and return the root element of the resulting XML tree. Subclasses must chain to this method, then customize the return value as needed. Namez%s:lnlrdensity)rLIGO_LW)rnamerrrto_xmlszLnLRDensity.to_xmlcsLdfdd|tjjD}t|dkrDtdtjjf|dS)z Sub-classes can use this in their overrides of the .from_xml() method to find the root element of the XML serialization. z%s:lnlrdensitycs$g|]}|dr|jkr|qS)r)Z hasAttributer)r*rk)rrrr sz,LnLRDensity.get_xml_root..r z5XML tree must contain exactly one %s element named %sr)ZgetElementsByTagNamerrZtagNamerEr )clsxmlrr)rr get_xml_root s  zLnLRDensity.get_xml_rootcCstdS)z In the XML document tree rooted at xml, search for the serialized LnLRDensity object named name, and deserialize it. The return value is the deserialized LnLRDensity object. N)r)rrrrrrfrom_xml s zLnLRDensity.from_xmlN)r8r9r:r;rArrrrrr classmethodrrrrrrrs  rc@s"eZdZdZddZdddZdS)LnLikelihoodRatioMixinaC Mixin to assist in implementing a log likelihood ratio ranking statistic class. The ranking statistic class that inherits from this must: (i) define a callable .numerator attribute that returns ln P(*args, **kwargs | signal); (ii) define a callable .denominator attribute that returns ln P(*args, **kwargs | noise). Inheriting from this will: 1. Add a .__call__() method that returns the natural logarithm of the likelihood ratio ln P(*args, **kwargs | signal) - ln P(*args, **kwargs | noise) The implementation handles various special cases sensibly, such as when either or both of the logarithms of the numerator and denominator diverge. 2. Add a .ln_lr_samples() method that makes use of the .numerator and .denominator attributes, together with the .__call__() method to transform a sequence of (*args, **kwargs) into a sequence of log likelihood ratios and their respective relative frequencies. This can be used to construct histograms of P(ln L | signal) and P(ln L | noise). These distributions are required for, for example, signal rate estimation and false-alarm probability estimation. Why is the likelihood ratio useful? Starting from Bayes' theorem, and using the fact that "signal" and "noise" are the only two choices: P(data | signal) * P(signal) P(signal | data) = ---------------------------- P(data) P(data | signal) * P(signal) = --------------------------------------------------------- P(data | noise) * P(noise) + P(data | signal) * P(signal) [P(data | signal) / P(data | noise)] * P(signal) = ---------------------------------------------------------------- 1 - P(signal) + [P(data | signal) / P(data | noise)] * P(signal) Lambda * P(signal) P(signal | data) = ---------------------------- 1 + (Lambda - 1) * P(signal) P(data | signal) where Lambda = ---------------- P(data | noise) Differentiating P(signal | data) w.r.t. Lambda shows the derivative is always positive, so the probability that a candidate is the result of a gravitiational wave is a monotonically increasing function of the likelihood ratio. Ranking events from "most likely to be a genuine signal" to "least likely to be a genuine signal" can be performed by sorting candidates by likelihood ratio. Or, if one wanted to set a threshold on P(signal | data) to select a subset of candidates such that the candidates selected have a given purity (the fraction of them that are real is fixed), that is equivalent to selecting candidates using a likelihood ratio threshold. These are expressions of the Neyman-Pearson lemma which tells us that thresholding on Lambda creates a detector that extremizes the detection efficiency at fixed false-alarm rate. cOsb|j||}|j||}t|rZt|rZ|dkr@|dkr@tS|dkrZ|dkrZtd||S)a Return the natural logarithm of the likelihood ratio for the given parameters, ln P(*args, **kwargs | signal) - ln P(*args, **kwargs | noise) The arguments are passed verbatim to the .__call__() methods of the .numerator and .denominator attributes of self and the return value is computed from the results. NOTE: sub-classes may override this method, possibly chaining to it if they wish. The .ln_lr_samples() mechanism does not require this method to return exactly the natural logarithm of the .numerator/.denominator ratio. The .ln_lr_samples() mechanism does not assume the numerator, denominator and ranking statistic are related to each other as the latter being the ratio of the former two, it evaluates all three separately. For this reason, the .__call__() method that implements the ranking statistic is free to include other logic, such as hierarchical cuts or bail-outs that are not stricly equivalent to the ratio of the numerator and denominator. Special cases: .numerator/.denominator=0/0 is mapped to ln Lambda = -inf, meaning P(signal | data) = 0. Although this condition is nonsensical because the data is claimed to be inconsistent with both noise and signal --- the only two things it can be --- our task here is to compute something that is monotonic in the probability the data is the result of a signal, and since this data cannot be from a signal the correct answer is -inf. .numerator/.denominator = +inf/+inf is mapped to ln Lambda = NaN. This is sufficiently nonsensical that there is no correct interpretation. A warning will be displayed when this is encountered. gzinf/inf encountered) numerator denominatorrisinfrwarningswarn)rrr lnP_signal lnP_noiserrrrAg s(    zLnLikelihoodRatioMixin.__call__Nc csh|dkr|j}|j}n |j}|j}x@|D]8\}}}|||}|||} |||||| |fVq(WdS)a Generator that transforms a sequence of candidate parameter samples into a sequence of log likelihood ratio samples. random_params_seq is a sequence (generator is OK) yielding 3-element tuples whose first two elements provide the *args and **kwargs values to be passed to the .numerator and .denominator functions, and whose third element is the natural logarithm of the probability density from which the (*args, **kwargs) parameters have been drawn evaluated at those parameters. The output of this generator is a sequence of 3-element tuples, each of whose elements are: 1. a value of the natural logarithm of the likelihood ratio, 2. the natural logarithm of the relative frequency of occurance of that likelihood ratio in the signal population corrected for the relative frequency at which the random_params_seq sampler is causing that value to be returned, and 3. the natural logarithm of the relative frequency of occurance of that likelihood ratio in the noise population similarly corrected for the relative frequency at which the random_params_seq sampler is causing that value to be returned. The intention is for the first element of each tuple to be added to histograms using the two relative frequencies as weights, i.e., the two relative frequencies give the number of times one should consider this one draw of log likelihood ratio to have occured in the two populations. On each iteration, the *args and **kwargs values yielded by random_params_seq are passed to our own .__call__() method to evalute the log likelihood ratio at that choice of parameter values. The parameters are also passed to the .__call__() mehods of our own .numerator and .denominator attributes to obtain the signal and noise population densities at those parameters. If signal_noise_pdfs is not None then, instead of using our own .numerator and .denominator attributes, the parameters are passed to the .__call__() methods of its .numerator and .denominator attributes to obtain those densities. This allows the distribution of ranking statistic values obtained from alternative signal and noise populations to be modelled. This is sometimes useful for diagnostic purposes. Normalizations: Within the context of the intended application, it is sufficient for all of the probabilities involved (the .numerator and .denominator probability densities, and the probability density supplied by the random_params_seq geneator) to be correct up to unknown normalization constants, i.e., the natural logarithms of the probabilties to be correct up to unknown additive constants. That is why the two probability densities yielded by each iteration of this generator are described as relative frequencies: the ratios among their values are meaningful, but not their absolute values. If all of the supplied probabilities are, in fact, properly normalized, then the relative frequencies returned by this generator are, also, correctly normalized probability densities. N)rr) rZrandom_params_seqZsignal_noise_pdfsZlnP_signal_funcZlnP_noise_funcrrZ lnP_paramsrrrrr ln_lr_samples sI  z$LnLikelihoodRatioMixin.ln_lr_samples)N)r8r9r:r;rArrrrrr$ sBEr)/r;bisectrZfpconstr ImportErrorrrfrr|rZscipy.optimizerrr collectionsrrrZligo.lwrrZ ligo.lw.utilsr rZligor rr __author__Z git_versionr __date__r __version__rrYrr>rZrtrrrrrrrrrs\          bMV`D<t