snakemake.ioutils package

Submodules

snakemake.ioutils.branch module

snakemake.ioutils.branch.branch(condition, then=None, otherwise=None, cases=None)

Branch based on a condition that is provided as a function pointer (i.e. a Callable) or a value.

If then and optionally otherwise are specified, do the following: If the condition is (or evaluates to) True, return the value of the then parameter. Otherwise, return the value of the otherwise parameter.

If cases is specified, do the following: Retrieve the value of the cases mapping using the return value of the condition (if it is a function), or the condition value itself as a key.

The given condition function has to take wildcards as its only parameter. Similarly, then, otherwise and the values of the cases mapping can be such functions.

If any such function is given to any of those arguments, this function returns a derived input function that will be evaluated once the wildcards are known.

snakemake.ioutils.collect module

snakemake.ioutils.evaluate module

snakemake.ioutils.evaluate.evaluate(expr)

Evaluate a python expression while replacing any wildcards given as {wildcardname} with the wildcard value represented as a string.

snakemake.ioutils.exists module

snakemake.ioutils.exists.exists(path)

Return True if the given file or directory exists.

This function considers any storage arguments given to Snakemake.

snakemake.ioutils.lookup module

class snakemake.ioutils.lookup.DpathWildcardHandler(func, **namespace)

Bases: WildcardHandlerBase

apply_func(expression, namespace=None)

class snakemake.ioutils.lookup.QueryWildcardHandler(func, cols=None, is_nrows=None, **namespace)

Bases: WildcardHandlerBase

apply_func(expression, namespace=None)

needs_wildcards(expression)

class snakemake.ioutils.lookup.WildcardHandlerBase(func, **namespace)

Bases: ABC

abstract apply_func(expression, namespace=None)

fmt_regex = re.compile('\\{(?P<stmt>[^\\{][^\\{\\}]+)\\}[^\\}]')

handle(expression)

needs_wildcards(expression)

snakemake.ioutils.lookup.lookup(dpath=None, query=None, cols=None, is_nrows=None, within=None, default=<object object>, **namespace)

Lookup values in a pandas dataframe, series, or python mapping (e.g. dict).

Required argument within should be a pandas dataframe or series (in which case use query, and optionally cols and is_nrows), or a Python mapping like a dict (in which case use the dpath argument is used).

In case of a pandas dataframe (see https://pandas.pydata.org), the query parameter is passed to DataFrame.query(). If the query results in multiple rows, the result is returned as a list of named tuples with the column names as attributes. If the query results in a single row, the result is returned as a single named tuple with the column names as attributes. In both cases, the result can be used by the expand or collect function, e.g. collect(“results/{item.sample}.txt”, sample=lookup(query=”someval > 2”, within=samples)). Since the result, in any case, also evaluates to True if it is not empty when interpreted as a boolean by Python, it can also be used as a condition for the branch function, e.g. branch(lookup(query="sample == '{sample}' & someval > 2", within=samples), then="foo", otherwise="bar"). In case your dataframe has an index, you can also access the index within the query, e.g. for faster, constant time lookups: lookup(query="index.loc[{sample}]", within=samples). Further, it is possible to constrain the output to a list of columns, e.g. lookup(query="sample == '{sample}'", within=samples, cols=["somecolumn"]) or to a single column, e.g. lookup(query="sample == '{sample}'", within=samples, cols="somecolumn"). In the latter case, just a list of items in that column is returned. Finally, if the integer argument is_nrows is used, this returns true if there are that many rows in the query results, false otherwise.

In case of a pandas series, the series is converted into a dataframe via Series.to_frame() and the same logic as for a dataframe is applied.

In case of a python mapping, the dpath parameter is passed to dpath.values() (see https://github.com/dpath-maintainers/dpath-python), and the query, cols, and is_nrows arguments are ignored. If the dpath is not found, a LookupError is raised, unless a default fallback value is provided via the default argument.

Query, dpath and cols may contain wildcards (e.g. {sample}). In that case, this function returns a Snakemake input function which takes wildcards as its only argument and will be evaluated by Snakemake once the wildcard values are known.

In addition to wildcard values, dpath, query and cols may refer via the same syntax to auxiliary namespace arguments given to the lookup function, e.g. lookup(query="cell_type == '{sample.cell_type}'", within=samples, sample=lookup("sample == '{sample}'", within=samples)) This way, one can e.g. pass additional variables or chain lookups into more complex queries.

snakemake.ioutils.rule_items_proxy module

class snakemake.ioutils.rule_items_proxy.KeyKind(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

ATTRIBUTE = 0

ITEM = 1

class snakemake.ioutils.rule_items_proxy.RuleItemProxy(name)

Bases: object

Proxy class for deferring access to attributes and keys of the given item to DAG phase.

snakemake.ioutils.rule_items_proxy.rule_item_factory(name)

Allows to access input, output etc. from statements inside a rule but outside of run/shell etc. blocks. Returns an object that defers evaluation to the DAG phase.

snakemake.ioutils.subpath module

snakemake.ioutils.subpath.subpath(path_or_func, strip_suffix=None, basename=False, parent=False, ancestor=None)

Return the subpath of a given path.

Parameters:

• path_or_func – A string, pathlib.Path, or a function returning a string or pathlib.Path.

• strip_suffix – If given, strip the suffix from the path.

• basename – If True, return the basename of the path (cannot be used together with parent or ancestor).

• parent – If True, return the parent directory of the path (cannot be used together with ancestor).

• ancestor – If given, return the ancestor directory of the path (cannot be used together with parent).

Module contents

snakemake.ioutils.register_in_globals(_globals)