microcalorimetry 0.4.1a0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (89) hide show
  1. microcalorimetry-0.4.1a0/CODEMETA.yaml +60 -0
  2. microcalorimetry-0.4.1a0/CODEOWNERS +10 -0
  3. microcalorimetry-0.4.1a0/LICENSE +35 -0
  4. microcalorimetry-0.4.1a0/MANIFEST.in +25 -0
  5. microcalorimetry-0.4.1a0/PKG-INFO +103 -0
  6. microcalorimetry-0.4.1a0/README.md +78 -0
  7. microcalorimetry-0.4.1a0/fair-software.md +297 -0
  8. microcalorimetry-0.4.1a0/pyproject.toml +83 -0
  9. microcalorimetry-0.4.1a0/setup.cfg +4 -0
  10. microcalorimetry-0.4.1a0/src/microcalorimetry/__init__.py +0 -0
  11. microcalorimetry-0.4.1a0/src/microcalorimetry/_cli.py +127 -0
  12. microcalorimetry-0.4.1a0/src/microcalorimetry/_gwex/__init__.py +2 -0
  13. microcalorimetry-0.4.1a0/src/microcalorimetry/_gwex/_common_xrformats.py +1266 -0
  14. microcalorimetry-0.4.1a0/src/microcalorimetry/_gwex/_test_collections.py +42 -0
  15. microcalorimetry-0.4.1a0/src/microcalorimetry/_gwex/_utils.py +2 -0
  16. microcalorimetry-0.4.1a0/src/microcalorimetry/_gwex/_xrformats.py +666 -0
  17. microcalorimetry-0.4.1a0/src/microcalorimetry/_helpers/__init__.py +19 -0
  18. microcalorimetry-0.4.1a0/src/microcalorimetry/_helpers/_collections.py +74 -0
  19. microcalorimetry-0.4.1a0/src/microcalorimetry/_helpers/_intf_tools.py +475 -0
  20. microcalorimetry-0.4.1a0/src/microcalorimetry/_helpers/_test_collections.py +11 -0
  21. microcalorimetry-0.4.1a0/src/microcalorimetry/_tkquick/__init__.py +3 -0
  22. microcalorimetry-0.4.1a0/src/microcalorimetry/_tkquick/_api.py +136 -0
  23. microcalorimetry-0.4.1a0/src/microcalorimetry/_tkquick/_gui/__init__.py +1 -0
  24. microcalorimetry-0.4.1a0/src/microcalorimetry/_tkquick/_gui/_experimentframe.py +119 -0
  25. microcalorimetry-0.4.1a0/src/microcalorimetry/_tkquick/_gui/_filebar.py +138 -0
  26. microcalorimetry-0.4.1a0/src/microcalorimetry/_tkquick/_gui/_forms.py +571 -0
  27. microcalorimetry-0.4.1a0/src/microcalorimetry/_tkquick/_gui/_graphicsframe.py +811 -0
  28. microcalorimetry-0.4.1a0/src/microcalorimetry/_tkquick/_gui/_stageframes.py +145 -0
  29. microcalorimetry-0.4.1a0/src/microcalorimetry/_tkquick/_gui/_themes.py +10 -0
  30. microcalorimetry-0.4.1a0/src/microcalorimetry/_tkquick/_gui/_toolbars.py +273 -0
  31. microcalorimetry-0.4.1a0/src/microcalorimetry/_tkquick/_gui/_workingmodes.py +91 -0
  32. microcalorimetry-0.4.1a0/src/microcalorimetry/_tkquick/dtypes.py +13 -0
  33. microcalorimetry-0.4.1a0/src/microcalorimetry/analysis/__init__.py +41 -0
  34. microcalorimetry-0.4.1a0/src/microcalorimetry/analysis/_calc_eta.py +547 -0
  35. microcalorimetry-0.4.1a0/src/microcalorimetry/analysis/_correction_factors.py +378 -0
  36. microcalorimetry-0.4.1a0/src/microcalorimetry/analysis/_sensitivity.py +293 -0
  37. microcalorimetry-0.4.1a0/src/microcalorimetry/configs.py +862 -0
  38. microcalorimetry-0.4.1a0/src/microcalorimetry/export/__init__.py +6 -0
  39. microcalorimetry-0.4.1a0/src/microcalorimetry/export/_eff_files.py +179 -0
  40. microcalorimetry-0.4.1a0/src/microcalorimetry/graphics/icon.ico +0 -0
  41. microcalorimetry-0.4.1a0/src/microcalorimetry/math/__init__.py +11 -0
  42. microcalorimetry-0.4.1a0/src/microcalorimetry/math/fitting.py +297 -0
  43. microcalorimetry-0.4.1a0/src/microcalorimetry/math/gc_models.py +29 -0
  44. microcalorimetry-0.4.1a0/src/microcalorimetry/math/numbers.py +50 -0
  45. microcalorimetry-0.4.1a0/src/microcalorimetry/math/rfpower.py +756 -0
  46. microcalorimetry-0.4.1a0/src/microcalorimetry/math/rmemeas_extras.py +121 -0
  47. microcalorimetry-0.4.1a0/src/microcalorimetry/math/trig.py +37 -0
  48. microcalorimetry-0.4.1a0/src/microcalorimetry/math/unc_models.py +202 -0
  49. microcalorimetry-0.4.1a0/src/microcalorimetry/math/vna.py +189 -0
  50. microcalorimetry-0.4.1a0/src/microcalorimetry/measurements/__init__.py +11 -0
  51. microcalorimetry-0.4.1a0/src/microcalorimetry/measurements/_sample/__init__.py +0 -0
  52. microcalorimetry-0.4.1a0/src/microcalorimetry/measurements/_sample/sample_experiment.py +31 -0
  53. microcalorimetry-0.4.1a0/src/microcalorimetry/measurements/dcsweep/__init__.py +8 -0
  54. microcalorimetry-0.4.1a0/src/microcalorimetry/measurements/dcsweep/_analysis.py +316 -0
  55. microcalorimetry-0.4.1a0/src/microcalorimetry/measurements/dcsweep/_main.py +542 -0
  56. microcalorimetry-0.4.1a0/src/microcalorimetry/measurements/rfsweep/__init__.py +5 -0
  57. microcalorimetry-0.4.1a0/src/microcalorimetry/measurements/rfsweep/_main.py +1340 -0
  58. microcalorimetry-0.4.1a0/src/microcalorimetry/measurements/rfsweep/_parser.py +3039 -0
  59. microcalorimetry-0.4.1a0/src/microcalorimetry/measurements/rfsweep/_runner.py +1801 -0
  60. microcalorimetry-0.4.1a0/src/microcalorimetry/schema/CorrectionFactorDataInputs.json +28 -0
  61. microcalorimetry-0.4.1a0/src/microcalorimetry/schema/DCSweep.json +10 -0
  62. microcalorimetry-0.4.1a0/src/microcalorimetry/schema/DCSweepConfiguration.json +236 -0
  63. microcalorimetry-0.4.1a0/src/microcalorimetry/schema/DataModelContainer.json +10 -0
  64. microcalorimetry-0.4.1a0/src/microcalorimetry/schema/Eta.json +10 -0
  65. microcalorimetry-0.4.1a0/src/microcalorimetry/schema/EtaHistorical.json +16 -0
  66. microcalorimetry-0.4.1a0/src/microcalorimetry/schema/GC.json +10 -0
  67. microcalorimetry-0.4.1a0/src/microcalorimetry/schema/InstrumentSettings.json +159 -0
  68. microcalorimetry-0.4.1a0/src/microcalorimetry/schema/ParsedDCSweep.json +18 -0
  69. microcalorimetry-0.4.1a0/src/microcalorimetry/schema/ParsedRFSweep.json +71 -0
  70. microcalorimetry-0.4.1a0/src/microcalorimetry/schema/RFSensorMasterList.json +91 -0
  71. microcalorimetry-0.4.1a0/src/microcalorimetry/schema/RFSweep.json +10 -0
  72. microcalorimetry-0.4.1a0/src/microcalorimetry/schema/RFSweepConfiguration.json +49 -0
  73. microcalorimetry-0.4.1a0/src/microcalorimetry/schema/RFSweepInstrumentRoles.json +78 -0
  74. microcalorimetry-0.4.1a0/src/microcalorimetry/schema/RFSweepLevellingSettings.json +111 -0
  75. microcalorimetry-0.4.1a0/src/microcalorimetry/schema/RFSweepMeasurementDescription.json +68 -0
  76. microcalorimetry-0.4.1a0/src/microcalorimetry/schema/RFSweepOutputSettings.json +42 -0
  77. microcalorimetry-0.4.1a0/src/microcalorimetry/schema/RFSweepParserConfig.json +72 -0
  78. microcalorimetry-0.4.1a0/src/microcalorimetry/schema/RFSweepRunSettingsColumns.json +29 -0
  79. microcalorimetry-0.4.1a0/src/microcalorimetry/schema/RFSweepSignalConfig.json +248 -0
  80. microcalorimetry-0.4.1a0/src/microcalorimetry/schema/RFSweepStatsSettings.json +46 -0
  81. microcalorimetry-0.4.1a0/src/microcalorimetry/schema/S11.json +10 -0
  82. microcalorimetry-0.4.1a0/src/microcalorimetry/schema/ThermoelectricFitCoefficients.json +10 -0
  83. microcalorimetry-0.4.1a0/src/microcalorimetry/schema/examples/sample_measurement_descr.yml +31 -0
  84. microcalorimetry-0.4.1a0/src/microcalorimetry.egg-info/PKG-INFO +103 -0
  85. microcalorimetry-0.4.1a0/src/microcalorimetry.egg-info/SOURCES.txt +87 -0
  86. microcalorimetry-0.4.1a0/src/microcalorimetry.egg-info/dependency_links.txt +1 -0
  87. microcalorimetry-0.4.1a0/src/microcalorimetry.egg-info/entry_points.txt +2 -0
  88. microcalorimetry-0.4.1a0/src/microcalorimetry.egg-info/requires.txt +13 -0
  89. microcalorimetry-0.4.1a0/src/microcalorimetry.egg-info/top_level.txt +1 -0
