From 2c8469f954a24948cf9db89f554756bfca54c4dd Mon Sep 17 00:00:00 2001 From: Bas des Tombe Date: Sat, 4 Nov 2023 11:48:00 +0100 Subject: [PATCH] Fix doc headers to end with colons --- src/dtscalibration/calibrate_utils.py | 49 +++++------ .../calibration/section_utils.py | 35 ++++---- src/dtscalibration/datastore_utils.py | 75 +++++++---------- src/dtscalibration/dts_accessor.py | 81 ++++++++----------- src/dtscalibration/io/apsensing.py | 37 +++------ src/dtscalibration/io/sensornet.py | 21 ++--- src/dtscalibration/io/sensortran.py | 15 ++-- src/dtscalibration/io/silixa.py | 53 +++++------- src/dtscalibration/io/utils.py | 13 ++- src/dtscalibration/plot.py | 15 ++-- src/dtscalibration/variance_helpers.py | 5 +- src/dtscalibration/variance_stokes.py | 34 ++++---- 12 files changed, 171 insertions(+), 262 deletions(-) diff --git a/src/dtscalibration/calibrate_utils.py b/src/dtscalibration/calibrate_utils.py index e1156157..ab7c3b59 100644 --- a/src/dtscalibration/calibrate_utils.py +++ b/src/dtscalibration/calibrate_utils.py @@ -6,8 +6,7 @@ def parse_st_var(st, st_var): - """ - Utility function to check the st_var input and to return in DataArray + """Utility function to check the st_var input and to return in DataArray format. Parameters @@ -24,7 +23,7 @@ def parse_st_var(st, st_var): distributed) define a DataArray of the shape as ds.st, where the variance can be a function of time and/or x. - Returns + Returns: ------- st_var_sec : DataArray The variance of the noise from the Stokes detector. @@ -57,7 +56,7 @@ def calibration_single_ended_helper( trans_att, solver, ): - """Only used in `calibration_single_ended()`""" + """Only used in `calibration_single_ended()`.""" nt = self.dts.nt nx = self.dts.nx nta = len(trans_att) @@ -203,8 +202,7 @@ def calibration_single_ended_solver( # noqa: MC0001 trans_att=[], verbose=False, ): - """ - The solver for single-ended setups. Assumes `ds` is pre-configured with + """The solver for single-ended setups. Assumes `ds` is pre-configured with `sections` and `trans_att`. Parameters @@ -237,7 +235,7 @@ def calibration_single_ended_solver( # noqa: MC0001 verbose : bool - Returns + Returns: ------- """ @@ -1131,8 +1129,7 @@ def calibrate_double_ended_solver( # noqa: MC0001 nta=None, verbose=False, ): - """ - The solver for double-ended setups. Assumes `ds` is pre-configured with + """The solver for double-ended setups. Assumes `ds` is pre-configured with `sections` and `trans_att`. The construction of X differs a bit from what is presented in the @@ -1183,7 +1180,7 @@ def calibrate_double_ended_solver( # noqa: MC0001 locations. This array is produced by `matching_sections()`. verbose : bool - Returns + Returns: ------- """ @@ -1592,11 +1589,10 @@ def matching_section_location_indices(ix_sec, hix, tix): def construct_submatrices_matching_sections(x, ix_sec, hix, tix, nt, trans_att): - """ - For all matching indices, where subscript 1 refers to the indices in + """For all matching indices, where subscript 1 refers to the indices in `hix` and subscript 2 refers to the indices in `tix`. F1 - F2 = E2 - E1 + TAF2 - TAF1 # EQ1 - B1 - B2 = E1 - E2 + TAB2 - TAB1 # EQ2 + B1 - B2 = E1 - E2 + TAB2 - TAB1 # EQ2. For matching indices (`hix` and `tix`) that are outside of the reference sections an additional equation is needed for `E` per time step. @@ -1628,7 +1624,7 @@ def construct_submatrices_matching_sections(x, ix_sec, hix, tix, nt, trans_att): tix : array-like of int nt : int - Returns + Returns: ------- """ @@ -1835,12 +1831,11 @@ def construct_submatrices(sections, nt, nx, ds, trans_att, x_sec): Zero_gamma (nt * nx, 1) zero_d (nt * nx, nt) Z_TA_fw (nt * nx, nta * 2 * nt) minus ones - Z_TA_bw (nt * nx, nta * 2 * nt) minus ones + Z_TA_bw (nt * nx, nta * 2 * nt) minus ones. I_fw = 1/Tref*gamma - D_fw - E - TA_fw I_bw = 1/Tref*gamma - D_bw + E - TA_bw """ - # Z \gamma # Eq.47 cal_ref = np.array( ds.dts.ufunc_per_section( @@ -1937,13 +1932,12 @@ def wls_sparse( return_werr=False, **solver_kwargs, ): - """ - If some initial estimate x0 is known and if damp == 0, one could proceed as follows: + """If some initial estimate x0 is known and if damp == 0, one could proceed as follows: - Compute a residual vector r0 = b - A*x0. - Use LSQR to solve the system A*dx = r0. - Add the correction dx to obtain a final solution x = x0 + dx. from: https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse. - linalg.lsqr.html + linalg.lsqr.html. Parameters ---------- @@ -1954,7 +1948,7 @@ def wls_sparse( verbose kwargs - Returns + Returns: ------- """ @@ -2051,9 +2045,7 @@ def wls_sparse( def wls_stats(X, y, w=1.0, calc_cov=False, x0=None, return_werr=False, verbose=False): - """ - - Parameters + """Parameters ---------- X y @@ -2061,7 +2053,7 @@ def wls_stats(X, y, w=1.0, calc_cov=False, x0=None, return_werr=False, verbose=F calc_cov verbose - Returns + Returns: ------- """ @@ -2114,8 +2106,8 @@ def calc_alpha_double( talpha_bw_var=None, ): """Eq.50 if weighted least squares. Assumes ds has `trans_att` - pre-configured.""" - + pre-configured. + """ assert ix_alpha_is_zero >= 0, "Define ix_alpha_is_zero" + str(ix_alpha_is_zero) if st_var is not None: @@ -2235,8 +2227,7 @@ def calc_df_db_double_est(ds, sections, ix_alpha_is_zero, gamma_est): def match_sections(ds, matching_sections): - """ - Matches location indices of two sections. + """Matches location indices of two sections. Parameters ---------- ds @@ -2246,7 +2237,7 @@ def match_sections(ds, matching_sections): that are matched. The third item is a boolean and is True if the two sections have a reverse direction ("J-configuration"), most common. - Returns + Returns: ------- matching_indices : array-like Is an array of size (np, 2), where np is the number of paired diff --git a/src/dtscalibration/calibration/section_utils.py b/src/dtscalibration/calibration/section_utils.py index df9edcb7..3b88353e 100644 --- a/src/dtscalibration/calibration/section_utils.py +++ b/src/dtscalibration/calibration/section_utils.py @@ -14,8 +14,7 @@ def set_matching_sections(ds: xr.Dataset, matching_sections: dict[str, list[slic def validate_no_overlapping_sections(sections: dict[str, list[slice]]): - """ - Check if the sections do not overlap. + """Check if the sections do not overlap. Parameters ---------- @@ -23,11 +22,11 @@ def validate_no_overlapping_sections(sections: dict[str, list[slice]]): The keys of the dictionary are the names of the sections. The values are lists of slice objects. - Returns + Returns: ------- None - Raises + Raises: ------ AssertionError If the sections overlap. @@ -50,11 +49,10 @@ def validate_no_overlapping_sections(sections: dict[str, list[slice]]): def validate_sections_definition(sections: dict[str, list[slice]]): - """ - Check if the sections are defined correctly. The sections are defined + """Check if the sections are defined correctly. The sections are defined correctly if: - The keys of the sections-dictionary are strings (assertion) - - The values of the sections-dictionary are lists (assertion) + - The values of the sections-dictionary are lists (assertion). Parameters ---------- @@ -62,11 +60,11 @@ def validate_sections_definition(sections: dict[str, list[slice]]): The keys of the dictionary are the names of the sections. The values are lists of slice objects. - Returns + Returns: ------- None - Raises + Raises: ------ AssertionError If the sections are not defined correctly. @@ -84,14 +82,13 @@ def validate_sections_definition(sections: dict[str, list[slice]]): def validate_sections(ds: xr.Dataset, sections: dict[str, list[slice]]): - """ - Check if the sections are valid. The sections are valid if: + """Check if the sections are valid. The sections are valid if: - The keys of the sections-dictionary refer to a valid timeserie already stored in ds.data_vars (assertion) - The values of the sections-dictionary are lists of slice objects. (assertion) - The slices are within the x-dimension (assertion) - - The slices do not overlap (assertion) + - The slices do not overlap (assertion). Parameters ---------- @@ -102,11 +99,11 @@ def validate_sections(ds: xr.Dataset, sections: dict[str, list[slice]]): The keys of the dictionary are the names of the sections. The values are lists of slice objects. - Returns + Returns: ------- None - Raises + Raises: ------ AssertionError If the sections are not valid. @@ -143,8 +140,7 @@ def ufunc_per_section( calc_per="stretch", **func_kwargs, ): - """ - User function applied to parts of the cable. Super useful, + """User function applied to parts of the cable. Super useful, many options and slightly complicated. @@ -183,12 +179,11 @@ def ufunc_per_section( to a list and concatenating after. - Returns + Returns: ------- - Examples + Examples: -------- - 1. Calculate the variance of the residuals in the along ALL the\ reference sections wrt the temperature of the water baths @@ -249,7 +244,7 @@ def ufunc_per_section( >>> ix_loc = d.ufunc_per_section(sections, x_indices=True) - Note + Note: ---- If `self[label]` or `self[subtract_from_label]` is a Dask array, a Dask array is returned else a numpy array is returned diff --git a/src/dtscalibration/datastore_utils.py b/src/dtscalibration/datastore_utils.py index 3fe3555a..7c0a74fa 100644 --- a/src/dtscalibration/datastore_utils.py +++ b/src/dtscalibration/datastore_utils.py @@ -14,8 +14,7 @@ def check_dims( labels: Union[list[str], tuple[str]], correct_dims: Optional[tuple[str]] = None, ) -> None: - """ - Compare the dimensions of different labels. For example: ['st', 'rst']. + """Compare the dimensions of different labels. For example: ['st', 'rst']. If a calculation is performed and the dimensions do not agree, the answers do not make sense and the matrices are broadcasted and the memory usage will explode. If no correct dims provided the dimensions of the different are compared. @@ -29,7 +28,7 @@ def check_dims( correct_dims : The correct dimensions. - Returns + Returns: ------- """ @@ -52,8 +51,7 @@ def check_dims( class ParameterIndexDoubleEnded: - """ - npar = 1 + 2 * nt + nx + 2 * nt * nta + """npar = 1 + 2 * nt + nx + 2 * nt * nta assert pval.size == npar assert p_var.size == npar if calc_cov: @@ -70,7 +68,7 @@ class ParameterIndexDoubleEnded: if nta > 0: ta = pval[1 + 2 * nt + nx:].reshape((nt, 2, nta), order='F') self['talpha_fw'] = (('time', 'trans_att'), ta[:, 0, :]) - self['talpha_bw'] = (('time', 'trans_att'), ta[:, 1, :]) + self['talpha_bw'] = (('time', 'trans_att'), ta[:, 1, :]). """ def __init__(self, nt, nx, nta, fix_gamma=False, fix_alpha=False): @@ -144,19 +142,17 @@ def ta(self): @property def taf(self): - """ - Use `.reshape((nt, nta))` to convert array to (time-dim and transatt-dim). Order is the default C order. + """Use `.reshape((nt, nta))` to convert array to (time-dim and transatt-dim). Order is the default C order. ta = pval[1 + 2 * nt + nx:].reshape((nt, 2, nta), order='F') - self['talpha_fw'] = (('time', 'trans_att'), ta[:, 0, :]) + self['talpha_fw'] = (('time', 'trans_att'), ta[:, 0, :]). """ return self.ta[:, 0, :].flatten(order="C") @property def tab(self): - """ - Use `.reshape((nt, nta))` to convert array to (time-dim and transatt-dim). Order is the default C order. + """Use `.reshape((nt, nta))` to convert array to (time-dim and transatt-dim). Order is the default C order. ta = pval[1 + 2 * nt + nx:].reshape((nt, 2, nta), order='F') - self['talpha_bw'] = (('time', 'trans_att'), ta[:, 1, :]) + self['talpha_bw'] = (('time', 'trans_att'), ta[:, 1, :]). """ return self.ta[:, 1, :].flatten(order="C") @@ -174,15 +170,15 @@ def get_ta_pars(self, pval): return np.zeros(shape=(self.nt, 2, 0)) def get_taf_pars(self, pval): - """returns taf parameters of shape (nt, nta) or (nt, nta, a)""" + """Returns taf parameters of shape (nt, nta) or (nt, nta, a).""" return self.get_ta_pars(pval=pval)[:, 0, :] def get_tab_pars(self, pval): - """returns taf parameters of shape (nt, nta) or (nt, nta, a)""" + """Returns taf parameters of shape (nt, nta) or (nt, nta, a).""" return self.get_ta_pars(pval=pval)[:, 1, :] def get_taf_values(self, pval, x, trans_att, axis=""): - """returns taf parameters of shape (nx, nt)""" + """Returns taf parameters of shape (nx, nt).""" pval = np.atleast_2d(pval) assert pval.ndim == 2 and pval.shape[1] == self.npar @@ -222,7 +218,7 @@ def get_taf_values(self, pval, x, trans_att, axis=""): return arr_out def get_tab_values(self, pval, x, trans_att, axis=""): - """returns tab parameters of shape (nx, nt)""" + """Returns tab parameters of shape (nx, nt).""" assert pval.shape[-1] == self.npar arr_out = np.zeros((self.nx, self.nt)) @@ -261,9 +257,8 @@ def get_tab_values(self, pval, x, trans_att, axis=""): class ParameterIndexSingleEnded: - """ - if parameter fixed, they are not in - npar = 1 + 1 + nt + nta * nt + """if parameter fixed, they are not in + npar = 1 + 1 + nt + nta * nt. """ def __init__(self, nt, nx, nta, includes_alpha=False, includes_dalpha=True): @@ -320,7 +315,7 @@ def c(self): @property def taf(self): - """returns taf parameters of shape (nt, nta) or (nt, nta, a)""" + """Returns taf parameters of shape (nt, nta) or (nt, nta, a).""" # ta = p_val[-nt * nta:].reshape((nt, nta), order='F') # self["talpha"] = (('time', 'trans_att'), ta[:, :]) if self.includes_alpha: @@ -352,7 +347,7 @@ def get_taf_pars(self, pval): return np.zeros(shape=(self.nt, 0)) def get_taf_values(self, pval, x, trans_att, axis=""): - """returns taf parameters of shape (nx, nt)""" + """Returns taf parameters of shape (nx, nt).""" # assert pval.ndim == 2 and pval.shape[1] == self.npar arr_out = np.zeros((self.nx, self.nt)) @@ -407,7 +402,7 @@ def get_netcdf_encoding( complevel ds : DataStore - Returns + Returns: ------- encoding: Encoding dictionary. @@ -691,8 +686,7 @@ def merge_double_ended( plot_result: bool = True, verbose: bool = True, ) -> xr.Dataset: - """ - Some measurements are not set up on the DTS-device as double-ended + """Some measurements are not set up on the DTS-device as double-ended meausurements. This means that the two channels have to be merged manually. This function can merge two single-ended DataStore objects into a single @@ -712,7 +706,7 @@ def merge_double_ended( Plot the aligned Stokes of the forward and backward channels verbose : bool - Returns + Returns: ------- ds : DataStore object With the two channels merged @@ -798,7 +792,7 @@ def merge_double_ended_times( verbose : bool Print additional information to screen - Returns + Returns: ------- ds_fw_sel : DataSore object DataStore object representing the forward measurement channel with @@ -896,8 +890,7 @@ def merge_double_ended_times( def shift_double_ended( ds: xr.Dataset, i_shift: int, verbose: bool = True ) -> xr.Dataset: - """ - The cable length was initially configured during the DTS measurement. For double ended + """The cable length was initially configured during the DTS measurement. For double ended measurements it is important to enter the correct length so that the forward channel and the backward channel are aligned. @@ -923,7 +916,7 @@ def shift_double_ended( If True, the function will inform the user which variables are dropped. If False, the function will silently drop the variables. - Returns + Returns: ------- ds2 : DataStore object With a shifted x-axis @@ -1013,7 +1006,7 @@ def suggest_cable_shift_double_ended( plot_result : bool Plot the summed error as a function of the shift. - Returns + Returns: ------- ishift1: int Suggested shift based on Err1 @@ -1121,8 +1114,7 @@ def ufunc_per_section_helper( calc_per="stretch", **func_kwargs, ): - """ - User function applied to parts of the cable. Super useful, + """User function applied to parts of the cable. Super useful, many options and slightly complicated. @@ -1166,12 +1158,11 @@ def ufunc_per_section_helper( func_kwargs : dict Dictionary with options that are passed to func - Returns + Returns: ------- - Examples + Examples: -------- - 1. Calculate the variance of the residuals in the along ALL the\ reference sections wrt the temperature of the water baths @@ -1232,7 +1223,7 @@ def ufunc_per_section_helper( >>> ix_loc = ufunc_per_section_helper(x_coords=d.x) - Note + Note: ---- If `dataarray` or `subtract_from_dataarray` is a Dask array, a Dask array is returned else a numpy array is returned @@ -1240,13 +1231,11 @@ def ufunc_per_section_helper( if not func: def func(a): - """ - - Parameters + """Parameters ---------- a - Returns + Returns: ------- """ @@ -1255,13 +1244,11 @@ def func(a): elif isinstance(func, str) and func == "var": def func(a): - """ - - Parameters + """Parameters ---------- a - Returns + Returns: ------- """ diff --git a/src/dtscalibration/dts_accessor.py b/src/dtscalibration/dts_accessor.py index c868ba01..cbcd7847 100644 --- a/src/dtscalibration/dts_accessor.py +++ b/src/dtscalibration/dts_accessor.py @@ -93,8 +93,7 @@ def __repr__(self): # noinspection PyIncorrectDocstring @property def sections(self): - """ - Define calibration sections. Each section requires a reference + """Define calibration sections. Each section requires a reference temperature time series, such as the temperature measured by an external temperature sensor. They should already be part of the DataStore object. @@ -110,7 +109,8 @@ def sections(self): temperature time series. Its values are lists of slice objects, where each slice object is a stretch. - Returns + + Returns: ------- """ @@ -134,8 +134,7 @@ def sections(self, value): # noinspection PyIncorrectDocstring @property def matching_sections(self): - """ - Define calibration sections. Each matching_section requires a reference + """Define calibration sections. Each matching_section requires a reference temperature time series, such as the temperature measured by an external temperature sensor. They should already be part of the DataStore object. @@ -150,7 +149,8 @@ def matching_sections(self): has three items. The first two items are the slices of the sections that are matched. The third item is a boolean and is True if the two sections have a reverse direction ("J-configuration"). - Returns + + Returns: ------- """ @@ -174,11 +174,10 @@ def matching_sections(self, value): raise NotImplementedError(msg) def get_default_encoding(self, time_chunks_from_key=None): - """ - Returns a dictionary with sensible compression setting for writing + """Returns a dictionary with sensible compression setting for writing netCDF files. - Returns + Returns: ------- """ @@ -272,9 +271,7 @@ def get_default_encoding(self, time_chunks_from_key=None): return encoding def get_timeseries_keys(self): - """ - Returns a list of the keys of the time series variables. - """ + """Returns a list of the keys of the time series variables.""" return [k for k, v in self._obj.data_vars.items() if v.dims == ("time",)] def ufunc_per_section( @@ -290,8 +287,7 @@ def ufunc_per_section( suppress_section_validation=False, **func_kwargs, ): - """ - User function applied to parts of the cable. Super useful, + """User function applied to parts of the cable. Super useful, many options and slightly complicated. @@ -331,12 +327,11 @@ def ufunc_per_section( to a list and concatenating after. - Returns + Returns: ------- - Examples + Examples: -------- - 1. Calculate the variance of the residuals in the along ALL the\ reference sections wrt the temperature of the water baths @@ -402,7 +397,7 @@ def ufunc_per_section( >>> ix_loc = d.ufunc_per_section(sections=sections, x_indices=True) - Note + Note: ---- If `self[label]` or `self[subtract_from_label]` is a Dask array, a Dask array is returned else a numpy array is returned @@ -460,8 +455,7 @@ def calibrate_single_ended( fix_dalpha=None, fix_alpha=None, ): - r""" - Calibrate the Stokes (`ds.st`) and anti-Stokes (`ds.ast`) data to + r"""Calibrate the Stokes (`ds.st`) and anti-Stokes (`ds.ast`) data to temperature using fiber sections with a known temperature (`ds.sections`) for single-ended setups. The calibrated temperature is stored under `ds.tmpf` and its variance under `ds.tmpf_var`. @@ -575,20 +569,18 @@ def calibrate_single_ended( A tuple containing two array-likes. The first array-like is the integrated differential attenuation of length x, and the second item is its variance. - Returns + Returns: ------- - References + References: ---------- - .. [1] des Tombe, B., Schilperoort, B., & Bakker, M. (2020). Estimation of Temperature and Associated Uncertainty from Fiber-Optic Raman- Spectrum Distributed Temperature Sensing. Sensors, 20(8), 2235. https://doi.org/10.3390/s20082235 - Examples + Examples: -------- - - `Example notebook 7: Calibrate single ended `_ @@ -759,8 +751,7 @@ def calibrate_double_ended( matching_sections=None, verbose=False, ): - r""" - See example notebook 8 for an explanation on how to use this function. + r"""See example notebook 8 for an explanation on how to use this function. Calibrate the Stokes (`ds.st`) and anti-Stokes (`ds.ast`) of the forward channel and from the backward channel (`ds.rst`, `ds.rast`) data to temperature using fiber sections with a known temperature @@ -804,7 +795,7 @@ def calibrate_double_ended( .. math:: T_\mathrm{B} (x,t) = \frac{\gamma}{I_\mathrm{B}(x,t) + \ - C_\mathrm{B}(t) + \int_x^L{\Delta\alpha(x')\,\mathrm{d}x'}} + C_\mathrm{B}(t) + \int_x^L{\Delta\alpha(x')\,\mathrm{d}x'}} with .. math:: @@ -963,23 +954,21 @@ def calibrate_double_ended( verbose : bool Show additional calibration information - Returns + Returns: ------- - References + References: ---------- - .. [1] des Tombe, B., Schilperoort, B., & Bakker, M. (2020). Estimation of Temperature and Associated Uncertainty from Fiber-Optic Raman- Spectrum Distributed Temperature Sensing. Sensors, 20(8), 2235. https://doi.org/10.3390/s20082235 - Examples + Examples: -------- - - `Example notebook 8: Calibrate double ended ` + dtscalibration/python-dts-calibration/blob/master/examples/notebooks/ + 08Calibrate_double_wls.ipynb>` """ # out contains the state out = xr.Dataset( @@ -1271,7 +1260,7 @@ def monte_carlo_single_ended( reduce_memory_usage=False, mc_remove_set_flag=True, ): - """The result object is what comes out of the single_ended_calibration routine) + """The result object is what comes out of the single_ended_calibration routine). TODO: Use get_params_from_pval_single_ended() to extract parameter sets from mc """ @@ -1459,8 +1448,7 @@ def monte_carlo_double_ended( mc_remove_set_flag=True, reduce_memory_usage=False, ): - r""" - Estimation of the confidence intervals for the temperatures measured + r"""Estimation of the confidence intervals for the temperatures measured with a double-ended setup. Double-ended setups require four additional steps to estimate the confidence intervals for the temperature. First, the variances of the @@ -1569,10 +1557,10 @@ def monte_carlo_double_ended( reduce_memory_usage : bool Use less memory but at the expense of longer computation time - Returns + Returns: ------- - References + References: ---------- .. [1] des Tombe, B., Schilperoort, B., & Bakker, M. (2020). Estimation of Temperature and Associated Uncertainty from Fiber-Optic Raman- @@ -1583,8 +1571,7 @@ def monte_carlo_double_ended( """ def create_da_ta2(no, i_splice, direction="fw", chunks=None): - """create mask array mc, o, nt""" - + """Create mask array mc, o, nt.""" if direction == "fw": arr = da.concatenate( ( @@ -1961,8 +1948,7 @@ def average_monte_carlo_single_ended( mc_remove_set_flag=True, reduce_memory_usage=False, ): - """ - Average temperatures from single-ended setups. + """Average temperatures from single-ended setups. Four types of averaging are implemented. Please see Example Notebook 16. @@ -2065,7 +2051,7 @@ def average_monte_carlo_single_ended( reduce_memory_usage : bool Use less memory but at the expense of longer computation time - Returns + Returns: ------- """ @@ -2304,8 +2290,7 @@ def average_monte_carlo_double_ended( reduce_memory_usage=False, **kwargs, ): - """ - Average temperatures from double-ended setups. + """Average temperatures from double-ended setups. Four types of averaging are implemented. Please see Example Notebook 16. @@ -2407,7 +2392,7 @@ def average_monte_carlo_double_ended( reduce_memory_usage : bool Use less memory but at the expense of longer computation time - Returns + Returns: ------- """ diff --git a/src/dtscalibration/io/apsensing.py b/src/dtscalibration/io/apsensing.py index f2164d9f..d03e219d 100644 --- a/src/dtscalibration/io/apsensing.py +++ b/src/dtscalibration/io/apsensing.py @@ -56,11 +56,11 @@ def read_apsensing_files( kwargs : dict-like, optional keyword-arguments are passed to DataStore initialization - Notes + Notes: ----- Only XML files are supported for now - Returns + Returns: ------- datastore : DataStore The newly created datastore. @@ -114,11 +114,10 @@ def apsensing_xml_version_check(filepathlist): ---------- filepathlist - Returns + Returns: ------- """ - sep = ":" attrs, _ = read_apsensing_attrs_singlefile(filepathlist[0], sep) @@ -132,8 +131,7 @@ def read_apsensing_files_routine( silent=False, load_in_memory="auto", ): - """ - Internal routine that reads AP Sensing files. + """Internal routine that reads AP Sensing files. Use dtscalibration.read_apsensing_files function instead. The AP sensing files are not timezone aware @@ -146,7 +144,7 @@ def read_apsensing_files_routine( silent load_in_memory - Returns + Returns: ------- """ @@ -224,17 +222,14 @@ def read_apsensing_files_routine( @dask.delayed def grab_data_per_file(file_handle): - """ - - Parameters + """Parameters ---------- file_handle - Returns + Returns: ------- """ - with open_file(file_handle, mode="r") as f_h: if skip_chars: f_h.read(3) @@ -296,13 +291,11 @@ def grab_data_per_file(file_handle): @dask.delayed def grab_timeseries_per_file(file_handle): - """ - - Parameters + """Parameters ---------- file_handle - Returns + Returns: ------- """ @@ -352,14 +345,12 @@ def grab_timeseries_per_file(file_handle): def read_apsensing_attrs_singlefile(filename, sep): - """ - - Parameters + """Parameters ---------- filename sep - Returns + Returns: ------- """ @@ -368,8 +359,7 @@ def read_apsensing_attrs_singlefile(filename, sep): import xmltodict def metakey(meta, dict_to_parse, prefix): - """ - Fills the metadata dictionairy with data from dict_to_parse. + """Fills the metadata dictionairy with data from dict_to_parse. The dict_to_parse is the raw data from a silixa xml-file. dict_to_parse is a nested dictionary to represent the different levels of hierarchy. For example, @@ -384,11 +374,10 @@ def metakey(meta, dict_to_parse, prefix): dict_to_parse : dict prefix - Returns + Returns: ------- """ - for key in dict_to_parse: if prefix == "": prefix_parse = key.replace("@", "") diff --git a/src/dtscalibration/io/sensornet.py b/src/dtscalibration/io/sensornet.py index ccac51c9..171e12a6 100644 --- a/src/dtscalibration/io/sensornet.py +++ b/src/dtscalibration/io/sensornet.py @@ -54,13 +54,13 @@ def read_sensornet_files( kwargs : dict-like, optional keyword-arguments are passed to DataStore initialization - Notes + Notes: ----- Compressed sensornet files can not be directly decoded because the files are encoded with encoding='windows-1252' instead of UTF-8. - Returns + Returns: ------- datastore : DataStore The newly created datastore. @@ -135,18 +135,17 @@ def read_sensornet_files( def sensornet_ddf_version_check(filepathlist): - """Function which checks and returns the .ddf file version + """Function which checks and returns the .ddf file version. Parameters ---------- filepathlist - Returns + Returns: ------- ddf_version """ - # Obtain metadata fro mthe first file _, meta = read_sensornet_single(filepathlist[0]) @@ -164,13 +163,11 @@ def sensornet_ddf_version_check(filepathlist): def read_sensornet_single(filename): - """ - - Parameters + """Parameters ---------- filename - Returns + Returns: ------- """ @@ -252,8 +249,7 @@ def read_sensornet_files_routine_v3( fiber_length=None, flip_reverse_measurements=False, ): - """ - Internal routine that reads Sensor files. + """Internal routine that reads Sensor files. Use dtscalibration.read_sensornet_files function instead. Parameters @@ -270,11 +266,10 @@ def read_sensornet_files_routine_v3( It is the fiber length between the two connector entering the DTS device. - Returns + Returns: ------- """ - # Obtain metadata from the first file data, meta = read_sensornet_single(filepathlist[0]) diff --git a/src/dtscalibration/io/sensortran.py b/src/dtscalibration/io/sensortran.py index b1077897..01111d60 100644 --- a/src/dtscalibration/io/sensortran.py +++ b/src/dtscalibration/io/sensortran.py @@ -38,12 +38,11 @@ def read_sensortran_files( kwargs : dict-like, optional keyword-arguments are passed to DataStore initialization - Returns + Returns: ------- DataStore The newly created datastore. """ - filepathlist_dts = sorted(Path(directory).glob("*BinaryRawDTS.dat")) # Make sure that the list of files contains any files @@ -88,7 +87,7 @@ def sensortran_binary_version_check(filepathlist: list[Path]): ---------- filepathlist - Returns + Returns: ------- """ @@ -108,8 +107,7 @@ def read_sensortran_files_routine( timezone_netcdf: str = "UTC", silent: bool = False, ) -> tuple[dict[str, Any], dict[str, Any], dict]: - """ - Internal routine that reads sensortran files. + """Internal routine that reads sensortran files. Use dtscalibration.read_sensortran_files function instead. The sensortran files are in UTC time @@ -121,7 +119,7 @@ def read_sensortran_files_routine( timezone_netcdf silent - Returns + Returns: ------- """ @@ -261,15 +259,14 @@ def read_sensortran_files_routine( def read_sensortran_single(file: Path) -> tuple[dict, dict]: - """ - Internal routine that reads a single sensortran file. + """Internal routine that reads a single sensortran file. Use dtscalibration.read_sensortran_files function instead. Parameters ---------- file - Returns + Returns: ------- data, metadata """ diff --git a/src/dtscalibration/io/silixa.py b/src/dtscalibration/io/silixa.py index 025b7b1f..ceb1e503 100644 --- a/src/dtscalibration/io/silixa.py +++ b/src/dtscalibration/io/silixa.py @@ -48,12 +48,11 @@ def read_silixa_files( kwargs : dict-like, optional keyword-arguments are passed to DataStore initialization - Returns + Returns: ------- datastore : DataStore The newly created datastore. """ - assert "timezone_input_files" not in kwargs, ( "The silixa files are " "already timezone aware" ) @@ -109,11 +108,10 @@ def silixa_xml_version_check(filepathlist): ---------- filepathlist - Returns + Returns: ------- """ - sep = ":" attrs = read_silixa_attrs_singlefile(filepathlist[0], sep) @@ -126,22 +124,19 @@ def silixa_xml_version_check(filepathlist): def read_silixa_attrs_singlefile(filename, sep): - """ - - Parameters + """Parameters ---------- filename sep - Returns + Returns: ------- """ import xmltodict def metakey(meta, dict_to_parse, prefix): - """ - Fills the metadata dictionairy with data from dict_to_parse. + """Fills the metadata dictionairy with data from dict_to_parse. The dict_to_parse is the raw data from a silixa xml-file. dict_to_parse is a nested dictionary to represent the different levels of hierarchy. For example, @@ -156,11 +151,10 @@ def metakey(meta, dict_to_parse, prefix): dict_to_parse : dict prefix - Returns + Returns: ------- """ - for key in dict_to_parse: if prefix == "": prefix_parse = key.replace("@", "") @@ -203,8 +197,7 @@ def read_silixa_files_routine_v6( # noqa: MC0001 silent=False, load_in_memory="auto", ): - """ - Internal routine that reads Silixa files. + """Internal routine that reads Silixa files. Use dtscalibration.read_silixa_files function instead. The silixa files are already timezone aware @@ -216,11 +209,10 @@ def read_silixa_files_routine_v6( # noqa: MC0001 timezone_netcdf silent - Returns + Returns: ------- """ - # translate names tld = {"ST": "st", "AST": "ast", "REV-ST": "rst", "REV-AST": "rast", "TMP": "tmp"} @@ -333,13 +325,11 @@ def read_silixa_files_routine_v6( # noqa: MC0001 @dask.delayed def grab_data_per_file(file_handle): - """ - - Parameters + """Parameters ---------- file_handle - Returns + Returns: ------- """ @@ -401,13 +391,11 @@ def grab_data_per_file(file_handle): @dask.delayed def grab_timeseries_per_file(file_handle, xml_version): - """ - - Parameters + """Parameters ---------- file_handle - Returns + Returns: ------- """ @@ -514,8 +502,7 @@ def grab_timeseries_per_file(file_handle, xml_version): def read_silixa_files_routine_v4( # noqa: MC0001 filepathlist, timezone_netcdf="UTC", silent=False, load_in_memory="auto" ): - """ - Internal routine that reads Silixa files. + """Internal routine that reads Silixa files. Use dtscalibration.read_silixa_files function instead. The silixa files are already timezone aware @@ -527,7 +514,7 @@ def read_silixa_files_routine_v4( # noqa: MC0001 timezone_netcdf silent - Returns + Returns: ------- """ @@ -640,13 +627,11 @@ def read_silixa_files_routine_v4( # noqa: MC0001 @dask.delayed def grab_data_per_file(file_handle): - """ - - Parameters + """Parameters ---------- file_handle - Returns + Returns: ------- """ @@ -709,13 +694,11 @@ def grab_data_per_file(file_handle): @dask.delayed def grab_timeseries_per_file(file_handle): - """ - - Parameters + """Parameters ---------- file_handle - Returns + Returns: ------- """ diff --git a/src/dtscalibration/io/utils.py b/src/dtscalibration/io/utils.py index b9a08338..17b82bf9 100644 --- a/src/dtscalibration/io/utils.py +++ b/src/dtscalibration/io/utils.py @@ -128,13 +128,11 @@ def open_file(path, **kwargs): def get_xml_namespace(element): - """ - - Parameters + """Parameters ---------- element - Returns + Returns: ------- """ @@ -152,9 +150,8 @@ def coords_time( dtBW=None, double_ended_flag=False, ): - """ - Prepares the time coordinates for the construction of DataStore - instances with metadata + """Prepares the time coordinates for the construction of DataStore + instances with metadata. Parameters ---------- @@ -175,7 +172,7 @@ def coords_time( double_ended_flag : bool A flag whether the measurement is double ended - Returns + Returns: ------- """ diff --git a/src/dtscalibration/plot.py b/src/dtscalibration/plot.py index d864cafe..6f28f1e9 100644 --- a/src/dtscalibration/plot.py +++ b/src/dtscalibration/plot.py @@ -16,8 +16,7 @@ def plot_residuals_reference_sections( method="split", cmap="RdBu_r", ): - """ - Analyze the residuals of the reference sections, between the Stokes + """Analyze the residuals of the reference sections, between the Stokes signal and a best-fit decaying exponential. @@ -45,7 +44,7 @@ def plot_residuals_reference_sections( Matplotlib colormap to use for the residual plot. By default it will use a diverging colormap. - Returns + Returns: ------- fig : Figurehandle @@ -244,8 +243,7 @@ def plot_residuals_reference_sections_single( units="", fig_kwargs=None, ): - """ - Analyze the residuals of the reference sections, between the Stokes + """Analyze the residuals of the reference sections, between the Stokes signal and a best-fit decaying exponential. @@ -269,7 +267,7 @@ def plot_residuals_reference_sections_single( "x" : str Name of the spatial dimension - Returns + Returns: ------- fig : Figurehandle @@ -379,8 +377,7 @@ def plot_accuracy( plot_names=True, sections=None, ): - """ - Analyze the residuals of the reference sections, between the Stokes + """Analyze the residuals of the reference sections, between the Stokes signal and a best-fit decaying exponential. @@ -402,7 +399,7 @@ def plot_accuracy( "x" : str Name of the spatial dimension - Returns + Returns: ------- fig : Figurehandle diff --git a/src/dtscalibration/variance_helpers.py b/src/dtscalibration/variance_helpers.py index 9ea6c834..aa243a54 100644 --- a/src/dtscalibration/variance_helpers.py +++ b/src/dtscalibration/variance_helpers.py @@ -170,8 +170,7 @@ def var_fun(stokes): def check_allclose_acquisitiontime(acquisitiontime, eps: float = 0.05) -> None: - """ - Check if all acquisition times are of equal duration. For now it is not possible to calibrate + """Check if all acquisition times are of equal duration. For now it is not possible to calibrate over timesteps if the acquisition time of timesteps varies, as the Stokes variance would change over time. @@ -184,7 +183,7 @@ def check_allclose_acquisitiontime(acquisitiontime, eps: float = 0.05) -> None: eps : float Default accepts 1% of relative variation between min and max acquisition time. - Returns + Returns: ------- """ dtmin = acquisitiontime.min() diff --git a/src/dtscalibration/variance_stokes.py b/src/dtscalibration/variance_stokes.py index 59819b87..fe6e5c4d 100644 --- a/src/dtscalibration/variance_stokes.py +++ b/src/dtscalibration/variance_stokes.py @@ -12,8 +12,7 @@ def variance_stokes_constant(st, sections, acquisitiontime, reshape_residuals=True): - """ - Approximate the variance of the noise in Stokes intensity measurements + """Approximate the variance of the noise in Stokes intensity measurements with one value, suitable for small setups. * `variance_stokes_constant()` for small setups with small variations in\ @@ -82,16 +81,15 @@ def variance_stokes_constant(st, sections, acquisitiontime, reshape_residuals=Tr st : DataArray sections : Dict[str, List[slice]] - Returns + Returns: ------- I_var : float Variance of the residuals between measured and best fit resid : array_like Residuals between measured and best fit - Notes + Notes: ----- - * Because there are a large number of unknowns, spend time on\ calculating an initial estimate. Can be turned off by setting to False. @@ -99,14 +97,14 @@ def variance_stokes_constant(st, sections, acquisitiontime, reshape_residuals=Tr your variance estimate does not change when including measurements\ additional time steps, you have included enough measurements. - References + References: ---------- .. [1] des Tombe, B., Schilperoort, B., & Bakker, M. (2020). Estimation of Temperature and Associated Uncertainty from Fiber-Optic Raman- Spectrum Distributed Temperature Sensing. Sensors, 20(8), 2235. https://doi.org/10.3390/s20082235 - Examples + Examples: -------- - `Example notebook 4: Calculate variance Stokes intensity measurements\