Download Seismic Records from the FDSN network

-------------------------------------------------------------------------------------------------------------------------------------------
       Download Seismic Records from the FDSN network
                       Version 1.0
-------------------------------------------------------------------------------------------------------------------------------------------
      Department of Theoretical Physics and the Cosmos, Science Faculty
---- Instituto Andaluz de Geofísica y Prevención de Desastres Sísmicos ----------
      Granada University (Ugr), Granada, Spain
-------------------------------------------------------------------------------------------------------------------------------------------

    Author: Ligdamis Gutiérrez PhD (1, 2)
    Granada, Spain 2021-2022

Institutions associated:

(1) Department of Theoretical Physics and Cosmos. Science Faculty. Avd. Fuentenueva s/n. University of Granada. 18071. Granada. Spain.

(2) Andalusian Institute of Geophysiscs. Campus de Cartuja. University of Granada. C/Profesor Clavera 12. 18071. Granada. Spain.

'' WARNING: Do not modify or edit the code without permission of the author.
    In case of using this software, indicate and refer to the author and the institution he represents.
    The University of Granada, Ugr ''

-------------------------------------------------------------------------------------------------------------------------------------------

Acknowledgment:

This software is the product of the research by the Spanish FEMALE project (PID2019-106260GB-I00).
FEMALE (Forecasting Volcanic Eruptions Using Signal Processing and Machine Learning Techniques on Seismic Signals)
https://femalevolcanoes.es/

-------------------------------------------------------------------------------------------------------------------------------------------

Introduction:

Dear User:

This file contains information related to the Application.
Please read it carefully before starting work.

In the same way, it is recommended to review the contents of the manual attached to the documents, in order to become familiar with the different actions that can be carried out, through the elements of system management.

The system was developed in version 3.8.6. of the Python language.
The software is open source and can be downloaded from the website:

https://www.python.org/downloads/release/python-386/

It works on 32 and 64 Bit Systems (x86, win64), under Windows (7, 8, 10).
It has also been tested on Linux systems on Ubuntu 20.

The version of Python in which the interface has been programmed is 3.8.6.
Any modification of the Python codes in a different version can be cause alterations in the functioning of the system.
The Python documentation must be revised to adapt the code to the correct version.

For the reading and manipulation of common file formats, access data centers and seismological signal processing routines the ObsPy library is used. ObsPy is a Python framework for Seismology, is an open-source. The documentation can be downloaded from the website:

https://docs.obspy.org/

Although it is not required in this module, in other modules of the system, the Matplotlib library is used to plot graphs. The documentation and terms of the use of the license of the Matplotlib by the user
can be read and downloaded from the website:

https://matplotlib.org/stable/users/index.html

IMPORTANT NOTE:  ********************************

In versions of Matplotlib lower than 3.4, it is necessary to update this library.
Due to the use of the tool to cut seismic events, they need these updates that are not considered in lower versions.
To do this, open a command window (CMD) and type the following command using the PIP:

       pip install -U matplotlib

On Linux systems "sudo" is used as super-user as follows:

       sudo pip install -U matplotlib

*****************************************************

The main interface is designed in English. The user manual document is written in Spanish.

-------------------------------------------------------------------------------------------------------------------------------------------
GENERAL CONTENT INDEX
-------------------------------------------------------------------------------------------------------------------------------------------
1.- Main system objective.
2.- General structure and folders organization.
3.- Description of the Folders and elements containing.
4.- Prerequisites (installing Python and Pip on windows)
5.- System installation and running under windows
6.- System installation and running under Linux
7.- Installation comments.
8.- Modules under construction.

-------------------------------------------------------------------------------------------------------------------------------------------
1.- MAIN OBJECTIVE OF THE SYSTEM
-------------------------------------------------------------------------------------------------------------------------------------------

Through a user-friendly interface, this application represents the first version of a software that provides "Download Seismic Records from the FDSN network (Federation of Digital Seismograph Networks), that help the human operator to:

a) In this way, a reliable automatic tool is available, which provides help to the operator to be able to download seismic records,
   whether tectonic or volcanic. Once the records have been downloaded, specific spectral analysis processes can be carried out on the seismic signals,
   using the software or modules that complement this system. Such as:
 
    * Several ways of spectral analysis of seismic-volcanic signals, of different formats
        (SAC, MSEED, GSE2, EVT, WAV among others),
        * Through the process of filtering the signals with filters:
         (Lowpass, Highpass, Bandpass and Bandstop).
        * Apply integral calculation techniques to seismic signals.
        * Perform cutting and merging of events in the records, among others.

-------------------------------------------------------------------------------------------------------------------------------------------
2.- GENERAL STRUCTURE AND ORGANIZATION OF FOLDERS
-------------------------------------------------------------------------------------------------------------------------------------------

Main items to download: Two compressed files in "Rar" format, containing the following:

a) Structure of the content to download files in:
     1.- Document folder
          1.1.- Download_Records_FDSN_User_Manual.pdf
          1.2.- README.txt
          1.3.- Download_FDSN_1.bat (download and copy to windows desktop)
          1.4.- Initial_requeriments.txt
     2.- Download_FDSN_1 folder, main software folder (Compressed folder with WinRar)
           2.1.- Images folder: (Icons and images, Folder must be inside the main folder)
           (Analysis, Back, Clean, Exit, Filter, IAG, Load, Next, Ugr).gif
            Masaya_Volcanoe.JPG, etc.
           2.2.- Download_FDSN_1.py main program (program must be inside the main folder)
           2.3.- Index.py program (program must be inside the main folder)
                    Welcome interface to access the main interface.
    
-------------------------------------------------------------------------------------------------------------------------------------------
3.- DESCRIPTION OF THE FOLDERS AND ELEMENTS CONTAINNING
-------------------------------------------------------------------------------------------------------------------------------------------

- In the main part there are the necessary programs for the operation of the analysis system
 
- The content is as follows:

   a) The user manual (PDF). System user manual, written in Spanish.
       It contains the necessary instructions for handling the system and the elements that make it up.
   b) The file README.txt. Contains the basic instructions for installing the software and all items
        that make up the system
   c) The file "Initial_requeriments.txt" contains the list of necessary libraries that python uses to run this system.
       It is recommended to execute each line in a console or "CMD" window, for the installation of the libraries                  
       through "Pip", after installing Python.
   d) The ".bat" file (Download_FDSN_1.bat), that facilitate the start of the system in Windows System.
        These files present a Welcome screen change to the working directory
        where the programs are located and run python with the startup program         
        "Index.py" to start the system.
   e) "Download_FDSN_1.py" Program of the interface. It is the main program.
   
   f) "Images" folder, which contains the icons and images of the interface. It must be located in the same place as             
        the main program. This is in the "My Documents" folder.

** At future, this Software may be expanded by adding new modules, containing other analysis tools,
     such as new Algorithm and analysis Methods, as well several classification and analysis modules. **

-------------------------------------------------------------------------------------------------------------------------------------------
4.- PREREQUISITES (INSTALLING PYTHON AND PIP ON WINDOWS)
-------------------------------------------------------------------------------------------------------------------------------------------

It's recommended to have at least 8 GB or more of memory in the system.

Python and its package manager (Pip) are native to Linux languages. That is, when Linux is installed, both the Python language and its package manager (Pip) are installed. Although it is always recommended to have the most up-to-date version, both of Python and pip. what in Linux is done almost automatically with the application manager and that, in addition, Linux generally communicates to the user.

In the Windows system, it must be installed before using the system. Because the system itself has been created with this language. The good thing is that Python can run without problems on Windows operating systems.

There is an easy way to do this.

a) Download the appropriate version from the Python distribution web page, located at the following web address:
             https://www.python.org/downloads/

    On the Web, the correct version must be selected, according to the type of operating system
    that is in the computer, including if it is 32 or 64 bits.

    On the Web, both the executable version (.exe) and the compressed file version (.zip) or (.tz) for Linux are available for download.

Once this version is downloaded, it is installed in the operating system (as administrator). When starting the installation, a screen of the installation assistant is presented, which indicates the steps to follow to install the language.

You just have to follow the steps. It is important to leave the box to add to the windows "path" the installation path where the Python files are located. If you skip this step, you have to do this manually. Because if it is not set, Python is not recognized by the system to run.

Manually, this can also be set from the system environment variables. Manually found in: Control Panel/System/Advanced System Settings/Environment Variables/Edit

Here you set where the Python scripts and programs are located on the system. But the easiest and most prudent thing to do is to simply check the box that allows this during the Python installation.

Once Python and pip are installed on the system, check that they work. To do this, you just have to see this in a windows command window (CMD), using the following commands.

> python –V

And to verify the “pip” the following command is typed:

> pip –V

After typing “pip – V”, it is usually seen that the version of pip is “20.2.1”. At this point, it is recommended to update that version, since by default "pip" is installed together with "Python", but it does not install the latest or most updated version. To do this, in the CMD window or console, type the following command in: (Windows/Linux).

> python –m pip install –upgrade pip    |   $ sudo python3 –m pip install –upgrade pip

This indicates that the "pip" will be updated to its latest version (In Linux, as "superuser", that is, "sudo" at startup). Note that for Windows, you type "python", but on Linux you must type "python3".

Once Python is installed and the "pip" is updated, you must proceed to install the additional packages and libraries that Python needs to run the system. This is done using the "pip". To do this, the file "Initial_requeriments.txt" is used, which is found with supplied files.

Proceed in the console or command window "Cmd" to install each recommended library.

Once this is done, the operating system is ready to run both python and the main program.

-------------------------------------------------------------------------------------------------------------------------------------------
5.- SYSTEM INSTALLATION AND RUNNING UNDER WINDOWS
-------------------------------------------------------------------------------------------------------------------------------------------

After downloading the items and once both the Python and the necessary additional libraries have been installed.

To install the system on Windows systems (either 32 or 64 bits), do the following:

a)  Copy the (all) folder containing the Python and data files.
     This is according to the "English" version 1.0
     Path to "Documents\Download_FDSN_1\"
     Remember, these folders (Data and Download_FDSN_1), should be copied to "My Documents" on the computer.

