neurocarto.util.util_blueprint

Blueprint functions:

neurocarto.util.edit
- How to write a blueprint script function
- Internal blueprint functions

Classes

class neurocarto.util.util_blueprint.BlueprintFunctions

Provide blueprint manipulating functions. It is used by BlueprintScriptView. However, it also can be used independently, but without some view interacting functions.

channelmap functions

check_probe()
new_channelmap()
add_electrodes()
del_electrodes()

selected_electrodes()
set_channelmap()
select_electrodes()

blueprint functions

electrode data processing

load_data()
save_data()
get_data()

put_data()
interpolate_nan()
draw()

Probe view functions

Call methods from ProbeView.

capture_electrode()
clear_capture_electrode()
captured_electrodes()

set_state_for_captured()
set_category_for_captured()
refresh_selection()

Atlas Brain image view functions

Call methods from AtlasBrainView.

atlas_get_region_name()
atlas_get_slice()
atlas_set_slice()
atlas_get_label()
atlas_add_label()
atlas_focus_label()
atlas_del_label()
atlas_clear_labels()

atlas_set_transform()
atlas_set_anchor()
atlas_new_probe()
atlas_current_probe()
atlas_set_anchor_on_probe()
atlas_coor_electrode()
atlas_mask_region()

Blueprint script view functions

Call methods from BlueprintScriptView.

has_script()
call_script()

interrupt_script()

UI communicating functions

set_status_line()
log_message()

use_view()

Miscellaneous

clone()
plot_channelmap()

plot_blueprint()
misc_profile_script()

Category attributes

BlueprintFunctions supports ‘CATE_*’ electrode category attributes, which come from probe without difference. Although BlueprintFunctions has declared some ‘CATE_*’ attributes, they do not have value. The actual value is delegated to the probe via __getattr__.

CATE_UNSET: int: electrode initial category

CATE_SET: int: electrode pre-select category. Electrode must be selected

CATE_EXCLUDED: int: electrode excluded category. Electrode must not be selected

CATE_LOW: int: electrode low-priority category.

__init__(probe, chmap)

initialization.

Case when chmap is None. In this case, BlueprintFunctions still be allowed to initialize. Although most of the functions will raise an error, it is okay because the caller (like BlueprintScriptView) would handle it, and it only happened when user forget to create a probe before running a script.

Parameters:

probe (str | ProbeDesp[M, E]) – ProbeDesp or a module path
chmap (int | str | M | None) – channelmap instance.

probe: Final[ProbeDesp[M, E]]: probe

channelmap: Final[M | None]: channelmap instance

categories: Final[dict[str, int]]: categories mapping.

electrodes: Final[list[E]]: all available electrodes

s: Final[ndarray[tuple[int, ...], dtype[int64]]]: shank

x: Final[ndarray[tuple[int, ...], dtype[int64]]]: x position in um

y: Final[ndarray[tuple[int, ...], dtype[int64]]]: y position in um

clone(pure=False)

Clone itself.

Pure

Whether the clone does not contain the controller to support UI functions, includes ProbeView, AtlasBrainView and BlueprintScriptView supporting.

A pure clone has limited functions, but it is good for being pickled, and it could be passed in multiple processor for parallel computing.

Parameters:: pure – Does not support UI function?
Returns:: itself
Raises:: RuntimeError – when probe is missing.
Return type:: Self

add_electrodes(e, *, overwrite=True)

Add electrode(s) e into the current channelmap.

Parameters:

e (int | list[int] | ndarray[tuple[int, ...], dtype[int64]] | ndarray[tuple[int, ...], dtype[bool]]) – electrode index, index list, index array or index mask.
overwrite – overwrite previous selected electrode.

Raises:

RuntimeError – when probe is missing.

See:

ProbeDesp. add_electrode()

del_electrodes(e)

delete electrode(s) e from the current channelmap.

