Skip to content

Commit

Permalink
Update docstrings
Browse files Browse the repository at this point in the history
  • Loading branch information
@nvictus
nvictus committed Apr 10, 2024
1 parent af7738c commit 1d796d9
Showing 1 changed file with 107 additions and 59 deletions.
166 changes: 107 additions & 59 deletions pybigtools/src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -933,7 +933,7 @@ fn to_entry_array_zoom<I: Iterator<Item = Result<ZoomRecord, _BBIReadError>>>(
Ok(())
}

/// This class is the interface for reading a bigWig or bigBed.
/// Interface for reading a BigWig or BigBed file.
#[pyclass(module = "pybigtools")]
struct BBIRead {
bbi: BBIReadRaw,
Expand Down Expand Up @@ -1665,9 +1665,10 @@ impl ZoomIntervalIterator {
}
}

/// This class is an iterator for `Values` from a bigWig.
/// It returns only values that exist in the bigWig, skipping
/// any missing intervals.
/// An iterator for intervals in a bigWig.
///
/// It returns only values that exist in the bigWig, skipping any missing
/// intervals.
#[pyclass(module = "pybigtools")]
struct BigWigIntervalIterator {
iter: Box<dyn Iterator<Item = Result<Value, _BBIReadError>> + Send>,
Expand All @@ -1688,7 +1689,7 @@ impl BigWigIntervalIterator {
}
}

/// This class is an interator for the entries in a bigBed file.
/// An iterator for the entries in a bigBed.
#[pyclass(module = "pybigtools")]
struct BigBedEntriesIterator {
iter: Box<dyn Iterator<Item = Result<BedEntry, _BBIReadError>> + Send>,
Expand Down Expand Up @@ -1716,19 +1717,32 @@ impl BigBedEntriesIterator {
}
}

/// This class is the interface for writing a bigWig.
/// Interface for writing to a BigWig file.
#[pyclass(module = "pybigtools")]
struct BigWigWrite {
bigwig: Option<BigWigWriteRaw>,
}

#[pymethods]
impl BigWigWrite {
/// Writes the values passsed to the bigwig file.
/// The underlying file will be closed automatically when the function completes (and no other operations will be able to be performed).
/// Write values to the BigWig file.
///
/// The underlying file will be closed automatically when the function
/// completes (and no other operations will be able to be performed).
///
/// The chroms argument should be a dictionary with keys as chromosome names and values as their length.
/// The vals argument should be an iterable with values (String, int, int, float) that represents each value to write in the format (chromosome, start, end, value).
/// Parameters
/// ----------
/// chroms : Dict[str, int]
/// A dictionary with keys as chromosome names and values as their
/// length.
/// vals : Iterable[tuple[str, int, int, float]]
/// An iterable with values that represents each value to write in the
/// format (chromosome, start, end, value).
///
/// Notes
/// -----
/// The underlying file will be closed automatically when the function
/// completes, and no other operations will be able to be performed.
fn write(&mut self, py: Python, chroms: &PyDict, vals: Py<PyAny>) -> PyResult<()> {
let runtime = runtime::Builder::new_multi_thread()
.worker_threads(
Expand Down Expand Up @@ -1844,29 +1858,43 @@ impl BigWigWrite {
})
}

/// close()
/// --
/// Close the file.
///
/// Manually closed the file.
/// No other operations will be allowed after it is closed. This is done automatically after write is performed.
/// No other operations will be allowed after it is closed. This is done
/// automatically after write is performed.
fn close(&mut self) -> PyResult<()> {
self.bigwig.take();
Ok(())
}
}

/// This class is the interface for writing to a bigBed.
/// Interface for writing to a BigBed file.
#[pyclass(module = "pybigtools")]
struct BigBedWrite {
bigbed: Option<BigBedWriteRaw>,
}

