# scope_profiler.region

*module*

Data container for a single profiling region loaded from HDF5.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L1-L1)

## scope_profiler.region.NS_PER_SECOND

*attribute* · *module attribute*

```python
NS_PER_SECOND = 1000000000.0
```

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L7-L7)

## scope_profiler.region.EventDataUnavailableError

*class*

```python
class EventDataUnavailableError(RuntimeError)
```

Bases: `RuntimeError`

Raised when a summary-only result is asked for per-call event data.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L10-L11)

## scope_profiler.region.Region

*class*

```python
class Region
```

Timing data for one region on one rank.

All duration and timestamp properties are reported in **seconds**;
the underlying HDF5 data is stored in nanoseconds.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L14-L650)

### scope_profiler.region.Region.average_duration

*property*

```python
average_duration: float
```

Average duration per call in seconds.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L530-L536)

### scope_profiler.region.Region.await_times

*property*

```python
await_times: np.ndarray | None
```

Seconds each call spent with its task suspended, or None.

The wall time inside the ``with`` block during which the task was not
running: awaiting, or switched away from. Subtracting it from the
call's duration leaves the time the lane actually held its thread.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L274-L283)

### scope_profiler.region.Region.await_times_ns

*property*

```python
await_times_ns: np.ndarray | None
```

Nanoseconds each call spent with its task suspended, or None.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L269-L271)

### scope_profiler.region.Region.call_ids

*property*

```python
call_ids
```

Explicit call ids, or None for legacy profiles.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L343-L345)

### scope_profiler.region.Region.durations

*property*

```python
durations: np.ndarray
```

Duration of all calls in seconds.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L462-L464)

### scope_profiler.region.Region.durations_ns

*property*

```python
durations_ns: np.ndarray
```

Duration of all calls in nanoseconds, as integers.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L414-L416)

### scope_profiler.region.Region.end_times

*property*

```python
end_times: np.ndarray
```

End times of all calls in seconds.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L457-L459)

### scope_profiler.region.Region.end_times_ns

*property*

```python
end_times_ns: np.ndarray
```

End times of all calls in nanoseconds, exactly as stored.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L409-L411)

### scope_profiler.region.Region.event_metadata

*property*

```python
event_metadata: tuple[dict, ...]
```

Per-call scoped metadata, aligned with the event arrays.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L251-L253)

### scope_profiler.region.Region.exclusive_duration

*property*

```python
exclusive_duration: float
```

Alias for :attr:`total_exclusive_duration`.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L525-L527)

### scope_profiler.region.Region.exclusive_durations

*property*

```python
exclusive_durations: np.ndarray
```

Exclusive duration of every call in seconds.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L479-L481)

### scope_profiler.region.Region.exclusive_durations_ns

*property*

```python
exclusive_durations_ns: np.ndarray
```

Exclusive duration of every call in nanoseconds.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L429-L431)

### scope_profiler.region.Region.first_duration

*property*

```python
first_duration: float
```

Duration of the first recorded call, in seconds.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L571-L575)

### scope_profiler.region.Region.first_start_time

*property*

```python
first_start_time: float
```

First start time in seconds.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L439-L445)

### scope_profiler.region.Region.gpu_average_duration

*property*

```python
gpu_average_duration: float | None
```

Average CUDA-event elapsed device time in seconds, or None if absent.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L539-L550)

### scope_profiler.region.Region.gpu_durations

*property*

```python
gpu_durations: np.ndarray | None
```

CUDA-event elapsed device times in seconds, or None if absent.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L467-L471)

### scope_profiler.region.Region.gpu_durations_ns

*property*

```python
gpu_durations_ns: np.ndarray | None
```

CUDA-event elapsed device times in nanoseconds, or None if absent.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L419-L421)

### scope_profiler.region.Region.gpu_total_duration

*property*

```python
gpu_total_duration: float | None
```

Total CUDA-event elapsed device time in seconds, or None if absent.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L498-L506)

### scope_profiler.region.Region.has_event_data

*property*

```python
has_event_data: bool
```

Whether per-call timestamps were loaded for this region.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L358-L360)

### scope_profiler.region.Region.has_gpu_timing

*property*

```python
has_gpu_timing: bool
```

Whether this region has CUDA-event elapsed timings.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L368-L372)

### scope_profiler.region.Region.has_source

*property*

```python
has_source: bool
```

Whether this region's call-site source was captured.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L363-L365)

### scope_profiler.region.Region.has_thread_data

*property*

```python
has_thread_data: bool
```

Whether this region recorded the thread each call ran on.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L293-L295)

### scope_profiler.region.Region.has_timing

*property*

```python
has_timing: bool
```

Whether this region recorded any calls at all.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L353-L355)

### scope_profiler.region.Region.inclusive_duration

*property*

```python
inclusive_duration: float
```

Total inclusive time, including nested regions, in seconds.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L509-L511)

### scope_profiler.region.Region.inclusive_durations

*property*

```python
inclusive_durations: np.ndarray
```

Inclusive duration of every call in seconds.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L474-L476)

### scope_profiler.region.Region.inclusive_durations_ns

*property*

```python
inclusive_durations_ns: np.ndarray
```

Inclusive duration of every call in nanoseconds.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L424-L426)

### scope_profiler.region.Region.last_duration

