haniwers.v0.cli

Command Line Interface for the haniwers package.

This module provides various command-line tools for data acquisition, processing, and analysis of cosmic ray data collected with the OSECHI detector.

The CLI is built using Typer and provides the following commands:

• version: Display version information

• docs: Open online documentation

• ports: Search for available ports

• scan: Run threshold scanning

• fit: Calculate thresholds from scan data

• vth: Set threshold values

• daq: Run data acquisition

• raw2tmp: Quick parsing of raw data

• run2csv: Parse run data to CSV format

• mock_daq: Run simulated data acquisition (for debugging)

Module Contents

Functions

_setup_logger	Configure loguru logger with appropriate formats and outputs.
_open_docs	Open documentation in default web browser.
version	Show haniwers version.
docs	Open online documentation in the default web browser.
ports	Search available ports and show device names.
scan	Start threshold scanning measurement.
fit	Calculate thresholds from scan data using error function fitting.
vth	Set threshold values for detector channels.
scan_serial	Perform threshold scanning measurement per channel in serial mode.
scan_parallel	Perform threshold scanning measurement in parallel mode.
daq	Start data acquisition with configured settings.
raw2tmp	Quick conversion of raw data for temporary analysis.
run2csv	Convert run data to CSV format for analysis.
mock_daq	Run simulated data acquisition for testing and debugging.

Data

DOCS	URLs of online documents for each command.
app

API

haniwers.v0.cli.DOCS

None

URLs of online documents for each command.

haniwers.v0.cli._setup_logger(level='INFO') → pathlib.Path

Configure loguru logger with appropriate formats and outputs.

Sets up the logger with different formats depending on the log level:

• For DEBUG level: Includes filename, function, and line number

• For other levels: Simpler format with timestamp, level, and message

Also configures a JSON file logger with DEBUG level for comprehensive logging.

Parameters

level : str, default “INFO” Log level for stderr output.

Returns

Path Path to the log file.

Notes

DEBUG level: Includes filename, function, and line number Other levels: Simpler format with timestamp, level, and message

haniwers.v0.cli._open_docs(value: bool, url: str) → None

Open documentation in default web browser.

Private function used as a callback for the --docs option in commands.

Parameters

value : bool Boolean flag indicating whether to open documentation. url : str URL of the documentation to open.

Raises

typer.Exit Exits the program after opening the documentation.

Examples

Used as callback function for --docs option in existing commands:

typer.Option( … “–docs”, … help=f"Open online document. ({DOCS[‘version’]})", … callback=lambda v: _open_docs(v, DOCS[“version”]), … )

haniwers.v0.cli.app

‘Typer(…)’

haniwers.v0.cli.version(env: typing_extensions.Annotated[bool, typer.Option(help='Show environment information.')] = False, log_level: typing_extensions.Annotated[str, typer.Option(help='Set log level (DEBUG, INFO, WARNING, ERROR).')] = 'INFO', docs: typing_extensions.Annotated[bool, typer.Option('--docs', help=f"Open online documentation. ({DOCS['version']})", callback=lambda v: _open_docs(v, DOCS['version']))] = False)

Show haniwers version.

Shows the current version of haniwers. With the --env flag, also displays detailed environment information such as Python version, platform details, and log file location.

Parameters

env : bool, default False Show with environment details. log_level : str, default “INFO” Log level.

Examples

Basic version display:

… code-block:: console

$ haniwers version
haniwers 0.19.1

With environment details:

… code-block:: console

$ haniwers version --env
haniwers 0.19.2

Environments:

Logs: ~/Library/Logs/haniwers/0.19.2/haniwers_log.json
Executable: ~/.local/pipx/venvs/haniwers/bin/python
Python: 3.12.5
Implementation: CPython
Compiler: Clang 15.0.0 (clang-1500.3.9.4)
OS: macOS-14.6.1-arm64-arm-64bit
System: darwin
Platform: Darwin
Kernel: 23.6.0
Arch: arm64

haniwers.v0.cli.docs(page: typing_extensions.Annotated[str, typer.Option(help='Set page name.')] = 'home')

Open online documentation in the default web browser.

Parameters

page : str, default “home” The name of the documentation to open.

Examples

Open home page:

… code-block:: console

$ haniwers docs

Open specific page:

… code-block:: console

$ haniwers docs --page version
$ haniwers docs --page scan
$ haniwers docs --page fit
$ haniwers docs --page vth
$ haniwers docs --page daq
$ haniwers docs --page raw2tmp
$ haniwers docs --page run2csv

Notes

Added in version 0.19.0

haniwers.v0.cli.ports(log_level: typing_extensions.Annotated[str, typer.Option(help='Change log level')] = 'INFO') → None

Search available ports and show device names.

Lists all available serial ports that can be used for connecting to OSECHI detector.

Parameters