b) Copy the ".bat" file (Download_FDSN_1.bat), to the desktop of the computer.

c) In the desktop, run this file as "administrator" (right click on the file and choose this option)
     The Welcome screen will be displayed:

                 ==================================================
                 =                                                                                                =
                 =      Welcome to:                                                                        =
                 =                                                                                                 =
                 =    Download Seismic Records from the FDSN network      =
                 =                                                                                                 =
                 =    Department of Theoretical Physics and Cosmos.                      =
                 =             Science Faculty                                                             =
                 =     Andalusian Institute of Geophysics                                          =
                 =     Granada University (Ugr)                                                       =
                 =                                                                                                  =
                 =    Developed in Python 3.8.6                                                       =
                 =    Execution for Windows and Linux System                                =
                 =    Ligdamis A. Gutiérrez E. PhD.                                                =
                 ==================================================

           Please, Minimize the CMD from the Python.exe window (in black).
               (Don't close it, because the system also closes).           
           When you exit the system, this window closes automatically.
           
                       To continue, please press a key.

                  *** Please, press a key to Start the System. ***   
    
Pressing any key will present two screens. One in black, which is the Python command window (cmd).
This must be minimized, so that it does not disturb the view of the system.

The start and welcome screen of the "Index.py" system will be presented. This screen is the presentation and entry to the system.
You can exit from here by clicking the "Exit" button, or continue by clicking the "Next" button.

When clicking the "Next" button, it presents the main interface.

This will present the main screen of the system. This is where load the seismic record, filter analysis, and cut records are performed.
In addition to presenting the resulting graphics. See the attached user manual in the documentation.

To exit, click the "Exit" button. In the dialog window, type "Ok" to accept the output. Otherwise "Cancel" to continue in the system.

IMPORTANT NOTE:
Also, the program can be accessed through a command window (CMD), copying the path of the file (file.py) using the command “cd (path/..file.py)”.
In this way, use the command “python Download_FDSN_1.py” and give “Enter”, which will execute directly the program.

-------------------------------------------------------------------------------------------------------------------------------------------
6.- SYSTEM INSTALLATION AND RUNNING UNDER LINUX
-------------------------------------------------------------------------------------------------------------------------------------------

Installation on Linux systems is similar to Windows. The main folder is copied either to the desktop, or to the personal folder, etc.

This is according to the "English" version 1.0
    Path to "Documents\Download_FDSN_1\"

From that location (inside the main folder, where the "Index.py", Download_FDSN_1.py, Images and Data_Examples files and folders " are located), open a window or command console and type:

“$ python3 Index.py”

This command is to start the system and proceed to perform the analysis normally.
The output is similar to Windows System, must be clicking in the "Exit" button.

Remember:
Once Python is installed and the "pip" is updated, you must proceed to install the additional packages and libraries that Python needs to run the system.
This is done using the "pip". To do this, the file "Initial_requeriments.txt" is used, which is found with supplied files.

IMPORTANT NOTE:
Also, the program can be accessed through a command window or command console, copying the path of the file (file.py) using the command “cd (path/..file.py)”.
In this way, use the command “python3 Download_FDSN_1.py” and give “Enter”, which will execute directly the program.

-------------------------------------------------------------------------------------------------------------------------------------------
7.- INSTALLATION COMMENTS
-------------------------------------------------------------------------------------------------------------------------------------------

The system works fine on Windows (XP, 7, 8, 10) 32-bit and 64-bit systems.

It's recommended to have at least 8 GB of memory in the system.

The system it’s designed to work in multiplatform.
It is allowed by programming in Python 3.8.6. On Windows, Linux and Mac systems without problems.

Warning: Other higher versions of Python may cause problems in some libraries, check their manual to ensure proper operation.

---------------------------------------------------------------------------------------------------------------------------------------------

Warning: It is recommended not to make alterations, changes, or eliminations of part or the complete content of the codes and programs that comprise the system,
without the necessary knowledge, since it can seriously affect its operation.

-------------------------------------------------------------------------------------------------------------------------------------------
8.- MODULES UNDER CONSTRUCTION
-------------------------------------------------------------------------------------------------------------------------------------------

The following modules are being developed to be available

1.    Analysis of Spectral Characteristics System of Seismic Records (https://doi.org/10.5281/zenodo.7008075)
2.    STA/LTA triggering methods for seismic records (https://doi.org/10.5281/zenodo.7041962)
3.    Coverting Seismic Records to Wav sound (https://doi.org/10.5281/zenodo.7320318)
4.    Integrate Seismic Signals. (https://doi.org/10.5281/zenodo.7048873)
5.    System to select, cut and save events since seismic records (https://doi.org/10.5281/zenodo.7268903)
6.    System to select, merge and save events since seismic records (https://doi.org/10.5281/zenodo.7318039)
7.    Downloading records from The FDSN (International of Digital Seismograph Networks), (This current module)

** THEY WILL BE AVAILABLE FOR DOWNLOAD IN THE FUTURE **

-------------------------------------------------------------------------------------------------------------------------------------------