rnalysis.filtering.Filter.filter_by_attribute

Filter.filter_by_attribute(attributes: str | List[str] = None, mode: Literal['union', 'intersection'] = 'union', ref: str | Path | Literal['predefined'] = 'predefined', opposite: bool = False, inplace: bool = True)

Filters features according to user-defined attributes from an Attribute Reference Table. When multiple attributes are given, filtering can be done in ‘union’ mode (where features that belong to at least one attribute are not filtered out), or in ‘intersection’ mode (where only features that belong to ALL attributes are not filtered out). To learn more about user-defined attributes and Attribute Reference Tables, read the user guide.

Parameters:

  • attributes (string or list of strings, which are column titles in the user-defined Attribute Reference Table.) – attributes to filter by.

  • mode ('union' or 'intersection'.) – If ‘union’, filters out every genomic feature that does not belong to one or more of the indicated attributes. If ‘intersection’, filters out every genomic feature that does not belong to ALL of the indicated attributes.

  • ref (str or pathlib.Path (default='predefined')) – filename/path of the attribute reference table to be used as reference.

  • opposite (bool (default=False)) – If True, the output of the filtering will be the OPPOSITE of the specified (instead of filtering out X, the function will filter out anything BUT X). If False (default), the function will filter as expected.

  • inplace (bool (default=True)) – If True (default), filtering will be applied to the current Filter object. If False, the function will return a new Filter instance and the current instance will not be affected.

Returns:

If ‘inplace’ is False, returns a new and filtered instance of the Filter object.

Examples:
>>> from rnalysis import filtering
>>> counts = filtering.Filter('tests/test_files/counted.csv')
>>> # keep only rows that belong to the attribute 'attribute1'
>>> counts.filter_by_attribute('attribute1',ref='tests/attr_ref_table_for_examples.csv')
Filtered 15 features, leaving 7 of the original 22 features. Filtered inplace.

>>> counts = filtering.Filter('tests/test_files/counted.csv')
>>> # keep only rows that belong to the attributes 'attribute1' OR 'attribute3' (union)
>>> counts.filter_by_attribute(['attribute1','attribute3'],ref='tests/attr_ref_table_for_examples.csv')
Filtered 14 features, leaving 8 of the original 22 features. Filtered inplace.

>>> counts = filtering.Filter('tests/test_files/counted.csv')
>>> # keep only rows that belong to both attributes 'attribute1' AND 'attribute3' (intersection)
>>> counts.filter_by_attribute(['attribute1','attribute3'],mode='intersection',
... ref='tests/attr_ref_table_for_examples.csv')
Filtered 19 features, leaving 3 of the original 22 features. Filtered inplace.

>>> counts = filtering.Filter('tests/test_files/counted.csv')
>>> # keep only rows that DON'T belong to either 'attribute1','attribute3' or both
>>> counts.filter_by_attribute(['attribute1','attribute3'],ref='tests/attr_ref_table_for_examples.csv',
... opposite=True)
Filtered 8 features, leaving 14 of the original 22 features. Filtered inplace.

>>> counts = filtering.Filter('tests/test_files/counted.csv')
>>> # keep only rows that DON'T belong to both 'attribute1' AND 'attribute3'
>>> counts.filter_by_attribute(['attribute1','attribute3'],mode='intersection',
... ref='tests/attr_ref_table_for_examples.csv',opposite=True)
Filtered 3 features, leaving 19 of the original 22 features. Filtered inplace.