haniwers.cli

Command Line Interface for the Haniwers Package.

This module provides a command-line interface (CLI) for all haniwers tools. The CLI is built with Typer, making it easy to run commands from your terminal.

Available Commands

System Commands:

• version: Show haniwers version and environment info

• docs: Open online documentation

• ports: Find available serial ports for detector connection

Data Acquisition:

• daq: Collect cosmic ray data from OSECHI detector

• mock_daq: Simulate data (for testing without hardware - developer use)

Data Processing:

• run2csv: Convert run data to CSV format for analysis

• raw2tmp: Quick preview conversion of raw data

Threshold Management:

• scan: Measure threshold response across a range

• fit: Calculate optimal thresholds from scan data

• vth: Set detector voltage thresholds

Example Workflow

# 1. Check available ports
haniwers ports

# 2. Scan threshold values
haniwers scan --ch 1

# 3. Calculate optimal thresholds
haniwers fit scan_data_directory

# 4. Apply thresholds to detector
haniwers vth

# 5. Collect data
haniwers daq

# 6. Convert to analysis format
haniwers run2csv 1 --save

Getting Help

Type any command with --help to see available options:

haniwers daq --help
haniwers scan --help

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.cli.DOCS

None

URLs of online documents for each command.

haniwers.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.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.cli.app

‘Typer(…)’

haniwers.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:

$ haniwers version
haniwers 0.19.1

With environment details:

$ 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.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. Available options: home, version, scan, fit, vth, daq, raw2tmp, run2csv

Examples

Open home page:

$ haniwers docs

Open specific page:

$ 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

haniwers.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:

$ 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.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

# for quick scan: [250, 350] with 5 step increment
$ haniwers scan --vstarts="250,250,250" --step=5 --nsteps=20

# for detailed scan: [250, 350] with 1 step increment
$ haniwers scan --vstarts="250,250,250" --step=1 --nsteps=100

Scan specific channel with custom parameters:

$ haniwers scan --ch 1 --duration=30 --step 5

Notes

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

haniwers.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:

$ haniwers fit path_data_directory

With custom fit parameters:

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

Notes

Results are saved to:

• thresholds_history.csv: Appends results with timestamps for historical tracking

• thresholds_latest.csv: Overwrites with most recent results for use by the vth command

haniwers.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 thresholds_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 thresholds_latest.csv:

$ haniwers vth

Set threshold for specific channel:

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

Notes

• If threshold writing fails, the command automatically retries up to max_retry times (default: 3).

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

haniwers.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.

Note: For most users, use the haniwers scan command instead. This command is provided for advanced usage and backward compatibility.

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.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.

Note: For most users, use the haniwers scan command instead. This command is provided for advanced usage and backward compatibility.

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.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:

$ haniwers daq

Start in quiet mode:

$ 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.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:

$ haniwers raw2tmp path_data_directory

With custom parameters:

$ 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.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):

$ haniwers run2csv 98

Process run #98 and save results:

$ haniwers run2csv 98 --save

With custom configuration location:

$ 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.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.

Developer and Test Use Only: This command is for development, testing, and debugging purposes. For actual cosmic ray measurements, use the daq command with real OSECHI hardware.

Creates simulated cosmic ray events without requiring actual OSECHI hardware.

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:

$ haniwers mock_daq

With custom configuration:

$ 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.