# BEDshift Module

<a id="geniml.bedshift"></a>

<a id="geniml.bedshift.Bedshift"></a>

## `Bedshift`

```python
class Bedshift(bedfile_path, chrom_sizes=None, delimiter='\t')
```

The bedshift object with methods to perturb regions.

Read in a .bed file to pandas DataFrame format.

Args:
    bedfile_path (str): The path to the BED file.
    chrom_sizes (str): The path to the chrom.sizes file.
    delimiter (str): The delimiter used in the BED file.

### Attributes

- <a id="geniml.bedshift.Bedshift.bedfile_path"></a>**`bedfile_path`**
- <a id="geniml.bedshift.Bedshift.chrom_lens"></a>**`chrom_lens`**
- <a id="geniml.bedshift.Bedshift.original_num_regions"></a>**`original_num_regions`**
- <a id="geniml.bedshift.Bedshift.bed"></a>**`bed`**
- <a id="geniml.bedshift.Bedshift.original_bed"></a>**`original_bed`**

### Methods

<a id="geniml.bedshift.Bedshift.reset_bed"></a>

#### `reset_bed`

```python
def reset_bed()
```

Reset the stored bedfile to the state before perturbations.

<a id="geniml.bedshift.Bedshift.pick_random_chroms"></a>

#### `pick_random_chroms`

```python
def pick_random_chroms(n)
```

Utility function to pick a random chromosome.

Args:
    n (str): The number of random chromosomes to pick.

Returns:
    zip: Tuples of (chrom_str, chrom_len) containing chromosome number and length.

<a id="geniml.bedshift.Bedshift.add"></a>

#### `add`

```python
def add(addrate, addmean, addstdev, valid_bed=None, delimiter='\t')
```

Add regions.

Args:
    addrate (float): The rate to add regions.
    addmean (float): The mean length of added regions.
    addstdev (float): The standard deviation of the length of added regions.
    valid_bed (str): The file with valid regions where new regions can be added.
    delimiter (str): The delimiter used in valid_bed.

Returns:
    int: The number of regions added.

<a id="geniml.bedshift.Bedshift.add_from_file"></a>

#### `add_from_file`

```python
def add_from_file(fp, addrate, delimiter='\t')
```

Add regions from another bedfile to this perturbed bedfile.

Args:
    fp (str): The filepath to the other bedfile.
    addrate (float): The rate to add regions.
    delimiter (str): The delimiter used in the bedfile.

Returns:
    int: The number of regions added.

<a id="geniml.bedshift.Bedshift.shift"></a>

#### `shift`

```python
def shift(shiftrate, shiftmean, shiftstdev, shift_rows=[])
```

Shift regions.

Args:
    shiftrate (float): The rate to shift regions (both the start and end are shifted by the same amount).
    shiftmean (float): The mean shift distance.
    shiftstdev (float): The standard deviation of the shift distance.
    shift_rows (list): Specific rows to shift.

Returns:
    int: The number of regions shifted.

<a id="geniml.bedshift.Bedshift.shift_from_file"></a>

#### `shift_from_file`

```python
def shift_from_file(fp, shiftrate, shiftmean, shiftstdev, delimiter='\t')
```

Shift regions that overlap the specified file's regions.

Args:
    fp (str): The file on which to find overlaps.
    shiftrate (float): The rate to shift regions (both the start and end are shifted by the same amount).
    shiftmean (float): The mean shift distance.
    shiftstdev (float): The standard deviation of the shift distance.
    delimiter (str): The delimiter used in fp.

Returns:
    int: The number of regions shifted.

<a id="geniml.bedshift.Bedshift.cut"></a>

#### `cut`

```python
def cut(cutrate)
```

Cut regions to create two new regions.

Args:
    cutrate (float): The rate to cut regions into two separate regions.

Returns:
    int: The number of regions cut.

<a id="geniml.bedshift.Bedshift.merge"></a>

#### `merge`

```python
def merge(mergerate)
```

Merge two regions into one new region.

Args:
    mergerate (float): The rate to merge two regions into one.

Returns:
    int: Number of regions merged.

<a id="geniml.bedshift.Bedshift.drop"></a>

#### `drop`

```python
def drop(droprate)
```

Drop regions.

Args:
    droprate (float): The rate to drop/remove regions.

Returns:
    int: The number of rows dropped.

<a id="geniml.bedshift.Bedshift.drop_from_file"></a>

#### `drop_from_file`

```python
def drop_from_file(fp, droprate, delimiter='\t')
```

Drop regions that overlap between the reference bedfile and the provided bedfile.

Args:
    fp (str): The filepath to the other bedfile containing regions to be dropped.
    droprate (float): The rate to drop regions.
    delimiter (str): The delimiter used in the bedfile.

Returns:
    int: The number of regions dropped.

<a id="geniml.bedshift.Bedshift.set_seed"></a>

#### `set_seed`

```python
def set_seed(seednum)
```

Set the random seed for reproducible perturbations.

Args:
    seednum (int): The seed value.

Raises:
    ValueError: If seednum cannot be converted to an integer.

<a id="geniml.bedshift.Bedshift.all_perturbations"></a>

#### `all_perturbations`

```python
def all_perturbations(addrate=0.0, addmean=320.0, addstdev=30.0, addfile=None, valid_regions=None, shiftrate=0.0, shiftmean=0.0, shiftstdev=150.0, shiftfile=None, cutrate=0.0, mergerate=0.0, droprate=0.0, dropfile=None, yaml=None, seed=None)
```

Perform all five perturbations in the order of shift, add, cut, merge, drop.

Args:
    addrate (float): The rate (as a proportion of the total number of regions) to add regions.
    addmean (float): The mean length of added regions.
    addstdev (float): The standard deviation of the length of added regions.
    addfile (str): The file containing regions to be added.
    valid_regions (str): The file containing regions where new regions can be added.
    shiftrate (float): The rate to shift regions (both the start and end are shifted by the same amount).
    shiftmean (float): The mean shift distance.
    shiftstdev (float): The standard deviation of the shift distance.
    shiftfile (str): The file containing regions to be shifted.
    cutrate (float): The rate to cut regions into two separate regions.
    mergerate (float): The rate to merge two regions into one.
    droprate (float): The rate to drop/remove regions.
    dropfile (str): The file containing regions to be dropped.
    yaml (str): The yaml_config filepath.
    seed (int): A seed for allowing reproducible perturbations.

Returns:
    int: The number of total regions perturbed.

<a id="geniml.bedshift.Bedshift.to_bed"></a>

#### `to_bed`

```python
def to_bed(outfile_name)
```

Write a pandas dataframe back into BED file format.

Args:
    outfile_name (str): The name of the output BED file.

<a id="geniml.bedshift.Bedshift.read_bed"></a>

#### `read_bed`

```python
def read_bed(bedfile_path, delimiter='\t')
```

Read a BED file into pandas dataframe.

Args:
    bedfile_path (str): The path to the BED file.
    delimiter (str): The delimiter used in the BED file.

Returns:
    pd.DataFrame: The BED file as a pandas DataFrame.