Parameters:: e (int | list[int] | ndarray[tuple[int, ...], dtype[int64]] | ndarray[tuple[int, ...], dtype[bool]]) – electrode index, index list, index array or index mask.
Raises:: RuntimeError – when probe is missing.
See:: ProbeDesp. del_electrode()

selected_electrodes(chmap=None)

The selected electrodes in the current channelmap.

Returns:: electrode index array, keep in ordering by its channel identify (skip None electrodes).
See:: ProbeDesp. all_channels()
Return type:: ndarray[tuple[int, …], dtype[int64]]

set_channelmap(chmap)

Apply the channelmap on the current channelmap.

Parameters:: chmap (M)
Raises:: RuntimeError – when probe is missing. call new_channelmap() first.

select_electrodes(chmap=None, blueprint=None, **kwargs)

Run electrode selection for a channelmap based on the blueprint.

Parameters:

chmap
blueprint (list[E] | BLUEPRINT | None)
kwargs – selector extra parameters

Returns:

new channelmap

See:

ProbeDesp.:attr:~neurocarto.probe.ProbeDesp.select_electrodes

Return type:

M

blueprint()

blueprint copy.

Returns:
Raises:: RuntimeError – when probe is missing.
Return type:: BLUEPRINT

new_blueprint()

new empty blueprint array.

Returns:
Raises:: RuntimeError – when probe is missing.
Return type:: BLUEPRINT

property blueprint_changed: bool: Has internal blueprint changed?

set_blueprint(blueprint)

set blueprint.

Parameters:

blueprint (int | BLUEPRINT | list[E]) – a blueprint or a category value (reset all electrodes).

Raises:

RuntimeError – when probe is missing.
ValueError – length mismatch

clear_blueprint()

unset blueprint.

Returns:: previous blueprint before clearing
Return type:: BLUEPRINT

apply_blueprint(electrodes=None, blueprint=None)

Apply blueprint back to electrode list.

Parameters:

electrodes (list[E] | None) – electrode list
blueprint (BLUEPRINT | None)

Returns:

electrodes

Raises:

RuntimeError – when probe is missing.

See:

from_blueprint()

Return type:

list[E]

from_blueprint(electrodes)

Get a blueprint from an electrode list.

Parameters:: electrodes (list[E]) – electrode list
Returns:
Raises:: RuntimeError – when probe is missing.
See:: apply_blueprint()
Return type:: BLUEPRINT

index_blueprint(electrodes)

Get an electrode index array from an electrode list.

Parameters:: electrodes (list[E] | ndarray[tuple[int, ...], dtype[int64]]) – list of electrode or an Array[int, N, (S,X,Y)].
Returns:: electrode index Array[E:int, N], follow electrodes ordering.
Raises:: RuntimeError – when probe is missing.
Return type:: ndarray[tuple[int, …], dtype[int64]]

load_blueprint(file)

Load the blueprint from the file.

Parameters:: file (str | Path) – file.blueprint.npy
Returns:
Raises:: RuntimeError – when probe is missing.
Return type:: BLUEPRINT

save_blueprint(file, blueprint=None)

Save blueprint to the file.

Parameters:

file (str | Path)
blueprint (BLUEPRINT | None)

Raises:

RuntimeError – when probe is missing.

set(blueprint, mask, category)

Set category on the blueprint with a mask.

It is a blueprint_function() function.

Parameters:

blueprint (BLUEPRINT)
mask (int | slice | list[int] | ndarray[tuple[int, ...], dtype[bool]] | ndarray[tuple[int, ...], dtype[int64]]) – category value (or list), electrode mask or electrode index
category (int)

Returns:

a (copied) blueprint

Raises:

RuntimeError – when probe is missing.

Return type:

BLUEPRINT

unset(blueprint, mask)

unset electrodes in the blueprint with a mask.

It is a blueprint_function() function.

Parameters:

blueprint (BLUEPRINT)
mask (int | slice | list[int] | ndarray[tuple[int, ...], dtype[bool]] | ndarray[tuple[int, ...], dtype[int64]]) – category value, electrode mask or electrode index

