utdquake 0.0.1__py3-none-any.whl

utdquake/clients/local/client.py

@@ -0,0 +1,123 @@
+# /**
+#  * @author Emmanuel Castillo
+#  * @email [castillo.280997@gmail.com]
+#  * @create date 2024-09-22 22:07:55
+#  * @modify date 2024-09-22 22:07:55
+#  * @desc [description]
+#  */
+
+
+
+
+# import objects
+import os 
+import glob
+import sqlite3
+import pandas as pd
+from obspy import UTCDateTime
+from datetime import timedelta
+from obspy.core.util.misc import BAND_CODE
+from scan.stats import get_rolling_stats
+from obspy.clients.fdsn import Client as FDSNClient
+from obspy.clients.filesystem.sds import Client
+
+class LocalClient(Client):
+
+    def __init__(self,root,fmt,**kwargs):
+        """
+        This script is an example to make a client class
+        for specific data structure archive on local filesystem. 
+
+        The mandatory parameters for LocalClient class is: root_path and field_name
+        Example:
+        ---------
+        root = "/home/emmanuel/myarchive"
+        fmt = "{year}-{month:02d}/{year}-{month:02d}-{day:02d}/{network}.{station}.{location}.{channel}.{year}.{julday:03d}"
+        client = LocalClient(root,fmt)
+        st = client.get_waveforms("YY","XXXX","00",
+                                channel="HHZ",starttime = UTCDateTime("20220102T000100"),
+                                endtime = UTCDateTime("20220102T000200"))
+        
+        Parameters:
+        -----------
+        root: str
+            Path where is located the Local structure
+        fmt: str
+            The parameter should name the corresponding keys of the stats object, e.g. 
+            "{year}-{month:02d}/{year}-{month:02d}-{day:02d}/{network}.{station}.{location}.{channel}.{year}.{julday:03d}"
+
+        **kwargs SDS client additional args
+        """
+        self.root = root
+        self.fmt = fmt
+        super().__init__(root,**kwargs)
+
+    def _get_filenames(self, network, station, location, channel, starttime,
+                       endtime, sds_type=None):
+        """
+        Get list of filenames for certain waveform and time span.
+        :type network: str
+        :param network: Network code of requested data (e.g. "IU").
+        :type station: str
+        :param station: Station code of requested data (e.g. "ANMO").
+        :type location: str
+        :param location: Location code of requested data (e.g. "").
+        :type channel: str
+        :param channel: Channel code of requested data (e.g. "HHZ").
+        :type time: :class:`~obspy.core.utcdatetime.UTCDateTime`
+        :param time: Time of interest.
+        :type sds_type: str
+        :param sds_type: None
+        :rtype: str
+        """
+        sds_type = sds_type or self.sds_type
+        # SDS has data sometimes in adjacent days, so also try to read the
+        # requested data from those files. Usually this is only a few seconds
+        # of data after midnight, but for now we play safe here to catch all
+        # requested data (and with MiniSEED - the usual SDS file format - we
+        # can use starttime/endtime kwargs anyway to read only desired parts).
+        year_doy = set()
+        # determine how far before starttime/after endtime we should check
+        # other dayfiles for the data
+        t_buffer = self.fileborder_samples / BAND_CODE.get(channel[:1], 20.0)
+        t_buffer = max(t_buffer, self.fileborder_seconds)
+        t = starttime - t_buffer
+        t_max = endtime + t_buffer
+        # make a list of year/doy combinations that covers the whole requested
+        # time window (plus day before and day after)
+        while t < t_max:
+            year_doy.add((t.year,t.month,t.day, t.julday))
+            t += timedelta(days=1)
+        year_doy.add((t_max.year,t_max.month,t_max.day, t_max.julday))
+
+        full_paths = set()
+        for year,month,day,doy in year_doy:
+            filename = self.fmt.format(
+                            network=network, station=station, location=location,
+                            channel=channel, year=year, month=month, 
+                            day=day, julday=doy,sds_type=sds_type)
+            full_path = os.path.join(self.sds_root, filename)
+            full_paths = full_paths.union(glob.glob(full_path))
+        
+        return full_paths
+
+    def _get_filename(self, network, station, location, channel, time, sds_type=None):
+        """
+        Get filename for certain waveform.
+        :type network: str
+        :param network: Network code of requested data (e.g. "IU").
+        :type station: str
+        :param station: Station code of requested data (e.g. "ANMO").
+        :type location: str
+        :param location: Location code of requested data (e.g. "").
+        :type channel: str
+        :param channel: Channel code of requested data (e.g. "HHZ").
+        :type time: :class:`~obspy.core.utcdatetime.UTCDateTime`
+        :param time: Time of interest.
+        """
+        sds_type = sds_type or self.sds_type
+        filename = self.fmt.format(
+                    network=network, station=station, location=location,
+                    channel=channel, year=time.year, month=time.month, 
+                    day=time.day, doy=time.julday,sds_type=sds_type)
+        return os.path.join(self.sds_root, filename)

utdquake/clients/utd/client.py

