You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/ops/doc/IntrospectingOps.md
+19-20Lines changed: 19 additions & 20 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,15 +1,18 @@
1
1
# Reasoning about Ops
2
2
3
-
The declarative nature of Ops is convenient for matching and execution, however there are times where it is necessary to understand where an Op comes from. This page describes the tools provided by SciJava Ops to understand the code underneath.
3
+
The declarative nature of Ops is convenient for matching and execution, but sometimes it is necessary to know where an Op comes from. This page describes the tools provided by SciJava Ops to understand the code underneath.
4
4
5
5
Naturally, to understand where an Op came from, you first need an Op:
6
6
7
7
```java
8
8
var img =...;
9
9
var out =...;
10
10
var sigma =5.0;
11
+
11
12
// This Op call finds a "filter.gauss Op" that blurs an image using a provided
12
-
// sigma, placing the result in out.
13
+
// sigma, placing the result in the output container "out".
14
+
//
15
+
// NB the Op is saved within the variable "op"
13
16
var op = ops.op("filter.gauss").input(img, sigma).output(out).computer();
14
17
```
15
18
@@ -26,51 +29,49 @@ var info = Ops.info(op);
26
29
The `OpInfo` often provides all needed information, but if `op` utilizes dependencies or other framework features, you may wish to introspect the "rich" Op instead, using the method `Ops.rich`.
27
30
28
31
```java
29
-
importorg.scijava.ops.api.Ops;
30
-
31
32
var richOp =Ops.rich(op);
32
33
```
33
34
34
35
These two methods provide gateways into learning more about where your Op came from!
35
36
36
-
## Code and Versions
37
+
## Implementations and Versions
37
38
38
-
For reproducibility, it is important to know not only the underlying lines of code backing each executed Op, but additionally the *version* of that line of code, as different versions of the same codebase can produce different results. Fortunately, SciJava Ops provides mechanisms to determine both!
39
+
For reproducibility, it is important to know not only the underlying implementations, or discrete lines of code, backing each executed Op, but additionally the *version* of that implementation if it changes over time. Fortunately, SciJava Ops provides mechanisms to determine both!
39
40
40
-
A unique identifier to the lines of code can be obtained from each Op's `OpInfo`, using the method `OpInfo.implementationName()`. For example, the following
41
+
A unique identifier to an Op's implementation can be obtained from its `OpInfo` using the method `OpInfo.implementationName()`. For example, the following
Note that in many cases, including the case above, the implementation name may not itself be an explicit piece of code, however it must always explain how an explicit piece of code became the Op you've matched.
53
54
54
55
Similarly, the method `OpInfo.version()` describes **the version of the Op**, which is set by whichever component declares the Op. This version might change due to:
55
-
* An update in the version of the underlying implementation (such as a bump in the version of OpenCV)
56
+
* An update in the version of the underlying implementation (such as a bump in the version of `scijava-ops-image`)
56
57
* An update to the Op itself (such as the inclusion of an additional alias, or a change in the Op priority)
57
58
58
-
SciJava Ops guarantees users identical outputs from an Op execution given identical Op inputs **and** an identical `OpEnvironment`. Notably, your results may differ slightly if you:
59
-
* Add new Ops into your `OpEnvironment`, usually by adding new Ops. This might cause a new Op to take precedence over an existing Op.
60
-
* Change the version of an Op within the `OpEnvironment`
61
-
* Pass different inputs to the Op.
59
+
SciJava Ops guarantees identical outputs from an Op execution given identical inputs **and** an identical `OpEnvironment`. Your results may differ slightly if you:
60
+
* Add new Ops into your `OpEnvironment`, if a new Op takes precedence over an existing Op
61
+
* Change the version of an Op within the `OpEnvironment` by updating a component
62
+
* Pass different inputs to the Op
62
63
63
64
## Op Signatures
64
65
65
-
While SciJava Ops requires the aforementioned constraints to ensure reproducible Op *matches*, the concept of **Op Signatures** enables SciJava Ops to **reproducibly reconstruct prior matches** in *new environments* (assuming the prior Op is still available). Op signatures allow users to enforce reproducibility when e.g. adding new Ops to the `OpEnvironment`.
66
+
While SciJava Ops requires the aforementioned constraints to ensure reproducible Op *matches*, the concept of **Op Signatures** enables SciJava Ops to **reproducibly reconstruct prior matches in new environments** (assuming all required Ops are still available).
66
67
67
68
Given an matched Op `op`, its signature can be obtained using the static method `Ops.signature()`, which *distills* all Op implementation names and versions into a single string. For example, the following
68
69
69
70
```java
70
71
System.out.println(Ops.signature(op));
71
72
```
72
73
73
-
might print out (again using `scijava-ops-image`):
74
+
might print out (again using `scijava-ops-image` version `1.0.0`):
@@ -98,7 +99,7 @@ There still exist limitations with reconstructive features, including:
98
99
99
100
## Info Trees
100
101
101
-
Often, Ops contain Op dependencies, which may have dependencies themselves. As such, the Ops returned by SciJava Ops are best thought of as a [Tree](https://en.wikipedia.org/wiki/Tree_(data_structure)). While an Op's signature, described above, describes the entire Tree, it is often more convenient to interrogate dependencies using the `InfoTree` data structure, obtained using the method `Ops.infoTree()`:
102
+
Ops often utilize Op dependencies, which may have dependencies themselves. As such, the Ops returned by SciJava Ops are best thought of as a [tree](https://en.wikipedia.org/wiki/Tree_(data_structure)). While an Op's signature, described above, describes the entire Tree, it is often more convenient to interrogate dependencies using the `InfoTree` data structure, obtained using the method `Ops.infoTree()`:
102
103
103
104
```java
104
105
var tree =Ops.infoTree(op);
@@ -108,11 +109,9 @@ The `InfoTree` API allows users to interrogate:
108
109
* The root `OpInfo`, accessible using `InfoTree.info()`
109
110
* All dependencies, which are each themselves an `InfoTree`, using `InfoTree.dependencies()`.
110
111
111
-
The `InfoTree` allows users to answer the question of which Ops are being used as dependencies, providing access to an otherwise unavailable feature of SciJava Ops.
112
-
113
112
## Op History
114
113
115
-
A final task essential to Op reproducibility is determining the list of Ops responsible for the current state of a given Object, which is helpful when many Ops contribute to some final state. To answer this question, each `OpEnvironment` records Op executions within an `OpHistory` object, accessible using the method `OpEnvironment.history()`.
114
+
It is often useful to determine the list of Ops responsible for the current state of a given Object. To aid in this task, each `OpEnvironment` records Op executions within an `OpHistory` object, accessible using the method `OpEnvironment.history()`.
116
115
117
116
```java
118
117
// OpEnvironment.history() provides access to a OpHistory object
0 commit comments