From 0a8c96c088b3d43d8dc61f794952cf1632152f91 Mon Sep 17 00:00:00 2001 From: md-arif-shaikh Date: Mon, 9 Oct 2023 12:21:47 +0900 Subject: [PATCH] polishing docs --- gw_eccentricity/eccDefinition.py | 85 ++++++++++++++++++-------------- gw_eccentricity/exceptions.py | 30 +++++------ 2 files changed, 62 insertions(+), 53 deletions(-) diff --git a/gw_eccentricity/eccDefinition.py b/gw_eccentricity/eccDefinition.py index 4264931..0b6f349 100644 --- a/gw_eccentricity/eccDefinition.py +++ b/gw_eccentricity/eccDefinition.py @@ -1079,9 +1079,12 @@ def check_num_extrema(self, extrema, extrema_type="extrema"): if num_extrema < 2: # check if the waveform is sufficiently long if self.approximate_num_orbits > 5: - # The waveform is long but the method fails to find the extrema - # This may happen because the eccentricity too small for the - # method to detect it. + # The waveform is sufficiently long but the extrema finding + # method fails to find enough number of extrema. This may + # happen if the eccentricity is too small and, therefore, the + # modulations in the amplitude/frequency is too small for the + # method to detect them. In such cases, the waveform can be + # assumed to be quasicircular. probably_quasicircular = True else: probably_quasicircular = False @@ -1100,10 +1103,11 @@ def check_num_extrema(self, extrema, extrema_type="extrema"): recommended_methods = ["ResidualAmplitude", "AmplitudeFits"] if self.method not in recommended_methods: method_message = ( - "It's possible that the eccentricity is too " - f"low for the {self.method} method to detect" - f" the {extrema_type}. Try one of " - f"{recommended_methods}.") + "It's possible that the eccentricity is too small for " + f"the {self.method} method to detect the " + f"{extrema_type}. Try one of {recommended_methods} " + "which should work even for a very small eccentricity." + ) else: method_message = "" raise InsufficientExtrema(extrema_type, num_extrema, @@ -1261,7 +1265,9 @@ def measure_ecc(self, tref_in=None, fref_in=None): raise KeyError("Exactly one of tref_in and fref_in" " should be specified.") elif tref_in is not None: + # Identify whether the reference point is in time or frequency self.domain = "time" + # Identify whether the reference point is scalar or array-like self.ref_ndim = np.ndim(tref_in) self.tref_in = np.atleast_1d(tref_in) else: @@ -1271,11 +1277,11 @@ def measure_ecc(self, tref_in=None, fref_in=None): # Get the pericenters and apocenters pericenters = self.find_extrema("pericenters") original_pericenters = pericenters.copy() - # Check if there are sufficient number of extrema. In case the waveform - # is long enough but do not have any extrema detected, it might be that - # the eccentricity is too small for the current method to detect - # it. See Fig.4 in arxiv.2302.11257. In such case we assume that the - # waveform is probably quasicircular. + # Check if there are a sufficient number of extrema. In cases where the + # waveform is long enough but the method fails to detect any extrema, + # it might be that the eccentricity is too small for the current method + # to detect it. See Fig.4 in arxiv.2302.11257. In such cases, we assume + # that the waveform is probably quasicircular. self.probably_quasicircular_pericenter = self.check_num_extrema( pericenters, "pericenters") # In some cases it is easier to find the pericenters than finding the @@ -1291,11 +1297,11 @@ def measure_ecc(self, tref_in=None, fref_in=None): self.probably_quasicircular_apocenter = self.check_num_extrema( apocenters, "apocenters") - # If the eccentricity is too small for a method to find the extrema and - # set_failures_to_zero is set to true, then we set the eccentricity and - # mean anomaly to zero and return it. In this case, the rest of the - # code in this function is not executed and therefore, many variables - # which are used in diagnostic tests are never computed thus making + # If the eccentricity is too small for a method to find the extrema, + # and `set_failures_to_zero` is set to true, then we set the + # eccentricity and mean anomaly to zero and return them. In this case, + # the rest of the code in this function is not executed, and therefore, + # many variables used in diagnostic tests are never computed, making # diagnostics irrelevant. if any([self.probably_quasicircular_pericenter, self.probably_quasicircular_apocenter]) \ @@ -1406,10 +1412,10 @@ def measure_ecc(self, tref_in=None, fref_in=None): def set_eccentricity_and_mean_anomaly_to_zero(self): """Set eccentricity and mean_anomaly to zero.""" if self.domain == "time": - # This function sets eccentricity and mean anomaly to zero - # when a method fails to detect any apoceneters or pericenrers, - # and therefore in such cases, we can set the tref_out to be - # the times that falls within the range of self.t. + # This function sets eccentricity and mean anomaly to zero when a + # method fails to detect any extrema, and therefore, in such cases, + # we can set tref_out to be the times that fall within the range of + # self.t. self.tref_out = self.tref_in[ np.logical_and(self.tref_in >= min(self.t), self.tref_in <= max(self.t))] @@ -1420,8 +1426,8 @@ def set_eccentricity_and_mean_anomaly_to_zero(self): self.tref_in, min(self.t), max(self.t)) else: # Since we don't have the maximum and minimum allowed reference - # frequencies computed from the frequencies at the pericenetrs and - # apoceneters, we simply set the maximum and minimum value to be + # frequencies computed from the frequencies at the pericenters and + # apocenters, we simply set the maximum and minimum values to be # the maximum and minimum of instantaneous f22, respectively. f22_min = min(self.omega22) / (2 * np.pi) f22_max = max(self.omega22) / (2 * np.pi) @@ -1438,18 +1444,21 @@ def set_eccentricity_and_mean_anomaly_to_zero(self): return self.make_return_dict_for_eccentricity_and_mean_anomaly() def make_return_dict_for_eccentricity_and_mean_anomaly(self): - """Prepare a dictionary with reference time/freq, ecc and mean ano. + """Prepare a dictionary with reference time/freq, ecc, and mean anomaly. In this function, we prepare a dictionary containing the measured - eccentricity, mean anomaly and the reference time or frequency where - these are measured at. - - We also make sure that if the input reference time/frequency is scalar - then the returned eccentricity and mean anomaly is also a scalar. To do - this, we use the information about the tref_in/fref_in that is provided - by the user. At the top of measure_ecc we set ref_ndim to identify - whether the original input was scalar or array-like and use that here. + eccentricity, mean anomaly, and the reference time or frequency where + these are measured. + + We also make sure that if the input reference time/frequency is scalar, + then the returned eccentricity and mean anomaly are also scalars. To do + this, we use the information about tref_in/fref_in that is provided by + the user. At the top of the measure_ecc function, we set ref_ndim to + identify whether the original input was scalar or array-like and use + that here. """ + # If the original input was scalar, convert the measured eccentricity, + # mean anomaly, etc., to scalar. if self.ref_ndim == 0: self.eccentricity = self.eccentricity[0] self.mean_anomaly = self.mean_anomaly[0] @@ -1462,14 +1471,14 @@ def make_return_dict_for_eccentricity_and_mean_anomaly(self): "eccentricity": self.eccentricity, "mean_anomaly": self.mean_anomaly } + # Return either tref_out or fref_out, depending on whether the input + # reference point was in time or frequency, respectively. if self.domain == "time": return_dict.update({ - "tref_out": self.tref_out - }) + "tref_out": self.tref_out}) else: return_dict.update({ - "fref_out": self.fref_out - }) + "fref_out": self.fref_out}) return return_dict def et_from_ew22_0pn(self, ew22): @@ -1585,7 +1594,7 @@ def compute_mean_anomaly(self, t): return mean_ano % (2 * np.pi) def check_input_limits(self, input_vals, min_allowed_val, max_allowed_val): - """Check that the input time/frequency is within allowed range. + """Check that the input time/frequency is within the allowed range. To avoid any extrapolation, check that the times or frequencies are always greater than or equal to the minimum allowed value and always @@ -1594,7 +1603,7 @@ def check_input_limits(self, input_vals, min_allowed_val, max_allowed_val): Parameters ---------- input_vals: float or array-like - Input times or frequencies where eccentricity/mean anomaly are to + Input times or frequencies where eccentricity/mean anomaly is to be measured. min_allowed_val: float diff --git a/gw_eccentricity/exceptions.py b/gw_eccentricity/exceptions.py index 536e109..f8b9aba 100644 --- a/gw_eccentricity/exceptions.py +++ b/gw_eccentricity/exceptions.py @@ -2,15 +2,15 @@ class InsufficientExtrema(Exception): - """Exception raised when number of extrema is not enough. + """Exception raised when the number of extrema is not enough. While measuring eccentricity, one common failure that may occur is due to - insufficient number of extrema. Applying gw_eccentricity on a large number - of waveforms, for example, when reconstructing PE posterior by measuring - the eccentricity at the samples, one may need to loop over all the - samples. In such cases, one may want to avoid failures that are due to - insufficient extrema. Having a specific exception class helps in such - scenario instead of using generic exceptions. + an insufficient number of extrema. Applying gw_eccentricity to a large + number of waveforms, for example, when reconstructing the PE posterior by + measuring eccentricity at the samples, one may need to loop over all the + samples. In such cases, one may want to avoid failures that are due to an + insufficient number of extrema. Having a specific exception class helps in + such scenarios instead of using a generic exception. Parameters ---------- @@ -20,7 +20,7 @@ class InsufficientExtrema(Exception): Number of extrema. additional_message : str Any additional message to append to the exception message. - Default is None which adds no additional message. + Default is None, which adds no additional message. """ def __init__(self, extrema_type, num_extrema, additional_message=None): @@ -37,24 +37,24 @@ def __init__(self, extrema_type, num_extrema, additional_message=None): class NotInAllowedInputRange(Exception): - """Exception raised when the reference point is outside allowed range. + """Exception raised when the reference point is outside the allowed range. Due to the nature of the eccentricity definition, one can measure the - eccentricity only in an allowed range of time/frequency. If the failure + eccentricity only within an allowed range of time/frequency. If the failure during eccentricity measurement is due to an input time/frequency that lies - outside the allowed range this exception helps in identifying that. + outside the allowed range, this exception helps in identifying that. Parameters ---------- reference_point_type : str - Type of reference point. Can be "tref_in" or "fref_in". + Type of reference point. Can be "time" or "frequency". lower : float - Minium allowed value, i. e., the lower boundary of allowed range. + Minimum allowed value, i.e., the lower boundary of the allowed range. upper : float - Maximum allowed value, i. e., the upper boundary of allowed range. + Maximum allowed value, i.e., the upper boundary of the allowed range. additional_message : str Any additional message to append to the exception message. - Default is None which adds no additional message. + Default is None, which adds no additional message. """ def __init__(self, reference_point_type, lower, upper,