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/src/index.md
+209-4Lines changed: 209 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,11 +4,216 @@ CurrentModule = CounterMarking
4
4
5
5
# CounterMarking
6
6
7
-
Documentation for [CounterMarking](https://github.com/HolyLab/CounterMarking.jl).
7
+
[CounterMarking](https://github.com/HolyLab/CounterMarking.jl) analyzes experiments on [scent-marking in mice](https://www.sciencedirect.com/science/article/pii/S0003347287800167),
8
+
specifically images of urine countermarking visualized by the [ninhydrin reaction](https://pubs.acs.org/doi/full/10.1021/jf030490p):
9
+
10
+
11
+
12
+
The yellow spot corresponds to a stimulus provided by the experimenter, and the small light-blue spots are deposited marks.
13
+
14
+
Tips on image quality:
15
+
16
+
- Put the stimulus near one of the four corners
17
+
- Ensure lighting is fairly uniform
18
+
- Try to ensure the entire image is of the filter paper, and that there aren't any black edges to the image (see lower left corner in the example above)
19
+
- Make sure that any extraneous marks (e.g., the black writing in the image above) are of a very different color from scent marks.
20
+
21
+
## Tutorial
22
+
23
+
### Installation and setup (one time setup)
24
+
25
+
There are several ways to organize your data, but one recommended approach is to have a parent "project" folder, and then store images collected on different days in subfolders named by date:
26
+
27
+
```sh
28
+
MyCounterMarkingFolder
29
+
Project.toml
30
+
2025-03-15/
31
+
2025-03-17/
32
+
...
33
+
```
34
+
35
+
We'll create the `Project.toml` for running the analysis. From the command line within `MyCounterMarkingFolder`, the steps below will:
36
+
37
+
- start Julia
38
+
- get into `pkg>` mode
39
+
- activate a new project
40
+
- install the packages you'll use
41
+
42
+
Here are the steps, starting from the OS command line:
However you launch it, you should see something like this:
101
+
102
+
103
+
104
+
On the top is the raw image. On the bottom is the segmented image; you should visually compare the two to check whether you're pleased with the quality of the segmentation.
105
+
(If not, click "Skip" to omit that file from analysis.)
106
+
107
+
If you like the segmentation, your tasks are:
108
+
- click on all the checkboxes with colors that correspond to urine spots. You'll notice that the stimulus spot is pre-clicked (you can correct its choice if it didn't pick correctly). Most of the time there will be only one you need to check, but you can click more than one.
109
+
In this example image, all the urine spots are marked red, so you'd check the box that has the red border. Leave the stimulus spot checked, too.
110
+
- click "Done & Next" to advance to the next image in the sequence
111
+
112
+
After it finishes cycling through all the images, it will save your results and close the window.
113
+
114
+
## Processing manually
115
+
116
+
### Step 1: start Julia with the right project
117
+
118
+
From within `MyCounterMarkingFolder` created above, start Julia like this:
119
+
120
+
```sh
121
+
MyCounterMarkingFolder$ julia --project
122
+
```
123
+
124
+
### Step 2: load the packages you'll need
125
+
126
+
From inside Julia, load the packages:
127
+
128
+
```
129
+
julia> using CounterMarking, ImageView, FileIO
130
+
```
131
+
132
+
CounterMarking is this package, used to perform and organize the analysis.
133
+
[ImageView](https://github.com/JuliaImages/ImageView.jl) is an image display tool.
134
+
[FileIO](https://github.com/JuliaIO/FileIO.jl) loads many different file formats, including images.
135
+
136
+
### Step 3: load a test image
137
+
138
+
If you want to use an image in one of the subfolders, use something like
139
+
140
+
```
141
+
julia> img = load("2025-03-15/picture1.png");
142
+
```
143
+
144
+
You'll need to replace the material inside quotes with the actual path and filename of your image.
145
+
146
+
Alternately, if you want to use the test image that comes with CounterMarking.jl, do the following:
It's usually a good idea to visually check that what you're working with makes sense:
155
+
156
+
```
157
+
julia> dct = imshow(img);
158
+
```
159
+
160
+
Note that as you move your mouse cursor over the image, a little text box in the lower left updates with the position and information about the color of the pixel under your cursor.
161
+
That can occasionally be handy, especially for checking locations of spots.
162
+
163
+
If all looks as expected, you can close the window.
164
+
165
+
### Step 5: segment the image
166
+
167
+
We'll split this image into different regions:
168
+
169
+
```
170
+
julia> seg = segment_image(img)
171
+
Pruning segments smaller than 50 pixels
172
+
Segmented Image with:
173
+
labels map: 1220×2441 Matrix{Int64}
174
+
number of labels: 153
175
+
176
+
julia> dct = randshow(img, seg);
177
+
```
178
+
179
+
After the second command, [`randshow`](@ref), you'll see two images: the original at the top, and the "segmented" image below. This displays the different segments (regions) using a randomly-chosen color, which can be handy for checking how well the analysis did in identifying separate spots. You can alternatively use [`meanshow`](@ref) to show each segment using the average color of all pixels in that segment.
180
+
181
+
If you Ctrl-click and drag on the image, you'll zoom in on both images. This can be handy for inspecting fine details. Ctrl-double-click takes you back to the full view.
182
+
183
+
!!! tip
184
+
If you don't like how [`segment_image`](@ref) performed, read its documentation to learn about some of the options you have for controlling it.
185
+
186
+
### Step 6: save the spots to an Excel file
187
+
188
+
The columns marked "raw" correspond to pixel locations in the original image; the columns marked "UL" come from flipping the image to place the stimulus spot in the Upper Left of the image.
189
+
This way of "standardizing" the location makes certain analyses easier.
### Step 8: create a "density map" of marks across multiple images
212
+
213
+
If you have many images collected under the same conditions (e.g., with different subject animals but the same stimuli), you can effectively overlay the entire collection of images:
0 commit comments