Instruments Module

This subpackage provides parsers for reading experimental instrument export files commonly used in fire science and fire safety engineering research. Supported formats include thermal analysis (STA, DSC, TGA) and calorimetry (MCC, Cone Calorimeter) instruments.

A generic reader with automatic file type detection is available via firescipy.instruments.read_instrument_file().

Reader

firescipy.instruments.reader.detect_file_type(file_path)

Detect instrument file type by inspecting file content.

Returns a key from FILE_TYPE_PARSERS, or None if the type is unknown.

firescipy.instruments.reader.read_instrument_file(file_path, file_type=None)

Load an instrument export file, optionally with a manually specified type.

Auto-detection is attempted when file_type is None. If detection fails and no file_type is provided, a ValueError is raised with the list of supported types.

Parameters

• file_path (str or Path) – Path to the instrument export file.

• file_type (str, optional) – Force a specific parser. Must be one of SUPPORTED_TYPES. If None, the file type is detected automatically.

Returns

• file_type (str) – The detected or provided file type.

• meta (dict) – Parsed metadata.

• df (pandas.DataFrame) – Parsed measurement table.

Raises

ValueError – If the file type cannot be detected and no file_type is given, or if the provided file_type is not in SUPPORTED_TYPES.

Netzsch STA / DSC / TGA

class firescipy.instruments.netzsch_sta.NetzschSTAParser(file_path, instrument_file=None)

Bases: object

Parser for NETZSCH STA/DSC/TGA ASCII export files.

• metadata lines starting with ‘#’

• table header line starting with ‘##’

• data rows below the table header

Example

#EXPORTTYPE: ;DATA ALL ;;; #DECIMAL: ;COMMA ;;; #SEPARATOR: ;SEMICOLON;;; … ##Temp./°C;Time/min;DSC/(mW/mg);Mass/%

29,958;0;7,67E-02;99,99772 …

DECIMAL_MAP = {'COMMA': ',', 'DOT': '.', 'POINT': '.'}

NUMERIC_METADATA_KEYS = {'REFERENCE CRUCIBLE MASS /mg', 'REFERENCE MASS /mg', 'SAMPLE CRUCIBLE MASS /mg', 'SAMPLE MASS /mg'}

SEPARATOR_MAP = {'COMMA': ',', 'SEMICOLON': ';', 'TAB': '\t'}

parse()

Parse metadata and data table.

Returns

• meta (dict) – Parsed metadata.

• data_df (pandas.DataFrame) – Parsed measurement table.

firescipy.instruments.netzsch_sta.read_netzsch_sta_file(file_path)

Convenience wrapper around NetzschSTAParser.

DEATAK MCC

class firescipy.instruments.deatak_mcc.DeatakMCCParser(file_path, instrument_file=None)

Bases: object

Parser for DEATAK MCC export files.

• metadata lines up top

• table header line starting after ‘@’

• data rows below the table header

Example

File Name: Wood_4mg_45Kmin_R1.txt Version: 8.3.7.3 … @ Time (s) Temperature (C) HRR (W/g)

0.000 74.821 -1.830 …

DECIMAL_MAP = {'COMMA': ',', 'DOT': '.', 'POINT': '.'}

NUMERIC_METADATA_KEYS = {'Baseline Flow', 'Baseline O2', 'Combuster Temperature (C)', 'End Total Mass (mg)', 'Heating Rate (C/s)', 'N2 Flow Rate (cc/min)', 'O2 Flow Rate (cc/min)', 'Sample Cup Mass (mg)', 'Sample Mass (mg)', 'T Correction Coefficients', 'Time Shift (s)'}

SEPARATOR_MAP = {'TAB': '\t'}

parse()

Parse metadata and data table.

Returns

• meta (dict) – Parsed metadata.

• data_df (pandas.DataFrame) – Parsed measurement table.

firescipy.instruments.deatak_mcc.read_deatak_mcc_file(file_path)

Convenience wrapper around DeatakMCCParser.

Netzsch Cone Calorimeter

class firescipy.instruments.netzsch_cone.NetzschConeParser(file_path, instrument_file=None)

Bases: object

Parser for NETZSCH Cone Calorimeter CSV export files.

• Row 0: “General information” label in column 0, measurement column names

  starting from column 2

• Row 1: measurement units starting from column 2 (columns 0-1 are empty)

• Rows 2+: metadata key in column 0, metadata value in column 1,

  measurement values starting from column 2

Unlike the NetzschSTA and Deatak parsers, metadata and measurement data are stored side by side in each row rather than in sequential blocks.

Example

General information;;time (s);O2 (%);HRR/a;… ;;;;;;kW/m²;… Test;;0;20,952;0,0;… Standard used;ISO 5660-1;1;20,954;0,0;… Date of test;27.03.2025;2;20,953;0,0;… …

DECIMAL = ','

NUMERIC_METADATA_KEYS = {'Ambient temperature (°C)', 'Barometric pressure (Pa)', 'C-factor (SI units)', 'CO delay time (s)', 'CO2 delay time (s)', 'Duct diameter (m)', 'E (MJ/kg)', 'Heat flux (kW/m²)', 'Initial mass (g)', 'Nominal duct flow rate (l/s)', 'O2 delay time (s)', 'OD correction factor', 'Relative humidity (%)', 'Sampling interval (s)', 'Separation (mm)', 'Surface area (cm²)', 'Test start time (s)', 'Thickness (mm)', 'Time to flameout (s)', 'Time to ignition (s)', 'User EOT time (s)'}

SEPARATOR = ';'

parse()

Parse metadata, units, and measurement table.

Returns

• meta (dict) – Parsed metadata.

• data_df (pandas.DataFrame) – Parsed measurement table.

firescipy.instruments.netzsch_cone.read_netzsch_cone_file(file_path)

Convenience wrapper around NetzschConeParser.