@@ -0,0 +1,154 @@
+
+import os
+import pandas as pd
+from .utils import get_event_ids, get_custom_info, save_info
+from utdquake.tools.stats import get_rolling_stats
+from obspy.clients.fdsn import Client as FDSNClient
+
+class Client(FDSNClient):
+    """
+    A client class for retrieving and calculating rolling statistics on seismic data.
+
+    Inherits from:
+        FDSNClient: Base class for FDSN web service clients.
+
+    Attributes:
+        output (str): Path to the SQLite database file for saving results.
+        step (int): Step size for the rolling window in seconds.
+    """
+
+    def __init__(self,*args, **kwargs):
+        """
+        Initializes the Client class by calling the constructor 
+        of the base FDSN Client class.
+
+        Parameters:
+        *args : variable length argument list
+            Positional arguments passed to the base class constructor.
+        **kwargs : variable length keyword arguments
+            Keyword arguments passed to the base class constructor.
+        """
+        super().__init__(*args, **kwargs)
+
+    def get_custom_events(self, *args, max_events_in_ram=1e6, 
+                          output_folder=None, drop_level=True,
+                          **kwargs):
+        """
+        Retrieves custom seismic event data including origins, picks, 
+        and magnitudes.
+
+        Parameters:
+        *args : variable length argument list
+            Positional arguments passed to the get_events method.
+        max_events_in_ram : int, optional, default=1e6
+            Maximum number of events to hold in memory (RAM) before stopping or 
+            prompting to save the data to disk.
+        output_folder : str, optional, default=None
+            Folder path where the event data will be saved if provided. If not 
+            specified, data will only be stored in memory.
+        drop_level : bool, optional, default=True
+            True if you want to have only one level in your origin dataframe.
+        **kwargs : variable length keyword arguments
+            Keyword arguments passed to the get_events method.
+
+        Returns:
+        tuple
+            A tuple containing:
+            - DataFrame of origins for all events.
+            - DataFrame of picks for all events.
+            - DataFrame of magnitudes for all events.
+        """
+        # Retrieve the catalog of events using the get_events method
+        catalog = self.get_events(*args, **kwargs)
+
+        # Extract event IDs from the catalog
+        ev_ids = get_event_ids(catalog)
+
+        # Initialize lists to store origins, picks, and magnitudes
+        all_origins, all_picks, all_mags = [], [], []
+
+        # Loop through each event ID to gather detailed event information
+        for ev_id in ev_ids[::-1]:
+            # Catalog with arrivals. This is a workaround to retrieve 
+            # arrivals by specifying the event ID.
+            cat = self.get_events(eventid=ev_id)
+
+            # Get the first event from the catalog
+            event = cat[0]
+
+            # Extract custom information for the event
+            origin, picks, mags = get_custom_info(event, drop_level)
+
+            info = {
+                "origin": origin,
+                "picks": picks,
+                "mags": mags
+            }
+
+            # Save information to the output folder, if specified
+            if output_folder is not None:
+                if not os.path.isdir(output_folder):
+                    os.makedirs(output_folder)
+                save_info(output_folder, info=info)
+
+            # Append information to the lists or break if memory limit is reached
+            if len(all_origins) < max_events_in_ram:
+                all_origins.append(origin)
+                all_picks.append(picks)
+                all_mags.append(mags)
+            else:
+                if output_folder is not None:
+                    print(f"max_events_in_ram: {max_events_in_ram} is reached. "
+                        "But it is still saving on disk.")
+                else:
+                    print(f"max_events_in_ram: {max_events_in_ram} is reached. "
+                        "It is recommended to save the data on disk using the 'output_folder' parameter.")
+                    break
+
+        # Concatenate data from all events, if multiple events are found
+        if len(ev_ids) > 1:
+            all_origins = pd.concat(all_origins, axis=0)
+            all_picks = pd.concat(all_picks, axis=0)
+            all_mags = pd.concat(all_mags, axis=0)
+        else:
+            # If only one event is found, retain the single DataFrame
+            all_origins = all_origins[0]
+            all_picks = all_picks[0]
+            all_mags = all_mags[0]
+
+        return all_origins, all_picks, all_mags
+
+    def get_stats(self, output, step, starttime, endtime, **kwargs):
+        """
+        Retrieve waveforms and compute rolling statistics for the specified time interval.
+
+        Args:
+            output (str): Path to the SQLite database file for saving results.
+            step (int): Step size for the rolling window in seconds.
+            starttime (UTCDateTime): Start time of the data.
+            endtime (UTCDateTime): End time of the data.
+            **kwargs: Keyword arguments for retrieving waveforms, including:
+                - Additional arguments required by `self.get_waveforms`.
+
+        Returns:
+            pd.DataFrame: A DataFrame containing rolling statistics for each interval, with columns including:
+            - Availability percentage
+            - Gaps duration
+            - Overlaps duration
+            - Gaps count
+            - Overlaps count
+        """
+        # Extract start and end times from keyword arguments
+        # Retrieve waveforms using base class method
+        st = self.get_waveforms(**kwargs)
+
+        # Compute rolling statistics for the retrieved waveforms
+        stats = get_rolling_stats(
+            st=st,
+            step=step,
+            starttime=starttime.datetime,
+            endtime=endtime.datetime,
+            sqlite_output=output
+        )
+
+        return stats