tag_expression

Module providing routines to check and convert between tag expressions. This simplfies the handling of list of files from using regular expressions to tag expression.

A tag is a simple placeholder for a string or number in a file name. An expression is a filename with any number of tags.

A tag has the format <Name,Type,Width>.

• Name : str that specifies the tag name

• Type : ‘I’ or ‘S’ for integer or string, optional and defaults to ‘I’

• Width : int, if given indicates a fixed width and missing digits or chars are replaced by trailing zeros or spaces.

The module also provides functions to infer the tag expressions from a list of file names via the function detect().

Expressions can also be converted to glob or regular expressions.

Example

An example tag expression would be ‘file_<X,2>_<Y,3>.npy’ and would for example match the filename ‘file_01_013.npy’

>>> import ClearMap.Utils.tag_expression as te
>>> e = te.Expression('file_<X,2>_<Y,3>.npy')
>>> e.tag_names()
e.tag_names()

>>> e.glob_pattern()
'file_[0-9][0-9]_[0-9][0-9].npy'

>>> e.indices('file_01_013.npy')
[1, 13]

>>> e.re()
'file_(?P<X>\d{2})_(?P<Y>\d{3})\.npy'

>>> e.string({'X':1, 'Y':10})
'file_01_010.npy'

See also

RegularExpression

class Expression(pattern=None)

Bases: object

static is_expression(expr) → bool

Return True if expr contains at least one <…> tag fragment. Accepts str, pathlib.Path or Expression instances.

char_index(tag_name, with_markups=False)

Return the character index range of the tag in the expression

Parameters:

• tag_name (str) – The name of the tag

• with_markups (bool) – If True, the markup characters (<,width,type>) are included in the index range

Returns

tuple[int]

The character index range of the tag in the expression

detect(strings, names=None, max_check=None, with_trange=False)

glob(sort=False)

Execute the glob pattern.

Parameters:

sort (bool) – If True, the paths are sorted using natsort.

Returns

list[str]

A list of paths that match the glob pattern.

glob_pattern(values=None)

Convert the expression to a glob pattern string. >>> exp = Expression(‘file_<X,2>_<Y,3>.npy’)

>>> exp.glob_pattern()
'file_[0-9][0-9]_[0-9][0-9].npy'

Parameters:

values (dict) – A dictionary with values for the tags

Returns

str

The glob pattern string

indices(string)

Infer the indices from a string.

Examples

>>> e.indices('file_01_013.npy')
[1, 13]

Parameters:

string (str) – The path string to infer the indices from

Returns

list[int]

The indices of the tags

n_tags()

parse(expression)

re()

Convert the expression to a regular expression string.

Examples

>>> e.re()
'file_(?P<X>\d{2})_(?P<Y>\d{3})\.npy'

Returns

str

The regular expression string.

string(values=None)

Convert a value to a string according to the tag specification.

Examples

>>> exp = Expression('file_<X,2>_<Y,3>.npy')
>>> exp.string({'X':1, 'Y':10})
'file_01_010.npy'

Parameters:

values (dict) – A dictionary with values for the tags. Each key is the tag name.

Returns

str

The string representation of the value.

string_from_index(indices)

Convert a dictionary or list of tag indices to a string according to the tag specification.

Examples

>>> exp = Expression('file_<X,2>_<Y,3>.npy')
>>> exp.string_from_index([1, 13])
'file_01_013.npy'

Parameters:

indices (list[int] | dict) – A list of indices for the tags. If a dictionary is given, the keys are the tag names.

Returns

tag()

tag_max(tag_name)

Return the maximum value (i.e. range[-1]) of a tag in the expression.

Parameters:

tag_name (str) – The name of the tag

Returns

int

The maximum value of the tag

tag_min(tag_name)

Return the minimum value (i.e. range[0]) of a tag in the expression.

Parameters:

tag_name (str) – The name of the tag

Returns

int

The minimum value of the tag

tag_names()

tag_range(tag_name)

Return the range of values of a tag in the expression.

Parameters:

tag_name (str) – The name of the tag

Returns

tuple[int]

The minimum and maximum value of the tag

values(string)

Extract the values from a string according to the tag specification.

Parameters:

string (str) – The expression string to extract the values from.

Returns

dict

A dictionary with the values for the tags. Keys are the tag names.

tag_regexp = re.compile('<.*?>')

class Tag(tag=None, name=None, ttype='I', width=None, reference=None, trange=None)

Bases: object

A tag is a simple placeholder for a string or number in a file name.

A tag has the format <Name,Type,Width>. * Name : str that specifies the tag name * Type : ‘I’ or ‘S’ for integer or string, optional and defaults to ‘I’ * Width : int, if given indicates a fixed width and missing digits or chars are replaced by trailing zeros or spaces.

name

The name of the tag

Type:

str

ttype

The type of the tag, either ‘I’ for integer or ‘S’ for string. defined from the constants TAG_INT and TAG_STR

Type:

str

width

The width of the tag, i.e. the number of digits or characters

Type:

int

dtype()

Return the data type (python) of the tag.

Returns

type

The data type of the tag.

glob_pattern()

index(value)

label(index=None)

parse(tag)

Parse a tag from a string. The string should be in the format of the tag. i.e. f’{TAG_START}{Name}{TAG_SEPARATOR}{Type}{TAG_SEPARATOR}{Width}{TAG_END}’ tag_type and tag_width are optional but the tag name is required. If any of the optional values are not given then the tag pattern is shortened accordingly. If tag_type is not given it defaults to ‘I’ for integer. If tag_width is not given the tag is considered to have variable width. This function will initialize the tag with the parsed values.

Parameters:

tag (str) – The tag string to parse.

Returns

None

re(name=None)

string(value=None)

string_from_index(index=None)

tag()

value(string)

default_tag_name(index=None)

detect(strings, names=None, max_check=None, with_trange=False)

escape_glob(string)

parse(expression)

ttype_to_dtype(ttype)