PDF output¶

Neptoon can create a processing report during normal station processing. The report is intended as a compact quality-control artefact: it combines station metadata, processing notes, selected figures, calibration information when available, and provenance for external data sources.

The PDF is useful for reviewing a run and sharing the main diagnostic plots. It is not a replacement for the exported CSV/JSON tables and flags, which remain the reproducible outputs for downstream analysis.

Enable report creation¶

Set create_report in the sensor configuration:

data_storage:
  save_location: ~/neptoon-outputs/station_A101
  append_timestamp_to_folder_name: true
  create_report: true
  report_plot_downsampling: true

figures:
  create_figures: true
  make_all_figures: true

The report is written to the same output folder as the processed data. The filename follows the pattern Report-<sensor-name>.pdf.

Report-related data-storage options¶

Option	Default	Description
`data_storage.create_report`	`false`	Enables the PDF report. When enabled, Neptoon activates the report backend during the processing run.
`data_storage.report_plot_downsampling`	`true`	Downsamples report-only plot data for readability and smaller PDFs. Processed CSV/JSON outputs are not downsampled.
`data_storage.save_location`	`null`	Output directory for processed tables, figures and the report. Relative YAML paths resolve relative to the config file.
`data_storage.append_timestamp_to_folder_name`	`true`	Adds a timestamp to the run folder so repeated runs do not overwrite each other.
`data_storage.append_audit_log_hash_to_folder_name`	`false`	Adds a short audit-log hash to the output folder for traceability.

report_plot_downsampling only affects figures drawn into the report or figure files. It never changes processed data tables.

Figures in reports¶

Report figures are controlled by the figures section:

figures:
  create_figures: true
  make_all_figures: true
  # auto switches to daily precipitation for long reports; hourly forces
  # hourly bars when an hourly precipitation column is available.
  precipitation_resolution: auto
  custom_list: null
  soil_moisture_sensor_comparison:
    columns: [smt1SoilMoist, smt2SoilMoist, smt3SoilMoist]
    units:
      smt1SoilMoist: vol_percent
      smt2SoilMoist: vol_percent
      smt3SoilMoist: fraction
    display_unit: vol_percent
    include_precipitation: true
    precipitation_resolution: hourly
    title: CRNS and in-situ soil moisture
    crns_label: CRNS soil moisture
  additional_plots:
    meteo_check:
      columns: [air_pressure, air_temperature, air_relative_humidity]
      title: Meteorological inputs
      y_label: Mixed units

Figure configuration reference¶

Option	Default	Description
`figures.create_figures`	`true`	Create configured figure files and report figures. If this is `false`, report figures are not generated even when `create_report` is true.
`figures.make_all_figures`	`true`	Generate all built-in figure types that have their required columns.
`figures.custom_list`	`null`	Generate only the named built-in figures when `make_all_figures` is false. Valid names include `nmdb_incoming_radiation`, `correction_factors_figure`, `neutron_counts_corr_uncorr`, `soil_moisture_uncertainty`, `atmospheric_variables`, `dwd_weather_products`, `soil_moisture_sensor_comparison`, and `additional_plots`.
`figures.precipitation_resolution`	`auto`	Controls precipitation bars in report soil-moisture plots. `auto` uses hourly bars for compact windows and daily totals for longer windows; `hourly` forces hourly when available and falls back to daily; `daily` always plots daily totals.
`figures.soil_moisture_sensor_comparison`	empty config	Optional CRNS/in-situ soil-moisture comparison plot.
`figures.additional_plots`	`{}`	User-defined plots keyed by plot identifier. Each entry can be a list of columns or a mapping with `columns`, `title` and `y_label`.

Built-in report figures¶

Figure id	Topic	What it shows
`nmdb_incoming_radiation`	NMDB	Incoming cosmic-ray reference data used for neutron correction.
`correction_factors_figure`	Neutrons	Correction factors applied to raw neutron counts.
`neutron_counts_corr_uncorr`	Neutrons	Corrected and uncorrected neutron count rates at the sensor.
`soil_moisture_uncertainty`	Soil moisture	Volumetric soil-moisture time series with uncertainty bounds.
`soil_moisture_sensor_comparison`	Soil moisture	CRNS volumetric soil moisture compared with configured in-situ soil-moisture columns.
`atmospheric_variables`	Atmospheric conditions	Pressure, temperature, relative humidity and absolute humidity when available.
`dwd_weather_products`	Weather/external sources	Optional weather products such as precipitation and solar/global radiation.
`additional_plots`	Additional plots	User-defined diagnostic plots configured in `figures.additional_plots`.

A built-in figure is skipped if the required columns for that figure are not present. This is normal: for example, calibration information only appears when calibration was run, and DWD/weather-product plots only appear when those columns were attached.

