Astronify is under active development. Currently the package can sonify data series and will ultimately grow to encompass a range of sonification functionality.
29 |
30 |
We welcome feedback and code contributions. Visit us on GitHub at:
Test your ears! Listen to real sonified data and answer questions about what you heard. Playing these games will help us learn how to improve our sonifications.
Astronify and the sonifications shared on this website are released under a BSD-3 Open License.
125 |
126 |
127 |
128 |
129 |
130 |
--------------------------------------------------------------------------------
/astronify/simulator/sim_lc_setup_args.py:
--------------------------------------------------------------------------------
1 | """
2 | .. module:: sim_lc_setup_args
3 | :synopsis: Sets up command-line argument parser.
4 |
5 | .. moduleauthor:: Scott W. Fleming
6 | """
7 |
8 | import argparse
9 | from .sim_lc_config import SimLcConfig as sim_lc_config
10 |
11 |
12 | def sim_lc_setup_args():
13 | """
14 | Set up command-line arguments and options.
15 |
16 | :returns: ArgumentParser -- Stores arguments and options.
17 | """
18 |
19 | parser = argparse.ArgumentParser(
20 | description="Create simulated light curves, as FITS files, for use with"
21 | " the Astronify sonification software. Types include flat, transit, sine"
22 | " and flare."
23 | )
24 |
25 | parser.add_argument(
26 | "lc_type",
27 | action="store",
28 | type=str,
29 | help="Type of light curve to create.",
30 | choices=["flat", "transit", "sine", "flare"],
31 | )
32 |
33 | parser.add_argument(
34 | "-o",
35 | dest="lc_ofile",
36 | action="store",
37 | type=str,
38 | help="Name of output FITS file to create.",
39 | default=sim_lc_config.sim_lc_ofile,
40 | )
41 |
42 | parser.add_argument(
43 | "-l",
44 | action="store",
45 | type=int,
46 | default=sim_lc_config.sim_lc_length,
47 | dest="lc_length",
48 | help="Total number of flux"
49 | " measurements in the light curve. Default ="
50 | " %(default)s.",
51 | )
52 |
53 | parser.add_argument(
54 | "-n",
55 | action="store",
56 | type=float,
57 | default=sim_lc_config.sim_lc_noise,
58 | dest="lc_noise",
59 | help="Amount of noise to add to the"
60 | " measurements in the light curve, specified by the"
61 | " standard deviation of the normal distribution to draw"
62 | " from. Set to zero for no noise. Default ="
63 | " %(default)s.",
64 | )
65 |
66 | parser.add_argument(
67 | "-v",
68 | action="store_true",
69 | dest="visualize",
70 | default=sim_lc_config.sim_lc_vizualize,
71 | help="If True, a plot of the light curve"
72 | " that is generated will be plot on the screen. Default"
73 | " = %(default)s.",
74 | )
75 |
76 | parser.add_argument(
77 | "-y",
78 | action="store",
79 | type=float,
80 | default=sim_lc_config.sim_lc_yoffset,
81 | dest="lc_yoffset",
82 | help="Baseline (unitless) flux height"
83 | " of the light curve. Used to test sonification of"
84 | " sources with different total brightness. Default ="
85 | " %(default)s.",
86 | )
87 |
88 | # Transit-related parameters here.
89 | transit_group = parser.add_argument_group(
90 | "transit", "Parameters for transit signals."
91 | )
92 |
93 | transit_group.add_argument(
94 | "--transit_depth",
95 | type=float,
96 | default=sim_lc_config.sim_lc_transit_depth,
97 | dest="transit_depth",
98 | help="Depth of the transit"
99 | " signal specified as a percent, e.g., set to"
100 | " 10.0 for a 10%% depth transit. Default ="
101 | " %(default)s.",
102 | )
103 |
104 | transit_group.add_argument(
105 | "--transit_period",
106 | type=int,
107 | default=sim_lc_config.sim_lc_transit_period,
108 | dest="transit_period",
109 | help="Period of the"
110 | " transit signal, specified as the number of"
111 | " fluxes (bins) between the start of each event."
112 | " Default = %(default)s.",
113 | )
114 |
115 | transit_group.add_argument(
116 | "--transit_start",
117 | type=int,
118 | default=sim_lc_config.sim_lc_transit_start,
119 | dest="transit_start",
120 | help="Start of the first"
121 | " transit, specified as the index of the"
122 | " flux (bin) to use as the start of the first"
123 | " transit event. Default = %(default)s.",
124 | )
125 |
126 | transit_group.add_argument(
127 | "--transit_width",
128 | type=int,
129 | default=sim_lc_config.sim_lc_transit_width,
130 | dest="transit_width",
131 | help="Width of the"
132 | " transit signal, specified as the number of"
133 | " fluxes (bins) between the start and end of each"
134 | " event. Default = %(default)s.",
135 | )
136 |
137 | # Sinusoidal-related parameters here.
138 | sine_group = parser.add_argument_group(
139 | "sinusoidal", "Parameters for sinusoidal signals."
140 | )
141 |
142 | sine_group.add_argument(
143 | "--sine_amp",
144 | type=float,
145 | default=sim_lc_config.sim_lc_sine_amp,
146 | dest="sine_amp",
147 | help="Amplitude of the sinusoidal signal to add. Default = %(default)s.",
148 | )
149 |
150 | sine_group.add_argument(
151 | "--sine_period",
152 | type=float,
153 | default=sim_lc_config.sim_lc_sine_period,
154 | dest="sine_period",
155 | help="Period of the sinusoidal signal, specified in the (unitless)"
156 | " time axis (flux bins). Default = %(default)s.",
157 | )
158 |
159 | # Flare-related parameters here.
160 | flare_group = parser.add_argument_group("flare", "Parameters for adding flares.")
161 |
162 | flare_group.add_argument(
163 | "--flare_time",
164 | type=int,
165 | default=sim_lc_config.sim_lc_flare_time,
166 | dest="flare_time",
167 | help="Time corresponding to"
168 | " the maximum flux of the flare, specified"
169 | " as the index of the flux (bin) to use as"
170 | " the peak time. Default = %(default)s.",
171 | )
172 |
173 | flare_group.add_argument(
174 | "--flare_amp",
175 | type=float,
176 | default=sim_lc_config.sim_lc_flare_amp,
177 | dest="flare_amp",
178 | help="Amplitude (maximum flux) of the flare to add. Default = %(default)s.",
179 | )
180 |
181 | flare_group.add_argument(
182 | "--flare_halfwidth",
183 | type=int,
184 | default="flare_halfwidth",
185 | help="The flare"
186 | " half-width (measured in indices) that"
187 | " corresponds to 't_1/2' in the Davenport et al."
188 | " flare template.",
189 | )
190 |
191 | return parser
192 |
--------------------------------------------------------------------------------
/astronify/utils/pitch_mapping.py:
--------------------------------------------------------------------------------
1 | # Licensed under a 3-clause BSD style license - see LICENSE.rst
2 | """
3 | Pitch mapping functionality
4 | ===========================
5 |
6 | Functionality for taking arbitrary data values to audible pitches.
7 | """
8 |
9 | import warnings
10 |
11 | import numpy as np
12 |
13 | from astropy.visualization import (
14 | SqrtStretch,
15 | LogStretch,
16 | AsinhStretch,
17 | SinhStretch,
18 | LinearStretch,
19 | MinMaxInterval,
20 | ManualInterval,
21 | AsymmetricPercentileInterval,
22 | )
23 |
24 | from .exceptions import InputWarning, InvalidInputError
25 |
26 | __all__ = ["data_to_pitch"]
27 |
28 |
29 | def data_to_pitch(
30 | data_array,
31 | pitch_range=[100, 10000],
32 | center_pitch=440,
33 | zero_point="median",
34 | stretch="linear",
35 | minmax_percent=None,
36 | minmax_value=None,
37 | invert=False,
38 | ):
39 | """
40 | Map data array to audible pitches in the given range, and apply stretch and scaling
41 | as required.
42 |
43 | Parameters
44 | ----------
45 | data_array : array-like
46 | Data to map to pitch values. Individual data values should be floats.
47 | pitch_range : array
48 | Optional, default [100,10000]. Range of acceptable pitches in Hz.
49 | center_pitch : float
50 | Optional, default 440. The pitch in Hz where that the the zero point of the
51 | data will be mapped to.
52 | zero_point : str or float
53 | Optional, default "median". The data value that will be mapped to the center
54 | pitch. Options are mean, median, or a specified data value (float).
55 | stretch : str
56 | Optional, default 'linear'. The stretch to apply to the data array.
57 | Valid values are: asinh, sinh, sqrt, log, linear
58 | minmax_percent : array
59 | Optional. Interval based on a keeping a specified fraction of data values
60 | (can be asymmetric) when scaling the data. The format is [lower percentile,
61 | upper percentile], where data values below the lower percentile and above the upper
62 | percentile are clipped. Only one of minmax_percent and minmax_value should be specified.
63 | minmax_value : array
64 | Optional. Interval based on user-specified data values when scaling the data array.
65 | The format is [min value, max value], where data values below the min value and above
66 | the max value are clipped.
67 | Only one of minmax_percent and minmax_value should be specified.
68 | invert : bool
69 | Optional, default False. If True the pitch array is inverted (low pitches become high
70 | and vice versa).
71 |
72 | Returns
73 | -------
74 | response : array
75 | The normalized data array, with values in given pitch range.
76 | """
77 | # Parsing the zero point
78 | if zero_point in ("med", "median"):
79 | zero_point = np.median(data_array)
80 | if zero_point in ("ave", "mean", "average"):
81 | zero_point = np.mean(data_array)
82 |
83 | # The center pitch cannot be >= max() pitch range, or <= min() of pitch range.
84 | # If it is, fall back to using the mean of the pitch range provided.
85 | if center_pitch <= pitch_range[0] or center_pitch >= pitch_range[1]:
86 | warnings.warn(
87 | "Given center pitch is outside the pitch range, defaulting to the mean.",
88 | InputWarning,
89 | )
90 | center_pitch = np.mean(pitch_range)
91 |
92 | if (data_array == zero_point).all():
93 | # All values are the same, no more calculation needed
94 | return np.full(len(data_array), center_pitch)
95 |
96 | # Normalizing the data_array and adding the zero point (so it can go through the same transform)
97 | data_array = np.append(np.array(data_array), zero_point)
98 |
99 | # Setting up the transform with the stretch
100 | if stretch == "asinh":
101 | transform = AsinhStretch()
102 | elif stretch == "sinh":
103 | transform = SinhStretch()
104 | elif stretch == "sqrt":
105 | transform = SqrtStretch()
106 | elif stretch == "log":
107 | transform = LogStretch()
108 | elif stretch == "linear":
109 | transform = LinearStretch()
110 | else:
111 | raise InvalidInputError("Stretch {} is not supported!".format(stretch))
112 |
113 | # Adding the scaling to the transform
114 | if minmax_percent is not None:
115 | transform += AsymmetricPercentileInterval(*minmax_percent)
116 |
117 | if minmax_value is not None:
118 | warnings.warn(
119 | "Both minmax_percent and minmax_value are set, minmax_value will be ignored.",
120 | InputWarning,
121 | )
122 | elif minmax_value is not None:
123 | transform += ManualInterval(*minmax_value)
124 | else: # Default, scale the entire image range to [0,1]
125 | transform += MinMaxInterval()
126 |
127 | # Performing the transform and then putting it into the pich range
128 | pitch_array = transform(data_array)
129 |
130 | if invert:
131 | pitch_array = 1 - pitch_array
132 |
133 | zero_point = pitch_array[-1]
134 | pitch_array = pitch_array[:-1]
135 |
136 | # In rare cases, the zero-point at this stage might be 0.0.
137 | # One example is an input array of two values where the median() is the same as the
138 | # lowest of the two values. In this case, the zero-point is 0.0 and will lead to error
139 | # (divide by zero). Change to small value to avoid dividing by zero (in reality the choice
140 | # of zero-point calculation by the user was probably poor, but not in purview to mandate or
141 | # change user's choice here. May want to consider providing info back to the user about the
142 | # distribution of pitches actually used based on their sonification options in some way.
143 | if zero_point == 0.0:
144 | zero_point = 1e-6
145 |
146 | if (
147 | (1 / zero_point) * (center_pitch - pitch_range[0]) + pitch_range[0]
148 | ) <= pitch_range[1]:
149 | pitch_array = (pitch_array / zero_point) * (
150 | center_pitch - pitch_range[0]
151 | ) + pitch_range[0]
152 | else:
153 | pitch_array = ((pitch_array - zero_point) / (1 - zero_point)) * (
154 | pitch_range[1] - center_pitch
155 | ) + center_pitch
156 |
157 | return pitch_array
158 |
--------------------------------------------------------------------------------
/docs/astronify/index.rst:
--------------------------------------------------------------------------------
1 | ***********************
2 | Astronify Documentation
3 | ***********************
4 |
5 | Introduction
6 | ============
7 |
8 | Astronify contains tools for sonifying astronomical data. Currently Astronify can sonify data series. This package is under active development, and will ultimately grow to encompass a range of sonification functionality.
9 |
10 |
11 | Data Series Sonification
12 | ========================
13 |
14 | Data series sonification refers to taking a data table and mapping one column to
15 | time, and one column to pitch. In astronomy this technique is commonly used to
16 | sonify light curves, where observation time is scaled to listening time
17 | and flux is mapped to pitch. While Astronify's sonification uses the columns "time"
18 | and "flux" by default, any two columns can be supplied and a sonification created.
19 |
20 |
21 | Basic Usage
22 | -----------
23 |
24 | At base, all that is required to make a sonification is an `~astropy.table.Table` with
25 | two columns. By default these columns are assumed to be named "time" and "flux", but
26 | alternate column names can also be provided (see `~astronify.series.SoniSeries`).
27 |
28 | .. code-block:: python
29 |
30 | >>> from astronify.series import SoniSeries
31 | >>> from astropy.table import Table
32 |
33 | >>> data_table = Table({"time":[0, 1, 2, 3, 4, 5, 9, 10, 11, 12],
34 | ... "flux": [0.3, 0.4, 0.3, 0.5, 0.5, 0.4, 0.3, 0.2, 0.3, 0.1]})
35 |
36 | >>> data_soni = SoniSeries(data_table)
37 | >>> data_soni.note_spacing = 0.2
38 | >>> data_soni.sonify()
39 | >>> data_soni.play() #doctest: +SKIP
40 |
41 |
42 | The default note spacing (median time between notes in seconds) is 0.01, so for short data series
43 | we need to slow it down to hear all the data points.
44 |
45 | This more interesting example sonifies real data from the Kepler space telescope.
46 | The package `Lightkurve `_ is used to download a Kepler
47 | light curve and then sonify it.
48 |
49 |
50 | .. code-block:: python
51 |
52 | >>> from astronify.series import SoniSeries
53 | >>> import lightkurve #doctest: +SKIP
54 |
55 | >>> kep12b_lc = lightkurve.search_lightcurvefile("KIC 11804465", cadence="long", quarter=1).download_all()[0].SAP_FLUX.to_table() #doctest: +SKIP
56 | >>> kep12b_obj = SoniSeries(kep12b_lc) #doctest: +SKIP
57 | >>> kep12b_obj.sonify() #doctest: +SKIP
58 | >>> kep12b_obj.play() #doctest: +SKIP
59 |
60 |
61 | A variety of arguments can be set to change the parameters of the sonification. You can control note spacing, note duration (each data point will get a note of the same duration),
62 | and change a number of aspects of the algorithm used to transform data values into pitches.
63 |
64 | .. code-block:: python
65 |
66 | >>> from astronify.series import SoniSeries
67 | >>> import lightkurve #doctest: +SKIP
68 |
69 | >>> kep12b_lc = lightkurve.search_lightcurvefile("KIC 11804465", cadence="long", quarter=1).download_all()[0].SAP_FLUX.to_table() #doctest: +SKIP
70 | >>> kep12b_obj = SoniSeries(kep12b_lc) #doctest: +SKIP
71 | >>> kep12b_obj.pitch_mapper.pitch_map_args["center_pitch"] = 880 #doctest: +SKIP
72 | >>> kep12b_obj.sonify() #doctest: +SKIP
73 | >>> kep12b_obj.play() #doctest: +SKIP
74 |
75 |
76 | See `~astronify.utils.data_to_pitch` for a full list of the parameters that can be changed in the
77 | default pitch mapping function. The default pitch mapping function can also be replaced with
78 | a user supplied function, see `~astronify.series.PitchMap` for the requirements on this function.
79 |
80 |
81 | Sonification Algorithm
82 | ----------------------
83 |
84 | While the user can supply any function they like to transform data values in to pitch in Hz,
85 | the default function for Astronify is `~astronify.utils.data_to_pitch` which takes in an array
86 | of float values and transformed them into audible pitch values (in Hz).
87 |
88 | **The algorithm is as follows:**
89 |
90 | Given a center pitch, zero point, and pitch range, the data values will be scaled with a
91 | chosen stretch (linear, hyperbolic sine, hyperbolic arcsine, logarithmic or square
92 | root) such that the zero point maps to the center pitch and all pitches fall within
93 | the pitch range. The given pitch range defines the maximum pitch boundaries, but
94 | depending on the parameters of sonification output pitches may not reach the edges.
95 |
96 | The zero point is calculated based on the input argument (mean, median, or specified value)
97 | and then appended to the data array. The resulting array is scaled to the interval [0,1]
98 | taking into account any requested clipping, and the requested stretch is applied. At this point
99 | if the invert argument is set, the array is inverted by subtracting all values from 1.
100 |
101 | The scaled zero point is then removed from the array which is scaled to the pitch range
102 | such that the scaled zero point becomes the center pitch value and the entire pitch range
103 | falls within the input pitch range. In practice this means one of two things:
104 | The array is scaled such that the 0 corresponds to the minimum of the input pitch range and the
105 | scaled zero point corresponds to the center pitch value. Or, the scaled zero point corresponds to
106 | the center pitch value and 1 corresponds to the maximum of the input pitch range. Whichever
107 | scaling means that all output pitch values fall within the desired range.
108 |
109 |
110 | Troubleshooting
111 | ---------------
112 |
113 | This package is still in beta and as such may not be completely stable.
114 | If you encounter problems please open a
115 | `github issue `_. We
116 | also welcome code contributions in the form of pull requests.
117 |
118 | The following are known issues/troubleshooting tips:
119 |
120 | - Sonifications cease playing when running in a Jupyter notebook—
121 | Restart the kernel, particularly if it has been running for a while.
122 |
123 | - Sonification will not play when run in a script—
124 | Currently sonifications cannot be played (using the `.play()` method from
125 | python scripts (as opposed to in interactive mode). Instead write the
126 | sonification to a file and play the result in the audio player of your choice.
127 |
128 |
129 |
130 | Light Curve Simulator
131 | =====================
132 |
133 | Astronify also provides a simulation package for creating synthetic light
134 | curves with various characteristics that can then be sonified. The main
135 | function is `~astronify.simulator.simulated_lc` which allows the user to
136 | create a light curve that is flat, sinusoidal, or contains a transiting
137 | exoplanet or stellar flare.
138 |
139 | .. code-block:: python
140 |
141 | >>> from astronify import simulator, series
142 |
143 | >>> lc_data = simulator.simulated_lc("transit", visualize=False, transit_depth=1.5,
144 | ... transit_period=145, transit_width=42,
145 | ... lc_noise=0.5, lc_length=750)
146 | >>> soni_obj = series.SoniSeries(lc_data)
147 | >>> soni_obj.sonify()
148 | >>> soni_obj.play() #doctest: +SKIP
149 |
--------------------------------------------------------------------------------
/docs/CreateWithLight.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 | Create With Light
8 |
9 |
10 |
11 |
12 |
13 |
14 |
15 |
16 |
17 |
CREATE WITH LIGHT
18 |
19 |
20 |
We hired students to create art inspired by space sonification that can be enjoyed by a blind audience. We all met by video chat for 6 weeks during the summer of 2021. The student artists were both blind and sighted themselves—so we had a lot of interesting discussions about acessibility and art.
21 |
22 |
The students created: 2 musical pieces, an animation with spoken word poetry, and a 3-dimensional painting.
70 | I have been thinking about making art all day, and haven’t taken action on it. Maybe a creative thought will slip through the exhaustion-induced chaos. I zombie walk to my desk. I pick up the iPhone then proceed to open Garageband. It certainly isn’t one of the better editors out there, but it’s accessibility is decent. I also happen to be very familiar with it, as I have played with it a lot in the past. I open up a new project file and begin aimlessly scrolling through the eleven selection categories. I stumble upon the sampler which, surprisingly, I have not found use for. This is mainly due to the fact that it makes a speed modification in edition to the pitch change, which I did not want or expect on my first use. Since I was letting ideas loose, and was not familiar with this interface in particular, I decided I would explore it. This art program is about problem solving and open mindedness. I click the button and begin exploring. From experience, I know my keyboard starts near the middle and extends to the bottom of the screen, when holding the phone in the proper orientation. I proceed to find the keyboard and start fiddling with it, making discoveries along the way. Once I got familiar with finding the sample controls, which hide in confusing (and sometimes inaccessible) menus, I record a test sample. Once I record a suitable test sample, I begin editing it and seeing what happens along the way. Though the experience is slow and laggy, it was also somewhat natural. I get carried away playing with this, using the different controls and tapping and sliding through the admittedly small keyboard screen. I became inspired to learn more about it, as the variations of interaction and response are so few and yet so many. This is especially true of samples which have pitch change recorded into them, such as those taken from certain types of sonified data files. This truly intrigues me and I can not wait to see what comes out of it! There is much work to be done…
71 |
72 |
73 |
74 |
75 |
76 |
77 |
Ashley Neall's Artist Statement
78 |
79 | The inspiration for this musical piece is derived from listening to various sonifications and incorporating such auditory data into the piece, while also expressing the emotions I feel when I listen to the sonifications through this piece. While listening to the sonifications before beginning the production process, I would condition myself to think about nothing else except for this auditory data. As I deciphered how the sonifications made me feel and what musical elements could describe this, I began to spontaneously play notes on my electric piano - hoping to find a melody that would successfully convey this emotion, while also blending with the chosen sonification itself.
80 |
81 |
82 | I picked one specific sonification that is considered a flare. To discover how I would create music from this auditory data, I began listening to this specific sonification and re-creating this sequence of notes on my piano by ear. From this exploration on my piano, I created a melody and used different virtual instruments with this same melody that have timbres that “feel” like something extraterrestrial. After adding some voices and synths to this melody, I decided to use a file converter to turn the audio file of the original flare sonification into a MIDI file so that I could further explore the elements of this sonification and manipulate its tempo, pitch, and timbre. From this MIDI version of the flare sonification, I gathered more inspiration as I had greater freedom to incorporate this flare into the melody I now had as a starting point. Continuing to transport, alter, and add tracks, I progressed slowly but ultimately finished with a piece that I believe merges the elements of - and feelings I perceive from - my melody with the flare sonification.
83 |
84 |
85 | I’d rather not explain what emotion I believe this work evokes. Instead, I encourage the audience to decipher their own perceptions of this piece by immersing themselves in the music as they think critically and creatively. Leaving the meaning of this musical piece implicit allows the music to have an infinitely sensational impact.
86 |
87 |
88 |
89 |
90 |
91 |
92 |
Moonasia Williams' Artist Statement
93 |
94 | A World Beyond Us is a word art and digital imagery design in graphics and shadow colors. In A Word Beyond Us it has beautifully done sound, and sound from other outside sources. A World Beyond Us was a developed idea that changed over time due to time constraints. The piece turned out pretty well but definitely could have some improvements in the future.
95 |
96 |
97 |
98 |
99 |
100 |
101 |
102 |
103 |
--------------------------------------------------------------------------------
/docs/conf.py:
--------------------------------------------------------------------------------
1 | # -*- coding: utf-8 -*-
2 | # Licensed under a 3-clause BSD style license - see LICENSE.rst
3 | #
4 | # Astropy documentation build configuration file.
5 | #
6 | # This file is execfile()d with the current directory set to its containing dir.
7 | #
8 | # Note that not all possible configuration values are present in this file.
9 | #
10 | # All configuration values have a default. Some values are defined in
11 | # the global Astropy configuration which is loaded here before anything else.
12 | # See astropy.sphinx.conf for which values are set there.
13 |
14 | # If extensions (or modules to document with autodoc) are in another directory,
15 | # add these directories to sys.path here. If the directory is relative to the
16 | # documentation root, use os.path.abspath to make it absolute, like shown here.
17 | # sys.path.insert(0, os.path.abspath('..'))
18 | # IMPORTANT: the above commented section was generated by sphinx-quickstart, but
19 | # is *NOT* appropriate for astropy or Astropy affiliated packages. It is left
20 | # commented out with this explanation to make it clear why this should not be
21 | # done. If the sys.path entry above is added, when the astropy.sphinx.conf
22 | # import occurs, it will import the *source* version of astropy instead of the
23 | # version installed (if invoked as "make html" or directly with sphinx), or the
24 | # version in the build directory (if "python setup.py build_sphinx" is used).
25 | # Thus, any C-extensions that are needed to build the documentation will *not*
26 | # be accessible, and the documentation will not build correctly.
27 |
28 | import os
29 | import sys
30 | import datetime
31 | from importlib import import_module
32 |
33 | try:
34 | from sphinx_astropy.conf.v1 import * # noqa
35 | except ImportError:
36 | print(
37 | "ERROR: the documentation requires the sphinx-astropy package to be installed"
38 | )
39 | sys.exit(1)
40 |
41 | # Get configuration information from setup.cfg
42 | from configparser import ConfigParser
43 |
44 | conf = ConfigParser()
45 |
46 | conf.read([os.path.join(os.path.dirname(__file__), "..", "setup.cfg")])
47 | setup_cfg = dict(conf.items("metadata"))
48 |
49 | # -- General configuration ----------------------------------------------------
50 |
51 | # By default, highlight as Python 3.
52 | highlight_language = "python3"
53 |
54 | # If your documentation needs a minimal Sphinx version, state it here.
55 | # needs_sphinx = '5.0'
56 |
57 | # To perform a Sphinx version check that needs to be more specific than
58 | # major.minor, call `check_sphinx_version("x.y.z")` here.
59 | # check_sphinx_version("1.2.1")
60 |
61 | # List of patterns, relative to source directory, that match files and
62 | # directories to ignore when looking for source files.
63 | # exclude_patterns.append('_templates')
64 |
65 | # This is added to the end of RST files - a good place to put substitutions to
66 | # be used globally.
67 | rst_epilog += """
68 | """
69 |
70 | # -- Project information ------------------------------------------------------
71 |
72 | # This does not *have* to match the package name, but typically does
73 | project = setup_cfg["name"]
74 | author = setup_cfg["author"]
75 | copyright = "{0}, {1}".format(datetime.datetime.now().year, setup_cfg["author"])
76 |
77 | # The version info for the project you're documenting, acts as replacement for
78 | # |version| and |release|, also used in various other places throughout the
79 | # built documents.
80 |
81 | import_module(setup_cfg["name"])
82 | package = sys.modules[setup_cfg["name"]]
83 |
84 | # The short X.Y version.
85 | version = package.__version__.split("-", 1)[0]
86 | # The full version, including alpha/beta/rc tags.
87 | release = package.__version__
88 |
89 |
90 | # -- Options for HTML output --------------------------------------------------
91 |
92 | # A NOTE ON HTML THEMES
93 | # The global astropy configuration uses a custom theme, 'bootstrap-astropy',
94 | # which is installed along with astropy. A different theme can be used or
95 | # the options for this theme can be modified by overriding some of the
96 | # variables set in the global configuration. The variables set in the
97 | # global configuration are listed below, commented out.
98 |
99 |
100 | # Add any paths that contain custom themes here, relative to this directory.
101 | # To use a different custom theme, add the directory containing the theme.
102 | # html_theme_path = ["_themes",]
103 |
104 | # Custome template path, adding custom css and home link
105 | templates_path = ["_templates"]
106 |
107 | # The theme to use for HTML and HTML Help pages. See the documentation for
108 | # a list of builtin themes. To override the custom theme, set this to the
109 | # name of a builtin theme or the name of a custom theme in html_theme_path.
110 | html_theme = "sphinx_rtd_theme"
111 |
112 |
113 | def setup_style(app):
114 | app.add_stylesheet("astronify.css")
115 |
116 |
117 | master_doc = "contents"
118 | html_extra_path = ["index.html", "CreateWithLight.html"]
119 |
120 | # Custom sidebar templates, maps document names to template names.
121 | html_sidebars = {"**": ["globaltoc.html", "localtoc.html", "searchbox.html"]}
122 |
123 | # The name of an image file (relative to this directory) to place at the top
124 | # of the sidebar.
125 | html_logo = "_static/ASTRONIFY_Ball_white.svg"
126 |
127 | # The name of an image file (within the static path) to use as favicon of the
128 | # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
129 | # pixels large.
130 | html_favicon = "_static/astronify-favicon.png"
131 |
132 | # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
133 | # using the given strftime format.
134 | # html_last_updated_fmt = ''
135 |
136 | # The name for this set of Sphinx documents. If None, it defaults to
137 | # " v documentation".
138 | html_title = "{0} v{1}".format(project, release)
139 |
140 | # Output file base name for HTML help builder.
141 | htmlhelp_basename = project + "doc"
142 |
143 | # Static files to copy after template files
144 | html_static_path = ["_static"]
145 | # html_style = 'astronify.css'
146 |
147 | html_css_files = ["astronify.css"]
148 |
149 |
150 | # -- Options for LaTeX output -------------------------------------------------
151 |
152 | # Grouping the document tree into LaTeX files. List of tuples
153 | # (source start file, target name, title, author, documentclass [howto/manual]).
154 | latex_documents = [
155 | ("index", project + ".tex", project + " Documentation", author, "manual")
156 | ]
157 |
158 |
159 | # -- Options for manual page output -------------------------------------------
160 |
161 | # One entry per manual page. List of tuples
162 | # (source start file, name, description, authors, manual section).
163 | man_pages = [("index", project.lower(), project + " Documentation", [author], 1)]
164 |
165 |
166 | # -- Options for the edit_on_github extension ---------------------------------
167 |
168 | if setup_cfg.get("edit_on_github").lower() == "true":
169 |
170 | extensions += ["sphinx_astropy.ext.edit_on_github"]
171 |
172 | edit_on_github_project = setup_cfg["github_project"]
173 | edit_on_github_branch = "main"
174 |
175 | edit_on_github_source_root = ""
176 | edit_on_github_doc_root = "docs"
177 |
178 | # -- Resolving issue number to links in changelog -----------------------------
179 | github_issues_url = "https://github.com/{0}/issues/".format(setup_cfg["github_project"])
180 |
181 | # -- Turn on nitpicky mode for sphinx (to warn about references not found) ----
182 | #
183 | # nitpicky = True
184 | # nitpick_ignore = []
185 | #
186 | # Some warnings are impossible to suppress, and you can list specific references
187 | # that should be ignored in a nitpick-exceptions file which should be inside
188 | # the docs/ directory. The format of the file should be:
189 | #
190 | #
191 | #
192 | # for example:
193 | #
194 | # py:class astropy.io.votable.tree.Element
195 | # py:class astropy.io.votable.tree.SimpleElement
196 | # py:class astropy.io.votable.tree.SimpleElementWithContent
197 | #
198 | # Uncomment the following lines to enable the exceptions:
199 | #
200 | # for line in open('nitpick-exceptions'):
201 | # if line.strip() == "" or line.startswith("#"):
202 | # continue
203 | # dtype, target = line.split(None, 1)
204 | # target = target.strip()
205 | # nitpick_ignore.append((dtype, six.u(target)))
206 |
--------------------------------------------------------------------------------
/docs/notebooks/Intro_Astronify_Series.ipynb:
--------------------------------------------------------------------------------
1 | {
2 | "cells": [
3 | {
4 | "cell_type": "markdown",
5 | "metadata": {},
6 | "source": [
7 | "# Astronify: Sonifying Time Series\n",
8 | "\n",
9 | "This tutorial will demonstrate the sonification of time series data, specifically light curves using Astronify. It will cover basic usage, adjusting sonification parameters, playing the sonification within the browser, and saving the sonification as a wav file.\n",
10 | "\n",
11 | "1. [Imports](#Imports)\n",
12 | "2. [Getting data](#Getting-data)\n",
13 | "3. [Basic sonification](#Basic-sonification)\n",
14 | "4. [Changing sonification parameters](#Changing-sonification-parameters)\n",
15 | "5. [Outputing an audio file](#Outputing-an-audio-file)"
16 | ]
17 | },
18 | {
19 | "cell_type": "markdown",
20 | "metadata": {},
21 | "source": [
22 | "## Imports\n",
23 | "\n",
24 | "In addition to Astronify, we will use the [Lightkurve](https://docs.lightkurve.org/) package to query and download Kepler light curves, [matplotlib](https://matplotlib.org/) to plot the light curves (these cells will be markes and can be skipped by those for whom plots are not useful), and [Astropy](https://www.astropy.org/) for various data manipulation tasks.\n",
25 | "\n",
26 | "\\* Don't worry if you get a warning about WxPython not being found, it's used for the GUI functionality audio library, which Astronify does not use."
27 | ]
28 | },
29 | {
30 | "cell_type": "code",
31 | "execution_count": null,
32 | "metadata": {},
33 | "outputs": [],
34 | "source": [
35 | "from astronify.series import SoniSeries\n",
36 | "import lightkurve\n",
37 | "\n",
38 | "import matplotlib\n",
39 | "%matplotlib inline\n",
40 | "import matplotlib.pyplot as plt\n",
41 | "\n",
42 | "from astropy.table import Table"
43 | ]
44 | },
45 | {
46 | "cell_type": "markdown",
47 | "metadata": {},
48 | "source": [
49 | "## Getting data\n",
50 | "\n",
51 | "Fundamentally all that Astronify requires is an Astropy Table object where one colum will be translated into time (default is “time”) and one column will be translated into pitch (default is “flux”).\n",
52 | "\n",
53 | "Simply because it is easy I will download a Kepler light curve using lightkurve (lightkurve is a user friendly way to get Kepler and TESS data). This is a light curve that shows Kepler 12b, a transiting exoplanet."
54 | ]
55 | },
56 | {
57 | "cell_type": "code",
58 | "execution_count": null,
59 | "metadata": {},
60 | "outputs": [],
61 | "source": [
62 | "kep12b_lc = lightkurve.search_lightcurvefile(\"KIC 11804465\", cadence=\"long\", quarter=1).download_all()[0].SAP_FLUX.to_table()"
63 | ]
64 | },
65 | {
66 | "cell_type": "markdown",
67 | "metadata": {},
68 | "source": [
69 | "## Basic sonification\n",
70 | "\n",
71 | "Here we will use all of the sonification defaults and see what we get.\n",
72 | "\n",
73 | "First a small peak at the data visually for those of us who find that useful."
74 | ]
75 | },
76 | {
77 | "cell_type": "code",
78 | "execution_count": null,
79 | "metadata": {},
80 | "outputs": [],
81 | "source": [
82 | "f, ax = plt.subplots(figsize=(12, 6))\n",
83 | "ax.plot(kep12b_lc['time'].jd, kep12b_lc['flux'])\n",
84 | "ax.set_xlabel(\"Time (JD)\")\n",
85 | "ax.set_ylabel(\"Flux\")\n",
86 | " \n",
87 | "plt.show()"
88 | ]
89 | },
90 | {
91 | "cell_type": "markdown",
92 | "metadata": {},
93 | "source": [
94 | "Now to sonify the same data."
95 | ]
96 | },
97 | {
98 | "cell_type": "code",
99 | "execution_count": null,
100 | "metadata": {},
101 | "outputs": [],
102 | "source": [
103 | "kep12b_obj = SoniSeries(kep12b_lc)\n",
104 | "kep12b_obj.sonify()"
105 | ]
106 | },
107 | {
108 | "cell_type": "markdown",
109 | "metadata": {},
110 | "source": [
111 | "And play the sonification."
112 | ]
113 | },
114 | {
115 | "cell_type": "code",
116 | "execution_count": null,
117 | "metadata": {},
118 | "outputs": [],
119 | "source": [
120 | "kep12b_obj.play()"
121 | ]
122 | },
123 | {
124 | "cell_type": "markdown",
125 | "metadata": {},
126 | "source": [
127 | "The playback will stop at the end, but we can also stop it early."
128 | ]
129 | },
130 | {
131 | "cell_type": "code",
132 | "execution_count": null,
133 | "metadata": {},
134 | "outputs": [],
135 | "source": [
136 | "kep12b_obj.stop()"
137 | ]
138 | },
139 | {
140 | "cell_type": "markdown",
141 | "metadata": {},
142 | "source": [
143 | "## Changing sonification parameters\n",
144 | "\n",
145 | "Let's look at the current sonification parameters."
146 | ]
147 | },
148 | {
149 | "cell_type": "code",
150 | "execution_count": null,
151 | "metadata": {},
152 | "outputs": [],
153 | "source": [
154 | "kep12b_obj.pitch_mapper.pitch_map_args"
155 | ]
156 | },
157 | {
158 | "cell_type": "markdown",
159 | "metadata": {},
160 | "source": [
161 | "We can change all of these default arguments as well as adding any additional arguments allowed by the pitch mapping function.\n",
162 | "\n",
163 | "### Changing the center pitch"
164 | ]
165 | },
166 | {
167 | "cell_type": "code",
168 | "execution_count": null,
169 | "metadata": {},
170 | "outputs": [],
171 | "source": [
172 | "kep12b_obj.pitch_mapper.pitch_map_args[\"center_pitch\"] = 880\n",
173 | "\n",
174 | "kep12b_obj.sonify()\n",
175 | "kep12b_obj.play()"
176 | ]
177 | },
178 | {
179 | "cell_type": "code",
180 | "execution_count": null,
181 | "metadata": {},
182 | "outputs": [],
183 | "source": [
184 | "kep12b_obj.stop()\n",
185 | "\n",
186 | "kep12b_obj.pitch_mapper.pitch_map_args[\"center_pitch\"] = 440"
187 | ]
188 | },
189 | {
190 | "cell_type": "markdown",
191 | "metadata": {},
192 | "source": [
193 | "### Changing the stretch to logarithmic"
194 | ]
195 | },
196 | {
197 | "cell_type": "code",
198 | "execution_count": null,
199 | "metadata": {},
200 | "outputs": [],
201 | "source": [
202 | "kep12b_obj.pitch_mapper.pitch_map_args[\"stretch\"] = \"log\"\n",
203 | "\n",
204 | "kep12b_obj.sonify()\n",
205 | "kep12b_obj.play()"
206 | ]
207 | },
208 | {
209 | "cell_type": "code",
210 | "execution_count": null,
211 | "metadata": {},
212 | "outputs": [],
213 | "source": [
214 | "kep12b_obj.stop()\n",
215 | "\n",
216 | "kep12b_obj.pitch_mapper.pitch_map_args[\"stretch\"] = \"linear\""
217 | ]
218 | },
219 | {
220 | "cell_type": "markdown",
221 | "metadata": {},
222 | "source": [
223 | "### Removing the outer 1% of data points"
224 | ]
225 | },
226 | {
227 | "cell_type": "code",
228 | "execution_count": null,
229 | "metadata": {},
230 | "outputs": [],
231 | "source": [
232 | "kep12b_obj.pitch_mapper.pitch_map_args[\"minmax_percent\"] = [0.5, 99.5]\n",
233 | "\n",
234 | "kep12b_obj.sonify()\n",
235 | "kep12b_obj.play()"
236 | ]
237 | },
238 | {
239 | "cell_type": "code",
240 | "execution_count": null,
241 | "metadata": {},
242 | "outputs": [],
243 | "source": [
244 | "kep12b_obj.stop()\n",
245 | "\n",
246 | "del kep12b_obj.pitch_mapper.pitch_map_args[\"minmax_percent\"]"
247 | ]
248 | },
249 | {
250 | "cell_type": "markdown",
251 | "metadata": {},
252 | "source": [
253 | "## Outputing an audio file\n",
254 | "\n",
255 | "Once the sonification sounds the way we like we can output the result to a wav file."
256 | ]
257 | },
258 | {
259 | "cell_type": "code",
260 | "execution_count": null,
261 | "metadata": {},
262 | "outputs": [],
263 | "source": [
264 | "kep12b_obj.write(\"kepler_12b.wav\")"
265 | ]
266 | }
267 | ],
268 | "metadata": {
269 | "kernelspec": {
270 | "display_name": "Python 3",
271 | "language": "python",
272 | "name": "python3"
273 | },
274 | "language_info": {
275 | "codemirror_mode": {
276 | "name": "ipython",
277 | "version": 3
278 | },
279 | "file_extension": ".py",
280 | "mimetype": "text/x-python",
281 | "name": "python",
282 | "nbconvert_exporter": "python",
283 | "pygments_lexer": "ipython3",
284 | "version": "3.8.1"
285 | }
286 | },
287 | "nbformat": 4,
288 | "nbformat_minor": 4
289 | }
290 |
--------------------------------------------------------------------------------
/docs/astronify/How_To_Use_The_Simulator.rst:
--------------------------------------------------------------------------------
1 | .. doctest-skip-all
2 |
3 | Astronify: How to Use the Simulator
4 | ===================================
5 |
6 | .. code:: python
7 |
8 | from astropy.io import fits
9 | from astropy.table import Table
10 | from astronify import simulator, series
11 |
12 |
13 | .. parsed-literal::
14 |
15 |
16 | WxPython is not found for the current python version.
17 | Pyo will use a minimal GUI toolkit written with Tkinter (if available).
18 | This toolkit has limited functionnalities and is no more
19 | maintained or updated. If you want to use all of pyo's
20 | GUI features, you should install WxPython, available here:
21 | http://www.wxpython.org/
22 |
23 |
24 |
25 | Let’s start off with a simulated light curve that has almost no
26 | variation at all, to orient ourselves. We’ll use the simulator to create
27 | a “flat” light curve with almost zero noise (specified via the noise
28 | parameter). The length parameter specifies how long we want our light
29 | curve to be. Setting visualize to True means a plot will be made showing
30 | the fluxes (brightness) as a function of time. The yoffset parameter is
31 | used to specify the baseline brightness level.
32 |
33 | .. code:: python
34 |
35 | lc_data = simulator.simulated_lc("flat", lc_length=500, lc_noise=0.1, visualize=True, lc_yoffset=100.)
36 |
37 |
38 |
39 | .. image:: How_To_Use_The_Simulator_files/How_To_Use_The_Simulator_2_0.png
40 |
41 |
42 | Now let’s create a sonified version of the data!
43 |
44 | .. code:: python
45 |
46 | soni_obj = series.SoniSeries(lc_data)
47 | soni_obj.sonify()
48 |
49 | And now let’s listen to the sound!
50 |
51 | .. code:: python
52 |
53 | soni_obj.play()
54 |
55 |
56 | .. parsed-literal::
57 |
58 | Pyo warning: Portmidi warning: no midi device found!
59 | Portmidi closed.
60 |
61 |
62 | You can inject different amounts of noise. Let’s make a light curve with
63 | a lot of noise. In our first example, we used a value of 0.1 for the
64 | noise parameter. Now we’ll make a light curve with 1000 times the level
65 | of noise.
66 |
67 | .. code:: python
68 |
69 | lc_data = simulator.simulated_lc("flat", lc_length=500, lc_noise=100., visualize=True, lc_yoffset=100.)
70 |
71 |
72 |
73 | .. image:: How_To_Use_The_Simulator_files/How_To_Use_The_Simulator_8_0.png
74 |
75 |
76 | Let’s sonify this light curve and listen to it.
77 |
78 | .. code:: python
79 |
80 | soni_obj = series.SoniSeries(lc_data)
81 | soni_obj.sonify()
82 | soni_obj.play()
83 |
84 |
85 | .. parsed-literal::
86 |
87 | Pyo warning: Portmidi warning: no midi device found!
88 | Portmidi closed.
89 |
90 |
91 | You can also use the simulator to inject signals of different types.
92 | Let’s inject a signal expected from a transiting extrasolar planet. For
93 | now, we will use all the defaults for the parameters.
94 |
95 | .. code:: python
96 |
97 | lc_data = simulator.simulated_lc("transit", visualize=True, transit_width=10)
98 |
99 |
100 |
101 | .. image:: How_To_Use_The_Simulator_files/How_To_Use_The_Simulator_12_0.png
102 |
103 |
104 | Let’s sonify this light curve and see if we can hear the drop in
105 | brightness caused by the planet blocking a very small part of the star’s
106 | surface when it passes in front of the star.
107 |
108 | .. code:: python
109 |
110 | soni_obj = series.SoniSeries(lc_data)
111 | soni_obj.pitch_mapper.pitch_map_args["zero_point"] = 95.
112 | soni_obj.sonify()
113 | soni_obj.play()
114 |
115 |
116 | .. parsed-literal::
117 |
118 | Pyo warning: Portmidi warning: no midi device found!
119 | Portmidi closed.
120 |
121 |
122 | Now let’s explore the options when adding a transiting extrasolar planet
123 | signal. We will specify the depth of the transit (how much the planet
124 | blocks), the period (how long it takes the planet to make one full pass
125 | around the star), and the width (how long the planet takes to cross the
126 | star’s surface). We’ll also add some noise to the light curve, and
127 | finally ask for a slightly longer light curve so we can get more
128 | opportunities to have the planet cross in front of the star.
129 |
130 | .. code:: python
131 |
132 | lc_data = simulator.simulated_lc("transit", visualize=True, transit_depth=1.5, transit_period=145,
133 | transit_width=42, lc_noise=0.5, lc_length=750)
134 |
135 |
136 |
137 | .. image:: How_To_Use_The_Simulator_files/How_To_Use_The_Simulator_16_0.png
138 |
139 |
140 | Let’s sonify this light curve!
141 |
142 | .. code:: python
143 |
144 | soni_obj = series.SoniSeries(lc_data)
145 | soni_obj.pitch_mapper.pitch_map_args["zero_point"] = 99.
146 | soni_obj.sonify()
147 | soni_obj.play()
148 |
149 |
150 | .. parsed-literal::
151 |
152 | Pyo warning: Portmidi warning: no midi device found!
153 | Portmidi closed.
154 |
155 |
156 | You can add a stellar flare to the data. Let’s add one using the default
157 | parameters. Stellar flares are sudden increases in brightness over a
158 | short time.
159 |
160 | .. code:: python
161 |
162 | lc_data = simulator.simulated_lc("flare", visualize=True)
163 |
164 |
165 |
166 | .. image:: How_To_Use_The_Simulator_files/How_To_Use_The_Simulator_20_0.png
167 |
168 |
169 | Time to sonify!
170 |
171 | .. code:: python
172 |
173 | soni_obj = series.SoniSeries(lc_data)
174 | soni_obj.sonify()
175 | soni_obj.play()
176 |
177 |
178 | .. parsed-literal::
179 |
180 | Pyo warning: Portmidi warning: no midi device found!
181 | Portmidi closed.
182 |
183 |
184 | You can change the amplitude (height) of the flare, and the width. Let’s
185 | make one that is 10 times larger in amplitude and lasts 10 times as
186 | long. You can also specify the index that corresponds to the peak of the
187 | flare.
188 |
189 | .. code:: python
190 |
191 | lc_data = simulator.simulated_lc("flare", visualize=True, flare_amp=1000., flare_halfwidth=50, flare_time=100)
192 |
193 |
194 |
195 | .. image:: How_To_Use_The_Simulator_files/How_To_Use_The_Simulator_24_0.png
196 |
197 |
198 | Let’s give it a listen.
199 |
200 | .. code:: python
201 |
202 | soni_obj = series.SoniSeries(lc_data)
203 | soni_obj.sonify()
204 | soni_obj.play()
205 |
206 |
207 | .. parsed-literal::
208 |
209 | Pyo warning: Portmidi warning: no midi device found!
210 | Portmidi closed.
211 |
212 |
213 | You can also add sinusoidal signals to the data. Let’s create a light
214 | curve like this using the default parameters.
215 |
216 | .. code:: python
217 |
218 | lc_data = simulator.simulated_lc("sine", visualize=True)
219 |
220 |
221 |
222 | .. image:: How_To_Use_The_Simulator_files/How_To_Use_The_Simulator_28_0.png
223 |
224 |
225 | Let’s sonify this light curve and listen to it.
226 |
227 | .. code:: python
228 |
229 | soni_obj = series.SoniSeries(lc_data)
230 | soni_obj.sonify()
231 | soni_obj.play()
232 |
233 |
234 | .. parsed-literal::
235 |
236 | Pyo warning: Portmidi warning: no midi device found!
237 | Portmidi closed.
238 |
239 |
240 | Now let’s make a sinusoidal signal and use some of the parameter
241 | options. We will change the amplitude (how “big” the curve is from top
242 | to bottom), and the period (how long it takes to make one full cycle
243 | from peak to bottom and back to peak again). We’ll also add a little
244 | noise to the light curve, and ask for a light curve that lasts twice as
245 | long as the default.
246 |
247 | .. code:: python
248 |
249 | lc_data = simulator.simulated_lc("sine", visualize=True, sine_amp=1.5, sine_period=142, lc_noise=0.5, lc_length=1000)
250 |
251 |
252 |
253 | .. image:: How_To_Use_The_Simulator_files/How_To_Use_The_Simulator_32_0.png
254 |
255 |
256 | Let’s sonify this.
257 |
258 | .. code:: python
259 |
260 | soni_obj = series.SoniSeries(lc_data)
261 | soni_obj.sonify()
262 | soni_obj.play()
263 |
264 |
265 | .. parsed-literal::
266 |
267 | Pyo warning: Portmidi warning: no midi device found!
268 | Portmidi closed.
269 |
270 |
271 | If you would like to save a light curve you create with the simulator to
272 | a file for use later, you can specify an output file name and a FITS
273 | file will be created that will store the parameters you used to create
274 | the light curve, as well as the times, fluxes, and fluxes without noise
275 | added. Let’s do that now using the call above (and we won’t ask for a
276 | plot this time). Note: because noise is added randomly, it won’t be
277 | exactly the same as the one above, but will be close enough.
278 |
279 | .. code:: python
280 |
281 | lc_data = simulator.simulated_lc("sine", lc_ofile="sim_lc_sine.fits", visualize=False, sine_amp=1.5, sine_period=142,
282 | lc_noise=0.5, lc_length=1000)
283 |
--------------------------------------------------------------------------------
/astronify/simulator/sim_lc.py:
--------------------------------------------------------------------------------
1 | """
2 | .. module:: sim_lc
3 | :synopsis: Creates simulated light curves with a variety of signals in them
4 | in a FITS format. The files are designed to be read by the Astronify
5 | software package to use when testing the sonification process.
6 |
7 | .. moduleauthor:: Scott W. Fleming
8 | """
9 |
10 | from astropy.io import fits
11 | from astropy.table import Table
12 | import matplotlib.pyplot as plt
13 | import numpy as np
14 | import os
15 | from .sim_lc_config import SimLcConfig
16 | from .add_flare_signal import add_flare_signal
17 | from .add_lc_noise import add_lc_noise
18 | from .add_sine_signal import add_sine_signal
19 | from .add_transit_signal import add_transit_signal
20 | from .check_transit_params import check_transit_params
21 | from .check_flare_params import check_flare_params
22 | from .sim_lc_setup_args import sim_lc_setup_args
23 |
24 |
25 | __all__ = ["simulated_lc", "SimLcConfig"]
26 |
27 |
28 | def simulated_lc(
29 | lc_type,
30 | lc_ofile=SimLcConfig.sim_lc_ofile,
31 | lc_length=SimLcConfig.sim_lc_length,
32 | lc_noise=SimLcConfig.sim_lc_noise,
33 | visualize=SimLcConfig.sim_lc_visualize,
34 | lc_yoffset=SimLcConfig.sim_lc_yoffset,
35 | transit_depth=SimLcConfig.sim_lc_transit_depth,
36 | transit_period=SimLcConfig.sim_lc_transit_period,
37 | transit_start=SimLcConfig.sim_lc_transit_start,
38 | transit_width=SimLcConfig.sim_lc_transit_width,
39 | sine_amp=SimLcConfig.sim_lc_sine_amp,
40 | sine_period=SimLcConfig.sim_lc_sine_period,
41 | flare_time=SimLcConfig.sim_lc_flare_time,
42 | flare_amp=SimLcConfig.sim_lc_flare_amp,
43 | flare_halfwidth=SimLcConfig.sim_lc_flare_halfwidth,
44 | ):
45 | """
46 | Create light curve with specified parameters as a `~astropy.table.Table`,
47 | and optionally writes a FITS file with the same information.
48 |
49 | All parameters default to the configuration values.
50 |
51 | Parameters
52 | ----------
53 | lc_type : str
54 | The type of light curve to make. Valid options are 'flat', 'transit',
55 | 'sine', and 'flare'.
56 |
57 | lc_ofile : str or None
58 | Optional. Name of output FITS file. If set to None,
59 | no file will be saved to disk.
60 |
61 | lc_length : int
62 | Optional. Length of the light curve (i.e. the number of flux values).
63 |
64 | lc_noise : float
65 | Optional. Standard deviation of normal distribution to draw from when
66 | adding noise, a value of zero means no noise is added.
67 |
68 | visualize : bool
69 | Optional. If True, plot the light curve being made to the screen.
70 |
71 | lc_yoffset : float
72 | Optional. Baseline flux level (unitless).
73 |
74 | transit_depth: float
75 | Depth of transit, as a percent (e.g., 10.0 = 10%.)
76 |
77 | transit_period : int
78 | Period of transit (number of fluxes/bins between the start of each event.)
79 | (Only relevant for transit type light curve).
80 |
81 | transit_start : int
82 | Start index of transit (the index of the flux/bin to use as the start of the first transit
83 | event.)
84 | (Only relevant for transit type light curve).
85 |
86 | transit_width : int
87 | Width of transit (number of fluxes/bins between the start and end of each event.)
88 |
89 | sine_amp : float
90 | Amplitude of the sinusoidal signal to add.
91 |
92 | sine_period : float
93 | Period of the sinusoidal signal to add.
94 |
95 | flare_time: int
96 | Time corresponding to the maximum flare flux.
97 |
98 | flare_amp : float
99 | The peak (maximum flux) of the flare.
100 |
101 | flare_halfwidth : float
102 | The flare half-width (measured in indices) that
103 | corresponds to "t_1/2" in the Davenport et al. flare template.
104 |
105 | Returns
106 | -------
107 | response : `~astropy.table.Table`
108 | The time and flux columns.
109 | """
110 |
111 | # Generate baseline light curve fluxes.
112 | fluxes = np.full(lc_length, lc_yoffset)
113 |
114 | # We don't need real times for the simulation, it's just an array of indexes.
115 | times = np.arange(fluxes.size)
116 |
117 | # Apply signal of choice if needed.
118 | if lc_type == "flare":
119 | check_flare_params(fluxes.size, flare_time, flare_amp)
120 | fluxes = add_flare_signal(fluxes, flare_time, flare_amp, flare_halfwidth)
121 | elif lc_type == "sine":
122 | fluxes = add_sine_signal(times, fluxes, sine_amp, sine_period)
123 | elif lc_type == "transit":
124 | check_transit_params(fluxes.size, transit_period, transit_start, transit_width)
125 | fluxes = add_transit_signal(
126 | fluxes, transit_depth, transit_period, transit_start, transit_width
127 | )
128 |
129 | # Add noise based on standard deviation.
130 | fluxes_with_noise = add_lc_noise(fluxes, lc_noise)
131 |
132 | # Visualize the light curve, if desired.
133 | if visualize:
134 | _, ax1 = plt.subplots(1)
135 | ax1.plot(times, fluxes_with_noise, "bo")
136 | plt.show()
137 |
138 | if lc_ofile:
139 | # Save light curve as FITS file.
140 | hdr = fits.Header()
141 | # Add input arguments as keyword headers here.
142 | hdr.append(("LCTYPE", lc_type, "Type of signal."))
143 | hdr.append(("LCLENGTH", lc_length, "Number of fluxes."))
144 | hdr.append(("LCYOFF", lc_yoffset, "Baseline flux value (unitless)."))
145 | hdr.append(
146 | ("LCNOISE", lc_noise, "Std. dev. of normal dist. used to apply noise.")
147 | )
148 | # Record the flare parameters used if adding a flare.
149 | if lc_type == "flare":
150 | hdr.append(
151 | (
152 | "FLARETIM",
153 | flare_time,
154 | "Index corresponding to the peak of the flare.",
155 | )
156 | )
157 | hdr.append(("FLAREAMP", flare_amp, "Amplitude of the flare."))
158 | hdr.append(
159 | ("FLAREWID", flare_halfwidth, "Flare half-width (number of indices).")
160 | )
161 | # Record the sinusoidal parameters if adding a sinusoid.
162 | if lc_type == "sine":
163 | hdr.append(("SINEAMP", sine_amp, "Amplitude of sine."))
164 | hdr.append(("SINEPER", sine_amp, "Period of sine."))
165 | # Record the transit parameters if adding a transit.
166 | if lc_type == "transit":
167 | hdr.append(("TRANDEP", transit_depth, "Depth of transit."))
168 | hdr.append(("TRANPER", transit_period, "Period of planet."))
169 | hdr.append(("TRANSTAR", transit_start, "Start index of transit."))
170 | hdr.append(("TRANWID", transit_width, "Width of transit."))
171 | # This builds the primary header, no data, just keywords.
172 | primary_hdu = fits.PrimaryHDU(header=hdr)
173 | # This sets up the binary table and creates the first extension header.
174 | col1 = fits.Column(name="time", array=times, format="D")
175 | col2 = fits.Column(name="flux", array=fluxes_with_noise, format="D")
176 | col3 = fits.Column(name="flux_pure", array=fluxes, format="D")
177 | hdu1 = fits.BinTableHDU.from_columns([col1, col2, col3])
178 | # If the output directory doesn't exist, create it.
179 | if not os.path.isdir(os.path.abspath(os.path.dirname(lc_ofile))):
180 | os.makedirs(os.path.dirname(os.path.abspath(lc_ofile)))
181 | # This combines the primary HDU and first extension header together and
182 | # writes to the output file.
183 | hdu_list = fits.HDUList([primary_hdu, hdu1])
184 | hdu_list.writeto(lc_ofile, overwrite=True, checksum=True)
185 |
186 | # Return the times and fluxes as an astropy Table so it can be directly
187 | # used later in a script.
188 | return Table(
189 | [times, fluxes_with_noise, fluxes], names=("time", "flux", "flux_pure")
190 | )
191 |
192 |
193 | if __name__ == "__main__":
194 | # Get command-line arguments.
195 | INPUT_ARGS = sim_lc_setup_args().parse_args()
196 |
197 | simulated_lc(
198 | INPUT_ARGS.lc_type,
199 | INPUT_ARGS.lc_ofile,
200 | INPUT_ARGS.lc_length,
201 | INPUT_ARGS.lc_noise,
202 | INPUT_ARGS.visualize,
203 | INPUT_ARGS.lc_yoffset,
204 | INPUT_ARGS.transit_depth,
205 | INPUT_ARGS.transit_period,
206 | INPUT_ARGS.transit_start,
207 | INPUT_ARGS.transit_width,
208 | INPUT_ARGS.sine_amp,
209 | INPUT_ARGS.sine_period,
210 | INPUT_ARGS.flare_time,
211 | INPUT_ARGS.flare_amp,
212 | INPUT_ARGS.flare_halfwidth,
213 | )
214 |
--------------------------------------------------------------------------------
/docs/_static/ASTRONIFY.svg:
--------------------------------------------------------------------------------
1 |
2 |
3 |
96 |
--------------------------------------------------------------------------------
/docs/notebooks/How_To_Use_The_Simulator.ipynb:
--------------------------------------------------------------------------------
1 | {
2 | "cells": [
3 | {
4 | "cell_type": "code",
5 | "execution_count": null,
6 | "metadata": {},
7 | "outputs": [],
8 | "source": [
9 | "from astropy.io import fits\n",
10 | "from astropy.table import Table\n",
11 | "from astronify import simulator, series"
12 | ]
13 | },
14 | {
15 | "cell_type": "markdown",
16 | "metadata": {},
17 | "source": [
18 | "Let's start off with a simulated light curve that has almost no variation at all, to orient ourselves. We'll use the simulator to create a \"flat\" light curve with almost zero noise (specified via the noise parameter). The length parameter specifies how long we want our light curve to be. Setting visualize to True means a plot will be made showing the fluxes (brightness) as a function of time. The yoffset parameter is used to specify the baseline brightness level."
19 | ]
20 | },
21 | {
22 | "cell_type": "code",
23 | "execution_count": null,
24 | "metadata": {},
25 | "outputs": [],
26 | "source": [
27 | "lc_data = simulator.simulated_lc(\"flat\", lc_length=500, lc_noise=0.1, visualize=True, lc_yoffset=100.)"
28 | ]
29 | },
30 | {
31 | "cell_type": "markdown",
32 | "metadata": {},
33 | "source": [
34 | "Now let's create a sonified version of the data!"
35 | ]
36 | },
37 | {
38 | "cell_type": "code",
39 | "execution_count": null,
40 | "metadata": {},
41 | "outputs": [],
42 | "source": [
43 | "soni_obj = series.SoniSeries(lc_data)\n",
44 | "soni_obj.sonify()"
45 | ]
46 | },
47 | {
48 | "cell_type": "markdown",
49 | "metadata": {},
50 | "source": [
51 | "And now let's listen to the sound!"
52 | ]
53 | },
54 | {
55 | "cell_type": "code",
56 | "execution_count": null,
57 | "metadata": {},
58 | "outputs": [],
59 | "source": [
60 | "soni_obj.play()"
61 | ]
62 | },
63 | {
64 | "cell_type": "markdown",
65 | "metadata": {},
66 | "source": [
67 | "You can inject different amounts of noise. Let's make a light curve with a lot of noise. In our first example, we used a value of 0.1 for the noise parameter. Now we'll make a light curve with 1000 times the level of noise."
68 | ]
69 | },
70 | {
71 | "cell_type": "code",
72 | "execution_count": null,
73 | "metadata": {},
74 | "outputs": [],
75 | "source": [
76 | "lc_data = simulator.simulated_lc(\"flat\", lc_length=500, lc_noise=100., visualize=True, lc_yoffset=100.)"
77 | ]
78 | },
79 | {
80 | "cell_type": "markdown",
81 | "metadata": {},
82 | "source": [
83 | "Let's sonify this light curve and listen to it."
84 | ]
85 | },
86 | {
87 | "cell_type": "code",
88 | "execution_count": null,
89 | "metadata": {},
90 | "outputs": [],
91 | "source": [
92 | "soni_obj = series.SoniSeries(lc_data)\n",
93 | "soni_obj.sonify()\n",
94 | "soni_obj.play()"
95 | ]
96 | },
97 | {
98 | "cell_type": "markdown",
99 | "metadata": {},
100 | "source": [
101 | "You can also use the simulator to inject signals of different types. Let's inject a signal expected from a transiting extrasolar planet. For now, we will use all the defaults for the parameters."
102 | ]
103 | },
104 | {
105 | "cell_type": "code",
106 | "execution_count": null,
107 | "metadata": {},
108 | "outputs": [],
109 | "source": [
110 | "lc_data = simulator.simulated_lc(\"transit\", visualize=True, transit_width=10)"
111 | ]
112 | },
113 | {
114 | "cell_type": "markdown",
115 | "metadata": {},
116 | "source": [
117 | "Let's sonify this light curve and see if we can hear the drop in brightness caused by the planet blocking a very small part of the star's surface when it passes in front of the star."
118 | ]
119 | },
120 | {
121 | "cell_type": "code",
122 | "execution_count": null,
123 | "metadata": {},
124 | "outputs": [],
125 | "source": [
126 | "soni_obj = series.SoniSeries(lc_data)\n",
127 | "soni_obj.pitch_mapper.pitch_map_args[\"zero_point\"] = 95.\n",
128 | "soni_obj.sonify()\n",
129 | "soni_obj.play()"
130 | ]
131 | },
132 | {
133 | "cell_type": "markdown",
134 | "metadata": {},
135 | "source": [
136 | "Now let's explore the options when adding a transiting extrasolar planet signal. We will specify the depth of the transit (how much the planet blocks), the period (how long it takes the planet to make one full pass around the star), and the width (how long the planet takes to cross the star's surface). We'll also add some noise to the light curve, and finally ask for a slightly longer light curve so we can get more opportunities to have the planet cross in front of the star."
137 | ]
138 | },
139 | {
140 | "cell_type": "code",
141 | "execution_count": null,
142 | "metadata": {},
143 | "outputs": [],
144 | "source": [
145 | "lc_data = simulator.simulated_lc(\"transit\", visualize=True, transit_depth=1.5, transit_period=145,\n",
146 | " transit_width=42, lc_noise=0.5, lc_length=750)"
147 | ]
148 | },
149 | {
150 | "cell_type": "markdown",
151 | "metadata": {},
152 | "source": [
153 | "Let's sonify this light curve!"
154 | ]
155 | },
156 | {
157 | "cell_type": "code",
158 | "execution_count": null,
159 | "metadata": {},
160 | "outputs": [],
161 | "source": [
162 | "soni_obj = series.SoniSeries(lc_data)\n",
163 | "soni_obj.pitch_mapper.pitch_map_args[\"zero_point\"] = 99.\n",
164 | "soni_obj.sonify()\n",
165 | "soni_obj.play()"
166 | ]
167 | },
168 | {
169 | "cell_type": "markdown",
170 | "metadata": {},
171 | "source": [
172 | "You can add a stellar flare to the data. Let's add one using the default parameters. Stellar flares are sudden increases in brightness over a short time."
173 | ]
174 | },
175 | {
176 | "cell_type": "code",
177 | "execution_count": null,
178 | "metadata": {},
179 | "outputs": [],
180 | "source": [
181 | "lc_data = simulator.simulated_lc(\"flare\", visualize=True)"
182 | ]
183 | },
184 | {
185 | "cell_type": "markdown",
186 | "metadata": {},
187 | "source": [
188 | "Time to sonify!"
189 | ]
190 | },
191 | {
192 | "cell_type": "code",
193 | "execution_count": null,
194 | "metadata": {},
195 | "outputs": [],
196 | "source": [
197 | "soni_obj = series.SoniSeries(lc_data)\n",
198 | "soni_obj.sonify()\n",
199 | "soni_obj.play()"
200 | ]
201 | },
202 | {
203 | "cell_type": "markdown",
204 | "metadata": {},
205 | "source": [
206 | "You can change the amplitude (height) of the flare, and the width. Let's make one that is 10 times larger in amplitude and lasts 10 times as long. You can also specify the index that corresponds to the peak of the flare."
207 | ]
208 | },
209 | {
210 | "cell_type": "code",
211 | "execution_count": null,
212 | "metadata": {},
213 | "outputs": [],
214 | "source": [
215 | "lc_data = simulator.simulated_lc(\"flare\", visualize=True, flare_amp=1000., flare_halfwidth=50, flare_time=100)"
216 | ]
217 | },
218 | {
219 | "cell_type": "markdown",
220 | "metadata": {},
221 | "source": [
222 | "Let's give it a listen."
223 | ]
224 | },
225 | {
226 | "cell_type": "code",
227 | "execution_count": null,
228 | "metadata": {},
229 | "outputs": [],
230 | "source": [
231 | "soni_obj = series.SoniSeries(lc_data)\n",
232 | "soni_obj.sonify()\n",
233 | "soni_obj.play()"
234 | ]
235 | },
236 | {
237 | "cell_type": "markdown",
238 | "metadata": {},
239 | "source": [
240 | "You can also add sinusoidal signals to the data. Let's create a light curve like this using the default parameters."
241 | ]
242 | },
243 | {
244 | "cell_type": "code",
245 | "execution_count": null,
246 | "metadata": {},
247 | "outputs": [],
248 | "source": [
249 | "lc_data = simulator.simulated_lc(\"sine\", visualize=True)"
250 | ]
251 | },
252 | {
253 | "cell_type": "markdown",
254 | "metadata": {},
255 | "source": [
256 | "Let's sonify this light curve and listen to it."
257 | ]
258 | },
259 | {
260 | "cell_type": "code",
261 | "execution_count": null,
262 | "metadata": {},
263 | "outputs": [],
264 | "source": [
265 | "soni_obj = series.SoniSeries(lc_data)\n",
266 | "soni_obj.sonify()\n",
267 | "soni_obj.play()"
268 | ]
269 | },
270 | {
271 | "cell_type": "markdown",
272 | "metadata": {},
273 | "source": [
274 | "Now let's make a sinusoidal signal and use some of the parameter options. We will change the amplitude (how \"big\" the curve is from top to bottom), and the period (how long it takes to make one full cycle from peak to bottom and back to peak again). We'll also add a little noise to the light curve, and ask for a light curve that lasts twice as long as the default."
275 | ]
276 | },
277 | {
278 | "cell_type": "code",
279 | "execution_count": null,
280 | "metadata": {},
281 | "outputs": [],
282 | "source": [
283 | "lc_data = simulator.simulated_lc(\"sine\", visualize=True, sine_amp=1.5, sine_period=142, lc_noise=0.5, lc_length=1000)"
284 | ]
285 | },
286 | {
287 | "cell_type": "markdown",
288 | "metadata": {},
289 | "source": [
290 | "Let's sonify this."
291 | ]
292 | },
293 | {
294 | "cell_type": "code",
295 | "execution_count": null,
296 | "metadata": {},
297 | "outputs": [],
298 | "source": [
299 | "soni_obj = series.SoniSeries(lc_data)\n",
300 | "soni_obj.sonify()\n",
301 | "soni_obj.play()"
302 | ]
303 | },
304 | {
305 | "cell_type": "markdown",
306 | "metadata": {},
307 | "source": [
308 | "If you would like to save a light curve you create with the simulator to a file for use later, you can specify an output file name and a FITS file will be created that will store the parameters you used to create the light curve, as well as the times, fluxes, and fluxes without noise added. Let's do that now using the call above (and we won't ask for a plot this time). Note: because noise is added randomly, it won't be exactly the same as the one above, but will be close enough."
309 | ]
310 | },
311 | {
312 | "cell_type": "code",
313 | "execution_count": null,
314 | "metadata": {},
315 | "outputs": [],
316 | "source": [
317 | "lc_data = simulator.simulated_lc(\"sine\", lc_ofile=\"sim_lc_sine.fits\", visualize=False, sine_amp=1.5, sine_period=142,\n",
318 | " lc_noise=0.5, lc_length=1000)"
319 | ]
320 | }
321 | ],
322 | "metadata": {
323 | "kernelspec": {
324 | "display_name": "Python 3",
325 | "language": "python",
326 | "name": "python3"
327 | },
328 | "language_info": {
329 | "codemirror_mode": {
330 | "name": "ipython",
331 | "version": 3
332 | },
333 | "file_extension": ".py",
334 | "mimetype": "text/x-python",
335 | "name": "python",
336 | "nbconvert_exporter": "python",
337 | "pygments_lexer": "ipython3",
338 | "version": "3.8.1"
339 | }
340 | },
341 | "nbformat": 4,
342 | "nbformat_minor": 2
343 | }
344 |
--------------------------------------------------------------------------------
16 |
17 | 
57 |
58 |
59 |
60 |
61 |
62 |
63 |
64 |