{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Data Structure\n",
    "\n",
    "\n",
    "The following datasets are required:\n",
    "\n",
    "1. `Obspy.Stream` with station metadata added.\n",
    "2. Station ``Subnetworks``.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Imports"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from obspy import UTCDateTime\n",
    "from obspy.core import AttribDict\n",
    "from obspy.clients.fdsn import Client\n",
    "client = Client(\"IRIS\")\n",
    " \n",
    "import seisscan as ss"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## ObsPy.Stream with station metadata added\n",
    "\n",
    "An `ObsPy.Stream` object contains a number of `Obspy.Trace` objects. Station coordinates are to be attached to each `Obspy.Trace`. Optionally, station response information can also be attached to `Obspy.Trace`. Let's follow the [ObsPy example](https://docs.obspy.org/packages/obspy.clients.fdsn.html) to download data and metadata.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Define starttime and endtime\n",
    "starttime = UTCDateTime(\"2010-02-27T06:45:00.000\")\n",
    "endtime = starttime + 60\n",
    "\n",
    "# Download Stream\n",
    "st = client.get_waveforms(\"IU\", \"ANMO\", \"00\", \"LHZ\", starttime, endtime, attach_response=True)\n",
    "\n",
    "#- Download station metadata\n",
    "inventory = client.get_stations(network=\"IU\", station=\"ANMO\", location=\"00\", channel=\"LHZ\",\n",
    "                                starttime=starttime, endtime=endtime, level=\"response\")\n",
    "    \n",
    "    \n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Station coordinates can be attached to each `Obspy.Trace` as shown below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "               network: IU\n",
      "               station: ANMO\n",
      "              location: 00\n",
      "               channel: LHZ\n",
      "             starttime: 2010-02-27T06:45:00.069538Z\n",
      "               endtime: 2010-02-27T06:45:59.069538Z\n",
      "         sampling_rate: 1.0\n",
      "                 delta: 1.0\n",
      "                  npts: 60\n",
      "                 calib: 1.0\n",
      "_fdsnws_dataselect_url: http://service.iris.edu/fdsnws/dataselect/1/query\n",
      "               _format: MSEED\n",
      "                 mseed: AttribDict({'dataquality': 'M', 'number_of_records': 1, 'encoding': 'STEIM2', 'byteorder': '>', 'record_length': 512, 'filesize': 512})\n",
      "            processing: ['ObsPy 1.4.0: trim(endtime=UTCDateTime(2010, 2, 27, 6, 46, 0, 69538)::fill_value=None::nearest_sample=True::pad=False::starttime=UTCDateTime(2010, 2, 27, 6, 45, 0, 69538))']\n",
      "              response: Channel Response\n",
      "\tFrom m/s (Velocity in Meters Per Second) to counts (Digital Counts)\n",
      "\tOverall Sensitivity: 3.25959e+09 defined at 0.020 Hz\n",
      "\t3 stages:\n",
      "\t\tStage 1: PolesZerosResponseStage from m/s to V, gain: 1952.1\n",
      "\t\tStage 2: CoefficientsTypeResponseStage from V to counts, gain: 1.67772e+06\n",
      "\t\tStage 3: CoefficientsTypeResponseStage from counts to counts, gain: 1\n",
      "                   sac: AttribDict({'stlo': -106.457133, 'stla': 34.945981, 'stel': 1671.0})\n"
     ]
    }
   ],
   "source": [
    "# loop over st\n",
    "for tr in st:\n",
    "    coordinates = inventory.get_coordinates(tr.id, datetime=tr.stats.starttime)\n",
    "    tr.stats.sac = AttribDict()\n",
    "    tr.stats.sac.stlo = coordinates['longitude']\n",
    "    tr.stats.sac.stla = coordinates['latitude']\n",
    "    tr.stats.sac.stel = coordinates['elevation']\n",
    "\n",
    "# print stats of the first\n",
    "print(st[0].stats)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Alternate method to attach station metadata\n",
    "\n",
    "**Alternatively**, the function `SeisScan.read_fdsn` can be used to retrive `ObsPy.Stream` with station metadata attached. It utilizes [FDSN web service client for ObsPy](https://docs.obspy.org/packages/obspy.clients.fdsn.html) to request `ObsPy.Stream` object and station metadata (station coordinates and response information). Finally, it attaches the metadata information to each `ObsPy.Trace` of the `Obspy.Stream` object and returns the `Obspy.Stream` object. The following example is similar to the previous example.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "starttime = UTCDateTime(\"2010-02-27T06:45:00.000\")\n",
    "endtime = starttime + 60\n",
    "\n",
    "st = ss.read_fdsn(starttime, endtime, \"IU\", \"ANMO\", \"00\", \"LHZ\", provider=\"IRIS\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Station Subnetworks\n",
    "\n",
    "\n",
    "<img src=\"seisscan_images/subnetwork.jpg\" alt=\"Alt text\" width=\"650\" height=\"300\"/>\n",
    "\n",
    "\n",
    "A `Subnetwork` is a station cluster where the central station is defined as the reference station, whereas the remaining stations are called secondary stations. It is represented by a `dictionary` with two keys, `reference` and `secondaries`. The value of `reference` is the central station code and the value of `secondaries` is a `list` of secondary station codes. An example is given below.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "subnetwork = {\"reference\": \"STA01\", \"secondaries\":[\"STA02\", \"STA03\"]}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A `Subnetworks` is a `list` of `Subnetwork`. For example,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "subnetwork_1 = {\"reference\": \"STA01\", \"secondaries\":[\"STA02\", \"STA03\"]}\n",
    "subnetwork_2 = {\"reference\": \"STA11\", \"secondaries\":[\"STA12\", \"STA13\"]}\n",
    "subnetwork_3 = {\"reference\": \"STA21\", \"secondaries\":[\"STA22\", \"STA23\"]}\n",
    "subnetworks = [subnetwork_1, subnetwork_2, subnetwork_3]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import os\n",
    "os.path.exists(\"seisscan_images/subnetwork.jpg\")"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "SeisScan",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.14"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}