Help
Projects
Projects hold catalogues and their events. Everyone in a project sees and can work on everything in it, with the role you give them. An event can belong to several catalogues of the same project. The project's history covers all of it.
Your account starts with a project called “My catalogues”. It is private until you share it. Signing in opens it.
The project's name at the top of the catalogues is a menu. It lists your projects: pick one to switch to it. It also creates, renames, leaves and deletes projects, and opens your groups.
To share only some catalogues, create a project for them with New project, and share that one.
Only the server API, the websocket path and the command-line tool still call a project a “room”.
Catalogues and events
A catalogue is a named list of events. A project's catalogues are listed on the left; pick one to see its events on a timeline and in a table.
An event is a time interval. It has:
- Start and stop, in UTC.
- Tags: short words to sort events, like “shock”.
- Status: preliminary, confirmed, reviewed, final or rejected.
- Confidence: a number from 0 to 1.
- Attributes: your own named values, like a spacecraft or a density.
- Comment: free text.
Pick a row to open the event. Editors change it there. Its Listed in part shows its catalogues, and adds it to another one.
To rename or delete a catalogue, use the ⋯ next to its name in the list, or right-click it. Deleting an event or a catalogue moves it to the Trash, at the bottom of the catalogue list; a deleted catalogue's events stay in the project. From there, Restore puts it back. Delete for good removes it, and cannot be undone.
Statistics
While no event is open, the panel on the right sums up the events the table shows: after the filter and the period picked on the timeline.
- Coverage is the time at least one event covers. Where events overlap, that time counts once. The percentage compares it with the span, from the first start to the last stop.
- Gaps are the waits between events: from the stop of one to the start of the next. Events that overlap have no gap between them.
- Durations and gaps go from seconds to days, so their histograms grow by a factor of ten every two bars.
More statistics opens the other sections. The page remembers which ones you keep open, in this browser.
Import and export
A catalogue can leave the project as a file, and a file can bring catalogues in.
To export one catalogue, open it and use More → Export…. Pick a format:
- VOTable (.xml): the astronomy table format. AMDA, TOPCAT and Python cocat read it. Every event must carry the same attributes.
- tscat JSON (.json): the file tscat writes. It keeps the ids, so a file imported again updates the same events. tscat keeps a confidence as a rating from 1 to 10, so it comes back rounded to one decimal. It does not keep the status or the comment.
- TFCat (.json): the radio catalogue format of time–frequency shapes, read by TOPCAT and the TFCat Python package. An event's shape is written as it is; an event without one becomes a rectangle from its start to its stop. When no event of the catalogue says where it sits in frequency (or in the catalogue's other quantity, such as energy), the page asks for the range to draw them over.
- CSV (.csv): for a spreadsheet. One row per event: start, stop, tags, status, confidence, author, comment, then one column per attribute. Times are UTC.
Event shapes and their axis travel in VOTable, tscat JSON and TFCat, and come back as they were. TFCat only knows shapes in frequency, wavelength, energy or wavenumber: for another quantity, such as pitch angle, the file is still written but is not strict TFCat, and the page says so.
A smart catalogue is saved with the events it holds now, without its rule.
To export several catalogues in one VOTable or tscat JSON file, use Export catalogues… in the project menu and tick the ones you want. TFCat makes one file per catalogue.
To import a file, use Import… in the project menu or the + above the catalogues, or drop the file on the events. It takes a VOTable, a tscat JSON file or a TFCat file. The page reads it first and says what it will do, for example "Adds 2 catalogues and 300 events, updates 5 events (same ids)". Nothing changes until you press Import.
- An event with the same id as one in the project is updated, not copied.
- A VOTable always makes new catalogues. A tscat JSON file updates a catalogue with the same id. A TFCat file makes one new catalogue, named by the file's title, else by the file's name.
- The whole import is one change, so the history shows one version and you can restore the project to the version before it.
Readers can export. Only editors can import.
Searching
The box above the events searches as you type. On a catalogue, Search in under the box says what it does:
- This catalogue filters what the catalogue holds. Nothing is saved: the catalogue stays as it is.
- All events is the catalogue's own search. Besides the events picked into it, a catalogue holds every event of the project its search finds. The box turns blue, the table shows what the catalogue would hold, and Save to (or Save changes) keeps it. Empty the box and save to remove the search; the picked events stay.
Each side keeps its own text. To search the whole project without touching a catalogue, open All events at the top of the catalogue list. Plain words find events whose tags, status, author or attributes contain them, or whose start time begins with them.
The box suggests as you type: field names, then the project's own tags, statuses, authors, catalogues and attributes. Arrow keys pick a suggestion, Enter or Tab takes it. Each term shows as a coloured token; a field the search does not know shows in red.
Name a field to be precise. A space between two terms means both;
OR, NOT and parentheses work as in a library search.
tag:shock | tagged “shock” |
confidence:>=0.8 | confidence 0.8 or more (also >, <, <=) |
status:reviewed | with that status |
author:alice | author contains “alice”; author:=alice@lab.fr for exactly that |
start:2015, start:2015-03 | starts during that year or month |
start:[2015-01-01 TO 2016-06-30] | starts between two dates; * leaves one end open |
created:now-7d | added in the last 7 days (units s, m, h, d, M, y) |
duration:>10min | lasts more than 10 minutes (s, min, h, d) |
#density:>10 | an attribute, by its name after # |
catalogue:"Bow shocks" | listed in that catalogue |
_exists_:shape | has a time–frequency shape; NOT _exists_:author has no author |
The button at the right of the box, Build a search, writes a search for you from rows of field, test and value.
A search can also become a catalogue of its own: press Save as new smart catalogue… and name it. It keeps what the table shows: a filter keeps the events of the catalogue that match, a search of all events keeps every event that matches. The + next to Catalogues also offers ready-made ones: recently added, mine, not reviewed yet, low confidence, with a shape.
A search with now in it is checked again whenever the project changes, not on
a timer: “added in the last 7 days” drops an old event at the next edit.
Smart catalogues
A smart catalogue has a rule. The rule picks events from the whole project. Its list updates by itself while people edit. You can still add events to it by hand.
The easiest way to make one is to search and save the search. For rules a search cannot say (joining, shifting or comparing sets of intervals), open a catalogue and use More → Add a rule…. The editor starts with an example to change. The catalogue keeps the events it lists and adds the ones the rule picks. On a smart catalogue, Edit rule changes the rule. Before you save, the editor says in words what the rule picks, or what is wrong with it. Python and a tscat dynamic catalogue import make smart catalogues too.
A rule is written in JSON. A few examples:
{% for (what, rule) in rules %}{{ rule }}
A rule can test start, stop, tags,
status, confidence, author, products,
and any attribute as #name. Write times like
2020-01-01T00:00:00Z. Gaps are in seconds.
Some rules make new intervals, like the last example. Those intervals are read-only. To keep what a smart catalogue holds today, use More → Freeze…. It makes a normal catalogue holding the events the rule picks now. Joined intervals become events you can edit. The smart catalogue stays as it is.
History
The server keeps every version of a project. In the catalogue browser, press History to see them, newest first.
A version is a run of changes by one person. A new version starts when:
- they pause for more than 5 minutes,
- an hour has passed since the version began,
- someone else makes a change,
- someone restores a version,
- or someone presses Save version.
Save version ends the current version on purpose. Give it a name, like “paper v1”, and a note that says why, like “as submitted”. Saved versions carry a mark in the list. Name this version names any version later.
Pick a version to see what it changed: the events it added, changed and removed.
Restore this version makes the project as it was then. Opened from a catalogue, the history shows that catalogue only, and a restore brings back only that catalogue. Nothing is lost. Events made since then go to the trash. The restore is a new version, so you can undo it by restoring the version before it.
To try something without touching the project, press Make a copy from this version. You get a new project of your own that starts as that version, with all its catalogues and events. Change it as you like: the original and its history stay as they were. Anyone in the project can make a copy, viewers too. A copy takes the whole project, even when you opened the history from one catalogue, and it counts in your own storage.
Sharing
The Share button at the top shows who is in the project. The owner and the editors share the project from there, in three ways:
- Share link: anyone with the link can join, with the role you pick. It works for 14 days, as many times as needed. The pending invitations say how many joined.
- Email invitation: we send a link to one address. It works once, for that address only, for 14 days.
- Group: everyone in a group gets the project at once.
Revoke stops a link or an invitation at once, whoever made it.
The same people change each member's role and remove members there. Nobody can change the owner's role or remove the owner.
The owner can keep this to themselves: untick Editors can change access and share in Share. Editors then see the lists without the controls, like viewers. Viewers never change who is in the project.
Any member can Leave a project from the project menu. The owner cannot leave: they transfer ownership first. Transfer ownership…, at the bottom of Share, hands the project to another member, and the old owner stays as an editor. Only the owner can do that.
Groups
A group is a set of people you share many projects with. Open Groups… in the project menu, create one there, then invite people with a share link or by email.
In Share, whoever shares the project adds a group they belong to, as editor or viewer. Everyone in the group gets the project, including people who join the group later. Someone who reaches a project both directly and through a group gets the higher of the two roles.
The group's owner invites and removes members, renames it and deletes it. Members can leave.
Public catalogues
Public catalogues are shared with everyone who has an account here. Open Public catalogues, on the left, under the catalogues (or at the top of the project menu). They are a place of their own, apart from your projects: the folders on the left, such as “AMDA / Solar wind”, sort them, with All at the top. Pick a folder to list its catalogues; the search box finds one by its name or its description, in that folder or, under All, everywhere. Pick a catalogue to open it; the folders stay on the left, so you can go from one to the next. To go back to a project, pick it in the menu at the top.
Each public catalogue is a project of its own, with one catalogue in it. You read it like any project: its events, its statistics, its history. You cannot change it. To use it in your own work, choose Copy to a project… on the catalogue, or next to it in the list: the catalogue and its events go into one of your projects, or a new one, under the same name. Change the copy as you like; the public catalogue stays as it is.
Curators keep the public catalogues: they add, change and delete them. Every administrator is a curator, and an administrator can make anyone a curator.
Nobody owns, joins or shares a public catalogue, so it has no Share button.
Adding yours
To offer one of your catalogues, open it and choose Submit…, above its events. Give it a title, a folder and a description, and a note for the curators if you like. The curators get the catalogue and its events as they are when you submit; what you change afterwards stays in your project (submit again to send it).
To improve a public catalogue, open it and choose Propose a change…. It is copied into one of your projects, or a new one. Change it there, then choose Submit update… above the copy's events, with a note saying what you changed.
My submissions, on the left of the public catalogues, shows each one you sent: waiting, accepted or declined, with the curator's note. You can Withdraw one while it waits.
What curators do
Curators see how many submissions are waiting next to Public catalogues on the left, and the list under Submissions, on the left of the public catalogues. Each one shows What changed: for a new catalogue, its events; for an update, the events it adds, changes (old → new) and removes, compared with the public catalogue as it is now. When the public catalogue changed after the copy was made, the page says so. Accept puts it in the public catalogues, under the author's name, as a saved version called “Submission” and its number. Decline sends it back with your note.
SciQLop and Python list them too: in Python, public_catalogues,
copy_public_catalogue to copy one, and submit_catalogue or propose_change and submit_update to
submit.
Roles
- Viewer
- Sees the catalogues, the events, the members and the history, and can make a copy of any version for themselves. Changes nothing in the project.
- Editor
- Also adds, changes and deletes events and catalogues, edits rules, saves, names and restores versions, and renames the project. Unless the owner said no, an editor also shares the project: invites people, changes roles, removes members and adds groups.
- Owner
- Can do all of that, always. Only the owner deletes the project, transfers ownership and decides whether editors can share. A project has one owner.
Nobody can give themselves a higher role. Anyone but the owner can leave.
Deleting a project deletes its catalogues and its history for everyone.
Who is here
In the catalogue browser, the round badges at the top are the other people in the project right now. Hover one to see who it is.
When someone edits an event, its row shows in their colour. Changes reach everyone at once. Live, at the top right, says your changes are reaching the server.
SciQLop and Python
This server's address is {{ server_url }}.
SciQLop: in the cocat plugin's settings, enter that address, then sign in with your email and password. Your projects appear there. Edits show up here live, and the other way round.
Python, with the cocat_rs package. Python calls Save version
commit.
import cocat_rs
url = "{{ server_url }}"
cookie = cocat_rs.login(url, "you@example.org", "your password")
for info in cocat_rs.projects(url, cookie):
print(info.id, info.name, info.role)
project = cocat_rs.Project.open("cocat-cache", info.id)
project.connect(url, cookie)
project.wait_synced(10)
for catalogue in project.catalogues():
print(catalogue.name, len(catalogue.events))
project.save()
cocat_rs.commit(url, cookie, info.id, name="paper v1", message="as submitted")
Your account
- Account: change your password. If you sign in through your institution, your password lives there.
- If your institution gave no email address, the Account page asks you for one.
- A password has at least 8 characters and must not be easy to guess. A few unrelated words work well; the page says what is wrong when it refuses one.
- Forgot your password? Use the link on the sign-in page.
- Groups: the groups you belong to, and the projects they share.
Signed-in apps
Python and SciQLop sign in with a link: they show it, you open it here, check that the code matches the one they show, and allow it. The app then stays signed in on that machine, without your password. The Account page lists these apps. Revoke one you no longer use, or one on a machine you lost: it stops working at once. An app unused for six months is signed out by itself. Changing your password keeps them signed in; resetting it with "Forgot password" signs every app out, in case someone else had your account.