Returns:

a (copied) blueprint

Return type:

BLUEPRINT

__setitem__(mask, category)

Set a category to the blueprint with a mask. The new category only apply on unset electrodes. If you want to overwrite the electrode’s category, please use set().

Parameters:

mask (int | ndarray[tuple[int, ...], dtype[bool]] | ndarray[tuple[int, ...], dtype[int64]]) – category value, electrode mask or electrode index
category (int | str)

See:

merge(), set()

__delitem__(mask)

unset electrodes in the blueprint with a mask.

Parameters:: mask (int | ndarray[tuple[int, ...], dtype[bool]] | ndarray[tuple[int, ...], dtype[int64]]) – category value, electrode mask or electrode index
See:: unset()

merge(blueprint: BLUEPRINT | BlueprintFunctions) → BLUEPRINT

merge(blueprint: BLUEPRINT, other: BLUEPRINT | BlueprintFunctions) → BLUEPRINT

Merge two blueprints. The latter blueprint won’t overwrite the former result.

merge(blueprint) works like set_blueprint(ret := merge(blueprint(), blueprint)); ret.

Parameters:

blueprint – Array[category, N]
other – blueprint Array[category, N]

Returns:

blueprint Array[category, N]

Raises:

RuntimeError – when only one argument is given and the probe is missing.
ValueError – incorrect length

count_categories(blueprint, categories, mask=None)

count number of electrode belonging to categories.

It is a blueprint_function() function.

Parameters:

blueprint (BLUEPRINT)
categories (int | list[int]) – category value or a category list.
mask (ndarray[tuple[int, ...], dtype[bool]]) – a blueprint mask.

Returns:

number of electrode in categories zone.

Return type:

int

mask(blueprint, categories=None)

Masking electrode belong to the categories.

It is a blueprint_function() function.

Parameters:

blueprint (BLUEPRINT)
categories (int | list[int]) – If not given, use all categories except CATE_UNSET and CATE_EXCLUDED.

Returns:

a blueprint mask.

Return type:

ndarray[tuple[int, …], dtype[bool]]

invalid(blueprint: BLUEPRINT, *, electrodes: int | list[E] | ndarray[tuple[int, ...], dtype[bool]] | ndarray[tuple[int, ...], dtype[int64]] | M = None, categories: int | list[int] = None, overwrite: bool = False) → ndarray[tuple[int, ...], dtype[bool]]

Masking or set value on invalid electrodes for electrode in categories.

It is a blueprint_function() function.

Parameters:

blueprint
electrodes – electrode index array, masking, or a channelmap (take selected electrodes).
categories – only consider electrode categories in list.
value – set value on invalid electrodes.
overwrite – Does the electrode in categories are included in the mask.

Returns:

a mask if value is omitted. Otherwise, a new blueprint.

move(a, *, tx=0, ty=0, mask=None, axis=0, init=0)

Move blueprint zone.

Parameters:

a (ndarray[tuple[int, ...], dtype[_ScalarType_co]]) – Array[V, …, N, …], where N means all electrodes
tx (int) – x movement in um.
ty (int) – y movement in um.
mask (ndarray[tuple[int, ...], dtype[bool]] | None) – move electrode only in mask
axis (int) – index of N
init (float) – initial value V for a.

Returns:

moved a (copied)

Return type:

ndarray[tuple[int, …], dtype[_ScalarType_co]]

move_i(a, *, tx=0, ty=0, mask=None, axis=0, init=0)

Move blueprint zone by steps of electrode interval space.

Parameters:

a (ndarray[tuple[int, ...], dtype[_ScalarType_co]]) – Array[V, …, N, …], where N means electrodes
tx (int) – number of dx
ty (int) – number of dy
mask (ndarray[tuple[int, ...], dtype[bool]] | None) – move electrode only in mask
axis (int) – index of N
init (float) – initial value V for a.

Returns:

