Teqcplot.py Documentation 17 Sep. 2017 Introduction Teqcplot.py is an open-source Python freeware program for visualization of teqc qc results, created in 2014. Teqcplot.py makes displays of data from teqc QC processing of GNSS receiver output (quality checks of GNSS station observables). Plotted data includes sky tracks, signal to noise estimates, multipath estimates, and ionosphere delay values. Plot types include skyplots, by time, by azimuth, and band plots. Teqcplot.py plots data from teqc plot files in the teqc COMPACT3 format, the current format for teqc +qc +plot output. You are free to revise the code to read older teqc plot file formats if you need to. Teqcploy.py is open-source freeware; the Python is at http://www.westernexplorers.us/teqcplot/teqcplot.py. Teqcplot.py can be installed on Linux, Mac, and Windows. Teqcplot.py uses recent versions of Python, Numpy, and matplotlib on your system. Teqcplot.py can be run programmatically with scripts for automated plot generation. You may need to install or upgrade Python, Numpy, and the matplotlib 1.3 library. Teqc is a program for pre-processing GPS, GLONASS, Galileo, Beidou-2/Compass, and QZSS data, and used by geodesists doing high-precision point positioning with GNSS. Teqc processes RINEX and native receiver files. Teqc is freeware from the UNAVCO teqc web site (https://www.unavco.org/software/data-processing/teqc/teqc.html). Teqcplot.py is not part of teqc, does not use teqc code, and is not supported by teqc or by teqc software development. This document is online at http://www.westernexplorers.us/teqcplot/Teqcplot_Documentation.txt. Teqcplot.py is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License. You must retain the original and complete Copyright and License Notice in all cases. System Requirements You can install Teqcplot.py on recent versions of Linux, Windows, and Mac. Teqcplot.py is a Python script or program in one file, teqcplot.py. Download the latest version of teqcplot.py from http://www.westernexplorers.us/teqcplot/teqcplot.py. Make sure the file is set to have execute permission on your file system, as with Linux command chmod 744 teqcplot.py. Teqcplot requires that your operating system have Python (apparently version or 2.7 or 3.3), and recent versions of the separate Python libraries Numpy (v 1.5 or higher) and matplotlib (v 1.3), which are all open source. You may have Python which will work, but you probably need to install (or upgrade to) Numpy 1.5 and matplotlib 1.3. This is described next. Teqcplot was developed on a Debian 7.5 Linux operating system, with these utilities: Python 2.7.3 NumPy 1.6.2 matplotlib 1.3.1 gcc 4.7.2 Teqcplot.py requires matplotlib version 1.3 (or higher), and matplotlib version 1.3 requires Numpy 1.5 or higher. You may need to install or upgrade these Python libraries. More recent versions are Python 3.4.3, NumPy 1.9.2, and Matplotlib 1.4.3. Teqcplot.py should work with these versions. Version 1.3 of matplotlib *cannot* be installed with reasonable effort on some older operating systems, for example, Ubuntu 10. Installation of Teqcplot.py On Linux You can check your versions with these commands (on Linux or Mac): which python which will show this: /usr/bin/python or something similar Python is installed. If you have Python, then do this to see your installed libraries' versions: python Python 2.7.3 (default, Mar 14 2014, 11:57:14) [GCC 4.7.2] >>> import numpy >>> print numpy.__version__ 1.6.2 >>> import matplotlib >>> matplotlib.__version__ '1.3.1' Installing matplotlib on Linux may be tricky. The best help I know of is "Building a numerical Python environment in Debian" ( http://www.westernexplorers.us/GNSSplotters/BuildingAnumericalPythonEnvironment-in-Debian.html ) (copied from the defunct www.eliteraspberries.com/blog/2013/10/building-a-numerical-python-environment-in-debian.html). The same instructions probably will be useful for Ubuntu, OpenSUSE and similar operating systems. "apt-get" is very useful and powerful on these version of Linux. On Windows For help installing Python and graphics software see Create a standalone Windows installer for your Python application by Cyrille Rossant. (http://cyrille.rossant.net/create-a-standalone-windows-installer-for-your-python-application) He says "for Windows users who are not familiar with Python or with a command-line interface it is notoriously difficult to distribute Python applications... and it's a common criticism made against Python." His guidance is helpful; you only need Python 2.7, NumPy 1.5, and Matplotlib 1.3 or higher versions. On other Systems Help should be available online for installing and updating Python and its libraries on other systems. Many systems come with some form of Python, but lack NumPy and matplotlib. The teqcplot developer has no experience running teqcplot or installating Python or its libraries on operating systems other than Debian and cannot help with installing numpy or matplotlib or any teqcplot problems on other operating systems. Programmatic Use As supplied teqcplot is an interactive program, that makes one plot image in a window on your screen. You can save that image with a click. To automatically make and save the image as a PNG file, do these code changes in the teqcplot.py file: 1. Uncomment the line # mptl.use('Agg') ; i.e. remove the # , preserving the indentation level 2. Comment out the line plt.show() ; i.e. start the line with # preserving the indentation level 3. Uncomment the line # plt.savefig(filename) ; i.e. remove the # , preserving the indentation level Now you can call a teqcplot.py command in another program, which could for example make plots for many input data files. How to Use Teqcplot Teqcplot plots data from the UNAVCO "teqc" program for analysing GNSS observations. UNAVCO is the home of teqc, and maintains and improves teqc.About teqc, see the UNAVCO web site, for example, http://www.unavco.org/software/data-processing/teqc/teqc.html. Teqcplot reads data from (only) teqc's "plot files" in teqc's COMPACT3 format, made with teqc versions of June 2015 and later. (an early release of this version was available as of Dec. 2013). To adapt teqcplot.py to read data from files in formats other than teqc's COMPACT3, you will need to change the method read_input_files() in teqcplot.py. Note the Python data objects used in plotting, and fill those from your data. Some experience in Python is helpful; this is not simple. Use Commands Teqcplot uses command line commands, with data filenames and options. Each run of teqcplot.py makes one plot on your screen (or alternately as a saved file when run in programmatic mode). To stop the program click on the 'x' in the upper right corner of the window which pops up. Spaces " " are not allowed in options. Option order should not matter. To save an image file of the display, click on the "Save the figure" button on the bottom of the window which pops up. To change the plot image file size (pixels) use the options +pw and +pd described below. Examples of teqcplot commands: To run teqcplot.py, you use the command teqcplot.py in the working directory where that file is, or use ./teqcplot.py if that directory is not in your Linux PATH. These examples use teqcplot.py. Entering the command teqcplot.py shows the teqcplot.py help message. To make skyplots (polar plots), use for example: teqcplot.py +skyplot jplv1200.azi jplv1200.ele This creates a skyplot of tracks of SVs, with data from teqc COMPACT3 plot files "jplv1200.azi" and "jplv1200.ele" To make azimuth-elevation plots (azimuth on x axis; elevation on y axis): teqcplot.py +azelplot jplv1200.azi jplv1200.ele This shows an azimuth-elevation plot of tracks of SVs, with data from teqc COMPACT3 plot files "jplv1200.azi" and "jplv1200.ele" To make plots with time of day on the x axis and elevation on the y axis teqcplot.py +timeelplot jplv1200.azi jplv1200.ele Options may added to the command, for example using the option -R means do not plot any GLONASS SVs. teqcplot.py +skyplot jplv1200.azi jplv1200.ele -R This makes a skyplot of tracks of SVs, but with no GLONASS SVs shown. Likewise use -G for no GPS SVs, -E for no Galileo, -J for no QZSS, -C for no Beidou, and -S for no SBAS. SVs are selected to plot from the data files, in the order the SVs appear in the data file. If you choose to plot 10 tracks and the first 5 are GPS and the next five are GLONASS in the file, those are the ones plotted, unless options change SV selection. Other options: +tcl=n n, an integer, is the maximum number of how many tracks to show (lines in plot). Default is 6. +msize=f.f f.f is a float number denoting point marker size, for line width or thickness. Default is 2.5. +legend to show a legend of colors identifying each SV next to the figure. Default is no legend. This is for plots where each SV data has one color. -tracklabels do not show the SV id (like G12) on each track (line on plot). Default is to show the SV labels. +pw=f.f f.f, a float number, sets the width of plot in centimeters. Default value is 20.0 cm. +pd=nn nn, an integer, is the pixel density, how many pixels per centimeter (multiply by 2.54 for "dots per inch"). Default is 50. For printing illustrations, you can adjust the quality of the figure image file by changing pw and/or pd. For example: teqcplot.py +skyplot +tcl=8 jplv0970.azi jplv0970.ele +pw=25.0 +pd=80 +GNN, +GNN-MM, +RNN, +RNN-MM, +J01, etc. Select SVs to plot by constellation and a single number or number range. +G12 to plot only data from GPS G12; likewise +R20 for GLONASS; +J01 for QZSS +G12-20 to plot only data from GPS SVs included in the list from G12 through G20; likewise +R20-24 for GLONASS from R20 through R24 +G12,23,24,25 to plot only data from G12, G23, G24 and G25; likewise +R15,20,22 to plot these three GLONASS SVs With the +G, +R, etc. options you may to also include a +tcl=N option. Example: teqcplot.py +skyplot mal20970.azi mal20970.ele +R15,20,22,23,25 +G12,23,24,25 +tcl=9 +color=orange sets this one color for all tracks (lines in plot). Use standard HTML color names. Has no effect on plot lines colored by parameter values as described below. +minHour=8.0, +maxHour=16.5 You can limit the time range shown in time plots with options +minHour, +maxHour: teqcplot.py +timeparmplot p2301220.azi p2301220.ele p2301220.m12 +G22 +minHour=8 +maxHour=16 To Color Tracks by Parameter Value To make plots like the above, and also color the SV tracks by data values, including signal to noise ratios, multipath values, or by ionosphere values, from the corresponding teqc plot files, use an additional teqc QC plot file name in the command, such as jplv1200.sn1 teqcplot.py +skyplot jplv0970.azi jplv0970.ele jplv1200.sn1 teqcplot.py +timeelplot jplv0970.azi jplv0970.ele jplv1200.m12 teqcplot.py +axelplot jplv0970.azi jplv0970.ele jplv1200.i12 Color ranges used depend on the parameter type, each of which has a preset range of values, to enable equal comparion of several plots, and to not stretch the color scale to cover a few extreme high and low values. The default limits for colors of values are: signal to noise: 20.0 to 60.0 multipath: -1.5 to 1.5 ionspheric delay: -30.0 to 40.0 ionspheric delay derivative: -0.5 to 0.5 You can change these with either or both of the options +colorMax and +colorMin, for example teqcplot.py +bandplot IRID1380.azi IRID1380.ele IRID1380.sn1 +colorMax=50 +colorMin=10 The default color map is the Python matplotlib color map named hsv. By experience this is the most distinct color map for many uses. You can change the Python code to change the color map used to any other matplotlib color map name. (About color maps see https://matplotlib.org/tutorials/colors/colormaps.html) Change the color map name in this line in teqcplot.py: cmap=mptl.cm.hsv. Another colored plot is the Band Plot. To make GNSS band plots, with a horizontal line for each SV, versus time, use the plot type option +bandplot: teqcplot.py +bandplot jplv0970.azi jplv0970.ele jplv1200.sn1 Time-Parameter Plots. To make plots with time of day on the x axis and the parameter value on the y axis. teqcplot.py +timeparmplot jplv1200.azi jplv1200.ele jplv1200.m12 +G23 Usually this is done with data from one SV, with an option like +G23. You can limit the time range shown, in integer hours, with options +minHour, +maxHour: teqcplot.py +timeparmplot p2301220.azi p2301220.ele p2301220.m12 +G22 +minHour=8 +maxHour=16 The default Time-Parameter Plot uses black points for data points. You can change the line style and color. For example to plot blue lines between the data points, in teqcplot.py in the line mplot = plt.plot (times, yvals, 'ko', markersize=1.5 ) which is the plotting command, the line style and color are combined in a single format string, 'ko' for black circles in this case. Change ko to b- for blue lines. First save a backup copy of teqcplot.py. Then edit the teqcplot.py line, only changing ko to b-: mplot = plt.plot (times, yvals, 'b-', markersize=1.5 ) to plot solid blue lines. b means blue and - solid line. You can use other colors and other line styles and markers. In the online document at matplotlib.org/api/pyplot_api.html see the section for matplotlib.pyplot.plot(*args, **kwargs) especially the parts at "The following format string characters are accepted to control the line style or marker:" (there are 26 line styles and markers), and the parts at "The following color abbreviations are supported". The colors include b blue g green r red c cyan m magenta y yellow and k black. Visibility Plot Bandplots without a 3rd (parameter values) file make a "Visibility" plot: teqcplot.py +bandplot jplv0970.azi jplv0970.ele Spaces " " are not allowed in options. Option order should not matter. Current Version of teqcplot.py: Sep 10, 2015 Version 1.5.1 Credit Many thanks to Lou Estey of UNAVCO, the creator of teqc, an amazing tool, who has also provided continuing teqc improvements and very professional teqc support for more than 17 years. This document Copyright (C) 2015, 2018 Stuart K. Wier. Reproduction, reuse, or retransmission in whole or in part prohibited without prior written permission from the author.