#[pymethods]
impl BigBedWrite {
/// Writes the values passsed to the bigwig file. The underlying file will be closed automatically when the function completes (and no other operations will be able to be performed).
/// The chroms argument should be a dictionary with keys as chromosome names and values as their length.
/// The vals argument should be an iterable with values (String, int, int, String) that represents each value to write in the format (chromosome, start, end, rest)
/// The rest String should consist of tab-delimited fields.
/// Write values to the BigBed file.
///
/// The underlying file will be closed automatically when the function
/// completes (and no other operations will be able to be performed).
///
/// Parameters
/// ----------
/// chroms : Dict[str, int]
/// A dictionary with keys as chromosome names and values as their
/// length.
/// vals : Iterable[tuple[str, int, int, str]]
/// An iterable with values that represents each value to write in the
/// format (chromosome, start, end, rest). The ``rest`` string should
/// consist of tab-delimited fields.
///
/// Notes
/// -----
/// The underlying file will be closed automatically when the function
/// completes, and no other operations will be able to be performed.
fn write(&mut self, py: Python, chroms: &PyDict, vals: Py<PyAny>) -> PyResult<()> {
let runtime = runtime::Builder::new_multi_thread()
.worker_threads(
Expand Down Expand Up @@ -1985,7 +2013,10 @@ impl BigBedWrite {
})
}

/// Manually closed the file. No other operations will be allowed after it is closed. This is done automatically after write is performed.
/// Close the file.
///
/// No other operations will be allowed after it is closed. This is done
/// automatically after write is performed.
fn close(&mut self) -> PyResult<()> {
self.bigbed.take();
Ok(())
Expand Down Expand Up @@ -2040,26 +2071,29 @@ impl BigWigAverageOverBedEntriesIterator {
}
}

/// This is the entrypoint for working with bigWigs or bigBeds.
/// Open a BigWig anb BigBed file for reading or writing.
///
/// The first argument can take one of three values:
/// 1) A path to a file as a string
/// 2) An http url for a remote file as a string
/// 3) A file-like object with a `read` and `seek` method
/// Parameters
/// ----------
/// path_url_or_file_like : str or file-like object
/// The path to a file or an http url for a remote file as a string, or
/// a Python file-like object with ``read`` and ``seek`` methods.
/// mode : Literal["r", "w"], optional [default: "r"]
/// The mode to open the file in. If not provided, it will default to read.
/// "r" will open a bigWig/bigBed for reading but will not allow writing.
/// "w" will open a bigWig/bigBed for writing but will not allow reading.
///
/// When writing, only a file path can be used.
/// Returns
/// -------
/// BigWigWrite or BigBedWrite or BBIRead
/// The object for reading or writing the BigWig or BigBed file.
///
/// The mode is either "w", "r", or None. "r" or None will open a
/// bigWig or bigBed for reading (but will not allow writing).
/// "w" Will open a bigWig/bigBed for writing (but will not allow reading).
/// Notes
/// -----
/// For writing, only a file path is currently accepted.
///
/// If passing a file-like object, simultaneous reading of different intervals
/// If passing a file-like object, concurrent reading of different intervals
/// is not supported and may result in incorrect behavior.
///
/// This returns one of the following:
/// - `BigWigWrite`
/// - `BigBedWrite`
/// - `BBIRead`
#[pyfunction]
fn open(py: Python, path_url_or_file_like: PyObject, mode: Option<String>) -> PyResult<PyObject> {
let iswrite = match &mode {
Expand Down Expand Up @@ -2239,24 +2273,39 @@ fn open_path_or_url(

/// Gets the average values from a bigWig over the entries of a bed file.
///
/// Parameters:
/// bigWig (str): The path to the bigWig.
/// bed (str): The path to the bed.
/// names (None, bool, or int):
/// If `None`, then each return value will be a single `float`,
/// the average value over an interval in the bed file.
/// If `True`, then each return value will be a tuple of the value of column 4
/// and the average value over the interval with that name in the bed file.
/// If `False`, then each return value will be a tuple of the interval in the format
/// `{chrom}:{start}-{end}` and the average value over that interval.
/// If `0`, then each return value will match as if `False` was passed.
/// If a `1+`, then each return value will be a tuple of the value of column of this
/// parameter (1-based) and the average value over the interval.
/// Parameters
/// ----------
/// bigWig : str
/// The path to the bigWig.
/// bed : str
/// The path to the bed.
/// names : bool or int, optional
/// If ``None``, then each return value will be a single float, the
/// average value over an interval in the bed file.
///
/// If ``True``, then each return value will be a tuple of the value of
/// column 4 and the average value over the interval with that name in the
/// bed file.
///
/// If ``False``, then each return value will be a tuple of the interval
/// in the format ``{chrom}:{start}-{end}`` and the average value over
/// that interval.
///
/// If ``0``, then each return value will match as if ``False`` was passed.
///
/// If a ``1+``, then each return value will be a tuple of the value of
/// column of this parameter (1-based) and the average value over the
/// interval.
///
/// Returns:
/// This returns a generator of values. (Therefore, to save to a list, do `list(bigWigAverageOverBed(...))`)
/// If no name is specified (see the `names` parameter above), then returns a generator of `float`s.
/// If a name column is specified (see above), then returns a generator of tuples `({name}, {average})`
/// Returns
/// -------
/// Generator of float or tuple.
///
/// Notes
/// -----
/// If no ``name`` field is specified, returns a generator of floats.
/// If a ``name`` column is specified, returns a generator of tuples
/// ``({name}, {average})``.
#[pyfunction]
fn bigWigAverageOverBed(
py: Python,
Expand Down Expand Up @@ -2356,22 +2405,21 @@ fn bigWigAverageOverBed(
Ok(res)
}

/// The base module for opening a bigWig or bigBed. The only defined function is `open`.
/// Read and write Big Binary Indexed (BBI) file types: BigWig and BigBed.
#[pymodule]
fn pybigtools(_py: Python, m: &PyModule) -> PyResult<()> {
m.add("BBIFileClosed", m.py().get_type::<BBIFileClosed>())?;
m.add("BBIReadError", m.py().get_type::<BBIReadError>())?;

m.add_wrapped(wrap_pyfunction!(open))?;
m.add_wrapped(wrap_pyfunction!(bigWigAverageOverBed))?;

m.add_class::<BBIRead>()?;
m.add_class::<BigWigWrite>()?;
m.add_class::<BigBedWrite>()?;
m.add_class::<BBIRead>()?;

m.add_class::<BigWigIntervalIterator>()?;
m.add_class::<BigBedEntriesIterator>()?;

m.add("BBIFileClosed", m.py().get_type::<BBIFileClosed>())?;
m.add("BBIReadError", m.py().get_type::<BBIReadError>())?;
m.add_wrapped(wrap_pyfunction!(bigWigAverageOverBed))?;

Ok(())
}

Expand Down

0 comments on commit 1d796d9

Please sign in to comment.