moved a (copied)

Return type:

ndarray[tuple[int, …], dtype[_ScalarType_co]]

find_clustering(blueprint, categories=None, *, diagonal=True)

find electrode clustering with the same category zone.

Parameters:

blueprint (BLUEPRINT) – Array[category, N]
categories (int | list[int] | None) – only for given categories.
diagonal – does surrounding includes electrodes on diagonal?

Returns:

Array[int, N]

Return type:

BLUEPRINT

clustering_edges(blueprint, categories=None)

For each clustering, and calculate its edges.

Parameters:

blueprint (BLUEPRINT)
categories (int | list[int])

Returns:

list of edge

Return type:

list[ClusteringEdges]

edge_rastering(edges, *, fill=False, overwrite=False)

For given edges, put them on the blueprint.

Parameters:

edges (ClusteringEdges | list[ClusteringEdges])
fill – fill the area.
overwrite – latter result overwrite previous results

Returns:

blueprint

Return type:

BLUEPRINT

fill(blueprint, categories=None, *, threshold=None, gap=1, unset=False)

fill each category zone as a rectangle zone.

It is a blueprint_function() function.

Parameters:

blueprint (BLUEPRINT) – Array[category, N]
categories (int | list[int]) – only consider given categories.
threshold (int) – only consider area which size larger than threshold.
gap (int | None) – fill the gap below (abs(y) <= gap). Use None, fill an zone as a prefect rectangle.
unset (bool) – unset small zone (depends on threshold)

Returns:

blueprint Array[category, N]

Return type:

BLUEPRINT

extend(blueprint, category, step, value=None, *, threshold=None, bi=True, overwrite=False)

extend the zone of each category’s zone.

It is a blueprint_function() function.

Parameters:

blueprint (BLUEPRINT) – Array[category, N]
category (int) – on which category zone.
step (int | tuple[int, int]) – expend step on y or (x, y)
value (int) – a category value used in the extending.
threshold (int | tuple[int, int]) – Positive value: extend the zone which size larger than threshold. Negative value: extend the zone which size smaller than threshold. A tuple: extend the zone which size in a range.
bi (bool) – both position and negative steps direction
overwrite (bool) – overwrite category value. By default, only change the unset electrode.

Returns:

a modified blueprint copy.

Return type:

BLUEPRINT

reduce(blueprint, category, step, *, threshold=None, bi=True)

reduce the size of each category’s zone.

It is a blueprint_function() function.

Parameters:

blueprint (BLUEPRINT) – Array[category, N]
category (int) – on which category zone.
step (int | tuple[int, int]) – reduce step on y or (x, y)
threshold (int | tuple[int, int]) – Positive value: extend the zone which size larger than threshold. Negative value: extend the zone which size smaller than threshold. A tuple: extend the zone which size in a range.
bi (bool) – both position and negative steps direction

Returns:

a modified blueprint copy.

Return type:

BLUEPRINT

load_data(file)

Load a data array.

support data type

numpy file (‘.npy’) with shape Array[float, E].
csv file (‘.csv’, ‘.tsv’) with reader shank,x,y,value.
data file supported by ProbeDesp. load_blueprint().

The value is read from category field.

Neuropixels

For the Neuropixels, NpxProbeDesp use the numpy array in this form:

Array[int, E, (shank, col, row, state, category)]

Because E’s category is expected as an int, this method also take it as an int by default.

Parameters:: file (str | Path) – data file
Returns:: Array[float, E] data array, where E is all electrodes.
Return type:: ndarray[tuple[int, …], dtype[float64]]

save_data(file, data)

Save a numpy data array.

support data type

csv file (‘.csv’, ‘.tsv’) with reader shank,x,y,value.
data file supported by ProbeDesp. load_blueprint().

The data value is stored into the category field.

If no specific requirement, consider use numpy.save first.

Neuropixels

For the Neuropixels, NpxProbeDesp use the numpy array in this form:

Array[int, E, (shank, col, row, state, category)]

Because E’s category is expected as an int, this method will cast it into an int by default.

Parameters:

file (str | Path) – data file
data (ndarray[tuple[int, ...], dtype[float64]]) – Array[float, E] data array, where E is all electrodes.

get_data(data, chmap)

Get the value of the used electrode (donated by chmap) from the data.

Parameters:

data (ndarray[tuple[int, ...], dtype[float64]]) – Array[float, E], where E is all electrodes
chmap (M) – a channelmap with number of (non-None) channel C

Returns:

Array[float, C] channel data.

Return type:

ndarray[tuple[int, …], dtype[float64]]

put_data(data, chmap, value)

put the value of used electrodes from chmap into data.

Parameters:

data (ndarray[tuple[int, ...], dtype[float64]]) – Array[float, E], where E is all electrodes
chmap (M) – a channelmap with number of (non-None) channel C
value (ndarray[tuple[int, ...], dtype[float64]]) – Array[float, C] channel data.

Returns:

data

Return type:

ndarray[tuple[int, …], dtype[float64]]

interpolate_nan(a, kernel=1, f='mean')

Interpolate the NaN value in the data a.

Warning

this method works different with interpolate_nan() on

this method works on 1-d array, but the latter one works on 2-d or 3-d array.
TBD

Parameters:

a (ndarray[tuple[int, ...], dtype[float64]]) – data array.
kernel (int | tuple[int, int]) – kernel size.
f (str | Callable[[ndarray[tuple[int, ...], dtype[float64]]], float]) – interpolate method. Default use mean.

Returns:

interpolated data.

Return type:

ndarray[tuple[int, …], dtype[float64]]

check_probe(probe=None, chmap_code=None, *, error=True)

Check whether the current used probe is type of probe.

If a blueprint function is called by BlueprintScriptView, RequestChannelmapTypeError could be captured, and the requested channelmap (new_channelmap()) will be created when needed.

def my_function(bp: BlueprintFunctions):
    bp.check_probe('npx', 24)
    ...

In another way to check used probe, a decorator use_probe() can be used to annotate the requested probe on a script, then BlueprintScriptView can handle the probe checking and creating before running the script.

@use_probe('npx', 24) # checking and creating probe if necessary
def my_function(bp: BlueprintFunctions):
    ...

Parameters:

probe (str | type[ProbeDesp] | None) – request probe. It could be family name (via get_probe_desp()), ProbeDesp type or class name. It None, checking a probe has created, and its type doesn’t matter.
chmap_code (int | None) – request channelmap code
error – raise an error when the checking fail.

Returns:

test success.

Raises:

RequestChannelmapTypeError – when check failed.

use_view(view)

Get corresponding ViewBase instance if activated.

Note

Avoiding import V at the global that might cause ImportError, either using type name or using local import.

Parameters:: view (str | type[V]) – view type or its type name.
Returns:
Return type:: V | None

draw(a)

Send a drawable data array a to a BlueprintScriptView.

Parameters:: a (ndarray[tuple[int, ...], dtype[float64]] | None) – Array[float, E], where E is all electrodes

set_status_line(message, *, decay=None)

Parameters:

message (str) – message
decay (float | None) – after give seconds, clear the message.

See:

ViewBase. ViewBase.set_status()

log_message(*message)

Send messages to log area in GUI.

Parameters:: message (str)
See:: CartoApp. log_message()

has_script(script)

Check whether script is existed in BlueprintScriptView’s action list.

Parameters:: script (str) – script name.
Returns:
Return type:: bool

call_script(script, /, *args, **kwargs)

run script in BlueprintScriptView.

There are some difference behavior when running a script from this method and BlueprintScriptView.:attr:~neurocarto.views.blueprint_script.BlueprintScriptView.run_script.

