Usage: Requirements

You will need to install docker on your computer to run BUVIC's docker image

Python version >=3.7 is also needed if you want to run the python app directly

Directory structure

BUVIC needs access to three main directories:

1. An instrument directory (e.g. instr)
2. A uv data directory (e.g. uvdata)
3. An output directory (e.g. output_dir)

The instrument directory is where you put your instrument files.

instr/
    arf_033.dat
    arf_070.dat
    ...
    UVR17319.070
    UVR17319.117
    UVR17419.033
    ...
    par_18.033
    par_18.070
    par_19.033
    par_19.070
    ...

It contains:

• ARF files with the name pattern arf_<brewer_id>.dat
• Calibration files with the name pattern UVRXXXXX.<brewer_id>
• Parameter files with the name pattern par_<year>.<brewer_id> where year is the last two digits of the year (e.g. 19)

The uv data directory is where you put your measurement files.

uvdata/
    B17019.033
    B17019.070
    B17119.033
    B17119.070
    ...
    UV17019.033
    UV17019.070
    UV17119.033
    UV17119.070
    ...

It contains:

• B files with the name pattern B<days><year>.<brewer_id> where days is the number of days since new year and year is the last two digits of the year (e.g. 19)
• UV files with the name pattern UV<days><year>.<brewer_id> where days is the number of days since new year and year is the last two digits of the year (e.g. 19)

Inside the instrument and uv data directories, you may use any directory structure that you want. The files will be searched recursively into this structure.

Example of more complex structure:

instr/
    033/
        arf_033.dat
        UVR17419.033
        par_18.033
        par_19.033
    070/
        arf_070.dat
        UVR17019.070
        UVR17319.070
        par_18.070
        par_19.070
    ...

uvdata/
    033/
        2018/
            B17018.033
            UV17018.033
            ...
        2019/
            B17019.033
            B17119.033
            UV17019.033
            UV17119.033
            ...
    070/
        2018/
            B17018.070
            UV17018.070
            ...
        2019/
            B17019.070
            B17119.070
            UV17019.070
            UV17119.070
            ...
    ...

The output directory is the place where BUVIC will write its output files. BUVIC will automatically create a structure to group files by year.

File formats

Parameter files

The parameter files are composed of multiple rows, where each row is composed of five values separated by a semicolon (;).

The first value of each row is the day since new year, the second value is the albedo, the third and fourth values are the angstrom's alpha and beta of the aerosol and the fifth value is the cloud coverage (0 for no cloud and 1 for cloudy).

In the first line of the file, only the cloud coverage is optional. The other values cannot be empty. For the following lines, the albedo, alpha and beta values can be omitted. If this is the case, the value of the last line with non empty value is used. If the cloud coverage is omitted in any line, the value will be retrieved from the darksky api.

Here is an example of a parameter file content par_19.033:

10;0.1;1;0.1;
11;;1.2;0.2;1
12;0.3;;;0
14;0.5;1.5;0.5;

Output files

The output files are in the qasume format. Their names have the following pattern: <days><hour><minute>.<brewer_id> and are placed in subdirectories with instrument id and year as names. In the file name pattern, days is the number of days since new year and hour and minute is the time of the measurement.

Each qasume file begins with five header lines, each beginning with % . The first header line contains information about the file generation. The second header line contains the URL to BUVIC's source code. The third header line contains the place of the measurement with its name, latitude and longitude. The fourth line gives information about the parameter used for calculation. Each info has the format <name>=<value> and infos are separated by a tabulation. The value for coscor is followed by the cloud coverage in parenthesis if this value was taken from darksky. The fifth line contains the headers for the three columns of data.

After the header, the following rows contain the data. Each row contains three values separated by white spaces: the wavelength, the spectral irradiance and the time of the measurement (see the third line of the header for more details).

Here is an example of a (truncated) qasume file 1751500G.166:

% Generated with Brewer UV Irradiance Calculation v4.1 at 2020-01-27 09:53:23
% https://github.com/pec0ra/buvic
% El Arenosillo 37.1N 6.73W
% type=ua	coscor=clear_sky(darksky:0.87)	tempcor=1.0	straylightcor=Applied	o3=304.1DU	albedo=0.04	alpha=1.3	beta=0.1	uvr_source=data/instr/UVR17319.166
% wavelength(nm)	spectral_irradiance(W m-2 nm-1)	time_hour_UTC
290.0	 0.000000000	   15.00017
290.5	 0.000000000	   15.00133
291.0	 0.000000000	   15.00217
291.5	 0.000000000	   15.00300
292.0	 0.000000753	   15.00383
292.5	 0.000019589	   15.00467
293.0	 0.000031382	   15.00550
293.5	 0.000040690	   15.00633
294.0	 0.000069275	   15.00717
294.5	 0.000108455	   15.00800
295.0	 0.000185324	   15.00883
...