{"action":"created","issue":{"url":"https://api.github.com/repos/Photon-Data/photon-hdf5/issues/8","labels_url":"https://api.github.com/repos/Photon-Data/photon-hdf5/issues/8/labels{/name}","comments_url":"https://api.github.com/repos/Photon-Data/photon-hdf5/issues/8/comments","events_url":"https://api.github.com/repos/Photon-Data/photon-hdf5/issues/8/events","html_url":"https://github.com/Photon-Data/photon-hdf5/issues/8","id":57741519,"number":8,"title":"Proposal for Photon-HDF5 version 0.3","user":{"login":"tritemio","id":4156237,"avatar_url":"https://avatars.githubusercontent.com/u/4156237?v=3","gravatar_id":"","url":"https://api.github.com/users/tritemio","html_url":"https://github.com/tritemio","followers_url":"https://api.github.com/users/tritemio/followers","following_url":"https://api.github.com/users/tritemio/following{/other_user}","gists_url":"https://api.github.com/users/tritemio/gists{/gist_id}","starred_url":"https://api.github.com/users/tritemio/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tritemio/subscriptions","organizations_url":"https://api.github.com/users/tritemio/orgs","repos_url":"https://api.github.com/users/tritemio/repos","events_url":"https://api.github.com/users/tritemio/events{/privacy}","received_events_url":"https://api.github.com/users/tritemio/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":10,"created_at":"2015-02-15T19:06:21Z","updated_at":"2015-02-18T19:30:43Z","closed_at":null,"body":"This document summarizes the new layout proposed for version 0.3 of the Photon-HDF5 file format.\r\n\r\nThe format includes a compulsory set of root fields, and at least a photon-data group.\r\n\r\n## Root group\r\n\r\n### Measurement overview fields\r\n\r\nThe following parameters in the root group are present in all types of measurement. They are sufficiently general to warrant their inclusion in all files.\r\nMeasurement-specific information necessary to interpret the data, is provided in measurement-specific group(s) described later.\r\n\r\n- `/num_spots` number of parallel excitation and/or detection spots. When using point-like detectors,\r\n  this number indicates the number of detection PSFs, even if the excitation does not involves \"spots\".   \r\n  With a widefield detector this field looses any meaning and its value should become 'undefined', or\r\n  the field should be removed altogether.\r\n\r\n- `/alex` (boolean) True (i.e. = 1) when the measurements uses any form of alternated/interleaved excitation at different wavelengths (us-ALEX, ns-ALEX or PIE, PAX). When there is no periodic alternation of the excitation wavelength this field must be `False`.\r\n\r\n- `/lifetime` (boolean) True (i.e. = 1) when the data contains explicitly a nanotime array. In the case of high-resolution timestamps with potential lifetime resolving resolution this filed will still be `False`.\r\n\r\n- `/num_spectral_ch`  (integer) number of different spectral bands in the detection channels (e.g. 2 for 2-color smFRET)\r\n\r\n- `/num_polariz_ch` (integer) number of different polarizations in the detection channels. The value is 1 if no polarization selection is performed and 2 if two polarizations are recorded.\r\n\r\n- `/acquisition_time` measurement duration [X: define. Is it the difference between the last and first timestamp or some different measure?]\r\n\r\n- `/measurement_description` (string): free-form user-supplied description of the measurement.\r\n\r\n**Note 1**: to be decided if all these parameters must be considered mandatory. \r\n\r\n**Note 2**: having these root parameters allows to support \"incomplete\" or \"test\" measurements that are not smFRET, and or ALEX. For example the multi-spot preliminary measurements with one laser excitation and one detection band. These simple \"test\" measurements don't need to have a separate measurement group because these root parameters are enough for interpretation. In other words we keep the simple case simple.\r\n\r\n### Measurement type\r\n\r\nThe field:\r\n\r\n    measurement_type\r\n\r\ncontains a string that identifies the measurement type. Examples of possible values are:\r\n\r\n- \"smFRET\" no alternation \r\n- \"smFRET us-ALEX\" (2 colors)\r\n- \"smFRET ns-ALEX\" (2 colors)\r\n- \"smFRET us-ALEX-3C\" (3 colors)\r\n\r\n### Measurement group:\r\n\r\nThis group named `measurements_specs` is placed inside the `photon_data` group so the multispot case is easily supported.\r\n\r\n### \"smFRET\"\r\n\r\n```\r\ndetectors_specs/\r\n    donor\r\n    acceptor\r\n```\r\n\r\n### \"smFRET us-ALEX\"\r\n\r\n```\r\nalternation_period\r\nalternation_period_donor\r\nalternation_period_acceptor\r\ndetectors_specs/\r\n    donor\r\n    acceptor\r\n```\r\n\r\n### \"smFRET ns-ALEX\"\r\n\r\n```\r\nlaser_pulse_rate\r\nalternation_period_donor\r\nalternation_period_acceptor\r\ndetectors_specs/\r\n    donor\r\n    acceptor\r\n```\r\n\r\n### \"smFRET us-ALEX-3C\"\r\n\r\n```\r\nalternation_period\r\nalternation_period_blue\r\nalternation_period_green\r\nalternation_period_red\r\ndetectors_specs/\r\n    blue\r\n    green\r\n    red\r\n```\r\n\r\n[X: Not sure BGR is the name you want to give to them. Maybe wavelength_n, n = 1, 2, 3?]\r\n\r\n## photon-data group layout:\r\n\r\n```\r\n/photon-data/\r\n    timestamps\r\n    timestamps_specs/\r\n        timestamps_unit\r\n    detectors\r\n    nanotimes\r\n    nanotimes_specs/\r\n        tcspc_unit\r\n        tcspc_range\r\n        tcspc_num_bins\r\n````\r\n**Notes**\r\n- `detectors` can be a 1D array or a 2D array. Each row always represents the detector(s) of one timestamp (represented by a single ID or a n-tuple of ID).\r\n\r\n- the `detectors_specs` group is now in `measurement_specs` and defines the associations between detectors and spectral bands or polarization bands."},"comment":{"url":"https://api.github.com/repos/Photon-Data/photon-hdf5/issues/comments/74930982","html_url":"https://github.com/Photon-Data/photon-hdf5/issues/8#issuecomment-74930982","issue_url":"https://api.github.com/repos/Photon-Data/photon-hdf5/issues/8","id":74930982,"user":{"login":"tritemio","id":4156237,"avatar_url":"https://avatars.githubusercontent.com/u/4156237?v=3","gravatar_id":"","url":"https://api.github.com/users/tritemio","html_url":"https://github.com/tritemio","followers_url":"https://api.github.com/users/tritemio/followers","following_url":"https://api.github.com/users/tritemio/following{/other_user}","gists_url":"https://api.github.com/users/tritemio/gists{/gist_id}","starred_url":"https://api.github.com/users/tritemio/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tritemio/subscriptions","organizations_url":"https://api.github.com/users/tritemio/orgs","repos_url":"https://api.github.com/users/tritemio/repos","events_url":"https://api.github.com/users/tritemio/events{/privacy}","received_events_url":"https://api.github.com/users/tritemio/received_events","type":"User","site_admin":false},"created_at":"2015-02-18T19:30:43Z","updated_at":"2015-02-18T19:30:43Z","body":"For wavelengths, spectral bands and dyes names the convention is to list then increasing order of reference wavelength (blue to red)."}}