@@ -0,0 +1,60 @@
1
+ # Topics for the NIST Open Source Portal <https://code.nist.gov>
2
+ #
3
+ # Set the topic tags for your open source repository from the nested
4
+ # list below. Un-comment the relevant lines:
5
+ #
6
+ # remove the `#` character *and* the space immediately after it
7
+ #
8
+ # so that the YAML syntax remains valid. You may delete everything
9
+ # that does not apply, and add new topics from the NIST Taxonomy
10
+ # <https://data.nist.gov/od/id/691DDF3315711C14E0532457068146BE1907>
11
+ #
12
+ # For example, a valid version of this file would be (note the `:`
13
+ # and `---`, they are important!) as follows:
14
+ #
15
+ # ---
16
+ # categories:
17
+ # - scientific-software
18
+ #
19
+ # themes:
20
+ # - Information Technology
21
+ # - Software research
22
+ # - Software performance
23
+ #
24
+ # Since scientific-software is most common it is left as the default
25
+ # category. Feel free to comment it with a hash (#) if it does not
26
+ # apply. There is no default theme; select as many as are relevant.
27
+ # Make sure to remove unwanted categories as the final topics are
28
+ # produced from this file.
29
+
30
+ ---
31
+ categories:
32
+ # - ai-ml
33
+ # - performance-and-workflow
34
+ - scientific-software
35
+ # - simulation
36
+ - tools
37
+ - visualization
38
+
39
+ themes:
40
+ - Advanced communications
41
+ - Optical communications
42
+ - Quantum communications
43
+ - Wireless (RF)
44
+
45
+ - Electronics
46
+ - Electromagnetics
47
+
48
+ - Mathematics and Statistics
49
+ - Uncertainty quantification
50
+
51
+ - Metrology
52
+ - Electrical and electromagnetic metrology
53
+
54
+ - Physics
55
+ - Magnetics
56
+
57
+ - Standards
58
+ - Reference instruments
59
+ - Reference materials
60
+
@@ -0,0 +1,10 @@
1
+ # This file lists the contributors responsible for the
2
+ # repository content. They will also be automatically
3
+ # asked to review any pull request made in this repository.
4
+
5
+ # Each line is a file pattern followed by one or more owners.
6
+ # The sequence matters: later patterns take precedence.
7
+
8
+ # FILES OWNERS
9
+ * @d-c-gray
10
+ * @ahagerstrom-NIST
@@ -0,0 +1,35 @@
1
+ # NIST Software Licensing Statement
2
+
3
+ NIST-developed software is provided by NIST as a public service.
4
+ You may use, copy, and distribute copies of the software in any
5
+ medium, provided that you keep intact this entire notice. You may
6
+ improve, modify, and create derivative works of the software or
7
+ any portion of the software, and you may copy and distribute such
8
+ modifications or works. Modified works should carry a notice
9
+ stating that you changed the software and should note the date
10
+ and nature of any such change. Please explicitly acknowledge the
11
+ National Institute of Standards and Technology as the source of
12
+ the software.
13
+
14
+ NIST-developed software is expressly provided "AS IS." NIST MAKES
15
+ NO WARRANTY OF ANY KIND, EXPRESS, IMPLIED, IN FACT, OR ARISING BY
16
+ OPERATION OF LAW, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
17
+ WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
18
+ NON-INFRINGEMENT, AND DATA ACCURACY. NIST NEITHER REPRESENTS NOR
19
+ WARRANTS THAT THE OPERATION OF THE SOFTWARE WILL BE UNINTERRUPTED
20
+ OR ERROR-FREE, OR THAT ANY DEFECTS WILL BE CORRECTED. NIST DOES
21
+ NOT WARRANT OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF THE
22
+ SOFTWARE OR THE RESULTS THEREOF, INCLUDING BUT NOT LIMITED TO THE
23
+ CORRECTNESS, ACCURACY, RELIABILITY, OR USEFULNESS OF THE
24
+ SOFTWARE.
25
+
26
+ You are solely responsible for determining the appropriateness of
27
+ using and distributing the software and you assume all risks
28
+ associated with its use, including but not limited to the risks
29
+ and costs of program errors, compliance with applicable laws,
30
+ damage to or loss of data, programs or equipment, and the
31
+ unavailability or interruption of operation. This software is not
32
+ intended to be used in any situation where a failure could cause
33
+ risk of injury or damage to property. The software developed by
34
+ NIST employees is not subject to copyright protection within the
35
+ United States.
@@ -0,0 +1,25 @@
1
+ # Exclude the entire tests directory from the sdist
2
+ recursive-exclude tests *
3
+
4
+ # Exclude the entire docs directory
5
+ recursive-exclude docs *
6
+
7
+ # exclude any hidden directories
8
+ recursive-exclude .* *
9
+
10
+ # exclude any hidden directories
11
+ recursive-exclude graphics_dev *
12
+
13
+ # exclude any hidden directories
14
+ recursive-exclude tools *
15
+
16
+ # Exclude all build artifacts within any sample? directory under examples
17
+ prune examples/sample?/build
18
+
19
+ # exclude ci files
20
+ exclude .pre-commit-config.yaml
21
+ exclude .gitlab-ci.yml
22
+ exclude dev_deps.txt
23
+ exclude uv.lock
24
+ exclude .gitignore
25
+
@@ -0,0 +1,103 @@
1
+ Metadata-Version: 2.4
2
+ Name: microcalorimetry
3
+ Version: 0.4.1a0
4
+ Summary: A package for performing and analyzing microcalorimeter measurements.
5
+ Author-email: Daniel Cole Gray <daniel.c.gray@nist.gov>, "Zenn C. Roberts" <zenn.roberts@nist.gov>, "Aaron M. Hagerstrom" <aaron.hagerstrom@nist.gov>
6
+ Classifier: Programming Language :: Python :: 3
7
+ Classifier: Operating System :: Microsoft :: Windows
8
+ Requires-Python: <3.14,>=3.12
9
+ Description-Content-Type: text/markdown
10
+ License-File: LICENSE
11
+ Requires-Dist: numpy>=2.0.0
12
+ Requires-Dist: matplotlib>=3.9.0
13
+ Requires-Dist: h5py>=3.11.0
14
+ Requires-Dist: rminstr-specs>=0.4.0
15
+ Requires-Dist: numpydoc>=1.8.0
16
+ Requires-Dist: click>=8.2.1
17
+ Requires-Dist: pyside6>=6.9.1
18
+ Requires-Dist: pyyaml>=6.0.2
19
+ Requires-Dist: jsonschema>=4.25.0
20
+ Requires-Dist: pyvisa>=1.14.0
21
+ Requires-Dist: rminstr>=0.6.5
22
+ Requires-Dist: rmellipse>=0.4
23
+ Requires-Dist: customtkinter>=5.2.2
24
+ Dynamic: license-file
25
+
26
+ # Microcalorimetry
27
+
28
+ > [!NOTE]
29
+ > This software is in active and early development by the RF power calibrations service at NIST to support
30
+ > RF power calibrations and the development primary RF power standards. Expect breaking breaking changes as the software
31
+ > evolves. Instrument interfaces are added and tested as needed for the calibration service. Bugs may
32
+ > be present in the instrument interfaces that we are unaware of. Please exercise caution when using interfaces
33
+ > presented in this code.
34
+
35
+ This package provides a library of data acquisition and analysis tools for RF power calibrations using microcalorimeters. Included in
36
+ this package is:
37
+
38
+ * A Python scripting API
39
+ * A User Inteface (CLI and GUI) for data acquisition and analysis.
40
+
41
+ This package is built using Rocky Mountain Ellipse ([RME](https://github.com/usnistgov/rmellipse)), a project to develop tools for digital traceability at NIST.
42
+
43
+
44
+ Please refer to the documentation ([here](https://github.com/usnistgov/microcalorimetry-ipages)) for detailed information on how to use the package.
45
+
46
+ ## Introduction
47
+ Install with pip or preffered package manager.
48
+
49
+ ```
50
+ pip install microcalorimetry
51
+ ```
52
+
53
+ ### CLI
54
+
55
+ The command line interface is can be accessed with the `ucal` command:
56
+
57
+ ```console
58
+ ucal --help
59
+ ```
60
+
61
+ ### GUI
62
+
63
+ The GUI is launched via the command line interface
64
+
65
+ ```console
66
+ ucal gui
67
+ ```
68
+
69
+ ### Python API
70
+
71
+ The Python API provides a functional interface for performing measurements and data analysis.
72
+
73
+ The ``microcalorimetry.measurements`` submodule provides an interface into RF sweep and DC sweep measurement procedures, as well as tools to parse the raw data.
74
+
75
+
76
+ ```Python
77
+ import microcalorimetry.measurements.dcsweep as dcsweep
78
+ import microcalorimetry.measurements.rfsweep as rfsweep
79
+ ```
80
+
81
+ Analysis functions that take in parsed data and generate new data sets with uncertainties (like the effective efficiency of power sensors) are provided in the ``microcalorimetry.analysis`` submodule.
82
+
83
+ ```Python
84
+ import microcalorimetry.analysis as analysis
85
+ ```
86
+
87
+
88
+ Configuration objects for measurements and analysis scripts are provided in a ``microcalorimetry.configs`` module.
89
+ ```Python
90
+ import microcalorimetry.configs as configs
91
+ ```
92
+
93
+ Mathematical operations compatable with ([RMEMeas](https://pages.nist.gov/rmellipse-ipages/stable/index.html)) objects are stored in the ``microcalorimetry.math`` submodule.
94
+
95
+ ```Python
96
+ import microcalorimetry.math as mcmath
97
+ ```
98
+
99
+ ## Authors
100
+
101
+ Contributors names and contact info
102
+
103
+ Daniel C. Gray, Zenn C. Roberts, Aaron M. Hagerstrom
@@ -0,0 +1,78 @@
1
+ # Microcalorimetry
2
+
3
+ > [!NOTE]
4
+ > This software is in active and early development by the RF power calibrations service at NIST to support
5
+ > RF power calibrations and the development primary RF power standards. Expect breaking breaking changes as the software
6
+ > evolves. Instrument interfaces are added and tested as needed for the calibration service. Bugs may
7
+ > be present in the instrument interfaces that we are unaware of. Please exercise caution when using interfaces
8
+ > presented in this code.
9
+
10
+ This package provides a library of data acquisition and analysis tools for RF power calibrations using microcalorimeters. Included in
11
+ this package is:
12
+
13
+ * A Python scripting API
14
+ * A User Inteface (CLI and GUI) for data acquisition and analysis.
15
+
16
+ This package is built using Rocky Mountain Ellipse ([RME](https://github.com/usnistgov/rmellipse)), a project to develop tools for digital traceability at NIST.
17
+
18
+
19
+ Please refer to the documentation ([here](https://github.com/usnistgov/microcalorimetry-ipages)) for detailed information on how to use the package.
20
+
21
+ ## Introduction
22
+ Install with pip or preffered package manager.
23
+
24
+ ```
25
+ pip install microcalorimetry
26
+ ```
27
+
28
+ ### CLI
29
+
30
+ The command line interface is can be accessed with the `ucal` command:
31
+
32
+ ```console
33
+ ucal --help
34
+ ```
35
+
36
+ ### GUI
37
+
38
+ The GUI is launched via the command line interface
39
+
40
+ ```console
41
+ ucal gui
42
+ ```
43
+
44
+ ### Python API
45
+
46
+ The Python API provides a functional interface for performing measurements and data analysis.
47
+
48
+ The ``microcalorimetry.measurements`` submodule provides an interface into RF sweep and DC sweep measurement procedures, as well as tools to parse the raw data.
49
+
50
+
51
+ ```Python
52
+ import microcalorimetry.measurements.dcsweep as dcsweep
53
+ import microcalorimetry.measurements.rfsweep as rfsweep
54
+ ```
55
+
56
+ Analysis functions that take in parsed data and generate new data sets with uncertainties (like the effective efficiency of power sensors) are provided in the ``microcalorimetry.analysis`` submodule.
57
+
58
+ ```Python
59
+ import microcalorimetry.analysis as analysis
60
+ ```
61
+
62
+
63
+ Configuration objects for measurements and analysis scripts are provided in a ``microcalorimetry.configs`` module.
64
+ ```Python
65
+ import microcalorimetry.configs as configs
66
+ ```
67
+
68
+ Mathematical operations compatable with ([RMEMeas](https://pages.nist.gov/rmellipse-ipages/stable/index.html)) objects are stored in the ``microcalorimetry.math`` submodule.
69
+
70
+ ```Python
71
+ import microcalorimetry.math as mcmath
72
+ ```
73
+
74
+ ## Authors
75
+
76
+ Contributors names and contact info
77
+
78
+ Daniel C. Gray, Zenn C. Roberts, Aaron M. Hagerstrom
@@ -0,0 +1,297 @@
1
+ # FAIR Software & Data
2
+
3
+ The following material is paraphrased from the NIST-internal
4
+ [Data Sponsorship][sponsors] repository by @tkphd.
5
+
6
+ ## Table of Contents
7
+
8
+ - [FAIR principles](#fair-principles)
9
+ - [Findable](#findable)
10
+ - [Accessible](#accessible)
11
+ - [Interoperable](#interoperable)
12
+ - [Reusable](#reusable)
13
+ - [Make It FAIR in Ten Easy Steps](#make-it-fair-in-ten-easy-steps)
14
+ - [What's "good enough"?](#whats-good-enough)
15
+ - [Data management](#data-management)
16
+ - [Software](#software)
17
+ - [Collaboration](#collaboration)
18
+ - [Project organization](#project-organization)
19
+ - [Keeping track of changes](#keeping-track-of-changes)
20
+ - [Manuscripts](#manuscripts)
21
+ - [Links](#links)
22
+
23
+ ## FAIR principles
24
+
25
+ What does FAIR even mean? The following sections reproduce the
26
+ summary from [Go FAIR][gofair], based on the original
27
+ [FAIR paper][fair].
28
+
29
+ Think you know FAIR? Please [use this tool][fair-aware] to check your
30
+ awareness!
31
+
32
+ ### Findable
33
+
34
+ The first step in (re)using data is to find them. Metadata and data
35
+ should be easy to find for both humans and computers.
36
+ Machine-readable metadata are essential for automatic discovery of
37
+ datasets and services, so this is an essential component of the
38
+ FAIRification process.
39
+
40
+ 1. (Meta)data are assigned a globally unique and persistent
41
+ identifier
42
+ 2. Data are described with rich metadata (defined by R1 below)
43
+ 3. Metadata clearly and explicitly include the identifier of the data
44
+ they describe
45
+ 4. (Meta)data are registered or indexed in a searchable resource
46
+
47
+ ### Accessible
48
+
49
+ Once the user finds the required data, she/he/they need to know how
50
+ can they be accessed, possibly including authentication and
51
+ authorisation.
52
+
53
+ 1. (Meta)data are retrievable by their identifier using a
54
+ standardised communications protocol
55
+ 1. The protocol is open, free, and universally implementable
56
+ 2. The protocol allows for an authentication and authorisation
57
+ procedure, where necessary
58
+ 2. Metadata are accessible, even when the data are no longer
59
+ available
60
+
61
+ ### Interoperable
62
+
63
+ The data usually need to be integrated with other data. In addition,
64
+ the data need to interoperate with applications or workflows for
65
+ analysis, storage, and processing.
66
+
67
+ 1. (Meta)data use a formal, accessible, shared, and broadly
68
+ applicable language for knowledge representation.
69
+ 2. (Meta)data use vocabularies that follow FAIR principles
70
+ 3. (Meta)data include qualified references to other (meta)data
71
+
72
+ ### Reusable
73
+
74
+ The ultimate goal of FAIR is to optimise the reuse of data. To
75
+ achieve this, metadata and data should be well-described so that they
76
+ can be replicated and/or combined in different settings.
77
+
78
+ 1. (Meta)data are richly described with a plurality of accurate and
79
+ relevant attributes
80
+ 1. (Meta)data are released with a clear and accessible data usage
81
+ license
82
+ 2. (Meta)data are associated with detailed provenance
83
+ 3. (Meta)data meet domain-relevant community standards
84
+
85
+ ## Make It FAIR in Ten Easy Steps
86
+
87
+ [Library Carpentry][lc] has a summary of [10 "easy" steps to make your
88
+ software FAIR][lc-fair-poster] (PDF). An annotated list follows.
89
+ Note that while the list is software-centric, it applies equally to data.
90
+
91
+ 1. *Create a description of your software.*
92
+ Write this in `README.md` with supporting tables, charts, images,
93
+ etc. Include its dependencies, installation instructions, and
94
+ citations of any work it builds upon.
95
+ 2. *Register your software in a software registry.*
96
+ [MIDAS][midas] is the go-to where Data Sponsorship is concerned,
97
+ but is not the only option.
98
+ 3. *Use a unique and persistent identifier for your software.*
99
+ Any registry compliant with [NIST O 5702][o5702] will provide you
100
+ with a persistent handle.
101
+ 4. *Make sure that people can download your software.*
102
+ If the data is fire- or pay-walled, provide an alternative site.
103
+ Wherever your data lives, check back from time to time to make
104
+ sure the links are still valid.
105
+ 5. *Explain the functionality of your software.*
106
+ Write this into a "Usage" section of `README.md`, or similar,
107
+ with example of how to configure, launch, and interact with the
108
+ software, with examples of output to be expected.
109
+ 6. *Use standard (community-agreed) formats for inputs and outputs.*
110
+ While open standards are preferred, if a proprietary format is the
111
+ *lingua franca* of the field, focus on that. Create open versions
112
+ if possible.
113
+ 7. *Document your software.*
114
+ This goes beyond `README.md` and in-line comments. Place
115
+ documentation, or its build scripts, in a folder named `doc` with
116
+ its own `README.md` describing how to build the docs and what to
117
+ expect.
118
+ 8. *Give your software a license.*
119
+ If all members of the development team are Federal employees, use
120
+ the standard NIST Disclaimer of Copyright and Warranty for your
121
+ [LICENSE.md][disc-copy]. Otherwise, decide on an appropriate
122
+ license.
123
+ 9. *State how to cite your software.*
124
+ This can be done in `README.md`, or as a separate
125
+ [`CITATION.md`][citation] using a BiBTeX-styled code block.
126
+ 10. *Follow best practices for software development.*
127
+ Broadly speaking, this starts with version control using
128
+ [git][git] or similar, [linting][lint] your code, and following
129
+ some type of branching workflow when multiple developers are
130
+ involved. The regularly-scheduled Software Carpentry workshops at
131
+ NIST teach the basics of some of these concepts.
132
+
133
+ ## What's good enough?
134
+
135
+ [*Good enough practices in scientific computing*][gepsc] is an
136
+ excellent paper outlining what you need to do to produce good science
137
+ in a FAIR frame of mind.
138
+
139
+ *tl;dr* follows.
140
+
141
+ ### Data management
142
+
143
+ 1. Save the raw data.
144
+ 2. Ensure that raw data are backed up in more than one location.
145
+ 3. Create the data you wish to see in the world.
146
+ 4. Create analysis-friendly data.
147
+ 5. Record all the steps used to process data.
148
+ 6. Anticipate the need to use multiple tables, and use a unique
149
+ identifier for every record.
150
+ 7. Submit data to a reputable DOI-issuing repository so that others
151
+ can access and cite it.
152
+
153
+ ### Software
154
+
155
+ 1. Place a brief explanatory comment at the start of every program.
156
+ 2. Decompose programs into functions.
157
+ 3. Be ruthless about eliminating duplication.
158
+ 4. Always search for well-maintained software libraries that do what
159
+ you need.
160
+ 5. Test libraries before relying on them.
161
+ 6. Give functions and variables meaningful names.
162
+ 7. Make dependencies and requirements explicit.
163
+ 8. Do not comment and uncomment sections of code to control a
164
+ program's behavior.
165
+ 9. Provide a simple example or test data set.
166
+ 10. Submit code to a reputable DOI-issuing repository.
167
+
168
+ ### Collaboration
169
+
170
+ 1. Create an overview of your project.
171
+ 2. Create a shared "to-do" list for the project.
172
+ 3. Decide on communication strategies.
173
+ 4. Make the license explicit.
174
+ 5. Make the project citable.
175
+
176
+ ### Project organization
177
+
178
+ 1. Put each project in its own directory, which is named after the
179
+ project.
180
+ 2. Put text documents associated with the project in the `doc`
181
+ directory.
182
+ 3. Put raw data and metadata in a `data` directory and files generated
183
+ during cleanup and analysis in a results directory.
184
+ 4. Put project source code in the `src` directory.
185
+ 5. Put external scripts or compiled programs in the `bin` directory.
186
+ 6. Name all files to reflect their content or function.
187
+
188
+ ### Keeping track of changes
189
+
190
+ 1. Back up (almost) everything created by a human being as soon as it
191
+ is created.
192
+ 2. Keep changes small.
193
+ 3. Share changes frequently.
194
+ 4. Create, maintain, and use a checklist for saving and sharing
195
+ changes to the project.
196
+ 5. Store each project in a folder that is mirrored off the
197
+ researcher's working machine.
198
+ 6. Add a file called `CHANGELOG.md` to the project's docs subfolder.
199
+ 7. Copy the entire project whenever a significant change has been
200
+ made.
201
+ 8. Use a version control system.
202
+
203
+ ### Manuscripts
204
+
205
+ 1. Write manuscripts using online tools with rich formatting, change
206
+ tracking, and reference management.
207
+ 2. Write the manuscript in a plain text format that permits version
208
+ control.
209
+
210
+ ## Links
211
+
212
+ - [F-UJI][fuji] (*tool*): analyze a repository and get a report of
213
+ its FAIR compliance, with an overall score and a checklist
214
+ - [FAIRaware][fair-aware] quiz/checklist of understanding
215
+ - [FAIR for Research Software (FAIR4RS)][fair4rs], a proposed
216
+ modification of the FAIR principles specifically for software.
217
+ - [10 easy things to make your software FAIR!][lc-fair-poster] (PDF)
218
+ from [Library Carpentry][lc-fair]
219
+ - [4 Simple Recommendations for Open-Source Software][4oss]
220
+ walk-through lesson, Carpentries-style
221
+
222
+ Some more general FAIR resources:
223
+
224
+ - Research Data Alliance: [Top 10 FAIR data and software things](https://www.rd-alliance.org/group/libraries-research-data-ig/outcomes/top-10-fair-data-software-things)
225
+ - Library Carpentries: [Top 10 FAIR Research Software Things](https://librarycarpentry.org/Top-10-FAIR//2018/12/01/research-software/)
226
+ - [NLeSC FAIR Software](https://fair-software.eu/)
227
+ - [NLeSC howfairis](https://github.com/fair-software/howfairis)
228
+ - [Data and Software Sharing Guidance for Authors Submitting to AGU journals](https://data.agu.org/resources/agu-data-software-sharing-guidance)
229
+ - [FAIRSharing and FAIRShake](https://presqt.readthedocs.io/en/latest/)
230
+ from the Preservation Quality Tool (PresQT)
231
+ - [Registry of Research Data Repositories](https://re3data.org/)
232
+ also has software locations
233
+ - [*Automating the Monitoring of Research Software FAIR Metrics*](https://doi.org/10.7490/f1000research.1117992.1)
234
+ - [Proposal for software indicators in the Open Science Monitor](https://www.ouvrirlascience.fr/about-the-proposal-for-software-indicators-in-open-science-monitor-3/)
235
+ - *National Plan for Open Science* (France, 2021-2024).
236
+ [Theme Three: Opening Up and Promoting Source Code Produced by Research](https://www.ouvrirlascience.fr/second-national-plan-for-open-science/)
237
+ - [The Turing Way](https://the-turing-way.netlify.app/welcome)
238
+ - [*Software Citation Guide*](https://doi.org/10.12688/f1000research.26932.2)
239
+ - [Managing Research Software Projects](https://swcarpentry.github.io/managing-research-software-projects/)
240
+ - [Guides](https://www.software.ac.uk/resources/guides)
241
+ for several groups (researchers, managers, developers, ...) from
242
+ the Software Sustainability Institute
243
+ - [Chorus Software Citation Policies Index](https://chorusaccess.org)
244
+ - [Software Discovery Through Registries](https://softdev4research.github.io/4OSS-lesson/05-use-registry/index.html)
245
+ - [Awesome FAIR Data][afd]: a list of FAIR data resources.
246
+ - [Awesome Research Software Registries](https://github.com/NLeSC/awesome-research-software-registries/blob/main/README.md)
247
+ - [CodeMeta Standard](https://codemeta.github.io/)
248
+ - [CodeMeta Generator][cmg] (*tool*): generate a complete set of
249
+ [CodeMeta][codemeta]-compliant metadata for your research software
250
+ and/or data with this handy form. Exports to JSON.
251
+ *Note:* `codemeta.json` is *not* the same as `codemeta.yaml`: the
252
+ former is a nascent general schema, while the latter is only used
253
+ to help index and link NIST websites.
254
+ - [SOftware Metadata Extraction Framework (SOMEF)](https://github.com/KnowledgeCaptureAndDiscovery/somef/)
255
+ - [*Good Enough Practices in Scientific Computing*](https://doi.org/10.1371/journal.pcbi.1005510)
256
+ - [Citation File Format][citation] docs from GitHub
257
+ - [Software REUSE Specification](https://reuse.software/spec/)
258
+ - [FAIR Computational Workflows][fcw] (*paper*): Data doesn't just
259
+ happen. Record the workflow that created it to be super FAIR.
260
+
261
+ Institutional guidance:
262
+
263
+ - DLR: [Software Engineering Initiative](https://rse.dlr.de/01_guidelines.html)
264
+ - MIT: [Software Citation and Publishing](https://libguides.mit.edu/software)
265
+ - MIT workshop: [Managing your research code](https://www.dropbox.com/s/gukkthqzcuea1kr/MgingCode_Slides_MIT.pdf?dl=0)
266
+ - TU Delft [*Guidelines on Research Software: Licensing, Registration and Commercialisation*](https://doi.org/10.5281/zenodo.4629635)
267
+ - TU Delft: [Choosing a Repository Manager](https://doi.org/10.5281/zenodo.4710206)
268
+ - Helmholtz: [Guidelines for Sustainable Research Software](https://gfzpublic.gfz-potsdam.de/pubman/faces/ViewItemOverviewPage.jsp?itemId=item_4906899)
269
+ - [Checklist for Helmholtz Guidelines](https://gfzpublic.gfz-potsdam.de/pubman/faces/ViewItemOverviewPage.jsp?itemId=item_5007561)
270
+ - NIH: [Best Practices for Sharing Research Software](https://datascience.nih.gov/tools-and-analytics/best-practices-for-sharing-research-software-faq)
271
+
272
+ <!-- links -->
273
+
274
+ [4oss]: https://softdev4research.github.io/4OSS-lesson/
275
+ [afd]: https://github.com/Materials-Data-Science-and-Informatics/awesome-fair-data
276
+ [citation]: https://github.com/citation-file-format/citation-file-format
277
+ [cmg]: https://codemeta.github.io/codemeta-generator/
278
+ [codemeta]: https://codemeta.github.io/
279
+ [disc-copy]: https://www.nist.gov/open/copyright-fair-use-and-licensing-statements-srd-data-software-and-technical-series-publications
280
+ [fair]: https://doi.org/10.1038/sdata.2016.18
281
+ [fair4rs]: https://doi.org/10.1016/j.patter.2021.100222
282
+ [fair-aware]: https://fairaware.dans.knaw.nl
283
+ [fcw]: https://doi.org/10.1162/dint_a_00033
284
+ [fuji]: https://www.f-uji.net/index.php?action=home
285
+ [gepsc]: https://doi.org/10.1371/journal.pcbi.1005510
286
+ [git]: https://git-scm.com
287
+ [git-open]: https://github.com/usnistgov/opensource-repo
288
+ [gofair]: https://www.go-fair.org/fair-principles/
289
+ [lc-fair]: https://librarycarpentry.org/Top-10-FAIR//2018/12/01/research-software/
290
+ [lc-fair-poster]: https://librarycarpentry.org/Top-10-FAIR/files/poster_10things_FAIRsoftware.pdf
291
+ [lint]: https://en.wikipedia.org/wiki/Lint_(software)
292
+ [midas]: https://midas.nist.gov/
293
+ [o5701]: https://inet.nist.gov/adlp/directives/managing-public-access-results-federally-funded-research-0
294
+ [o5702]: https://inet.nist.gov/adlp/directives/preservation-maintenance-published-research-data
295
+ [sp811]: https://dx.doi.org/10.6028/NIST.SP.811e2008
296
+ [sponsors]: https://gitlab.nist.gov/gitlab/tkphd/data-sponsorship
297
+ [taxon]: https://doi.org/10.18434/T4/1432795