@@ -9,49 +9,65 @@ This example will demonstrate how diffpy.utils lets us easily process and serial
99Using the parsers module, we can load file data into simple and easy-to-work-with Python objects.
1010
11111) To begin, unzip :download: `parser_data<./example_data/parser_data.zip> ` and take a look at ``data.txt ``.
12- Our goal will be to extract and serialize the data table as well as the parameters listed in the header of this file.
12+ This is a fairly standard format for 1D powder diffraction data.
13+ Our goal will be to extract the data, and the parameters listed in the header, from this file and
14+ load it into our program.
1315
14162) To get the data table, we will use the ``loadData `` function. The default behavior of this
15- function is to find and extract a data table from a file.::
17+ function is to find and extract a data table from a file.
18+
19+ .. code-block :: python
1620
1721 from diffpy.utils.parsers.loaddata import loadData
1822 data_table = loadData(' <PATH to data.txt>'
1923
20- While this will work with most datasets, on our ``data.txt `` file, we got a ``ValueError ``. The reason for this is
21- due to the comments ``$ Phase Transition Near This Temperature Range `` and ``--> Note Significant Jump in Rw <-- ``
22- embedded within the dataset. To fix this, try using the ``comments `` parameter. ::
24+ data.txt `` file, we got a ``ValueError ``. The reason for this is
25+ due to the comments ``$ Phase Transition Near This Temperature Range `` and ``--> Note Significant Jump in Rw <-- ``
26+ embedded within the dataset. To fix this, try using the ``comments `` parameter.
27+
28+ .. code-block :: python
2329
2430 data_table = loadData(' <PATH to data.txt>' comments = [' $' ' -->'
2531
26- This parameter tells ``loadData `` that any lines beginning with ``$ `` and ``--> `` are just comments and
27- more entries in our data table may follow.
32+ loadData `` that any lines beginning with ``$ `` and ``--> `` are just comments and
33+ more entries in our data table may follow.
2834
29- Here are a few other parameters to test out:
35+ Here are a few other parameters to test out:
3036
3137 * ``delimiter=',' ``: Look for a comma-separated data table. Useful for csv file types.
32- However, since ``data.txt `` is whitespace separated, running ::
38+ However, since ``data.txt `` is whitespace separated, running
39+
40+ .. code-block :: python
3341
3442 loadData(' <PATH to data.txt>' comments = [' $' ' -->' delimiter = ' ,'
3543
36- returns an empty list.
44+
3745 * ``minrows=50 ``: Only look for data tables with at least 50 rows. Since our data table has much less than that many
38- rows, running ::
46+ rows, running
47+
48+ .. code-block :: python
3949
4050 loadData(' <PATH to data.txt>' comments = [' $' ' -->' minrows = 50 )
4151
42- returns an empty list.
52+
4353 * ``usecols=[0, 3] ``: Only return the 0th and 3rd columns (zero-indexed) of the data table. For ``data.txt ``, this
44- corresponds to the temperature and rw columns. ::
54+ corresponds to the temperature and rw columns.
55+
56+ .. code-block :: python
4557
4658 loadData(' <PATH to data.txt>' comments = [' $' ' -->' usecols = [0 , 3 ])
4759
4860loadData ``,
49- but this time with the ``headers `` parameter enabled. ::
61+ but this time with the ``headers `` parameter enabled.
62+
63+ .. code-block :: python
5064
5165 hdata = loadData(' <PATH to data.txt>' comments = [' $' ' -->' headers = True )
5266
5367data_table `` and ``hdata `` objects, it may be easier to combine them into a single
54- dictionary. We can do so using the ``serialize_data `` function. ::
68+ dictionary. We can do so using the ``serialize_data `` function.
69+
70+ .. code-block :: python
5571
5672 from diffpy.utils.parsers.loaddata import serialize_data
5773 file_data = serialize_data(' <PATH to data.txt'
@@ -60,45 +76,59 @@ Using the parsers module, we can load file data into simple and easy-to-work-wit
6076 # The entry is a dictionary containing data from hdata and data_table
6177 data_dict = file_data[' data.txt'
6278
63- This dictionary ``data_dict `` contains all entries in ``hdata `` and an additional entry named
64- ``data table `` containing ``data_table ``. ::
79+ data_dict `` contains all entries in ``hdata `` and an additional entry named
80+ ``data table `` containing ``data_table ``.
81+
82+ .. code-block :: python
6583
6684 here_is_the_data_table = data_dict[' data table'
6785
68- There is also an option to name columns in the data table and save those columns as entries instead. ::
86+
87+
88+ .. code-block :: python
6989
7090 data_table_column_names = [' temperature' ' scale' ' stretch' ' rw' # names of the columns in data.txt
7191 file_data = serialize_data(' <PATH to data.txt>' dt_colnames = data_table_column_names)
7292 data_dict = file_data[' data.txt'
7393
74- Now we can extract specific data table columns from the dictionary. ::
94+
7595
96+ .. code-block :: python
7697 data_table_temperature_column = data_dict[' temperature'
7798 data_table_rw_column = data_dict[' rw'
7899
79- 5) When we are done working with the data, we can store it on disc for later use. This can also be done using the
80- ``serialize_data `` function with an additional ``serial_file `` parameter.::
100+
101+ ``serialize_data `` function with an additional ``serial_file `` parameter.
102+
103+ .. code-block :: python
81104
82105 parsed_file_data = serialize_data(' <PATH to data.txt>' serial_file = ' <PATH to serialfile.json>'
83106
84107 The returned value, `` parsed_file_data`` , is the dictionary we just added to `` serialfile.json`` .
85- To extract the data from the serial file, we use ``deserialize_data ``. ::
108+ To extract the data from the serial file , we use `` deserialize_data`` .
109+
110+ code-block :: python
86111
87112 from diffpy.utils.parsers.serialization import deserialize_data
88113 parsed_file_data = deserialize_data(' <PATH to serialdata.json>'
89114
90- 6) Finally, ``serialize_data `` allows us to store data from multiple text file in a single serial file. For one last bit
91- of practice, we will extract and add the data from ``moredata.txt `` into the same ``serialdata.json `` file.::
115+ serialize_data `` allows us to store data from multiple text files in a single serial file. For one last bit
116+ of practice, we will extract and add the data from ``moredata.txt `` into the same ``serialdata.json `` file.
117+
118+ .. code-block :: python
92119
93120 data_table = loadData(' <PATH to moredata.txt>'
94121 hdata = loadData(' <PATH to moredata.txt>' headers = True )
95122 serialize_data(' <PATH to moredata.txt>' serial_file = ' <PATH to serialdata.json>'
96123
97- The serial file ``serialfile.json `` should now contain two entries: ``data.txt `` and ``moredata.txt ``.
98- The data from each file can be accessed using ::
124+ serialfile.json `` should now contain two entries: ``data.txt `` and ``moredata.txt ``.
125+ The data from each file can be accessed using
126+
127+ .. code-block :: python
99128
100129 serial_data = deserialize_data(' <PATH to serialdata.json>'
101130 data_txt_data = serial_data[' data.txt' # Access data.txt data
102131 moredata_txt_data = serial_data[' moredata.txt' # Access moredata.txt data
103132
104133:ref: `documentation<Parsers Documentation> ` of the ``parsers `` module.
134+ b
0 commit comments