Both check script are up-to-date.
This method does not handle use_probe() and RequestChannelmapTypeError
This method does not print same logging message as RequestChannelmapTypeError.
This method does not record history step.
Both are allow a generator from the script, but
- this method pass the generator to the BlueprintScriptView.
- BlueprintScriptView mark the target script as interruptable, instead of this method.
- this method will lost control on the generator.

Parameters:

script (str) – script name in BlueprintScriptView action list.
args – script positional arguments.
kwargs – script keyword arguments.

interrupt_script(script)

Interrupt script.

Parameters:: script (str) – script name.
Returns:: is interrupt success?
See:: BlueprintScriptView. interrupt_script()
Return type:: bool

set_script_input(script, *text)

Set the script input for script.

Parameters:

script (str | None) – script name. If None, use current script.
text (str | None) – each argument

new_channelmap(code)

Create a new channelmap with type code.

Parameters:: code (int | str) – channelmap type code.
Returns:: new channelmap instance.
See:: ProbeView. reset()
Return type:: M

capture_electrode(index, state=None, mode='replace')

Capture electrodes.

Parameters:

index (ndarray[tuple[int, ...], dtype[int64]] | ndarray[tuple[int, ...], dtype[bool]]) – index (Array[E, N]) or bool (Array[bool, E]) array.
state (list[int] | None) – restrict electrodes on given states.
mode (Literal['r', 'replace', 'a', 'append', 'x', 'exclude'])

See:

ProbeView. set_captured_electrodes()

clear_capture_electrode()

clear capturing.

See:: ProbeView. clear_capture_electrode()

captured_electrodes(all=False)

get captured electrodes.

Parameters:: all – capture excluded electrodes?
Returns:: index of captured electrodes.
See:: ProbeView. get_captured_electrodes_index()
Return type:: ndarray[tuple[int, …], dtype[int64]]

set_state_for_captured(state, index=None)

Set state for captured electrodes.

Parameters:

state (int) – a state value
index (ndarray[tuple[int, ...], dtype[int64]] | ndarray[tuple[int, ...], dtype[bool]] | None) – index (Array[E, N]) or bool (Array[bool, E]) array.

See:

capture_electrode()

See:

ProbeView. set_state_for_captured()

set_category_for_captured(category, index=None)

Set category for captured electrodes.

Parameters:

category (int) – a category value
index (ndarray[tuple[int, ...], dtype[int64]] | ndarray[tuple[int, ...], dtype[bool]] | None) – index (Array[E, N]) or bool (Array[bool, E]) array.

See:

capture_electrode()

See:

ProbeView. set_category_for_captured()

refresh_selection(selector=None)

refresh electrode selection base on current blueprint.

Parameters:: selector (str | None)
See:: ProbeView. refresh_selection()

atlas_get_region_name(region)

Get region acronym.

Parameters:: region (int | str) – region ID, acronym or its partial description
Returns:: region acronym
See:: Structure
Return type:: str | None

atlas_get_slice(*, um=False)

Get atlas brain image projection view and slicing plane.

Parameters:: um – is plane index in return um? If so, then use bregma as origin.
Returns:: tuple of (projection name, plane index)
Return type:: tuple[str | None, int | None]

atlas_set_slice(view=None, plane=None, *, um=False)

Set atlas image projection view and slicing plane.

Parameters:

view (str | None) – ‘coronal’, ‘sagittal’, or ‘transverse’
plane (int | None) – plane index
um – is plane um? If so, then use bregma as origin.

See:

AtlasBrainView. update_brain_view()

See:

AtlasBrainView. update_brain_slice()

atlas_add_label(text, pos=None, *, origin='bregma', color='cyan', replace=True)

Add a label on atlas image view.

Parameters:

text (str) – text content.
pos (tuple[float, float] | tuple[float, float, float]) – text position
origin (str) – origin reference point
color (str) – label color
replace – replace label which has same text content

Returns:

label

See:

AtlasBrainView. add_label()

Return type:

Label | None

atlas_get_label(index)

Get the label from atlas image view.