log_level : str, default “INFO” Set the logging level.

Examples

Run on macOS:

… code-block:: console

$ haniwers ports
| INFO     | Found 2 ports
| INFO     | Port0: /dev/cu.Bluetooth-Incoming-Port - n/a
| INFO     | Port1: /dev/cu.usbserial-140 - USB Serial

Notes

The name of USB port varies by operating system: - Linux: /dev/ttyUSB0 - macOS: /dev/cu.usbserial-* (CP2102N USB to UART Bridge Controller) - Windows: COM3

haniwers.v0.cli.scan(ch: typing_extensions.Annotated[int, typer.Option(help='Set channel ID.')] = 0, duration: typing_extensions.Annotated[int, typer.Option(help='Set duration. Unit: [sec]')] = 10, step: typing_extensions.Annotated[int, typer.Option(help='Set step interval. Unit: [step]')] = 1, vmin: typing_extensions.Annotated[int, typer.Option(help='Set start point. Unit: [step]')] = 250, vmax: typing_extensions.Annotated[int, typer.Option(help='Set end point. Unit: [step]')] = 311, vstarts: typing_extensions.Annotated[str, typer.Option(help='Comma-separated start thresholds per channel.')] = '250, 250, 250', nsteps: typing_extensions.Annotated[int, typer.Option(help='Number of threshold steps.')] = 50, quiet: typing_extensions.Annotated[bool, typer.Option(help='Quiet mode.')] = False, load_from: typing_extensions.Annotated[str, typer.Option(help='Set filename.')] = 'scan.toml', log_level: typing_extensions.Annotated[str, typer.Option(help='Change log level.')] = 'INFO', docs: typing_extensions.Annotated[bool, typer.Option('--docs', help=f"Open online document. ({DOCS['scan']})", callback=lambda v: _open_docs(v, DOCS['scan']))] = False) → None

Start threshold scanning measurement.

Performs threshold scanning by measuring the event rate at various threshold values. This is used to determine the optimal threshold settings for each channel.

Parameters

ch : int, default 0 Channel ID (1-3, or 0 for all channels). duration : int, default 10 Measurement duration per point in seconds. step : int, default 1 Step interval for threshold scanning. vmin : int, default 250 Start point for scanning range (deprecated). vmax : int, default 311 End point for scanning range (deprecated). nsteps : int, default 50 Number of threshold steps to measure. vstarts : str, default “250,250,250” Comma-separated start thresholds per channel. quiet : bool, default False Suppress progress output. load_from : str, default “scan.toml” Configuration file path. log_level : str, default “INFO” Log level. docs : bool, default False Open online documentation.

Examples

Scan all channels with default settings:

… code-block:: console

$ haniwers scan

Scan specific channel with custom parameters:

… code-block:: console

$ haniwers scan --ch 1 --duration=30 --step 5
$ haniwers scan --vstarts="200,200,200" --nsteps=40

Notes

The --vmin and --vmax parameters are deprecated. Use --vstarts, --step, and --nsteps instead.

haniwers.v0.cli.fit(read_from: typing_extensions.Annotated[str, typer.Argument(help='Set directory.')], params: typing_extensions.Annotated[str, typer.Option(help='Set initial fit parameters (commma separated string).')] = '10,300,1,1', search_pattern: typing_extensions.Annotated[str, typer.Option(help='Set filename.')] = 'threshold_scan.csv', ch: typing_extensions.Annotated[int, typer.Option(help='Set channel ID')] = 0, log_level: typing_extensions.Annotated[str, typer.Option(help='Change log level')] = 'INFO', docs: typing_extensions.Annotated[bool, typer.Option('--docs', help=f"Open online document. ({DOCS['fit']})", callback=lambda v: _open_docs(v, DOCS['fit']))] = False)

Calculate thresholds from scan data using error function fitting.

Analyzes threshold scan data to estimate optimal threshold values using error function fitting. Results are saved to both a historical record and a latest version file for use by other commands.

Parameters

read_from : str Directory containing threshold scan data. params : str, default “10,300,1,1” Initial fit parameters as comma-separated string. search_pattern : str, default “threshold_scan.csv” Filename pattern for scan data files. ch : int, default 0 Channel ID (1-3, or 0 for all channels). log_level : str, default “INFO” Log level. docs : bool, default False Open online documentation.

Examples

Calculate thresholds for all channels:

… code-block:: console

$ haniwers fit path_data_directory

With custom fit parameters:

… code-block:: console

$ haniwers fit data_dir --params="5,250,2,0.5"

Notes

Results are saved to: - threshold_history.csv: Appends results with timestamps for historical tracking - threshold_latest.csv: Overwrites with most recent results for use by the vth command