*property*

```python
last_duration: float
```

Duration of the last recorded call, in seconds.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L578-L582)

### scope_profiler.region.Region.last_end_time

*property*

```python
last_end_time: float
```

Last end time in seconds.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L448-L454)

### scope_profiler.region.Region.max_duration

*property*

```python
max_duration: float
```

Maximum duration among all calls in seconds.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L562-L568)

### scope_profiler.region.Region.min_duration

*property*

```python
min_duration: float
```

Minimum duration among all calls in seconds.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L553-L559)

### scope_profiler.region.Region.num_calls

*property*

```python
num_calls: int
```

Number of recorded calls.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L484-L486)

### scope_profiler.region.Region.p50_duration

*property*

```python
p50_duration: float | None
```

Median duration in seconds.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L617-L619)

### scope_profiler.region.Region.p95_duration

*property*

```python
p95_duration: float | None
```

95th-percentile duration in seconds.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L622-L624)

### scope_profiler.region.Region.p99_duration

*property*

```python
p99_duration: float | None
```

99th-percentile duration in seconds.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L627-L629)

### scope_profiler.region.Region.parent_ids

*property*

```python
parent_ids
```

Explicit parent ids, or None for legacy profiles.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L348-L350)

### scope_profiler.region.Region.source_file

*property*

```python
source_file: str | None
```

Path of the file this region is defined in, or None if not captured.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L380-L382)

### scope_profiler.region.Region.source_lineno

*property*

```python
source_lineno: int | None
```

Line the region's call site starts at, or None if not captured.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L385-L387)

### scope_profiler.region.Region.source_text

*property*

```python
source_text: str | None
```

Source text of the region's ``with`` block or decorated function.

None if it was not captured - either the file it came from is no
longer readable, or the file predates this being recorded.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L390-L396)

### scope_profiler.region.Region.start_times

*property*

```python
start_times: np.ndarray
```

Start times of all calls in seconds.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L434-L436)

### scope_profiler.region.Region.start_times_ns

*property*

```python
start_times_ns: np.ndarray
```

Start times of all calls in nanoseconds, exactly as stored.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L404-L406)

### scope_profiler.region.Region.std_duration

*property*

```python
std_duration: float
```

Standard deviation of durations in seconds.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L585-L597)

### scope_profiler.region.Region.stored_summary

*property*

```python
stored_summary: dict | None
```

Fixed-size statistics used by aggregate and summary-only results.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L375-L377)

### scope_profiler.region.Region.tags

*property*

```python
tags: tuple[str, ...]
```

User-defined tags attached to this region.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L399-L401)

### scope_profiler.region.Region.task_ids

*property*

```python
task_ids: np.ndarray | None
```

Task-table index of every call, ``-1`` outside a task.

None unless the run used ``track_async``.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L261-L266)

### scope_profiler.region.Region.thread_ids

*property*

```python
thread_ids: np.ndarray | None
```

Thread-table index of every call, or None if threads were not tracked.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L256-L258)

### scope_profiler.region.Region.threads

*property*

```python
threads: list[int]
```

Sorted thread-table indices this region recorded calls on.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L298-L302)

### scope_profiler.region.Region.total_await_duration

*property*

```python
total_await_duration: float | None
```

Total awaited seconds over every call, or None if not tracked.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L286-L290)

### scope_profiler.region.Region.total_duration

*property*

```python
total_duration: float
```

Total time spent in this region in seconds (sum of all durations).

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L489-L495)

### scope_profiler.region.Region.total_exclusive_duration

*property*

```python
total_exclusive_duration: float
```

Total time excluding nested regions, in seconds.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L514-L522)

### scope_profiler.region.Region.events

*method*

```python
def events(origin: float = 0.0) -> list[dict[str, Any]]
```

Return one dict per recorded call.

Parameters
----------
origin : float, optional
    Seconds subtracted from every timestamp, so passing
    ``results.minimum_start_time`` yields a timeline starting at zero
    (default: 0.0, i.e. raw timestamps).

Returns
-------
list of dict
    One entry per call with keys ``call_index``, ``start``, ``end``
    and ``duration``, in seconds and in recorded order.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L200-L248)

### scope_profiler.region.Region.for_thread

*method*

```python
def for_thread(thread_index: int) -> Region
```

A view of this region holding only the calls of one thread.

Every column is sliced with the same mask, so the returned region is
an ordinary :class:`Region` - summaries, durations and percentiles
all describe that thread alone.

Raises
------
ValueError
    If this region has no thread column (the run did not use
    ``track_threads``).

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L304-L340)

### scope_profiler.region.Region.get_summary

*method*

```python
def get_summary() -> dict[str, Any]
```

Return a summary of the region's statistics as a dictionary.

Returns
-------
Dict[str, Any]
    Dictionary containing statistics: num_calls, total_duration,
    average_duration, min_duration, max_duration, first_duration,
    last_duration, and std_duration. Durations are in seconds.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L111-L137)

### scope_profiler.region.Region.percentile_duration

*method*

```python
def percentile_duration(percentile: float) -> float | None
```

Return a duration percentile in seconds.

``percentile`` follows :func:`numpy.percentile` and must be between
0 and 100. Empty regions return ``0.0`` for consistency with the
other duration statistics.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/region.py#L599-L614)