ebas_plot

The program ebas_plot plots data, as graphs or as maps, from the EBAS database or from Nasa/ames files.

New in version 3.00.08.

Synopsis

ebas_plot [-h] [--version] [--cfgfile CFGFILE]
          [--loglevconsole LOGLEVCONSOLE] [--loglevfile LOGLEVFILE]
          [--logfile LOGFILE] [--profile] [--nodb] [--dbHost DBHOST]
          [--db DB] [--dbUser DBUSER] [--dbPasswd DBPASSWD]
          [--do_id DO_ID] [--setkey SETKEY] [--station STATION]
          [--project PROJECT] [--instrument INSTRUMENT]
          [--component COMPONENT] [--matrix MATRIX] [--group GROUP]
          [--fi_ref FI_REF] [--me_ref ME_REF]
          [--resolution RESOLUTION] [--statistics STATISTICS]
          [--datalevel DATALEVEL] [--time TIME] [--state STATE]
          [--diff DIFF] [--format FORMAT] [--graphstyle GRAPHSTYLE]
          [--flags FLAGS] [--gridsize GRIDSIZE] [--figsize FIGSIZE]
          [--notitle] [--nolegend] [--settitles SETTITLES]
          [--colormap COLORMAP] [--stationmap]
          [--projection PROJECTION] [--showlatlon] [--modscale]
          [--dotsize DOTSIZE] [--setscale SETSCALE]
          [--setlatlon SETLATLON] [--setcolorbar SETCOLORBAR]
          [--stat STAT] [--year | --month | --week | --day | --hour]
          [--lower_limit LOWER_LIMIT] [--upper_limit UPPER_LIMIT]
          [--perc PERC | --aot AOT] [--zenith] [--amount]
          [--filenames [FILENAMES [FILENAMES ...]]]
          [--createfiles CREATEFILES] [--destdir DESTDIR]

Commandline arguments

General arguments

-h, --help

Show help text and exit.

-v, --version

Display version information and exit.

Configuration arguments

--cfgfile=CFGFILE

Set the EBAS configuration file to be used. See Configuration file for detailed information.

This argument requires an argument value CFGFILE (the configuration file to be used). CFGFILE is the full path and file name, the file path might be absolute or relative. The current user’s home directory may be specified with a tilde character (~), other user’s home directory may be specified as ~other_user.

Note