haniwers.v0.cli.vth(ch: typing_extensions.Annotated[int, typer.Option(help='Set channel ID')] = 0, vth: typing_extensions.Annotated[int, typer.Option(help='Set threshold value.')] = 0, max_retry: typing_extensions.Annotated[int, typer.Option(help='Set numbers to retry.')] = 3, load_from: typing_extensions.Annotated[str, typer.Option(help='Set filename.')] = 'daq.toml', log_level: typing_extensions.Annotated[str, typer.Option(help='Change log level.')] = 'INFO', docs: typing_extensions.Annotated[bool, typer.Option('--docs', help=f"Open online document. ({DOCS['vth']})", callback=lambda v: _open_docs(v, DOCS['vth']))] = False) → None

Set threshold values for detector channels.

Sets threshold values for detector channels. Can set values individually by channel or apply optimal values calculated by the fit command to all channels.

Each step corresponds to 4mV. For example, a value of 250 equals 1000mV.

Parameters

ch : int, default 0 Channel ID to set (1, 2, 3). Use 0 to set all channels. vth : int, default 0 Threshold value to set. Use 0 to apply values from threshold_latest.csv. max_retry : int, default 3 Maximum retry attempts if threshold setting fails. load_from : str, default “daq.toml” Configuration file path. log_level : str, default “INFO” Log level. docs : bool, default False Open online documentation.

Examples

Set thresholds for all channels using values from threshold_latest.csv:

… code-block:: console

$ haniwers vth

Set threshold for specific channel:

… code-block:: console

$ haniwers vth --ch 1 --vth 278
$ haniwers vth --ch 2 --vth 268
$ haniwers vth --ch 3 --vth 300

Notes

• We still don’t know the reason why threshold setting fails sometimes.

• If threshold writing fails, it will retry up to max_retry times.

• When setting all channels (ch=0 and vth=0), values are read from threshold_latest.csv.

haniwers.v0.cli.scan_serial(ch: int = 0, duration: int = 10, step: int = 1, vmin: int = 250, vmax: int = 311, quiet: bool = False, load_from='daq.toml', log_level: str = 'INFO') → None

Perform threshold scanning measurement per channel in serial mode.

Parameters

ch : int, default 0 Channel number (1-3, or 0 for all channels). duration : int, default 10 Measurement time per point in seconds. step : int, default 1 Step interval for scanning. vmin : int, default 250 Minimum threshold value for scanning range. vmax : int, default 311 Maximum threshold value for scanning range. quiet : bool, default False Suppress progress output. load_from : str, default “daq.toml” Configuration file path. log_level : str, default “INFO” Log level.

haniwers.v0.cli.scan_parallel(ch: int = 0, duration: int = 10, step: int = 1, vmin: int = 250, vmax: int = 311, quiet: bool = False, load_from='daq.toml', log_level: str = 'INFO') → None

Perform threshold scanning measurement in parallel mode.

Parameters

ch : int, default 0 Channel number (1-3, or 0 for all channels). duration : int, default 10 Measurement time per point in seconds. step : int, default 1 Step interval for scanning. vmin : int, default 250 Minimum threshold value for scanning range. vmax : int, default 311 Maximum threshold value for scanning range. quiet : bool, default False Suppress progress output. load_from : str, default “daq.toml” Configuration file path. log_level : str, default “INFO” Log level.

haniwers.v0.cli.daq(quiet: typing_extensions.Annotated[bool, typer.Option(help='Quiet mode.')] = False, load_from: typing_extensions.Annotated[str, typer.Option(help='Set filename.')] = 'daq.toml', log_level: typing_extensions.Annotated[str, typer.Option(help='Change log level')] = 'INFO', docs: typing_extensions.Annotated[bool, typer.Option('--docs', help=f"Open online document. ({DOCS['daq']})", callback=lambda v: _open_docs(v, DOCS['daq']))] = False) → None

Start data acquisition with configured settings.

Starts the data acquisition process using settings from the configuration file. Collects cosmic ray events and environmental data from the OSECHI detector.

Parameters

quiet : bool, default False Suppress progress output. load_from : str, default “daq.toml” Configuration file path. log_level : str, default “INFO” Log level. docs : bool, default False Open online documentation.

Examples

Start data acquisition with default settings:

… code-block:: console

$ haniwers daq

Start in quiet mode:

… code-block:: console

$ haniwers daq --quiet

Notes

• Data is saved to the directory specified in the configuration file, organized by date in YYYYMMDD format.

• Press Ctrl+c to stop data acquisition.

• The program automatically creates directories if they don’t exist.

