Using the Command-Line Interface (CLI)¶
Introduction¶
Starting from version 0.9.0, Libinsdb provides insdb, a stand-alone program that works on the terminal and lets users to navigate a local copy of a database. (It is not possible to access remote copies: for them, you must rely on the web interface provided by InstrumentDB.)
The insdb program has been designed with the purpose of providing an exploratory interface to navigate complex hierarchies of entities.
Starting the CLI¶
To start insdb, you just execute it from the command line:
$ insdb PATH_TO_THE_DATABASE
where PATH_TO_THE_DATABASE is the folder where the database is saved. Be sure to activate the virtual environment where you installed Libinsdb before running insdb, otherwise the command will fail.
The program accepts a few command-line options; you can get help on them by running insdb --help.
Once the program has started, you will enter a Read-Eval-Print Loop (REPL). At the prompt
>
you can enter commands that will be executed immediately. To exit the program and go back to your shell, you can run quit or press the Ctrl-D key.
Inspecting Entities and Quantities¶
The program insdb lets you show the details of any object in the database with the command show. You can either provide the name of the entity/quantity or its UUID (the Tab key works in this context too, so you do not have to type UUIDs in full):
frequency_217_ghz> show 1
Entity name 1
UUID 1f755446-be00-4cca-8133-baa38468bed4
Full path /HFI/frequency_217_ghz/1
Parent UUID a010e190-4db0-458b-a50e-12315c611c93
Quantities ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ UUID ┃ Name ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━┩
│ fc3798a6-0d9c-489d-a4bd-958921b4558b │ bandpass │
└──────────────────────────────────────┴──────────┘
frequency_217_ghz> show bandpass
Quantity name bandpass
UUID fea6f626-c992-438d-8972-96111a19a46a
Parent entity frequency_217_ghz
Format specification e406caf2-95c0-4e18-8980-a86934479423
Data files ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┓
┃ UUID ┃ Upload date ┃ File name ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━┩
│ 3a29d860-2289-4691-82de-1fcb4adfff0e │ 2017-09-26 │ bandpass217.csv │
│ d85fb364-56a2-4745-8139-a117d64d47f4 │ 2013-03-11 │ bandpass217.csv │
└──────────────────────────────────────┴─────────────┴─────────────────┘
frequency_217_ghz> show 3a29d860-2289-4691-82de-1fcb4adfff0e
Data file name bandpass217.csv
UUID 3a29d860-2289-4691-82de-1fcb4adfff0e
Local path tests/mock_db_json/data_files/3a29d860-2289-4691-82de-1fcb4adfff0e_bandpass217.csv
Parent quantity fea6f626-c992-438d-8972-96111a19a46a
Comment
Specification version 1.0
In releases ┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Tag ┃ Date ┃ Path to this object ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ planck2018 │ 2017-09-26 │ /releases/planck2018/HFI/frequency_217_ghz/bandpass │
└────────────┴────────────┴─────────────────────────────────────────────────────┘
Note that for data files you must provide an UUID. The filename alone will not work, as there might be the case that several data files share the same name, as it is the case for the bandpass shown above: both 3a29d860 and d85fb364 share the name bandpass217.csv. (This is expected, as they are two measurements of the same quantity.)
Working with Data Files¶
Apart from the command show we saw in the previous section, insdb provides two more commands to work with them: open and metadata.
The open command accepts the UUID of a data file and starts the default application configured on your computer to open that kind of file; thus, the result depends on the applications installed on your computer. In the case of data file 3a29d860 (the bandpass for the 217 GHz HFI channel), which is a CSV file, my computer opens LibreOffice Calc; in other cases, Microsoft Excel or Apple Numbers might start instead:
frequency_217_ghz> open 3a29d860-2289-4691-82de-1fcb4adfff0e
opening data file "tests/mock_db_json/data_files/3a29d860-2289-4691-82de-1fcb4adfff0e_bandpass217.csv"
[LibreOffice Calc opens in a new window]
What open does behind the curtains is to rely on some OS-specific command that takes care of opening the file. For Windows, the command is start; for Mac OS X it is open; and for Linux it is xdg-open. If you are using Linux and the command fails, check that you can start xdg-open from your default shell: it might be necessary to install it. (For instance, Ubuntu/Debian/Arch Linux users should install xdg-utils.)
The metadata command requires the UUID of a data file and shows the metadata associated with it. In the case of bandpass there is no metadata:
frequency_217_ghz> metadata 3a29d860-2289-4691-82de-1fcb4adfff0e
None
However, if we open data file 25109593, which corresponds to the most updated file associated with quantity LFI/reduced_focal_plane, we can get some actual metadata. (Note that, when we use UUIDs, there is no need to navigate into the parent entity: UUIDs are unique and there is no ambiguity when using them to refer to any object.)
frequency_217_ghz> show 25109593-c5e2-4b60-b06e-ac5e6c3b7b83
Data file name file
UUID 25109593-c5e2-4b60-b06e-ac5e6c3b7b83
Local path None
Parent quantity c20f4b61-0162-4316-8d8e-d768287123e1
Comment
Specification version 1.0
In releases ┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Tag ┃ Date ┃ Path to this object ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ planck2018 │ 2017-09-26 │ /releases/planck2018/LFI/reduced_focal_plane │
└────────────┴────────────┴──────────────────────────────────────────────┘
frequency_217_ghz> metadata 25109593-c5e2-4b60-b06e-ac5e6c3b7b83
{
'030': {
'frequency': '030',
'fwhm': 33.102652125,
'noise': 0.0001480171,
'centralfreq': 28.3999996185,
'fwhm_eff': 32.2879981995,
'fwhm_eff_sigma': 0.0209999997,
'ellipticity_eff': 1.3150000572,
'ellipticity_eff_sigma': 0.0309999995,
'solid_angle_eff': 1190.1109619141,
'solid_angle_eff_sigma': 0.7049999833
},
'044': {
'frequency': '044',
'fwhm': 27.94348615,
'noise': 0.0001740843,
'centralfreq': 44.0999984741,
'fwhm_eff': 26.9969997406,
'fwhm_eff_sigma': 0.5830000043,
'ellipticity_eff': 1.1900000572,
'ellipticity_eff_sigma': 0.0299999993,
'solid_angle_eff': 831.6110229492,
'solid_angle_eff_sigma': 35.0410003662
},
'070': {
'frequency': '070',
'fwhm': 13.07645961,
'noise': 0.0001518777,
'centralfreq': 70.4000015259,
'fwhm_eff': 13.218000412,
'fwhm_eff_sigma': 0.0309999995,
'ellipticity_eff': 1.2230000496,
'ellipticity_eff_sigma': 0.0370000005,
'solid_angle_eff': 200.8029937744,
'solid_angle_eff_sigma': 0.9909999967
}
}
Other Commands¶
Other useful commands are listed here:
pwdprints the path to the currently selected entityreleasesprints a list of all the releases included in the database.treeshows a tree-like representation of all the entities and quantities within the current entity.
Troubleshooting and Tips¶
You can get help for all the commands with
help COMMAND. For instance:> help ls List the entities and quantities at the current level Usage: ls [-s] [-e] The command accepts the following flags: -s Short format: do not print the UUIDs -e Print entities but no quantities
You can run single commands using the
-cflag when invoking the executableinsdb:$ insdb -c "show 87230a9f-70c7-4fa3-8843-834d52c9fd06" tests/mock_db_json/schema.json Data file name file UUID 87230a9f-70c7-4fa3-8843-834d52c9fd06 Local path None Parent quantity a862183e-572f-4629-9eec-fb3abeb21aa2 Comment Specification version 1.0 In releases ┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ Tag ┃ Date ┃ Path to this object ┃ ┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ │ planck2018 │ 2017-09-26 │ /releases/planck2018/LFI/full_focal_plane │ └────────────┴────────────┴───────────────────────────────────────────┘