There may not be any blank characters in the CFGFILE argument value! If the filename contains blank characters, wrap it into double quotes ("). Example:

--cfgfile="my ebas config.cfg"

Examples:

Specify a config file named ebas.cfg in the current working directory (relative path):

--cfgfile=ebas.cfg

Specify a config file named ebas.cfg in the directory config under the current working directory (relative path):

--cfgfile=config/ebas.cfg

Specify a config file named ebas.cfg in the directory /home/me (absolute path):

--cfgfile=/home/me/ebas.cfg

Specify a config file named ebas.cfg in the current user’s home directory:

--cfgfile=~/ebas.cfg

Specify a config file named ebas.cfg in user collegue‘s home directory:

--cfgfile=~collegue/ebas.cfg

Default: ~/ebas.cfg

Logging arguments

--loglevconsole=LOGLEVEL

Set log level for console output.

This argument requires an argument value LOGLEVEL. All messages from EBAS are categorized with logging severities (e.g. error messages are written with a different severity as information messages). Severities are: CRITICAL, ERROR, WARNING, INFO, DEBUG (descending severity)

Setting the LOGLEVEL controls which category of messages will be displayed to the user. Possible values for LOGLEVEL are:

  • silent - no messages will be displayed in the console output
  • critical - only CRITICAL messages will be displayed in the console output
  • errors - only messages with severity CRITICAL or ERROR will be displayed in the console output
  • warnings - only messages with severity CRITICAL, ERROR or WARNING will be displayed in the console output
  • info - messages with severity CRITICAL, ERROR, WARNING or INFO will be displayed in the console output
  • debug - all messages will be displayed in the console output

Default: info

--loglevfile=LOGLEVEL

Set log level for logfile output.

This argument requires an argument value LOGLEVEL. All messages from EBAS are categorized with logging severities (e.g. error messages are written with a different severity as information messages). Severities are: CRITICAL, ERROR, WARNING, INFO, DEBUG (descending severity)

Setting the LOGLEVEL controls which category of messages will be included in the logfile. Possible values for LOGLEVEL are:

  • silent - no messages will be written to the logfile and no logfile will be created
  • critical - only CRITICAL messages will be written to the logfile
  • errors - only messages with severity CRITICAL or ERROR will be written to the logfile
  • warnings - only messages with severity CRITICAL, ERROR or WARNING will be written to the logfile
  • info - messages with severity CRITICAL, ERROR, WARNING or INFO will be written to the logfile
  • debug - all messages will be written to the logfile

Default: silent

--logfile=LOGFILE

Set file name for logfile output (including path).

This argument requires an argument value LOGFILE. LOGFILE is the full path and file name, the file path might be absolute or relative. The current user’s home directory may be specified with a tilde character (~), other user’s home directory may be specified as ~other_user.

Note

There may not be any blank characters in the LOGFILE argument value! If the path or file name contains blank characters, wrap it into double quotes ("). Example:

--logfile="ebas logfiles/logfile.log"

Default: filename constructed of program name and start time in the current working directory (e.g. ./ebas_list_ds_2015-12-27_123147.log)

Changed in version V.3.02.00: the previous default file name included colons (:) as time separator, (e.g. ./ebas_list_ds_2015-12-27_12:31:47.log)

--profile

Activate program profiling.

Note

This option is for EBAS developers only. Code profiling is an analytical technique used in runtime optimization. Using this option has no benefit for a user (it makes the code slower actually).

Default: False

Database arguments

Database user and password can also be fetched from your .netrc file (recommended authentication method).

See Database Authentication for more information on this. If you want to use netrc authentication, you need to leave the --dbUser and --dbPasswd agruments away!

--nodb

Do not connect to the database. Most programs will have limited functionality without database connection (e.g. ebas_insert can still perform file syntax checks and limited semantic checks). Some programs will lose all their functionality, but even in those cases, the nodb option might be useful for tests or other arguments validation, or simply to get a –version and –help output when the database is unreachable.

New in version 3.00.07.

--dbHost=DBHOST

Specify the database host name according to the database client configuration file (sql.ini for sybase drivers, freetds.conf for freetds drivers). If this sounds unfamiliar, ask a system administrator. At NILU, we use two database servers for EBAS, ODIN (database server for the test system) and SLEIPNER (operational database server). The respective names to be used for the argument –dbHost on ratatoskr are:

  • ODIN_ASE
  • SLEIPNER_ASE
--db=DBNAME

The name of the database to be used. If you don’t know for sure that you want to change this, leave it at the default (ebas_new)

--dbUser=DBUSER

The user name to be used for connecting to the database. See Database Authentication.

--dbPasswd=DBPASSWD

The password to be used for connecting to the database. See Database Authentication.

Warning

Please do NOT use the --dbPasswd argument!

On multi-user UNIX systems, each users is able to see the command used to start any program on the system.

Therefore, including sensitive information in commands is generally strongly discouraged on UNIX systems.

See Database Authentication for alternatives to using the --dbPasswd argument.

Note

There may not be any blank characters in the DBPASSWD argument value! If the password contains blank characters, wrap it into double quotes ("). Example:

--dbPasswd="with blank"

Commandline arguments for dataset selection criteria

Dataset selection criteria are used to define a set of datasets to be plotted by ebas_plot.

--do_id=DO_ID

Selection by download id (set of datasets to be downloaded. Normally specified by EBAS Web when using ebas_extract as a back-end for the web download.

Optional, Default: None

-k, --setkey=SETKEY

Selection by dataset setkey.

This argument requires an argument value SETKEY. SETKEY can be a single setkey, a range of stekeys (SETKEY1-SETKEY2), or a list of setkeys (SETKEY1,SETKEY2,...).

Note

Make sure there are no blank characters in the argument value (not even after the commas or around the hyphens)!

Otherwise, the argument parser assumes that the next argument starts after a blank character and an error will occur.

Optional, Default: None

-s, --station=STATION_CODE

Selection by station code.

This argument requires an argument value STATION_CODE. STATION_CODE can be a single station code or a list of station codes (STATION_CODE1,STATION_CODE2,...). In addition, each station code can be specified exactly (full station code, e.g. NO0002R), partly without station type (e.g. NO0002) or partly with only the country code part (e.g. NO, which matches all Norwegian stations).

Note

Make sure there are no blank characters in the argument value (not even after the commas)!

Otherwise, the argument parser assumes that the next argument starts after a blank character and an error will occur.

Examples:

Select all datasets from the station which station codes is NO0001R:

--station NO0001R

Same, but you can’t remember the station type of the station:

--station NO0001

Select all datasets from stations which station codes are in NO0001R, NO0002R and NO0042G:

--station NO0001R,NO0002R,NO0042G

Same, but you can’t remember the station types of those 3 stations:

--station NO0001,NO0002,NO0042

Select all datasets from Norwegian and Austrian stations:

--station NO,AT

Optional, Default: None

-p, --project=PROJECT

Selection by project acronym.

This argument requires an argument value PROJECT. PROJECT can be a single project acronym or a list of project acronyms (PROJECT1,PROJECT2,...).

Note

Make sure there are no blank characters in the argument value (not even after the commas)!

Otherwise, the argument parser assumes that the next argument starts after a blank character and an error will occur.

Optional, Default: None

-i, --instrument=INSTRUMENT

Selection by instrument type.

This argument requires an argument value INSTRUMENT. INSTRUMENT can be a single instrument type or a list of instrument types (INSTRUMENT1,INSTRUMENT2,...).

Note

Make sure there are no blank characters in the argument value (not even after the commas)!

Otherwise, the argument parser assumes that the next argument starts after a blank character and an error will occur.

Optional, Default: None

-c, --component=COMPONENT

Selection by component name.

New in version 3.01.00: Strict synonyms can be used instead of component names. Lookup names, as a special case of strict synonyms, may be used case insensitively, but only if there are not conflicts with other component names and synonyms. E.g.:

  • --component mg will find the componnet name magnesium
  • --component co will throw an error message (may be the synonym Co for component cobalt or synonym CO for component carbon_monoxide)
  • --component Co and --component CO will still work as expected.

This argument requires an argument value COMPONET. COMPONENT can be a single component name or a list of component names (COMPONENT1,COMPONENT2,...).

Note

Make sure there are no blank characters in the argument value (not even after the commas)!

Otherwise, the argument parser assumes that the next argument starts after a blank character and an error will occur.

Optional, Default: None

-m, --matrix=MATRIX

Selection by matrix name.

This argument requires an argument value MATRIX. MATRIX can be a single matrix name or a list of matrix names (MATRIX1,MATRIX2,...).

Note

Make sure there are no blank characters in the argument value (not even after the commas)!

Otherwise, the argument parser assumes that the next argument starts after a blank character and an error will occur.

Optional, Default: None

-g, --group=GROUP

Selection by parameter group.

This argument requires an argument value GROUP. GROUP can be a single parameter group or a list of parameter groups (GROUP1,GROUP2,...).

Note

Make sure there are no blank characters in the argument value (not even after the commas)!

Otherwise, the argument parser assumes that the next argument starts after a blank character and an error will occur.

Optional, Default: None

--fi_ref=FI_REF

Selection by instrument reference.

This argument requires an argument value FI_REF. FI_REF can be a single instrument reference or a list of instrument references (FI_REF1,FI_REF2,...).

Note

Make sure there are no blank characters in the argument value (not even after the commas)!

Otherwise, the argument parser assumes that the next argument starts after a blank character and an error will occur.

Optional, Default: None

--me_ref=ME_REF

Selection by method reference.

This argument requires an argument value ME_REF. ME_REF can be a single method reference or a list of method references (ME_REF1,ME_REF2,...).

Note

Make sure there are no blank characters in the argument value (not even after the commas)!

Otherwise, the argument parser assumes that the next argument starts after a blank character and an error will occur.

Optional, Default: None

--resolution=RESOLUTION

Selection by resolution code.

This argument requires an argument value RESOLUTION. RESOLUTION can be a single resolution code or a list of resolution codes (RESOLUTION1,RESOLUTION2,...).

Note

Make sure there are no blank characters in the argument value (not even after the commas)!

Otherwise, the argument parser assumes that the next argument starts after a blank character and an error will occur.

Optional, Default: None

--statistics=STATISTICS

Selection by statistics code.

This argument requires an argument value STATISTICS. STATISTICS can be a single statistics code or a list of statistics codes (STATISTICS1,STATISTICS2,...).

Note

Make sure there are no blank characters in the argument value (not even after the commas)!

Otherwise, the argument parser assumes that the next argument starts after a blank character and an error will occur.

Optional, Default: None

--datalevel=DATALEVEL

Selection by data level.

This argument requires an argument value DATALEVEL. DATALEVEL can only be a single data level.

Optional, Default: None

New in version 3.00.08.

Time interval criteria

-t, --time=TIME

Specifies the time interval the program should operate on.

This argument requires an argument value TIME. TIME has the format FROM[-TO]. FROM and TO each has the format YYYY[-MM[-DD[THH[:MM[:SS]]]]].

If only one time is specified, the period which is defined by the precision of the time format will be chosen:

2012-01 –> [2011-01-01T00:00:00,2011-02-01T00:00:00[ (i.e. the period January 2011).

2011-11-23T11 –> [11:00, 12:00[ on 23 Nov.

If both FROM and TO are given, the interval is defined by the start of the FROM period and the end of the TO period:

2011-01-2012-01-22 –> [2011-01-01T00:00:00, 2012-01-23T00:00:00[

The time criteria works by overlapping the given criteria with the measurement sample sequence.

When time is specified as YYYY or YYYY-MM, a slightly different approach is used: sample sequences that overlap only partly with the first or last sample in the sequence are not included. This is to prevent non-intuitive overlaps when one e.g. 07:00-07:00 sample overlaps from the last month or year of data

With other words: when specifying only YYYY or YYYY-MM, a hit is only considered, if at least one _full_ sample is within the respective year or month.

Note

Make sure there are no blank characters in the argument value (not even around the hyphens when specifying FROM and TO times)!

Otherwise, the argument parser assumes that the next argument starts after a blank character and an error will occur.

Database state arguments

--state=STATE

Used to query the database in an historic state.

This argument requires an argument value STATE. STATE is the historic point in time you want to look at the data. The result of the operation will be the same as if the operation had been performed at the historic point in time specified. This can be thought of as a time travel option (unfortunately we can only travel back in time - sorry, no future observations in this version of EBAS). See Historic states of data for more information.

Format: YYYY[-MM[-DD[THH[:MM[:SS]]]]].

Note

Make sure there are no blank characters in the argument value!

Otherwise, the argument parser assumes that the next argument starts after a blank character and an error will occur.

Default: If the –state option is not given, the current point in time is used (current state of the database)

Examples:

--state 2015-03-27T23:21:12 queries the database as it was 27th March 2015, 23:21:12

--state 2015-01-01T00:00:00 queries the database as it was 1st January 2015 midnight

--state 2015-01-01 same state, but less typing

--state 2015 same state, minimal typing

--diff=DIFF

The diff criteria is used to restrict the set of data and metadata to only those that have been changed between two historic states of the database.

This argument requires an argument value DIFF.

Format: YYYY[-MM[-DD[THH[:MM[:SS]]]]].

Note

Make sure there are no blank characters in the argument value!

Otherwise, the argument parser assumes that the next argument starts after a blank character and an error will occur.

Only data and metadata that changed between the database state specified by DIFF and the database state specified by the argument --state will be processed. If the --state argument is not given, the current database state is used and only data changed since DIFF will be processed (see the default value for the argument --state).

The usual case will be that DIFF is earlier in time then STATE, however the opposite case is technically possible: Work on data in an old database state which will have been changed at a certain point of time in the future.

Examples:

--diff 2015-03-27T23:21:12 --state 2015-05-01T00:00:00 Only processes data and metadata changed between 27th March 2015, 23:21:12 and 1st of May 2015 midnight. The results will be in the database state of 1st of May 2015.

--diff 2015-01-01T00:00:00 Only processes data and metadata changed since 1st January 2015 midnight. The results will be in the current database state.

--diff 2015-01-01 same, but less typing

--diff 2015 same, minimal typing

New in version 3.00.08.

Arguments specific to ebas_plot

By default the figures will be shown on screen, to the user, in an interface.

Here is a link to a guide explaning how to use the interface:

https://matplotlib.org/users/navigation_toolbar.html

Plot arguments

--format=FORMAT

Available options: map, multi, stationmap

If no format is specified each graph will be plotted, as time series, in separate plots. If a format is specified with –format the following effects will be applied:

  • map: The datapoints will be plotted on a map. One map will be created for each sample in time. It is recommended to use statistical arguments in combination with map in order to recieve a manageable number of maps.
  • stationmap: A map showing the placement of the stations will be created.
  • multi: All regular time series will be plotted in together in a single plot.

Optional, Default: None

--graphstyle=GRAPHSTYLE

Allowed values: scatter, forcelines

Choose a special graphstyle for the plot.

  • scatter: Creates a scatter plot. (Markers instead of lines)
  • forcelines: Create lines even if the measurements are discontinous.

Optional, Default: None

--setminmax=SETMINMAX

Set the minimum and maximum values for the y-axis or the colorbar. The values should be given as a list of two floats.

Format: MIN,MAX

Optional, Default: None

--flags=FLAGS

Inculde information on data flags.

Allowed values: (Multiple can be given in a list)

  • I: Show invalid values as red dots.
  • V: Show valid values as green dots.
  • A: Plot all values ignoring validity.

Note

I and V are only avalible for time series only.

Optional, Default: None

--gridsize=GRIDSIZE

The number of plots to place in the figure.

Format: X,Y

X: The number of plots, horizontally, in a figure.

Y: The number of plots, vertically, in a figure.

Optional, Default: (1, 1)

--figsize=FIGSIZE

Size of the figure in inches.

Format: X,Y

Optional, Default: None

--nolegend

Remove legends from all plots.

Optional, Default: False

--legendsize=FONTSIZE_LEGEND

Set the fontsize/dotsize for legends. The value should be given in points.

Optional, Default: None

--settitle=SETTITLES

Set custom titles for the plots. For one plot specify a string. For multiple plots specify a list of strings separated by a comma.

–settitle ‘notitle’ will remove the titles from all plots.

Optional, Default: None

--titlesize=TITLESIZE

Set the size of the titles. The value should be given in points.

Optional, Default: None

--colormap=COLORMAP

Set a colormap for dmps/map/stationmap plots.

Allowed values:

'jet', 'jet_r', 'gnuplot2', 'gnuplot2_r',
'Purples', 'Purples_r', 'hot', 'hot_r',
'cool', 'cool_r', 'spring', 'spring_r',
'gist_rainbow', 'gist_rainbow_r', 'winter', 'winter_r'

Optional, Default: jet

Map arguments

--projection=PROJECTION

Allowed values: merc, cyl, stere, europe, scand, norway, CAMP

Choose a projection type for map plots.

  • merc: Mercator projection.
  • cyl: Cylindrical projection.
  • stere: Stereographic projection.
  • europe: Europe in stereographic projection.
  • scand: Scandinavia in stereographic projection.
  • norway: Norway in stereographic projection.
  • CAMP: CAMP in stereographic projection.

Optional, Default: merc/cyl

--showlatlon

Show the latitude and longitude for the lower left and upper right corner of the map. The latitude and longitudes will be shown at the bottom of the map.

Optional, Default: False

--setlatlon=SETLATLON

Format Mercator And Cylindrical projection:

A list of positive floats specifying the latitude and longitude for the lower left and upper right corner of the map. This is used to choose a custom map section.

Format: lower_left_latitude, lower_left_longitude, upper_right_latitude, upper_right_longitude

Note

Positive latitude values must be followed by N, and negative values by S. Positive longitude values must be followed by E, and negative values by W.

Example:

Europe:

--setlatlon 27N,30W,72N,43E

Format Stereographic projection:

All numbers must be positive floats.

Format: lat_ts, lat_0, lon_0, width, height

  • lat_ts: latitude of true scale.
  • lat_0: centre point latitude.
  • lon_0: centre point longitude.
  • width: Width of the map in meters.
  • height: Height of the map in meters.

Note

Positive latitude values must be followed by N, and negative values by S. Positive longitude values must be followed by E, and negative values by W.

Example:

Europe:

Europe: --setlatlon 60N,58N,5E,5850000,5850000
Helcom: --setlatlon 62N,62N,15E,2000000,2000000

Optional, Default: None

--setscale=SETSCALE

A list of floats specifying at what values the map markers will change color.

Optional, Default: None

--intscale=INTSCALE

A list of integers specifying at what values the map markers will change color.

Optional, Default: None

--modscale

Interactive mode for modifying scale. If active, the plot will be showed on screen, and you will be prompted for a new scale.

Optional, Default: False

--background=BACKGROUND

Set the map colors and borders.

Format: A list of one or two elements consisting of one color (‘white’, ‘light’, ‘medium’, ‘dark’ or ‘relief’) and/or ‘countryborders’.

  • white: The map is white.
  • light: The map has light colors (blue and grey).
  • medium: The map has medium colors (blue and grey).
  • dark: The map has dark colors (blue and grey).
  • relief: A relief map is used.
  • countryborders: The country borders are drawn.

Optional, Default: medium

--dotsize=DOTSIZE

Set the size of the markers on the map.

Optional, Default: 150

--ignore=IGNORE

Allowed values: ‘zero’

  • zero: Ignore zero values. Ignored values will not be plotted.

Optional, Default: None

Statistical arguments

--stat=STAT

Allowed values: mean, capture, dep, sum, max, min, stdev, geom_mean, geom_stdev, perc, diurnal, aot, num_samples, num_bdl, num_days

Apply a statistical method to the data before plotting.

Note

The statistical method perc requires - -perc to be specified. The statistical method aot requres - -aot to be specified.

Optional, Default: None

--year, --month, --week, --day, --hour

Preforms the statistical method on data from one year/month/week/day/hour at a time.

Optional, Default: False

--lower_limit=LOWER_LIMIT, --above=LOWER_LIMIT

Only include values above the limit.

Optional, Default: None

--upper_limit=UPPER_LIMIT, --below=UPPER_LIMIT

Only include values below the limit.

Optional, Default: None

--perc=PERC

A percentile value or a list of percentile values.

Optional, Default: None

--aot=AOT

An aot value.

Optionl, Default: None

--zenith

Use zenith angle of 89 as cutoff for aot calulations.

Optional, Default: False

--amount

Include a plot of the precipitation amount.

Optional, Default: False

Input arguments

--nasaames=[NASAAMES [NASAAMES ...]]

Plot data from Nasa/Ames files. A filename or a list of filenames must be specified. In the list of filenames the names should be separated with space.

Optional, Default: None

--file=[FILE [FILE ...]]

Plot data from files. A filename or a list of filenames must be specified. Two file formats are supported, statistics files and station class files. Station class files are used to create stationmapmaps with station classes.

File format statistics files:

station_code component_name matrix latitude longitude start_time - end_time value

File format for station class files:

# number_of_classes
1 class_1
\.\.\.
n class_n
station_code latitude longitude class_number

Optional, Default: None

--file_db=[FILE_DB [FILE_DB ...]]

Plot data from files together with data from the database. A filename or a list of filenames must be specified. One file format is supported.

File format:

station_code component_name matrix latitude longitude start_time - end_time value

Optional, Default: None

Output arguments

--createfiles=CREATEFILES

Allowed values: png, eps, svg, pdf, jpg

Set a file format for saving files. If you specify a file format with –createfiles the plots will be saved as files of the specified format. If you do not use the –createfiles option the plots will not be saved, but will be diplayed on the computer screen.

Optional, Default: None

--destdir=DESTDIR

Set the destination directory for the files created with –createfiles.

Optional, Default: Current folder