haniwers.v0.cli.raw2tmp(read_from: typing_extensions.Annotated[str, typer.Argument(help='Directory containing raw data.')], search_pattern: typing_extensions.Annotated[str, typer.Option(help='Filename pattern for raw data.')] = '*.csv', interval: typing_extensions.Annotated[int, typer.Option(help='Resampling interval in seconds.')] = 600, offset: typing_extensions.Annotated[int, typer.Option(help='Datetime offset in seconds')] = 0, tz: typing_extensions.Annotated[str, typer.Option(help='Timezone for data.')] = 'UTC+09:00', log_level: typing_extensions.Annotated[str, typer.Option(help='Set log level (DEBUG, INFO, WARNING, ERROR).')] = 'INFO', docs: typing_extensions.Annotated[bool, typer.Option('--docs', help=f"Open online documentation. ({DOCS['raw2tmp']})", callback=lambda v: _open_docs(v, DOCS['raw2tmp']))] = False) → None

Quick conversion of raw data for temporary analysis.

Converts raw cosmic ray data into a simplified CSV format for quick analysis. This is intended for temporary use to quickly check data during measurement. For thorough analysis, use the run2csv command instead.

Parameters

read_from : str Path to the directory containing raw data files. search_pattern : str, default “*.csv” Pattern to match raw data files. interval : int, default 600 Resampling interval in seconds (10 minutes). offset : int, default 0 Time offset correction in seconds. tz : str, default “UTC+09:00” Timezone for data timestamps. log_level : str, default “INFO” Log level. docs : bool, default False Open online documentation.

Examples

Quick convert data with default settings:

… code-block:: console

$ haniwers raw2tmp path_data_directory

With custom parameters:

… code-block:: console

$ haniwers raw2tmp data_dir --search-pattern="*.dat"
$ haniwers raw2tmp data_dir --interval=10
$ haniwers raw2tmp data_dir --offset=36480
$ haniwers raw2tmp data_dir --tz="UTC+09:00"

Notes

Output files: - tmp_raw2tmp.csv.gz: Raw data with all events - tmp_raw2tmp.csv: Resampled data at specified interval

The time offset option is useful for correcting clock drift on Raspberry Pi devices that lack a real-time clock.

haniwers.v0.cli.run2csv(run_id: typing_extensions.Annotated[int, typer.Argument(help='Run ID')], save: typing_extensions.Annotated[bool, typer.Option(help='Save results to files.')] = False, load_from: typing_extensions.Annotated[str, typer.Option(help='Run configuration files.')] = 'runs.csv', drive: typing_extensions.Annotated[str, typer.Option(help='Data directory.')] = '../data', log_level: typing_extensions.Annotated[str, typer.Option(help='Set log level (DEBUG, INFO, WARNING, ERROR).')] = 'INFO', docs: typing_extensions.Annotated[bool, typer.Option('--docs', help=f"Open online documentation. ({DOCS['run2csv']})", callback=lambda v: _open_docs(v, DOCS['run2csv']))] = False) → None

Convert run data to CSV format for analysis.

Processes raw data from a specific run and converts it to CSV format for analysis. Uses run configuration information from runs.csv to determine proper processing parameters.

Parameters

run_id : int Run identifier number to process. save : bool, default False Save processed data to files. load_from : str, default “runs.csv” Run configuration file path. drive : str, default “…/data” Base directory containing data. log_level : str, default “INFO” Log level. docs : bool, default False Open online documentation.

Examples

Process run #98 without saving (preview mode):

… code-block:: console

$ haniwers run2csv 98

Process run #98 and save results:

… code-block:: console

$ haniwers run2csv 98 --save

With custom configuration location:

… code-block:: console

$ haniwers run2csv 98 --drive="../data" --load_from="runs.csv"

Notes

• If run_id is invalid or not found in the configuration, the program will exit with an error message.

• When --save is not specified, the command will process data but not save any files, acting as a preview mode.

• Output files are determined by the run configuration and include:

  • A compressed raw data file (.csv.gz)

  • A resampled data file (.csv)

haniwers.v0.cli.mock_daq(quiet: typing_extensions.Annotated[bool, typer.Option(help='Quiet mode.')] = False, load_from: typing_extensions.Annotated[str, typer.Option(help='Set filename')] = 'daq.toml', log_level: typing_extensions.Annotated[str, typer.Option(help='Change log level')] = 'DEBUG')

Run simulated data acquisition for testing and debugging.

Creates simulated cosmic ray events without requiring actual OSECHI hardware. This command is useful for development, testing, and debugging purposes.

Parameters

quiet : bool, default False Suppress progress output. load_from : str, default “daq.toml” Configuration file path. log_level : str, default “DEBUG” Log level.

Examples

Run simulated data acquisition:

… code-block:: console

$ haniwers mock_daq

With custom configuration:

… code-block:: console

$ haniwers mock_daq --load_from="test_config.toml"

Notes

• Generated data follows the same format as real data but uses random values.

• The mock DAQ uses reduced file counts and row counts for quicker execution.

• Data is saved to the directory specified in the configuration file, organized by date in YYYYMMDD format, just like the real daq command.