Soil-moisture sensor comparison¶

figures.soil_moisture_sensor_comparison.columns configures optional in-situ soil-moisture sensors to draw on the same y-axis as the CRNS volumetric soil-moisture product. Neptoon first normalises all configured inputs to its internal m³/m³ fraction representation. Use the units mapping for explicit, reproducible input conversion; columns without an entry keep the legacy auto heuristic based on the column name and value range. The separate display_unit option controls whether the finished plot uses fractions (0..1) or volumetric percent (0..100).

Option	Default	Description
`columns`	`[]`	In-situ soil-moisture columns to plot. Up to ten columns are accepted to keep the report readable. The short-list form is also accepted: `soil_moisture_sensor_comparison: [smt1, smt2]`.
`units`	`{}`	Input-unit mapping from configured column names to `fraction`, `vol_percent`, or `auto`. Aliases such as `m3/m3`, `m³/m³`, `vol%`, `percent`, and `pct` are accepted and stored canonically. Explicit values override heuristic detection.
`display_unit`	`fraction`	Output unit for the shared plot axis: `fraction` displays m³/m³ values from `0..1`; `vol_percent` displays volumetric percent from `0..100`. Common aliases such as `m3/m3` and `vol%` are accepted.
`include_precipitation`	`true`	Overlay precipitation bars on an inverted right y-axis when precipitation data are available.
`precipitation_resolution`	inherits global setting	Optional override for this plot: `auto`, `hourly` or `daily`.
`title`	auto	Optional plot title.
`crns_label`	`CRNS soil moisture`	Legend label for the CRNS volumetric soil-moisture series.
`y_label`	automatic	Optional shared y-axis label. When omitted, Neptoon uses `Water content (m³/m³)` for `fraction` and `Water content (vol%)` for `vol_percent`.

Set include_precipitation: false to suppress the precipitation overlay when the report should show only soil-moisture lines.

Additional plots¶

Use figures.additional_plots for simple report plots that combine arbitrary existing DataFrame columns. This is useful for checking meteorological inputs, external-source columns, QA flags or custom sensor channels.

figures:
  additional_plots:
    meteo_sources:
      columns:
        - air_pressure
        - air_temperature
        - air_relative_humidity
      title: Meteorological inputs used for correction
      y_label: Mixed units
    neutron_diagnostics:
      - epithermal_neutrons_raw
      - epithermal_neutrons_raw_coverage_fraction

Each additional plot entry must contain at least one column. Missing columns are detected during validation; check column names with neptoon explain-output-columns or inspect the processed CSV when creating custom plots.

Report layout and content¶

Generated PDFs use a compact scientific report layout. Each report starts with a cover page summarising the station, processing period, record count, coordinates, elevation when available, and generation time.

The report can contain these topic pages when data are available:

Neutrons and NMDB — neutron counts, incoming radiation and correction factors.
Soil Moisture — final soil moisture, uncertainty and optional CRNS/in-situ comparison.
Atmospheric Conditions — pressure, temperature, humidity and absolute humidity.
External Sources and Weather — DWD/external-meteo provenance and optional precipitation or solar-radiation products.
Additional Plots — user-defined diagnostic plots.
Calibration — calibration summary and figures when calibration was run.
Data Preparation — preparation notes and processing metadata where available.

Figure pages use publication-style axes with closed frames, muted grid lines, compact legends, and consistent CRNS colour choices.

Recommendations for good reports¶

Keep report_plot_downsampling: true for long time series. Turn it off only when every plotted point must be visible.
Use figures.precipitation_resolution: auto for most runs. Use hourly for short event-scale reports and daily for long-term overview reports.
Configure soil_moisture_sensor_comparison.units for every in-situ series when input units are known. Use fraction for m³/m³ values and vol_percent for volumetric percent; reserve auto for legacy or exploratory configs. Select the common plot scale independently with display_unit.
Use additional_plots for run-specific diagnostics rather than adding rarely used plots to the built-in figure list.
Enable DWD or external_meteo provenance columns when meteorological data sources need to be auditable in the report.

Troubleshooting¶

If no PDF appears, confirm that data_storage.create_report is true, figures.create_figures is not false, the report dependencies are installed, and save_location is writable.
If a figure is missing, check whether the required columns existed for that stage. Built-in figures are skipped when their data are unavailable.
If a custom additional_plots figure is missing, check that all configured column names exist after ingestion and renaming.
If plots are too dense, keep report_plot_downsampling: true. Set it to false only when every point must be visible in the report graphic.
If precipitation bars look too dense or too sparse, adjust figures.precipitation_resolution or the per-plot soil_moisture_sensor_comparison.precipitation_resolution.