tsp 1.8.1__py3-none-any.whl → 1.10.2__py3-none-any.whl

tsp/time.py

@@ -1,46 +1,46 @@
-import re
-from datetime import datetime, tzinfo
-
-from typing import Union
-
-
-def get_utc_offset(offset: "Union[str,int]") -> int:
-    """Get the UTC offset in seconds from a string or integer"""
-
-    if isinstance(offset, str):
-        if offset.lower() == "utc" or (offset.lower() == "z"):
-            return 0
-        
-        pattern = re.compile(r"([+-]?)(\d{2}):(\d{2})")
-        match = pattern.match(offset)
-        
-        if not match:
-            raise ValueError("Offset must be a string in the format '+HH:MM' or '-HH:MM'")
-        
-        sign = match.group(1)
-        hours = int(match.group(2))
-        minutes = int(match.group(3))
-        utc_offset = (hours*60 + minutes)*60
-        if sign == "-":
-            utc_offset *= -1
-
-    elif isinstance(offset, int):
-        utc_offset = offset
-
-    else:
-        raise ValueError("Offset must be a string in the format '+HH:MM' or '-HH:MM' or an integer in seconds")
-
-    return utc_offset
-
-
-def format_utc_offset(offset: tzinfo) -> str:
-    """Format a UTC offset as a string in the format '+HH:MM' or '-HH:MM'"""
-    utc_offset = offset.utcoffset(datetime.now()).total_seconds()
-    sign = "-" if utc_offset < 0 else "+"
-    hours = int(abs(utc_offset)//3600)
-    minutes = int(abs(utc_offset)%3600/60)
-    
-    if hours == 0 and minutes == 0:
-        return "UTC"
-
+import re
+from datetime import datetime, tzinfo
+
+from typing import Union
+
+
+def get_utc_offset(offset: "Union[str,int]") -> int:
+    """Get the UTC offset in seconds from a string or integer"""
+
+    if isinstance(offset, str):
+        if offset.lower() == "utc" or (offset.lower() == "z"):
+            return 0
+        
+        pattern = re.compile(r"([+-]?)(\d{2}):(\d{2})")
+        match = pattern.match(offset)
+        
+        if not match:
+            raise ValueError("Offset must be a string in the format '+HH:MM' or '-HH:MM'")
+        
+        sign = match.group(1)
+        hours = int(match.group(2))
+        minutes = int(match.group(3))
+        utc_offset = (hours*60 + minutes)*60
+        if sign == "-":
+            utc_offset *= -1
+
+    elif isinstance(offset, int):
+        utc_offset = offset
+
+    else:
+        raise ValueError("Offset must be a string in the format '+HH:MM' or '-HH:MM' or an integer in seconds")
+
+    return utc_offset
+
+
+def format_utc_offset(offset: tzinfo) -> str:
+    """Format a UTC offset as a string in the format '+HH:MM' or '-HH:MM'"""
+    utc_offset = offset.utcoffset(datetime.now()).total_seconds()
+    sign = "-" if utc_offset < 0 else "+"
+    hours = int(abs(utc_offset)//3600)
+    minutes = int(abs(utc_offset)%3600/60)
+    
+    if hours == 0 and minutes == 0:
+        return "UTC"
+
     return f"{sign}{hours:02d}:{minutes:02d}"

tsp/tspwarnings.py

@@ -1,15 +1,27 @@
-import numpy as np
-
-
-class DuplicateTimesWarning(UserWarning):
-    """For when duplicate times are found in a file."""
-    def __init__(self, times):
-        self.times = times
-    
-    def _msg(self, times) -> str:
-        m = f"Duplicate timestamps found: {times[np.where(times.duplicated())[0]]}. That's bad."
-        return m
-    
-    def __str__(self):
-        return self._msg(self.times)
-    
+import numpy as np
+
+
+class DuplicateTimesWarning(UserWarning):
+    """For when duplicate times are found in a file."""
+    def __init__(self, times):
+        self.times = times
+    
+    def _msg(self, times) -> str:
+        m = f"Duplicate timestamps found: {times[np.where(times.duplicated())[0]]}. That's bad."
+        return m
+    
+    def __str__(self):
+        return self._msg(self.times)
+
+class NonIncreasingTimesWarning(UserWarning):
+    """For when non-increasing times are found in a file."""
+    def __init__(self, times):
+        self.times = times
+    
+    def _msg(self, times) -> str:
+        n_bad = np.sum(np.diff(times.values) <= np.timedelta64(0, 'ns'))
+        m = f"{n_bad} non-increasing timestamps found. That's bad."
+        return m
+    
+    def __str__(self):
+        return self._msg(self.times)

tsp/utils.py

@@ -1,101 +1,131 @@
-import pandas as pd
-import numpy as np
-
-import tsp
-from tsp import TSP
-
-
-def resolve_duplicate_times(t: TSP, keep="first") -> TSP:
-    """Eliminate duplicate times in a TSP.
-    
-    Parameters
-    ----------
-    tsp : TSP
-        TSP to resolve duplicate times in.
-    keep : str, optional
-        Method to resolve duplicate times. Chosen from "first", "average", "last", "strip"
-        by default "first"
-    
-    Returns
-    -------
-    TSP
-        TSP with no duplicated times."""
-    resolver = _get_duplicate_resolver(keep)
-    return resolver(t)
-    
-
-def _get_duplicate_resolver(keep: str):
-    if keep == "first":
-        return _first_duplicate_time
-    elif keep == "average":
-        return _average_duplicate_time
-    elif keep == "last":
-        return _last_duplicate_time
-    elif keep == "strip":
-        return _strip_duplicate_time
-    else:
-        raise ValueError(f"Unknown duplicate resolver method: {keep}")
-
-
-def _first_duplicate_time(t: TSP):
-    df = t.wide
-    df = df[~df.index.duplicated(keep="first")]
-    
-    time = df.index
-    values = df.drop(['time'], axis=1).values
-    depths = df.drop(['time'], axis=1).columns
-    
-    t_new = TSP(times=time, values=values, depths=depths, 
-                latitude=t.latitude, longitude=t.longitude,
-                site_id=t.site_id, metadata=t.metadata)
-    
-    return t_new
-
-
-def _last_duplicate_time(t: TSP):
-    df = t.wide
-    df = df[~df.index.duplicated(keep="last")]
-    
-    time = df.index
-    values = df.drop(['time'], axis=1).values
-    depths = df.drop(['time'], axis=1).columns
-    
-    t_new = TSP(times=time, values=values, depths=depths, 
-                latitude=t.latitude, longitude=t.longitude,
-                site_id=t.site_id, metadata=t.metadata)
-    
-    return t_new
-
-
-def _strip_duplicate_time(t: TSP):
-    df = t.wide
-    df = df[~df.index.duplicated(keep=False)]
-
-    time = df.index
-    values = df.drop(['time'], axis=1).values
-    depths = df.drop(['time'], axis=1).columns
-    
-    t_new = TSP(times=time, values=values, depths=depths, 
-                latitude=t.latitude, longitude=t.longitude,
-                site_id=t.site_id, metadata=t.metadata)
-    
-    return t_new
-
-
-def _average_duplicate_time(t: TSP):
-    singleton = t.wide[~t.wide.index.duplicated(keep=False)]
-    duplicated = t.wide[t.wide.index.duplicated(keep=False)].drop(['time'], axis=1).reset_index()
-    averaged = duplicated.groupby(duplicated['index']).apply(lambda x: x[~x.isna()].mean(numeric_only=True))  
-    averaged.insert(0, 'time',averaged.index)
-
-    df = pd.concat([singleton, averaged], ignore_index=False).sort_index()
-
-    time = df.index
-    values = df.drop(['time'], axis=1).values
-    depths = df.drop(['time'], axis=1).columns
-
-    t_new = TSP(times=time, values=values, depths=depths, 
-                latitude=t.latitude, longitude=t.longitude,
-                site_id=t.site_id, metadata=t.metadata)
-    
-    return t_new
+import pandas as pd
+import numpy as np
+import warnings
+
+import tsp
+from tsp import TSP
+
+
+def resolve_duplicate_times(t: TSP, keep="first") -> TSP:
+    """Eliminate duplicate times in a TSP.
+    
+    Parameters
+    ----------
+    tsp : TSP
+        TSP to resolve duplicate times in.
+    keep : str, optional
+        Method to resolve duplicate times. Chosen from "first", "average", "last", "strip"
+        by default "first"
+    
+    Returns
+    -------
+    TSP
+        TSP with no duplicated times."""
+    resolver = _get_duplicate_resolver(keep)
+    return resolver(t)
+    
+
+def _get_duplicate_resolver(keep: str):
+    if keep == "first":
+        return _first_duplicate_time
+    elif keep == "average":
+        return _average_duplicate_time
+    elif keep == "last":
+        return _last_duplicate_time
+    elif keep == "strip":
+        return _strip_duplicate_time
+    else:
+        raise ValueError(f"Unknown duplicate resolver method: {keep}")
+
+
+def _first_duplicate_time(t: TSP):
+    df = t.wide
+    df = df[~df.index.duplicated(keep="first")]
+    
+    time = df.index
+    values = df.drop(['time'], axis=1).values
+    depths = df.drop(['time'], axis=1).columns
+    
+    t_new = TSP(times=time, values=values, depths=depths, 
+                latitude=t.latitude, longitude=t.longitude,
+                site_id=t.site_id, metadata=t.metadata)
+    
+    return t_new
+
+
+def _last_duplicate_time(t: TSP):
+    df = t.wide
+    df = df[~df.index.duplicated(keep="last")]
+    
+    time = df.index
+    values = df.drop(['time'], axis=1).values
+    depths = df.drop(['time'], axis=1).columns
+    
+    t_new = TSP(times=time, values=values, depths=depths, 
+                latitude=t.latitude, longitude=t.longitude,
+                site_id=t.site_id, metadata=t.metadata)
+    
+    return t_new
+
+
+def _strip_duplicate_time(t: TSP):
+    df = t.wide
+    df = df[~df.index.duplicated(keep=False)]
+
+    time = df.index
+    values = df.drop(['time'], axis=1).values
+    depths = df.drop(['time'], axis=1).columns
+    
+    t_new = TSP(times=time, values=values, depths=depths, 
+                latitude=t.latitude, longitude=t.longitude,
+                site_id=t.site_id, metadata=t.metadata)
+    
+    return t_new
+
+
+def _average_duplicate_time(t: TSP):
+    singleton = t.wide[~t.wide.index.duplicated(keep=False)]
+    duplicated = t.wide[t.wide.index.duplicated(keep=False)].drop(['time'], axis=1).reset_index()
+    averaged = duplicated.groupby(duplicated['index']).apply(lambda x: x[~x.isna()].mean(numeric_only=True))  
+    averaged.insert(0, 'time',averaged.index)
+
+    df = pd.concat([singleton, averaged], ignore_index=False).sort_index()
+
+    time = df.index
+    values = df.drop(['time'], axis=1).values
+    depths = df.drop(['time'], axis=1).columns
+
+    t_new = TSP(times=time, values=values, depths=depths, 
+                latitude=t.latitude, longitude=t.longitude,
+                site_id=t.site_id, metadata=t.metadata)
+    
+    return t_new
+
+
+def midnight_offset_24_hr(t: TSP, reverse: bool = False) -> TSP:
+    """ (de-)increment any timestamps that are exactly at midnight by 24 hours.
+    
+    Description:
+    -----------
+    Some dataloggers misattribute data at midnight to the previous day 
+    which can cause problems when plotting or analyzing data. This function
+    corrects any timestamps that are exactly at midnight by adding/subtracting 24 hours.
+    """
+    
+    values = t.values.copy()
+    midnight_indices = np.where(t.times.hour==0)[0]
+    times = t.times.to_numpy().copy()
+    if len(midnight_indices) > 0:
+        if reverse:
+            times[midnight_indices] -= np.timedelta64(24, 'h')
+        else:
+            times[midnight_indices] += np.timedelta64(24, 'h')
+    
+    with warnings.catch_warnings():
+        warnings.filterwarnings("ignore", category=tsp.tspwarnings.NonIncreasingTimesWarning)
+        
+    t_new = TSP(times=times, values=values, depths=t.depths,
+                latitude=t.latitude, longitude=t.longitude,
+                site_id=t.site_id, metadata=t.metadata)
+    
+    return t_new

tsp/version.py

@@ -1 +1 @@
-version="1.8.1"
+version="1.10.2"

{tsp-1.8.1.dist-info → tsp-1.10.2.dist-info}/METADATA

@@ -1,86 +1,95 @@
-Metadata-Version: 2.4
-Name: tsp
-Version: 1.8.1
-Summary: Making permafrost data effortless
-Home-page: https://gitlab.com/permafrostnet/teaspoon
-Author: Nick Brown
-Author-email: nick.brown@carleton.ca
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: GNU General Public License (GPL)
-Classifier: Operating System :: POSIX
-Classifier: Programming Language :: Python
-Classifier: Topic :: Software Development :: Libraries
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: pandas
-Requires-Dist: numpy
-Requires-Dist: regex
-Requires-Dist: matplotlib
-Requires-Dist: setuptools
-Provides-Extra: nc
-Requires-Dist: netCDF4; extra == "nc"
-Requires-Dist: pfit==0.2.1; extra == "nc"
-Provides-Extra: plotting
-Requires-Dist: scipy; extra == "plotting"
-Provides-Extra: rbr
-Requires-Dist: pyrsktools; extra == "rbr"
-Requires-Dist: openpyxl; extra == "rbr"
-Provides-Extra: full
-Requires-Dist: scipy; extra == "full"
-Requires-Dist: pfit==0.2.1; extra == "full"
-Requires-Dist: netCDF4; extra == "full"
-Requires-Dist: pyrsktools; extra == "full"
-Requires-Dist: openpyxl; extra == "full"
-Provides-Extra: dev
-Requires-Dist: manuel; extra == "dev"
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: pytest-cov; extra == "dev"
-Requires-Dist: coverage; extra == "dev"
-Requires-Dist: mock; extra == "dev"
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: license-file
-Dynamic: provides-extra
-Dynamic: requires-dist
-Dynamic: summary
-
-# Teaspoon
-
-## See the full documentation on the [ReadTheDocs Pages](https://permafrostnet.gitlab.io/teaspoon/source/about.html)
-
-## [What is it?](https://permafrostnet.gitlab.io/teaspoon/source/about.html)
-`tsp` ('teaspoon') is a python library designed to make working with permafrost ground temperature time series data more straightforward, efficient, and reproduceable. Some of the features include:
-
-* Read a variety of common published data formats, datalogger outputs, and model results into a common data structure
-    * GEOtop model output
-    * GTN-P database export csv
-    * NTGS ground temperature report csv
-    * Geoprecision datalogger export
-    * HoboWare datalogger export
-* Export data in a variety of common formats
-    * netcdf
-    * 'GTN-P'-style csv
-    * 'NTGS'-style csv
-* Perform common data transformations
-    * Calculate daily, monthly, or yearly means, ignoring averaging periods with missing data
-    * Switch between "long" and "wide" dataframes
-* Visualize and explore your data with commonly used plots
-    * Trumpet curves
-    * Temperature-time graphs
-    * Colour-contour profiles
-
-## [Installation](https://permafrostnet.gitlab.io/teaspoon/source/install.html)
-
-## [Usage Examples](https://permafrostnet.gitlab.io/teaspoon/source/examples.html)
-
-## [How to contribute](https://permafrostnet.gitlab.io/teaspoon/source/contributions.html)
-
-## Citation
-If you find this software helpful, please consider using the following citation:
-
-> Brown, N., (2022). tsp ("Teaspoon"): A library for ground temperature data. Journal of Open Source Software, 7(77), 4704, [https://doi.org/10.21105/joss.04704](https://doi.org/10.21105/joss.04704)
+Metadata-Version: 2.4
+Name: tsp
+Version: 1.10.2
+Summary: Making permafrost data effortless
+Home-page: https://gitlab.com/permafrostnet/teaspoon
+Author: Nick Brown
+Author-email: nick.brown@carleton.ca
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License (GPL)
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python
+Classifier: Topic :: Software Development :: Libraries
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas
+Requires-Dist: numpy
+Requires-Dist: regex
+Requires-Dist: matplotlib
+Requires-Dist: setuptools
+Requires-Dist: netCDF4
+Requires-Dist: pfit>=0.3.0
+Requires-Dist: scipy
+Requires-Dist: pyrsktools
+Requires-Dist: openpyxl
+Provides-Extra: nc
+Requires-Dist: netCDF4; extra == "nc"
+Requires-Dist: pfit>=0.3.0; extra == "nc"
+Provides-Extra: plotting
+Requires-Dist: scipy; extra == "plotting"
+Provides-Extra: rbr
+Requires-Dist: pyrsktools; extra == "rbr"
+Requires-Dist: openpyxl; extra == "rbr"
+Provides-Extra: full
+Requires-Dist: scipy; extra == "full"
+Requires-Dist: pyrsktools; extra == "full"
+Requires-Dist: netCDF4; extra == "full"
+Requires-Dist: openpyxl; extra == "full"
+Requires-Dist: pfit>=0.3.0; extra == "full"
+Provides-Extra: dev
+Requires-Dist: manuel; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: mock; extra == "dev"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: summary
+
+# Teaspoon
+
+## See the full documentation on the [ReadTheDocs Pages](https://permafrostnet.gitlab.io/teaspoon/source/about.html)
+
+## [What is it?](https://permafrostnet.gitlab.io/teaspoon/source/about.html)
+`tsp` ('teaspoon') is a python library designed to make working with permafrost ground temperature time series data more straightforward, efficient, and reproduceable. Some of the features include:
+
+* Read a variety of common published data formats, datalogger outputs, and model results into a common data structure
+    * GEOtop model output
+    * GTN-P database export csv
+    * NTGS ground temperature report csv
+    * Geoprecision datalogger export
+    * HoboWare datalogger export
+* Export data in a variety of common formats
+    * TSP-recommended csv format
+    * netcdf
+    * 'GTN-P'-style csv
+    * 'NTGS'-style csv
+* Perform common data transformations
+    * Calculate daily, monthly, or yearly means, ignoring averaging periods with missing data
+    * Switch between "long" and "wide" dataframes
+* Visualize and explore your data with commonly used plots
+    * Trumpet curves
+    * Temperature-time graphs
+    * Colour-contour profiles
+
+## [Installation](https://permafrostnet.gitlab.io/teaspoon/source/install.html)
+
+## [Usage Examples](https://permafrostnet.gitlab.io/teaspoon/source/examples.html)
+
+## [How to contribute](https://permafrostnet.gitlab.io/teaspoon/source/contributions.html)
+
+## Data Standard
+TSP also defines a recommended csv format for ground temperature data (which can also be extended to many other kinds of permafrost data). It is described in the [DATA_STANDARD.md](./DATA_STANDARD.md) file in this directory. Files can be read (using the `TSP.to_csv` method) and written (using `read_tsp`) using the teaspoon software package. 
+
+## Citation
+If you find this software helpful, please consider using the following citation:
+
+> Brown, N., (2022). tsp ("Teaspoon"): A library for ground temperature data. Journal of Open Source Software, 7(77), 4704, [https://doi.org/10.21105/joss.04704](https://doi.org/10.21105/joss.04704)