# ucncycle

[Ucndata Index](./README.md#ucndata-index) / ucncycle

> Auto-generated documentation for [ucncycle](../ucndata/ucncycle.py) module.

- [ucncycle](#ucncycle)
  - [ucncycle](#ucncycle-1)
    - [ucncycle.check_data](#ucncyclecheck_data)
    - [ucncycle.draw_cycle_times](#ucncycledraw_cycle_times)
    - [ucncycle.get_nhits](#ucncycleget_nhits)
    - [ucncycle.get_period](#ucncycleget_period)
    - [ucncycle.shift_timing](#ucncycleshift_timing)

## ucncycle

[Show source in ucncycle.py:18](../ucndata/ucncycle.py#L18)

View for the data from a single UCN cycle

#### Notes

Any changes to the data frame affects all periods (for the time steps
contained in that period) and the containing run

#### Arguments

- `urun` *ucnrun* - object to pull cycle from
- `cycle` *int* - cycle number

#### Signature

```python
class ucncycle(ucnbase):
    def __init__(self, urun, cycle): ...
```

#### See also

- [ucnbase](./ucnbase.md#ucnbase)

### ucncycle.check_data

[Show source in ucncycle.py:200](../ucndata/ucncycle.py#L200)

Run some checks to determine if the data is ok.

#### Arguments

- `period_production` *int* - index of period where the beam should be stable. Enables checks of beam stability
- `period_count` *int* - index of period where we count ucn. Enables checks of data quantity
- `period_background` *int* - index of period where we do not count ucn. Enables checks of background
- `raise_error` *bool* - if true, raise an error if check fails, else return false. Inactive if quiet=True
- `quiet` *bool* - if true don't print or raise exception

#### Returns

- `bool` - true if check passes, else false.

#### Notes

Checks performed

* is there BeamlineEpics data?
* is the cycle duration greater than 0?
* is at least one valve opened during at least one period?
* are there counts in each detector?

#### Examples

```python
>>> cycle = run[0]
>>> x = cycle.check_data()
Run 1846, cycle 0: Beam current dropped to 0.0 uA
>>> x
False
```

#### Signature

```python
def check_data(self, raise_error=False, quiet=False): ...
```

### ucncycle.draw_cycle_times

[Show source in ucncycle.py:283](../ucndata/ucncycle.py#L283)

Draw cycle start times as thick black lines, period end times as dashed lines

#### Arguments

- `ax` *plt.Axes* - axis to draw in, if None, draw in current axes
- `xmode` *str* - datetime|duration|duration_run|duration_cycle|epoch

#### Notes

- `Assumed` *periods* - 0 - irradiation
                    1 - storage
                    2 - count

#### Signature

```python
def draw_cycle_times(self, ax=None, xmode="datetime"): ...
```

### ucncycle.get_nhits

[Show source in ucncycle.py:364](../ucndata/ucncycle.py#L364)

Get number of ucn hits

#### Arguments

- `detector` *str* - Li6|He3
- `bin_ms` *int* - UCN hit event resolution in milliseconds.
    If 0, use raw hits for max precision. Else construct histogram
    with bins of size resolution_ms, and compute per-period/cycle hits
    from that.

#### Returns

- `int` - number of events

#### Notes

Getting the hits with resolution_ms=0 requires that you parse the
entire tree, so to speed this up, a histogram is created where the
bin edges are set to the period and cycle start/end times. This
histogram is cached as `self._nhits` so future requests of the
number of hits is fast. However, if you modify the start/end times
of the periods, this histogram is no longer accurate and so must
be recomputed. This happens automatically, but rebuilding the
histogram adds to your runtime. Thus the following works, but is
slow:

```python
hits = []
for cycle in run:
    cycle[1].modify_timing(1)
    hits.append(cycle[1].get_nhits('Li6')) # hits histogram recomputed every loop
```

Whereas the following is much faster but does the same thing:

```python
for cycle in run:
    cycle[1].modify_timing(1)
hits = run[:, 1].get_nhits('Li6') # hits histogram recomputed only once
```

In contrast, when bin_ms > 0, a histogram with bins of size bins_ms
is created. This histogram is independent of the period timings and
is only recreated when get_nhits is called with a new value of
bin_ms is changed. While the above rules still apply, recreating
the periods hits histogram from the bin_ms histogram is much faster,
allowing for speedups of analyses where modifying the period timings
frequently is important.

#### Signature

```python
def get_nhits(self, detector, bin_ms=0): ...
```

### ucncycle.get_period

[Show source in ucncycle.py:415](../ucndata/ucncycle.py#L415)

Return a copy of this object, but trees are trimmed to only one period.

#### Notes

* This process converts all objects to dataframes
* Must be called for a single cycle only
* Equivalent to indexing style: `cycle[period]`

#### Arguments

- `period` *int* - period number, if None, get all periods
cycle (int|None) if cycle not specified then specify a cycle

#### Returns

run:
    if period > 0: a copy of this object but with data from only one period.
    if period < 0 | None: a list of copies of this object for all periods for a single cycle

#### Examples

```python
>>> cycle = run[0]
>>> cycle.get_period(0)
run 1846 (cycle 0, period 0):
    comment            cycle_stop         period_start       shifters           tfile
    cycle              experiment_number  period_stop        start_time         year
    cycle_param        month              run_number         stop_time
    cycle_start        period             run_title          supercycle
```

#### Signature

```python
def get_period(self, period=None): ...
```

### ucncycle.shift_timing

[Show source in ucncycle.py:454](../ucndata/ucncycle.py#L454)

Shift all periods by a constant time, maintaining the period durations.
This shifts the cycle start time and shortens the cycle, potentially creating gaps between cycles

#### Arguments

- `dt` *float* - time in seconds to add to each period start/end time

#### Examples

```python
# this avoids recomputing the histograms each iteration
dt = [cyc.get_time_shift('Li6', 2, 50) if cyc[2].period_dur > 0 else 0 for cyc in run]
for i, t in enumerate(dt):
    run[i].shift_timing(t)
```

#### Notes

* This function makes use of `ucnrun._modify_ptiming`, which resets all saved histograms and hits

#### Signature

```python
def shift_timing(self, dt): ...
```