Parameters:: index (int | str) – label index or its content
See:: AtlasBrainView. get_label()
See:: AtlasBrainView. index_label()
Return type:: Label | None

atlas_focus_label(label)

Move slice to the label’s position.

Note

Only works on the labels which its origin is referring on the bregma. Otherwise, nothing will happen.

Parameters:: label (int | str | Label) – label index, content or a Label.
See:: AtlasBrainView. focus_label()

atlas_del_label(i)

Remove labels from atlas image.

Parameters:: i (int | str | Label | list[int | str | Label]) – index, or label text or list of them.
See:: AtlasBrainView. del_label()

atlas_clear_labels()

Clear all labels on the atlas image.

See:: AtlasBrainView. clear_labels()

atlas_set_transform(p=None, s=None, rt=None)

updating atlas image transforming.

Parameters:

p (tuple[float, float] | None) – center position (x, y)
s (float | tuple[float, float] | None) – scaling (sx, sy)
rt (float | None) – rotating degree

See:

BoundView. update_boundary_transform()

atlas_set_anchor(p, a=(0, 0))

Update atlas image boundary transform to move a onto p.

Parameters:

p (tuple[float, float]) – target point on figure. figure (probe) origin as origin.
a (tuple[float, float]) – anchor point on image, center point as origin.

See:

BoundView. set_anchor_to()

atlas_new_probe(ap, dv, ml, shank=0, rx=0, ry=0, rz=0, depth=0, ref='bregma')

Create a probe coordinate instance.

Parameters:

ap (float) – ap um, from ref (default bregma).
dv (float) – dv um, from ref (default bregma).
ml (float) – ml um, from ref (default bregma).
shank (int) – shank index
rx (float) – ap-axis rotate
ry (float) – dv-axis rotate
rz (float) – ml-axis rotate
depth (float) – insert depth
ref (str) – reference origin.

Returns:

a probe coordinate. None if origin not set.

Return type:

ProbeCoordinate | None

atlas_current_probe(shank=0, ref='bregma')

Get the current coordinate of the probe.

The dv value of the returned coordinate always zero.

Parameters:

shank (int) – which shank is the returned coordinate is based on.
ref (str) – which origin is the returned coordinate is referring to.

Returns:

a probe coordinate. None if origin not found.

Return type:

ProbeCoordinate | None

atlas_set_anchor_on_probe(coor)

Update atlas image boundary transform to anchor insertion point onto the probe.

Parameters:: coor (ProbeCoordinate) – probe coordinate

atlas_coor_electrode(coor=None, electrode=None, bregma='bregma')

Transform electrode position to altas coordinate (AP,DV,ML) according the given probe coordinate.

Parameters:

coor (ProbeCoordinate) – probe coordinate
electrode (NDArray[np.int_] | NDArray[np.bool_] | NDArray[np.float64]) – electrode index (Array[int, N]), mask (Array[bool, E]) or position (Array[um:float, N, (x, y)])
bregma (str | None) – use which bregma coordinate as origin.

Returns:

electrode position in Array[um:float, N, (ap, dv, ml)]

See:

use atlas_current_probe() when coor is None.

Return type:

NDArray[np.float64]

atlas_mask_region(region, coor=None, electrode=None)

Return a mask that electrode located in the given region.

Parameters:

region (str) – region name
coor (ProbeCoordinate) – probe coordinate
electrode (NDArray[np.int_] | NDArray[np.bool_] | NDArray[np.float64]) – electrode index (Array[int, N]), mask (Array[bool, E]) or position (Array[um:float, N, (x, y)])

Returns:

Array[bool, N]

See:

use atlas_current_probe() when coor is None.

See:

use atlas_coor_electrode()

Return type:

NDArray[np.bool_]

plot_channelmap(channelmap=None, color='black', *, ax=None, **kwargs)

call ProbeDesp primary plotting method for plot a channelmap with a matplotlib axes.

If ax is None, create one with the rc file used by PltImageView.

Parameters:

channelmap (M) – a channelmap instance
color (Any) – color of selected electrodes, where color is used by matplotlib.
ax (Axes) – matplotlib.Axes
kwargs

Raises:

TypeError – Probe not a ProbePlotElectrodeProtocol

plot_blueprint(blueprint=None, colors=None, *, ax=None, **kwargs)

call ProbeDesp primary plotting method for plotting a blueprint with a matplotlib axes.

If ax is None, create one with the rc file used by PltImageView.

It is a blueprint_function() function.

Parameters:

blueprint (BLUEPRINT) – Array[category:int, E], where E means all electrodes
colors (dict[int, Any]) – categories color {category: color}, where color is used by matplotlib.
ax (Axes) – matplotlib.Axes
kwargs

Raises:

TypeError – Probe not a ProbePlotElectrodeProtocol

See:

ProbePlotElectrodeProtocol

misc_profile_script(script, /, *args, **kwargs)

Call script under cProfile.

This method works almost as same as call_script(), but

under profiling
This method does handle generator, but ignoring the yield value. Just loop until it stops.
generate a profiling result named profile-SCRIPT.dat at the cache directory.

The profile-SCRIPT.dat file can use following command to generate a figure:

python -m gprof2dot -f pstats profile-SCRIPT.dat | dot -T png -o profile-SCRIPT.png

Add profiling action in :class:`~neurocarto.views.blueprint_script.BlueprintScriptView`

Create a function at somewhere

def profile_call(bp: BlueprintFunctions, script: str, *args, **kwargs):
    bp.misc_profile_script(script, *args, **kwargs)

Add function into user config

{
  "BlueprintScriptView": {
    "actions": {
      "profile": "path:profile_call"
    }
  }
}

Parameters:

script (str) – script name
args – script positional arguments
kwargs – script keyword arguments

See:

call_script()

neurocarto.util.util_blueprint.blueprint_function(func=None, *, set_return=True)

Decorate a blueprint function to make it is able to direct apply function on the internal blueprint array.

The function should have a signature (blueprint, ...) -> blueprint|None.

If the first parameter blueprint is given, it works as usually.

bp.func(blueprint, ...)

If the first parameter blueprint is omitted, use BlueprintFunctions. blueprint() as first arguments, and use BlueprintFunctions. set_blueprint() after it returns.

bp.set_blueprint(bp.func(bp.blueprint(), ...))

Parameters:

func
set_return – check the return and set the blueprint

neurocarto.util.util_blueprint.use_probe(probe=<class 'neurocarto.probe.ProbeDesp'>, code=None, *, create=None, check=True)

Decorate a blueprint script (BlueprintScript) to indicate this function request a particular probe type.

@use_probe('npx', 24) # checking and creating probe if necessary
def my_probe(bp: BlueprintFunctions):
    bp.check_probe('npx', 24) # no need anymore in common case.

It also allows BlueprintScriptView to filter suitable scripts for a probe.

Parameters:

probe (str | type[ProbeDesp]) – probe type or its name. It is omitted, just check a probe is existed.
code (int | tuple[int, ...] | None) – channelmap code
create (bool | None) – create the probe if there is no probe in the main figure. If True, it requires code should be not None. Force False if probe is omitted.
check – check the current probe type automatically before entering the script.

See:

get_use_probe()

See:

BlueprintFunctions. check_probe()

neurocarto.util.util_blueprint.use_view(view)

Decorate a blueprint script (BlueprintScript) to indicate this function request a particular ViewBase to work.

@use_view('AtlasView')
def my_function(bp: BlueprintFunctions):
    if (atlas := bp.use_view('AtlasView')) is None:
        raise RuntimeError('AtlasView is not loaded')

It also allows BlueprintScriptView to filter suitable scripts, which depends on existed views.

Parameters:: view (str | type[neurocarto.views.base.ViewBase]) – request view name or type.
Returns:
See:: get_use_view()
See:: BlueprintFunctions. use_view()